https://github.com/mfm-347/lightnamer
LightNamer is a CLI tool for renaming 100s of files in seconds.
https://github.com/mfm-347/lightnamer
automatic automation batch-file-renamer contributions-welcome mfm3478 opensource py-lib python renamer
Last synced: 9 months ago
JSON representation
LightNamer is a CLI tool for renaming 100s of files in seconds.
- Host: GitHub
- URL: https://github.com/mfm-347/lightnamer
- Owner: MFM-347
- License: mit
- Created: 2025-08-26T05:34:34.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-26T06:52:50.000Z (10 months ago)
- Last Synced: 2025-08-26T07:23:45.804Z (10 months ago)
- Topics: automatic, automation, batch-file-renamer, contributions-welcome, mfm3478, opensource, py-lib, python, renamer
- Language: Python
- Homepage: https://pypi.org/project/lightnamer/
- Size: 19.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# **LightNamer: CLI & Library for Auto Renaming** 🚀
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.
## **📌 Features**
| 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. |
## **🛠️ Prerequisites**
- **Python 3.x** installed
- Basic knowledge of **command-line usage**
### **📦 Required Python Packages**
LightNamer requires the following package(s):
- `pyfiglet` (for CLI banner text)
To install dependencies, run:
```sh
pip install -r requirements.txt # Use pip3 on macOS
```
## **⚡ Installation**
### **🔹 Install via Pip**
To install LightNamer as a library:
```sh
pip install lightnamer
```
### **🔹 Install from Source**
To install and run the tool from the source code:
```sh
git clone https://github.com/MFM-347/LightNamer.git
cd LightNamer
pip install .
```
## **💻 CLI Usage**
### **📌 Run the CLI**
```sh
lightnamer [-r ] [-s]
```
### **Example**
Rename files inside `C:\Users\YourName\Documents\Folder`, using "File" as the base name:
```sh
lightnamer "File" C:\Users\YourName\Documents\Folder
```
### **📂 Given Directory (`C:\Docs`)**
```
report.docx
notes.txt
summary.pdf
```
### **🏷️ Renaming Command**
```sh
lightnamer "Document" C:\Docs -r alphabet
```
### **📝 Output**
```
Document-1.docx
Document-2.pdf
Document-3.txt
```
## **⚙️ Command-Line Options**
| Option | Description |
| --------------------- | -------------------------------------------- |
| `` | Prefix for renamed files. |
| `` | Path to folder containing the files. |
| `-r, --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. |
## **📦 Using LightNamer as a Library**
### **🔹 Installed Library Usage**
If you have installed LightNamer via `pip`, you can use it in your Python scripts as follows:
```python
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)
```
### **🔹 Source Code Usage**
If running directly from the cloned source repository:
```python
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)
```
### **Sorting Files Only**
If you only need to **get sorted files** without renaming:
```python
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)
```
### **Handling Errors Gracefully**
You can wrap it in a try-except block:
```python
try:
renFn("Example", Path("/home/user/files"), "old", False, False)
except Exception as e:
print(f"An error occurred: {e}")
```
## **🧪 Running Tests (For Source Code Only)**
Run all tests:
```sh
python -m unittest discover tests
```
## Future Plans
- Add option to rename only specific file type.
- Add Graphic User Interface (GUI).
## **🤝 Contributing**
We welcome contributions! Please check the [CONTRIBUTING.md](https://github.com/MFM-347/LightNamer/blob/main/CONTRIBUTING.md) for guidelines.
## **👨💻 Credits**
Created and maintained by [MFM-347](https://github.com/MFM-347).
## **📜 License**
This project is licensed under the **MIT License**.
[](https://github.com/MFM-347/LightNamer/LICENSE)