# **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 <base_name> <directory> [-r <order>] [-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 |
| --------------------- | -------------------------------------------- |
| `<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. |
## **📦 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)
Raw data
{
"_id": null,
"home_page": null,
"name": "lightnamer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "renamer, cli, auto, automation, automatic, python, opensource",
"author": null,
"author_email": "Farhan Madni <madnifm347@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/31/01/e079cde2ffbfe7884d31545e290cb38527c627f0f78bfc2402f8cf9a8a01/lightnamer-1.0.0.tar.gz",
"platform": null,
"description": "# **LightNamer: CLI & Library for Auto Renaming** \ud83d\ude80\r\n\r\nLightNamer 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.\r\n\r\n## **\ud83d\udccc Features**\r\n\r\n| Feature | Availability | Description |\r\n| ------------------- | ------------ | ----------------------------------------------------------------------------- |\r\n| **Batch Rename** | \u2714 | Rename multiple files at once with a custom prefix. |\r\n| **Sorting Options** | \u2714 | Rename files in alphabetical, newest, or oldest order. |\r\n| **Simulation Mode** | \u2714 | Preview renaming changes without modifying files. No actual changes are made. |\r\n| **Library Support** | \u2714 | Use LightNamer as a module in your Python scripts for automation. |\r\n| **Cross-Platform** | \u2714 | Works seamlessly on Windows, macOS, and Linux. |\r\n\r\n## **\ud83d\udee0\ufe0f Prerequisites**\r\n\r\n- **Python 3.x** installed\r\n- Basic knowledge of **command-line usage**\r\n\r\n### **\ud83d\udce6 Required Python Packages**\r\n\r\nLightNamer requires the following package(s):\r\n\r\n- `pyfiglet` (for CLI banner text)\r\n\r\nTo install dependencies, run:\r\n\r\n```sh\r\npip install -r requirements.txt # Use pip3 on macOS\r\n```\r\n\r\n## **\u26a1 Installation**\r\n\r\n### **\ud83d\udd39 Install via Pip**\r\n\r\nTo install LightNamer as a library:\r\n\r\n```sh\r\npip install lightnamer\r\n```\r\n\r\n### **\ud83d\udd39 Install from Source**\r\n\r\nTo install and run the tool from the source code:\r\n\r\n```sh\r\ngit clone https://github.com/MFM-347/LightNamer.git\r\ncd LightNamer\r\npip install .\r\n```\r\n\r\n## **\ud83d\udcbb CLI Usage**\r\n\r\n### **\ud83d\udccc Run the CLI**\r\n\r\n```sh\r\nlightnamer <base_name> <directory> [-r <order>] [-s]\r\n```\r\n\r\n### **Example**\r\n\r\nRename files inside `C:\\Users\\YourName\\Documents\\Folder`, using \"File\" as the base name:\r\n\r\n```sh\r\nlightnamer \"File\" C:\\Users\\YourName\\Documents\\Folder\r\n```\r\n\r\n### **\ud83d\udcc2 Given Directory (`C:\\Docs`)**\r\n\r\n```\r\nreport.docx\r\nnotes.txt\r\nsummary.pdf\r\n```\r\n\r\n### **\ud83c\udff7\ufe0f Renaming Command**\r\n\r\n```sh\r\nlightnamer \"Document\" C:\\Docs -r alphabet\r\n```\r\n\r\n### **\ud83d\udcdd Output**\r\n\r\n```\r\nDocument-1.docx\r\nDocument-2.pdf\r\nDocument-3.txt\r\n```\r\n\r\n## **\u2699\ufe0f Command-Line Options**\r\n\r\n| Option | Description |\r\n| --------------------- | -------------------------------------------- |\r\n| `<base_name>` | Prefix for renamed files. |\r\n| `<directory>` | Path to folder containing the files. |\r\n| `-r, --order <order>` | Sorting order before renaming: |\r\n| | - `alphabet` \u2192 A-Z order |\r\n| | - `new` \u2192 Newest to oldest |\r\n| | - `old` \u2192 Oldest to newest (default) |\r\n| `-s, --simulate` | Run a **simulation** without renaming files. |\r\n| `--case-sensitive` | Sorts filenames in case-sensitive mode. |\r\n| `--debug` | Enables debug logging. |\r\n\r\n## **\ud83d\udce6 Using LightNamer as a Library**\r\n\r\n### **\ud83d\udd39 Installed Library Usage**\r\n\r\nIf you have installed LightNamer via `pip`, you can use it in your Python scripts as follows:\r\n\r\n```python\r\nfrom lightnamer import renFn\r\nfrom pathlib import Path\r\n\r\ndirectory = Path(\"C:/Users/YourName/Documents/Folder\")\r\nrenFn(base_name=\"Document\", directory=directory, order=\"alphabet\", simulate=False, case_sensitive=False)\r\n```\r\n\r\n### **\ud83d\udd39 Source Code Usage**\r\n\r\nIf running directly from the cloned source repository:\r\n\r\n```python\r\nfrom lightnamer import renFn\r\nfrom pathlib import Path\r\n\r\ndirectory = Path(\"C:/Users/YourName/Documents/Folder\")\r\nrenFn(base_name=\"Document\", directory=directory, order=\"alphabet\", simulate=False, case_sensitive=False)\r\n```\r\n\r\n### **Sorting Files Only**\r\n\r\nIf you only need to **get sorted files** without renaming:\r\n\r\n```python\r\nfrom lightnamer import sortFn\r\nfrom pathlib import Path\r\n\r\ndirectory = Path(\"/path/to/files\")\r\nsorted_files = sortFn(directory, order=\"new\", case_sensitive=True)\r\nprint(sorted_files)\r\n```\r\n\r\n### **Handling Errors Gracefully**\r\n\r\nYou can wrap it in a try-except block:\r\n\r\n```python\r\ntry:\r\n renFn(\"Example\", Path(\"/home/user/files\"), \"old\", False, False)\r\nexcept Exception as e:\r\n print(f\"An error occurred: {e}\")\r\n```\r\n\r\n## **\ud83e\uddea Running Tests (For Source Code Only)**\r\n\r\nRun all tests:\r\n\r\n```sh\r\npython -m unittest discover tests\r\n```\r\n\r\n## Future Plans\r\n\r\n- Add option to rename only specific file type.\r\n- Add Graphic User Interface (GUI).\r\n\r\n## **\ud83e\udd1d Contributing**\r\n\r\nWe welcome contributions! Please check the [CONTRIBUTING.md](https://github.com/MFM-347/LightNamer/blob/main/CONTRIBUTING.md) for guidelines.\r\n\r\n## **\ud83d\udc68\u200d\ud83d\udcbb Credits**\r\n\r\nCreated and maintained by [MFM-347](https://github.com/MFM-347).\r\n\r\n## **\ud83d\udcdc License**\r\n\r\nThis project is licensed under the **MIT License**.\r\n\r\n[](https://github.com/MFM-347/LightNamer/LICENSE)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "LightNamer is a CLI tool for renaming 100s of files in seconds.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/MFM-347/LightNamer"
},
"split_keywords": [
"renamer",
" cli",
" auto",
" automation",
" automatic",
" python",
" opensource"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "29a72ebcfd653961e288de901626afd650e957ba42fb4beb1d206e516ae62a3d",
"md5": "8b2164fe6716063a65df49102ad9d4cf",
"sha256": "e2b664b1ccbe665c94c881a0a8bd524b3113b7799d7253c8e42362e330a8a62a"
},
"downloads": -1,
"filename": "lightnamer-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b2164fe6716063a65df49102ad9d4cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6260,
"upload_time": "2025-08-26T06:42:19",
"upload_time_iso_8601": "2025-08-26T06:42:19.717677Z",
"url": "https://files.pythonhosted.org/packages/29/a7/2ebcfd653961e288de901626afd650e957ba42fb4beb1d206e516ae62a3d/lightnamer-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3101e079cde2ffbfe7884d31545e290cb38527c627f0f78bfc2402f8cf9a8a01",
"md5": "a5fd1ed22cf744cfcfbd2fd90f1f8921",
"sha256": "7719fd679178971eaad0916bf067f83d7327b24ef96a8114e8d7af748c9c9f55"
},
"downloads": -1,
"filename": "lightnamer-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a5fd1ed22cf744cfcfbd2fd90f1f8921",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6086,
"upload_time": "2025-08-26T06:42:21",
"upload_time_iso_8601": "2025-08-26T06:42:21.795635Z",
"url": "https://files.pythonhosted.org/packages/31/01/e079cde2ffbfe7884d31545e290cb38527c627f0f78bfc2402f8cf9a8a01/lightnamer-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 06:42:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MFM-347",
"github_project": "LightNamer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lightnamer"
}
JSON
