LightNamer is a Python library and CLI tool designed to automate file renaming in a given directory. It sequentially renames files using a specified base name, appending a numeric index while preserving the original file extension.
| Feature | Availability | Description |
|---|---|---|
| Batch Rename | ✔ | Rename multiple files at once with a custom prefix. |
| Sorting Options | ✔ | Rename files in alphabetical, newest, or oldest order. |
| Simulation Mode | ✔ | Preview renaming changes without modifying files. No actual changes are made. |
| Library Support | ✔ | Use LightNamer as a module in your Python scripts for automation. |
| Cross-Platform | ✔ | Works seamlessly on Windows, macOS, and Linux. |
- Python 3.x installed
- Basic knowledge of command-line usage
LightNamer requires the following package(s):
pyfiglet(for CLI banner text)
To install dependencies, run:
pip install -r requirements.txt # Use pip3 on macOSTo install LightNamer as a library:
pip install lightnamerTo install and run the tool from the source code:
git clone https://github.com/MFM-347/LightNamer.git
cd LightNamer
pip install .lightnamer <base_name> <directory> [-r <order>] [-s]Rename files inside C:\Users\YourName\Documents\Folder, using "File" as the base name:
lightnamer "File" C:\Users\YourName\Documents\Folderreport.docx
notes.txt
summary.pdf
lightnamer "Document" C:\Docs -r alphabetDocument-1.docx
Document-2.pdf
Document-3.txt
| Option | Description |
|---|---|
<base_name> |
Prefix for renamed files. |
<directory> |
Path to folder containing the files. |
-r, --order <order> |
Sorting order before renaming: |
- alphabet → A-Z order |
|
- new → Newest to oldest |
|
- old → Oldest to newest (default) |
|
-s, --simulate |
Run a simulation without renaming files. |
--case-sensitive |
Sorts filenames in case-sensitive mode. |
--debug |
Enables debug logging. |
If you have installed LightNamer via pip, you can use it in your Python scripts as follows:
from lightnamer import renFn
from pathlib import Path
directory = Path("C:/Users/YourName/Documents/Folder")
renFn(base_name="Document", directory=directory, order="alphabet", simulate=False, case_sensitive=False)If running directly from the cloned source repository:
from lightnamer import renFn
from pathlib import Path
directory = Path("C:/Users/YourName/Documents/Folder")
renFn(base_name="Document", directory=directory, order="alphabet", simulate=False, case_sensitive=False)If you only need to get sorted files without renaming:
from lightnamer import sortFn
from pathlib import Path
directory = Path("/path/to/files")
sorted_files = sortFn(directory, order="new", case_sensitive=True)
print(sorted_files)You can wrap it in a try-except block:
try:
renFn("Example", Path("/home/user/files"), "old", False, False)
except Exception as e:
print(f"An error occurred: {e}")Run all tests:
python -m unittest discover tests- Add option to rename only specific file type.
- Add Graphic User Interface (GUI).
We welcome contributions! Please check the CONTRIBUTING.md for guidelines.
Created and maintained by MFM-347.
This project is licensed under the MIT License.