Tempren - template-based file renaming utility

run-tests

tempren is a powerful batch file renamer that can generate filenames based on flexible template expressions. It can create new or process existing filenames or sort files into directories based on their attributes (metadata).

This project is currently in a Work-In-Progress stage so if you are looking for working solution... keep looking.

Features

Template-based filename/path generation
Configurable file selection (filtering)
Metadata-based sorting

Quickstart (5 minutes required)

People don't have to rename massive amounts of files very often and learning new software just to solve the problem you are facing sporadically might be daunting.

This quickstart is meant to introduce you to the tempren and give you enough information to make sure it is up to the task you are facing. You will need around 5 minutes total to work through it.

For more comprehensive documentation please refer to the manual.

Install

$ pip install [--user] tempren

Usage

Note: When playing with tempren make sure to use --dry-run (-d) flag so that the actual files are not accidentally changed.

Tempren have two main modes of operation: name and path.

In the name mode (default, enabled by -n, --name flag), the template is used for filename generation only. This is useful if you want to operate on files specified on the command line or in a single directory.

With path mode (enabled by -p, --path flag), the template generates a whole path (relative to the input directory). This way you can sort files into dynamically generated catalogues.

Template syntax

Tag template consists of raw text interleaved with tag invocations. Each tag invocation starts with % (percent) character followed by tag name, tag configuration (argument) list (enclosed in () parentheses) and - optionally - tag context (enclosed in {} parentheses). Consider following template:

File_%Count(start=100).%Lower(){%Ext()}

Above expression can be split into:

Raw text File_
Count tag configured with start parameter set to 100
Raw text .
Lower tag (with empty configuration list) operating on context rendered from:
- Ext tag

Note: You can use --list-tags flag to print tag names provided by your tempren version.

When used withing tempren:

$ tempren -d "File_%Count(start=100).%Lower(){%Ext()}" test_directory/

One may expect results as:

Input name	Output name
test.sh	File_100.sh
img1.jpg	File_101.jpg
IMG_1414.jpg	File_102.jpg
document.pdf	File_102.pdf

Tag configuration

Pipe list sugar

Name mode

Path mode

Filtering

To select which files should be considered for processing one can use filtering predicate.

There are three types of a filtering expressions supported (by -ft, --filter-type option):

glob (default) - filename globbing expression, eg: *.mp3, IMG_????.jpg
regex - python-flavored regex, eg: .*\.jpe?g
template - tag-template evaluated python expression, eg: %Size() > 10*1024

Sometimes it might be easier to specify filter for files which should not be included. To negate/invert filtering expression you can use -fi, --filter-invert flag.

Glob filtering

Regex filtering

Template filtering

Case sensitiveness and filter inversion

TODO: IMPLEMENT

By default, glob and regex filtering expressions will match case-sensitive. To allow case-insensitive matching use -fc, --filter-case flag.

template filter isn't affected by case-sensitivity flag - you will have to make use of str.upper or str.lower python methods to simulate that.

Sorting

Contribution

Minimal Python version supported is 3.7, so you should make sure that you have it installed on your system. You can use pyenv for that:

$ pyenv shell 3.7.10

After cloning repo you should install poetry as it is used for dependency resolution and packaging:

$ pip install [--user] poetry

It is good to use separate virtualenv for development, poetry can spawn one:

# Make sure that your `python --version` is at least 3.7 before this step
$ poetry shell

Now you can install required packages (specified in pyproject.toml) via:

$ poetry install

Code conventions are enforced via pre-commit. It is listed in development depenencies so if you are able to run tests - you should have it installed too. To get started you will still need to install git hooks:

$ pre-commit install

Now every time you invoke git commit a series of cleanup scripts will run and modify your patchset.

Testing

Tests are written with a help of pytest. Just enter repository root and run:

$ pytest

mypy on the other hand takes care of static analysis - it can catch early type-related errors:

$ mypy

TODO: Tags development

Metadata

Release files for tempren 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tempren 0.4.2
File	Size	Uploaded
tempren-0.4.2.tar.gz	46.3 kB	Jul 21, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for tempren 0.4.2
File	Interpreter	ABI	Platform	Reset
tempren-0.4.2-py3-none-any.whl 52.6 kB Jul 21, 2022	Python 3	none	any	Details

Total release size: 99.0 kB

Release files / tempren-0.4.2.tar.gz

Download URL	tempren-0.4.2.tar.gz
Size	46.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`48bc896a4ea0cfbdbf981752851fa6cdc79adfa49ec2142dbfeb8a469692b0c6`
BLAKE2b-256 checksum How to use checksums	`f3503fecac03e8169fe80799d972455321dc1e1b50031bc6a5c6ea5565a30d8c`
Upload date	Jul 21, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.1.14 CPython/3.10.2 Linux/5.15.0-1014-azure`

Release files / tempren-0.4.2-py3-none-any.whl

Download URL	tempren-0.4.2-py3-none-any.whl
Size	52.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`efbd65b56e3617b63457aca60edc4decf757b7788126eec00669e0a4bfcf1800`
BLAKE2b-256 checksum How to use checksums	`0147f276fb62423cc3f4bd54ce44259bdcf6fd7ef21e7c3c92e97db189432883`
Upload date	Jul 21, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.1.14 CPython/3.10.2 Linux/5.15.0-1014-azure`