tl.rename provides an implementation of the rename program some form of which is included with many POSIX operating systems. While those tools usually do only substring or regular expression replacement, planned file name transformations in tl.rename include:
Version 0.1 implements reading names from a file or standard input, case transformations, simple substring replacement and interactive renaming using readline.
The tl.rename package is readily usable as a library but also installs an executable script that exercises its functionality.
rename [options] [file paths]
File paths may contain directory paths and be either absolute or relative to the current working directory. The specified files do not need to exist when rename is called but will cause it to fail if they do not exist when the actual renaming is being done.
-h, --help | show this help message and exit |
-d, --debug | debug mode, do not catch Python exceptions |
-D, --dry-run | dry-run mode, do not touch the file system |
-s SLICE, --slice=SLICE | |
transform only a slice of each name, value is LOWER:UPPER, both bounds are optional | |
-n NAMES_FILE, --names-file=NAMES_FILE | |
read new names from file where - denotes standard input | |
-c CASE, --case=CASE | |
case-transform names, possible values are upper, lower, sentence | |
-r FROM_TO, --replace=FROM_TO | |
where FROM_TO is two distinct arguments (-r FROM TO); globally replace first option argument with second, may be given multiple times | |
-i, --interactive | |
edit names interactively (assumed if no transformation is explicitly specified) |
tl.rename runs one or more string transformations on a sequence of file names given as command arguments, then renames the files accordingly.
Which transformations to apply is determined by command line options. If multiple transformations are selected, they will be run in the following order:
Read new file names from a file or standard input, one name per line.
Replace substrings of the file names where match patterns and replacements are given literally as two arguments. Any number of replacements can be made in one go.
Let the user edit each file name in turn using the readline library if available. This provides comfortable line editing including a history.
The list of file names must fulfill the following conditions:
Once all transformations have been performed on the file names, those items whose names have actually changed will be renamed in the file system (except if dry-run mode is active). Renaming is subject to the following rules:
It is possible to restrict transformations to a specified portion of each file name. As an example, this can be useful when applying sentence case to prefixed file names if the prefix should not count as the beginning of a sentence.
Which portion (or slice) of each file name to subject to transformations is determined by a specification given as the value of the --slice option. The syntax of this value is that of Python’s simple slices: two integer numbers separated by a colon. The numbers denote the start and stop index of the slice where counting starts from 0. The stop index is the index of the first character after the slice. Both start and stop index may be omitted (but the colon may not); they default to the beginning and the end of the name (0 and a very big number), respectively. Negative indexes are understood to count from the end of the name.
Let’s give some examples, applied to the file name “05 - An interesting song.ogg” (28 characters):
Specification | Slice |
---|---|
: | 05 - An interesting song.ogg |
5:100 | An interesting song.ogg |
:-4 | 05 - An interesting song |
5:-4 | An interesting song |
5:24 | An interesting song |