Package: renamerename
RenameRenameRenameRenameis a command-line utility app that bulk renames a set of files based on some specifications.
What's special about this tool, among so many other similar ones, is that it's straightforward to use.If you don't feel like dealing with complex regex's and just want the job done without any learning effort,
then hopefully RenameRename can cater to your bulk renaming needs. 😄The main usage of RenameRename is as a CLI tool.
Nevertheless, it can also be used as a package of modules containing utility classes and functions for your own modules.Feel free to take a look at theAPI reference / documentation.RequirementsTo run the CLI tool, you primarily need the following installed on your system:Python 3.6+InstallTo install the package, you can do so withpip.pipinstallrenamerenameOtherwise, if you want to install from source, just clone the repository in the directory of your choice,
and then install it withpip, as such:gitclonehttps://github.com/mhmdkanj/RenameRename.git
pipinstall-eRenameRenameUsageIn order to use RenameRename, run the Python package with:renamerename[options]FilteringBy default, RenameRename searches for files in the current working directory.
Otherwise, a different one can be set using the--diroption.Filtering of files is done via Unix filename patterns supplied with the--filter, such as:PatternUsageExampleNoneexact charactersfile->file*any number of charactersimg*->img_foo.tar.gz,img123.png,img, etc.?any single characterdoc?file->doc_file,doc1file,docsfile, etc.[seq]any character inseqfile_[abcdef].txt->file_a.txt,file_b.txt, etc.[!seq]any character not inseqfile_[!abc].txt->file_d.txt,file_1.txt,file__.txt, etc.You can check which files are filtered out by providing the filter option without any actions.renamerename--filter"img_*"# OUTPUT: filter all files beginning with: img_NOTES:It is necessary to enclose filter arguments with double quotation marks" ", as this would allow you to pass the literal filter expression to the command (otherwise, the shell would process it, resolve the filenames itself, and pass invalid arguments to the command).RenameRename acts on non-hidden files inside a directory. Also, the file search is non-recursive and does not take into account directory names.Basic ActionsSome basic actions to rename filtered files are provided.
The more specific the action, the better.ActionUsageExample--prefix PREFIXprependsPREFIXto the filenamefile.txt->PREFIXfile.txt--suffix SUFFIXappendsSUFFIXto the filenamefile.txt->fileSUFFIX.txt--change-extension .extchanges the file extensionfile.txt->file.ext--add-numbering PREFIXchanges the filename toPREFIXand appends a countermyarchive.tar.gz,myfile.txt->PREFIX1.tar.gz,PREFIX2.txtYou can of course use multiple actions at the same time.For instance, if you want to add a prefix, suffix, and change the extension of files beginning with "myfile" and ending with ".png", execute the following:renamerename--filter"myfile*.png"--prefixfoo_--suffix_bar--change-extension.jpeg# Filtered files: myfile_a.png , myfileee.png , myfile_somechars.png# OUTPUT:#        myfile_a.png  --->  foo_myfile_a_bar.jpeg#        myfileee.png  --->  foo_myfileee_bar.jpeg#        myfile_somechars.png ---> foo_myfile_somechars_bar.jpegOnly Show Renaming Output without ExecutionIf you just want toseewhat would happen if some options and actions were supplied without actually renaming your files,
you can do so by supplying the--only-output-resultsor-oflag.
This way, you can review if the renaming will be done as intended and without any consequences.renamerename[actions]-oSaving What Was Renamed to WhatIf you want to save all the source and target filenames for future reference (in case wrong files were renamed),
you can supply the--save-renamingflag to do that.renamerename[actions]--save-renamingThis creates aJSONfile in the directory supplied with--dir(or if no directory was supplied, the current directory) that contains the necessary changes.Rename by Loading a JSON fileRenaming can also be done by supplying a JSON file that dictates the source and target filenames needed.
In this case, no filtering is done, but rather the source filenames are manually entered in the JSON file.The supplied file, via the--from-jsonoption, should be a dictionary of source filenames mapped to target filenames. Example:{"myfile_a.png":"foo_myfile_a_bar.jpeg","myfileee.png":"foo_myfileee_bar.jpeg","myfile_somechars.png":"foo_myfile_somechars_bar.jpeg"}Suppose this file was calledrenaming.json, you can execute the renaming by:renamerename--dirDIR--from-jsonrenaming.jsonUndo RenamingIn case you did not intend to execute the renaming of files, you can undo this with the--undo-from-jsonoption,
in which RenameRename will reverse the renaming.The renaming can only be undone if in the previous call to RenameRename, you used the--save-renamingoption.
The JSON file created in that call needs to be supplied to the--undo-from-jsonoption.
The mapping is reversed internally.renamerename--dirDIR--undo-from-jsonrenaming.jsonOtherwise, if you do not have the JSON file, you can create one manually and execute RenameRename with the--from-jsonoption.Synopsisusage: renamerename [options]

Bulk renaming of files made easy.

optional arguments:
  -h, --help            show this help message and exit
  --dir directory       directory whose filenames are processed
  --only-output-results, -o
                        only show renaming results without execution
  --filter FILTER, -f FILTER
                        filter the directory contents according to Unix
                        patterns
  --prefix PREFIX, -p PREFIX
                        add a prefix to filtered filenames
  --suffix SUFFIX, -s SUFFIX
                        add a suffix to filtered filenames
  --change-extension CHANGE_EXTENSION, -e CHANGE_EXTENSION
                        change the extension of the filtered filenames
  --add-numbering ADD_NUMBERING, -n ADD_NUMBERING
                        change filtered filenames to same name suffixed with
                        increasing numbers
  --save-renaming, -sr  create JSON file containing all files renamed
  --from-json JSON file path
                        rename set of files as described from JSON file
  --undo-from-json JSON file path
                        undo renaming of set of files based on saved renaming
                        specification
  --version             show program's version number and exitTestThe RenameRename Python package includes unit tests for developers who wish to locally test it (especially upon contributing).For that, you first need to install the testing dependencies via:pipinstall-rrequirements-dev.txtThe tests can be run withpytestand executed via the following:cdrepository_root# enter the root directory of the repositorypytestDocumentationThedocumentation(mostly the API reference) to the Python package currently resides on GitHub Pages.For contributing developers, building the docs locally requires the following:pipinstall-rdocs/requirements-docs.txt
apt-getinstallmakeYou can then build the docs with:cddocs# relative to repository rootmakehtml