jedburke / lemony

A simple Python script used to rename files in a directory with regular expressions.

Abandon all hope, ye who enter here

This script is still in its infancy and is therefore subject to breaking or not doing what it's been intended to do.

Introduction

Lemony is a simple batch file renaming script written in Python 3.6. Its goal is to allow users to rename their files using regular expressions.

Getting Started

For now, clone / download the repo and run main.py with Python. As mentioned earlier, the script has been written targetting Python version 3.6.

Usage

The following is an incomplete guide for using the script. Please refer to the Wiki for more.

Replace lemony.py in the examples with main.py. The final entry-point is subject to change.

Basic

> lemony.py rename "path/to/files" --match "_+" --replace " "

What that does is rename all files in the specified directory, replacing the underscores (_) with a single space.

Dry run

It's a good idea to test your replacement before it happens. Use the --dry-run flag or its shortened form -n for this.

Multiple directories

To supply multiple directories, separate them with the semi-colon (;) character.

> lemony.py rename "path/to/directory;path/to/ecchi/pictures" -m "_" -r " "

Extensions & Exclusions

You have a directory with multiple file types and don't want to apply the replacement on all of them. Use the --ext option to include the file types to be renamed. To keep it simple, we're using the semi-colon to separate the files extensions. Notice the comma.

> lemony.py rename "path" --ext "txt;srt,ass"

In the case where you wish to allow all but exclude some, you'll use the --blacklist flag. All files will be processed except for those mention in the --ext argument.

Profiles

The main reason why the script exists as it does now is to be able to reuse for other renaming purposes.

"I may need to replace the underscores again, but I may need to replace other characters or do advanced text manipulation too." That was the thought I had and the reason why it is more than just a one-off script.

Simply put, profiles allow you to store and invoke commonly used operations. The profiles are contained in a JSON document under the name profiles.json in the main directory.

Here is an example of the profile structure:

{
    "_2s": {
        "match" : "_",
        "replace": " ",
        "whitelist": true
    }
}

The profile stated in the above section matches the replacement operation performed earlier.

Invoke as such:

> lemony.py rename "path/to/files" --profile _2s

You may also store a separate profile.json file in "~/.lemony" / "%HOMEPATH%.lemony". The values from the local file will override those of the main one.

https://github.com/JedBurke/Lemony/wiki/Profiles

Need to know more?

At this point in time, the script itself is better friend in knowing how to use it.

> lemony.py --help

Future

I originally wrote this script in Python because I wanted to get into Python having failed to see the appeal several times. Please keep in mind that it is shoddily written with below-novice proficiency in Python. Ideally, I'd like to fix the shoddy bits and make the script more robust.

Check issues with the "Quality of Life" label for more.

Bugs

While I am only able to test on Windows, I would appreciate any bug reports if it doesn't work as expected.

If you have any feature suggestions, please feel free to create an issue for one using the 'new feature' or 'enhancement' label.

lemony's Issues

Document code and functions

Document all new and existing classes and functions.

Move end-user documentation to wiki

Remove clutter from the readme file by moving all but the bare essential commands and particulars to the wiki. New users should get a feel for the project and the way it goes about things without being overwhelmed with all of its details.

Allow a single path or extension to be set as a string literal instead of an array

When setting the directory in the profile, users should have the choice to set the directory as a string literal and not an array.

Current

    directory: ["path/to/ecchi/pics"]

Proposed:

    directory: "path/to/ecchi/pics"

The same will go for extensions and everything else which accepts an array which the user supplies and may only have one element. Being able to pass an array of directories and file extensions will obviously remain, however the user will not be forced into specifying them when unnecessary.

Implement content filters

Doing so will allow for plugins or other methods to short-circuit the renaming. For example, a liquid-style syntax could be implemented and be decoupled from the main renaming methods.

Employ unit testing

Write and document unit tests for each of the existing classes.

Decouple arguments

Restructure Lemony's arguments (rename etc) into plug-ins which load when it starts. Doing so will allow arguments to be added or removed in a simpler manner without affecting the core of the project.

Conform to coding conventions

Make sure new and existing code conforms to Python coding conventions, specifically PEP8.

Introduce directory globbing

Allow users to specify directories with globbing syntax.

> lemony "path/to/ecchi/**/*"

Result:
path/to/ecchi/pics/{files}
path/to/ecchi/vids/{files}

Revoke rename

As safety is imperative, Lemony could keep track of the files it renames in the event the user incorrectly renames a set of files. With the list of files it renamed and their original names, the script will be able to 'revoke' the rename.

The data may be stored in a JSON formatted document for perpetual use. Size may however become an issue as the script is used. As with logs, the renaming history may be split into days and cleared after X days. While not necessarily for users, the structure of the file itself needs to be simple and uncluttered.

Consider:
> lemony rename "path/to/ecchi/pictures" --revoke

A switch called revoke is added to the rename subparser. The files in the directory passed will be queried against the history file and renamed accordingly.

The dry run switch must be available. Being able to specify which files rename are to be revoked should be present as well.

> lemony revoke "path/to/ecchi/pictures/" --file "best_ecchi_pic.jpg;second_best_ecchi_pic.jpg" --prompt

In this example, revoke becomes a subparser as apposed to a switch on the rename subparser. It accepts a directory like rename. If the file argument is omitted, all files are processed. The names specified in file are the current names. The prompt switch presents a [Y/N] option for each reversion.

The idea is still squishy, so the implementation may be a little ways away.

Move all renaming arguments to 'rename' sub-parser

The switches currently related to the rename operation must be moved to the "rename" sub-parser.

Current way:

lemony "path/to/ecchi/pics"

New way:

lemony rename "/path/to/ecchi/pics"

Doing so will allow for opportunities at larger functionality without cluttering the parser with options.

Migrate code to the Object-Orientated paradigm

Modularize the code into components which may be easily tested and re-used.

Employ passive logging

Log the function calls to better understand went wrong with the script and caused unexpected behavior. If possible, the logs need to be simple for non-technical users to be able to read and understand it themselves, yet provide enough information and to be useful to technical user.