# Path-Friendly Filename Generator
[](https://pypi.org/project/path-friendly-filename-generator/)
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Detailed Usage](#detailed-usage)
- [Making Filenames Safe](#making-filenames-safe)
- [Validating Filenames](#validating-filenames)
- [Handling Reserved Names](#handling-reserved-names)
- [Customizing Replacement Characters](#customizing-replacement-characters)
- [Examples](#examples)
- [API Reference](#api-reference)
- [Advanced Configuration](#advanced-configuration)
- [Testing](#testing)
- [Running Unit Tests](#running-unit-tests)
- [Using pytest](#using-pytest)
- [Continuous Integration](#continuous-integration)
- [Contributing](#contributing)
- [Guidelines](#guidelines)
- [Code of Conduct](#code-of-conduct)
- [Changelog](#changelog)
- [License](#license)
- [Contact](#contact)
- [Acknowledgements](#acknowledgements)
## Overview
**Path-Friendly Filename Generator** is a robust Python package crafted to ensure that filenames are safe, valid, and compliant across various operating systems. Whether you're developing cross-platform applications, managing file systems, or automating file operations, this tool streamlines the process by automatically sanitizing filenames, removing or replacing invalid characters, and adhering to OS-specific file system rules. It is an indispensable utility for developers, system administrators, and anyone engaged in file management tasks across multiple platforms.
## Features
- **Cross-Platform Compatibility:** Seamlessly handles filename rules for Windows, Linux, macOS, and other Unix-like systems.
- **Invalid Character Replacement:** Automatically detects and replaces or removes characters that are invalid in filenames.
- **Reserved Name Handling:** Identifies and modifies reserved filenames (e.g., `CON`, `PRN` on Windows) to prevent conflicts.
- **Filename Length Trimming:** Ensures filenames do not exceed the maximum allowed length for the target operating system.
- **Customizable Replacement Characters:** Offers flexibility to specify custom characters for replacing invalid characters.
- **Validation Utilities:** Provides comprehensive functions to validate filenames without altering them.
- **Legacy Windows Support:** Optionally trims filenames to comply with legacy Windows 8.3 filename conventions.
- **Unicode Support:** Effectively handles filenames with Unicode characters, ensuring broad compatibility.
- **Extensible Configuration:** Allows advanced users to modify default settings through configuration classes.
## Installation
Installing the **Path-Friendly Filename Generator** is straightforward. You can choose between installing via [PyPI](https://pypi.org/) or directly from the source repository on GitHub.
### Using pip (Recommended)
Install the package using `pip`:
```bash
pip install path-friendly-filename-generator
```
### From Source
Alternatively, install the package directly from the GitHub repository:
```bash
git clone https://github.com/greenstorm5417/path-friendly-filename-generator.git
cd path-friendly-filename-generator
pip install -e .
```
## Quick Start
After installation, you can quickly start using the package to sanitize filenames.
```python
from path_friendly_filename_generator import make_filename_safe
original_filename = 'example<filename>:with*invalid|chars?.txt'
safe_filename = make_filename_safe(original_filename)
print(f"Original: {original_filename}")
print(f"Safe: {safe_filename}")
```
**Output:**
```
Original: example<filename>:with*invalid|chars?.txt
Safe: example_filename__with_invalid_chars_.txt
```
## Detailed Usage
### Making Filenames Safe
The primary function, `make_filename_safe`, sanitizes filenames by removing or replacing invalid characters and ensuring compliance with the target OS's rules.
```python
from path_friendly_filename_generator import make_filename_safe
original = 'report<>:"/\|?*.pdf'
safe = make_filename_safe(original)
print(safe) # Output: report________.pdf
```
### Validating Filenames
Before sanitizing, you might want to check if a filename is already valid using the `is_valid_filename` function.
```python
from path_friendly_filename_generator import is_valid_filename
filename = 'valid_filename.txt'
is_valid = is_valid_filename(filename)
print(f"Is '{filename}' a valid filename? {'Yes' if is_valid else 'No'}")
```
### Handling Reserved Names
Certain filenames are reserved by operating systems (e.g., `CON`, `PRN` on Windows). The generator detects these and modifies them to prevent conflicts.
```python
from path_friendly_filename_generator import make_filename_safe
original = 'CON.txt'
safe = make_filename_safe(original)
print(safe) # Output: CON_reserved.txt
```
### Customizing Replacement Characters
You can specify your own replacement character instead of the default underscore (`_`).
```python
from path_friendly_filename_generator import make_filename_safe
original = 'data*analysis?.csv'
safe = make_filename_safe(original, replacement_char='-')
print(safe) # Output: data-analysis-.csv
```
## Testing
Ensuring the reliability and stability of the **Path-Friendly Filename Generator** is paramount. A comprehensive test suite has been developed using Python's built-in `unittest` framework and `pytest` for enhanced testing capabilities.
### Running Unit Tests
To run the unit tests:
1. **Clone the Repository (if not already done):**
```bash
git clone https://github.com/greenstorm5417/path-friendly-filename-generator.git
cd path-friendly-filename-generator
```
2. **Create and Activate a Virtual Environment (Optional but Recommended):**
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scriptsctivate
```
3. **Install Dependencies:**
```bash
pip install -e .
```
4. **Run the Test Suite:**
```bash
python -m unittest discover -s tests
```
**Expected Output:**
```
......................
----------------------------------------------------------------------
Ran 22 tests in 0.456s
OK
```
### License
This project is licensed under the [MIT License](LICENSE). You are free to use, modify, and distribute this software as per the license terms.
## Contact
**Sammy**
Email: [dussinsa01@esj.org](mailto:dussinsa01@esj.org)
GitHub: [greenstorm5417](https://github.com/greenstorm5417)
For any inquiries, feature requests, or support, feel free to reach out via email or open an issue on the [GitHub repository](https://github.com/greenstorm5417/path-friendly-filename-generator).
Raw data
{
"_id": null,
"home_page": "https://github.com/greenstorm5417/path-friendly-filename-generator",
"name": "path-friendly-filename-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "filename, generator, path-friendly, cross-platform",
"author": "Sammy",
"author_email": "Sammy <dussinsa01@esj.org>",
"download_url": "https://files.pythonhosted.org/packages/a7/52/364e2c621683c8620566641cc77082ba91d25b0fdde2f217bcea4d8c34d6/path_friendly_filename_generator-0.1.2.tar.gz",
"platform": null,
"description": "\r\n# Path-Friendly Filename Generator\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n[](https://pypi.org/project/path-friendly-filename-generator/)\r\n\r\n## Table of Contents\r\n\r\n- [Overview](#overview)\r\n- [Features](#features)\r\n- [Installation](#installation)\r\n- [Quick Start](#quick-start)\r\n- [Detailed Usage](#detailed-usage)\r\n - [Making Filenames Safe](#making-filenames-safe)\r\n - [Validating Filenames](#validating-filenames)\r\n - [Handling Reserved Names](#handling-reserved-names)\r\n - [Customizing Replacement Characters](#customizing-replacement-characters)\r\n- [Examples](#examples)\r\n- [API Reference](#api-reference)\r\n- [Advanced Configuration](#advanced-configuration)\r\n- [Testing](#testing)\r\n - [Running Unit Tests](#running-unit-tests)\r\n - [Using pytest](#using-pytest)\r\n- [Continuous Integration](#continuous-integration)\r\n- [Contributing](#contributing)\r\n - [Guidelines](#guidelines)\r\n - [Code of Conduct](#code-of-conduct)\r\n- [Changelog](#changelog)\r\n- [License](#license)\r\n- [Contact](#contact)\r\n- [Acknowledgements](#acknowledgements)\r\n\r\n## Overview\r\n\r\n**Path-Friendly Filename Generator** is a robust Python package crafted to ensure that filenames are safe, valid, and compliant across various operating systems. Whether you're developing cross-platform applications, managing file systems, or automating file operations, this tool streamlines the process by automatically sanitizing filenames, removing or replacing invalid characters, and adhering to OS-specific file system rules. It is an indispensable utility for developers, system administrators, and anyone engaged in file management tasks across multiple platforms.\r\n\r\n\r\n## Features\r\n\r\n- **Cross-Platform Compatibility:** Seamlessly handles filename rules for Windows, Linux, macOS, and other Unix-like systems.\r\n- **Invalid Character Replacement:** Automatically detects and replaces or removes characters that are invalid in filenames.\r\n- **Reserved Name Handling:** Identifies and modifies reserved filenames (e.g., `CON`, `PRN` on Windows) to prevent conflicts.\r\n- **Filename Length Trimming:** Ensures filenames do not exceed the maximum allowed length for the target operating system.\r\n- **Customizable Replacement Characters:** Offers flexibility to specify custom characters for replacing invalid characters.\r\n- **Validation Utilities:** Provides comprehensive functions to validate filenames without altering them.\r\n- **Legacy Windows Support:** Optionally trims filenames to comply with legacy Windows 8.3 filename conventions.\r\n- **Unicode Support:** Effectively handles filenames with Unicode characters, ensuring broad compatibility.\r\n- **Extensible Configuration:** Allows advanced users to modify default settings through configuration classes.\r\n\r\n## Installation\r\n\r\nInstalling the **Path-Friendly Filename Generator** is straightforward. You can choose between installing via [PyPI](https://pypi.org/) or directly from the source repository on GitHub.\r\n\r\n### Using pip (Recommended)\r\n\r\nInstall the package using `pip`:\r\n\r\n```bash\r\npip install path-friendly-filename-generator\r\n```\r\n\r\n### From Source\r\n\r\nAlternatively, install the package directly from the GitHub repository:\r\n\r\n```bash\r\ngit clone https://github.com/greenstorm5417/path-friendly-filename-generator.git\r\ncd path-friendly-filename-generator\r\npip install -e .\r\n```\r\n\r\n## Quick Start\r\n\r\nAfter installation, you can quickly start using the package to sanitize filenames.\r\n\r\n```python\r\nfrom path_friendly_filename_generator import make_filename_safe\r\n\r\noriginal_filename = 'example<filename>:with*invalid|chars?.txt'\r\nsafe_filename = make_filename_safe(original_filename)\r\n\r\nprint(f\"Original: {original_filename}\")\r\nprint(f\"Safe: {safe_filename}\")\r\n```\r\n\r\n**Output:**\r\n\r\n```\r\nOriginal: example<filename>:with*invalid|chars?.txt\r\nSafe: example_filename__with_invalid_chars_.txt\r\n```\r\n\r\n## Detailed Usage\r\n\r\n### Making Filenames Safe\r\n\r\nThe primary function, `make_filename_safe`, sanitizes filenames by removing or replacing invalid characters and ensuring compliance with the target OS's rules.\r\n\r\n```python\r\nfrom path_friendly_filename_generator import make_filename_safe\r\n\r\noriginal = 'report<>:\"/\\|?*.pdf'\r\nsafe = make_filename_safe(original)\r\n\r\nprint(safe) # Output: report________.pdf\r\n```\r\n\r\n### Validating Filenames\r\n\r\nBefore sanitizing, you might want to check if a filename is already valid using the `is_valid_filename` function.\r\n\r\n```python\r\nfrom path_friendly_filename_generator import is_valid_filename\r\n\r\nfilename = 'valid_filename.txt'\r\nis_valid = is_valid_filename(filename)\r\n\r\nprint(f\"Is '{filename}' a valid filename? {'Yes' if is_valid else 'No'}\")\r\n```\r\n\r\n\r\n### Handling Reserved Names\r\n\r\nCertain filenames are reserved by operating systems (e.g., `CON`, `PRN` on Windows). The generator detects these and modifies them to prevent conflicts.\r\n\r\n```python\r\nfrom path_friendly_filename_generator import make_filename_safe\r\n\r\noriginal = 'CON.txt'\r\nsafe = make_filename_safe(original)\r\n\r\nprint(safe) # Output: CON_reserved.txt\r\n```\r\n\r\n### Customizing Replacement Characters\r\n\r\nYou can specify your own replacement character instead of the default underscore (`_`).\r\n\r\n```python\r\nfrom path_friendly_filename_generator import make_filename_safe\r\n\r\noriginal = 'data*analysis?.csv'\r\nsafe = make_filename_safe(original, replacement_char='-')\r\n\r\nprint(safe) # Output: data-analysis-.csv\r\n```\r\n\r\n## Testing\r\n\r\nEnsuring the reliability and stability of the **Path-Friendly Filename Generator** is paramount. A comprehensive test suite has been developed using Python's built-in `unittest` framework and `pytest` for enhanced testing capabilities.\r\n\r\n### Running Unit Tests\r\n\r\nTo run the unit tests:\r\n\r\n1. **Clone the Repository (if not already done):**\r\n\r\n ```bash\r\n git clone https://github.com/greenstorm5417/path-friendly-filename-generator.git\r\n cd path-friendly-filename-generator\r\n ```\r\n\r\n2. **Create and Activate a Virtual Environment (Optional but Recommended):**\r\n\r\n ```bash\r\n python -m venv venv\r\n source venv/bin/activate # On Windows: venv\\Scripts\u0007ctivate\r\n ```\r\n\r\n3. **Install Dependencies:**\r\n\r\n ```bash\r\n pip install -e .\r\n ```\r\n\r\n4. **Run the Test Suite:**\r\n\r\n ```bash\r\n python -m unittest discover -s tests\r\n ```\r\n\r\n **Expected Output:**\r\n\r\n ```\r\n ......................\r\n ----------------------------------------------------------------------\r\n Ran 22 tests in 0.456s\r\n\r\n OK\r\n ```\r\n\r\n### License\r\n\r\nThis project is licensed under the [MIT License](LICENSE). You are free to use, modify, and distribute this software as per the license terms.\r\n\r\n## Contact\r\n\r\n**Sammy** \r\nEmail: [dussinsa01@esj.org](mailto:dussinsa01@esj.org) \r\nGitHub: [greenstorm5417](https://github.com/greenstorm5417)\r\n\r\nFor any inquiries, feature requests, or support, feel free to reach out via email or open an issue on the [GitHub repository](https://github.com/greenstorm5417/path-friendly-filename-generator).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package to generate path-friendly filenames across different operating systems.",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/greenstorm5417/path-friendly-filename-generator",
"Homepage": "https://github.com/greenstorm5417/path-friendly-filename-generator",
"Source Code": "https://github.com/greenstorm5417/path-friendly-filename-generator"
},
"split_keywords": [
"filename",
" generator",
" path-friendly",
" cross-platform"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "89841460338f31ed51c3603a37f3c56daa513161d9674ee19ebe00c91d3b31e7",
"md5": "acd7bcdefd7fc7071c8f99a15b1f077f",
"sha256": "bd2d25798e157b96905ceee4882681d4953cd0696456b9dbaa115f4fad441ec5"
},
"downloads": -1,
"filename": "path_friendly_filename_generator-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acd7bcdefd7fc7071c8f99a15b1f077f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 4940,
"upload_time": "2024-10-29T01:56:28",
"upload_time_iso_8601": "2024-10-29T01:56:28.778999Z",
"url": "https://files.pythonhosted.org/packages/89/84/1460338f31ed51c3603a37f3c56daa513161d9674ee19ebe00c91d3b31e7/path_friendly_filename_generator-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a752364e2c621683c8620566641cc77082ba91d25b0fdde2f217bcea4d8c34d6",
"md5": "7a1289cafbfb2f4a3f08d236845e6ab6",
"sha256": "cc6f2cf69dc40e1d8cbbbe2075f40ad1284574cd2d537db1d22a992899350101"
},
"downloads": -1,
"filename": "path_friendly_filename_generator-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7a1289cafbfb2f4a3f08d236845e6ab6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7134,
"upload_time": "2024-10-29T01:56:29",
"upload_time_iso_8601": "2024-10-29T01:56:29.746382Z",
"url": "https://files.pythonhosted.org/packages/a7/52/364e2c621683c8620566641cc77082ba91d25b0fdde2f217bcea4d8c34d6/path_friendly_filename_generator-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-29 01:56:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "greenstorm5417",
"github_project": "path-friendly-filename-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "path-friendly-filename-generator"
}
JSON
