Metadata-Version: 2.1
Name: renamerename
Version: 1.0.0
Summary: Bulk renaming of files made easy
Home-page: https://github.com/mhmdkanj/RenameRename
Author: Mohamad Kanj
Author-email: mhmd.kanj@gmail.com
License: MIT
Description: # RenameRename
        
        ![docs](https://github.com/mhmdkanj/RenameRename/actions/workflows/docs.yml/badge.svg?branch=main)
        ![test](https://github.com/mhmdkanj/RenameRename/actions/workflows/test.yml/badge.svg?branch=main)
        [![codecov](https://codecov.io/gh/mhmdkanj/RenameRename/branch/main/graph/badge.svg?token=VYS7K7KRVB)](https://codecov.io/gh/mhmdkanj/RenameRename)
        
        **RenameRename** is 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 the [API reference / documentation](https://mhmdkanj.github.io/RenameRename/html/index.html).
        
        ## Requirements
        
        To run the CLI tool, you primarily need the following installed on your system:
        - [Python 3.6+](https://www.python.org/)
        
        ## Install
        
        To install the package, you can do so with [pip](https://pypi.org/project/pip/).
        
        ```sh
        pip install renamerename
        ```
        
        Otherwise, if you want to install from source, just clone the repository in the directory of your choice,
        and then install it with `pip`, as such:
        
        ```sh
        git clone https://github.com/mhmdkanj/RenameRename.git
        pip install -e RenameRename
        ```
        
        ## Usage
        
        In order to use RenameRename, run the Python package with:
        ```sh
        renamerename [options]
        ```
        
        ### Filtering
        
        By default, RenameRename searches for files in the current working directory.
        Otherwise, a different one can be set using the `--dir` option.
        
        Filtering of files is done via Unix filename patterns supplied with the `--filter`, such as:
        
        |  Pattern  |  Usage  |  Example  |
        |  -------  |  ------ |  -------  |
        |  *None*   |  exact characters  |  `file` -> `file` |
        |  `*`      |  any number of characters |  `img*` -> `img_foo.tar.gz`, `img123.png`, `img`, etc.  |
        |  `?`      |  any single character  | `doc?file` -> `doc_file`, `doc1file`, `docsfile`, etc.  |
        |  `[seq]`  |  any character in *seq*  |  `file_[abcdef].txt` -> `file_a.txt`, `file_b.txt`, etc.  |
        |  `[!seq]` |  any character not in *seq*  |  `file_[!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.
        ```sh
        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 Actions
        
        Some basic actions to rename filtered files are provided.
        The more specific the action, the better.
        
        |  Action   |  Usage   |  Example  |
        |  -------  |  ------  | -------   |
        |  `--prefix PREFIX`         |  prepends `PREFIX` to the filename  |  `file.txt` -> `PREFIXfile.txt` |
        |  `--suffix SUFFIX`         |  appends `SUFFIX` to the filename   |  `file.txt` -> `fileSUFFIX.txt` |
        |  `--change-extension .ext` |  changes the file extension         |  `file.txt` -> `file.ext`       |
        |  `--add-numbering PREFIX`  |  changes the filename to `PREFIX` and appends a counter  |  `myarchive.tar.gz`, `myfile.txt` -> `PREFIX1.tar.gz`, `PREFIX2.txt`  |
        
        You 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:
        ```sh
        renamerename --filter "myfile*.png" --prefix foo_ --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.jpeg
        ```
        
        ### Only Show Renaming Output without Execution
        
        If you just want to *see* what would happen if some options and actions were supplied without actually renaming your files,
        you can do so by supplying the `--only-output-results` or `-o` flag.
        This way, you can review if the renaming will be done as intended and without any consequences.
        
        ```sh
        renamerename [actions] -o
        ```
        
        ### Saving What Was Renamed to What
        
        If you want to save all the source and target filenames for future reference (in case wrong files were renamed),
        you can supply the `--save-renaming` flag to do that.
        
        ```sh
        renamerename [actions] --save-renaming
        ```
        
        This creates a `JSON` file 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 file
        
        Renaming 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-json` option, should be a dictionary of source filenames mapped to target filenames. Example:
        ```json
        {
        "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 called `renaming.json`, you can execute the renaming by:
        ```sh
        renamerename --dir DIR --from-json renaming.json
        ```
        
        ### Undo Renaming
        
        In case you did not intend to execute the renaming of files, you can undo this with the `--undo-from-json` option,
        in which RenameRename will reverse the renaming.
        
        The renaming can only be undone if in the previous call to RenameRename, you used the `--save-renaming` option.
        The JSON file created in that call needs to be supplied to the `--undo-from-json` option.
        The mapping is reversed internally.
        
        ```sh
        renamerename --dir DIR --undo-from-json renaming.json
        ```
        
        Otherwise, if you do not have the JSON file, you can create one manually and execute RenameRename with the `--from-json` option.
        
        ### Synopsis
        
        
        ```
        usage: 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 exit
        ```
        
        ## Test
        
        The 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:
        ```sh
        pip install -r requirements-dev.txt
        ```
        
        The tests can be run with `pytest` and executed via the following:
        ```sh
        cd repository_root   # enter the root directory of the repository
        pytest
        ```
        
        ## Documentation
        
        The [documentation](https://mhmdkanj.github.io/RenameRename/html/index.html) (mostly the API reference) to the Python package currently resides on GitHub Pages.
        
        For contributing developers, building the docs locally requires the following:
        
        ```sh
        pip install -r docs/requirements-docs.txt
        apt-get install make
        ```
        
        You can then build the docs with:
        
        ```sh
        cd docs   # relative to repository root
        make html
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Desktop Environment :: File Managers
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
