| Name | ALT-file-utils JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Robust file I/O utilities with atomic writes, retries, and comprehensive error handling |
| upload_time | 2025-09-08 07:20:19 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
file
io
atomic
write
utilities
yaml
json
toml
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ALT-file-utils
[](https://badge.fury.io/py/ALT-file-utils)
[](https://pypi.org/project/ALT-file-utils/)
[](https://opensource.org/licenses/MIT)
Robust file I/O utilities for Python with atomic writes, retries, and comprehensive error handling.
## Features
- 🔒 **Atomic file writes** - Prevents corruption by writing to temp files and atomically replacing
- 🔄 **Automatic retries** - Configurable retry logic for transient failures
- 🛡️ **Comprehensive error handling** - Detailed exceptions for different failure modes
- 📁 **Safe file operations** - Read, write, copy, delete with proper error handling
- 🔧 **Multiple format support** - JSON, YAML, TOML with safe loading/dumping
- 🌐 **Cross-platform** - Works on Windows, macOS, and Linux
- 🐍 **Type hints** - Full typing support for better IDE integration
## Installation
```bash
pip install ALT-file-utils
```
For TOML support on Python < 3.11:
```bash
pip install "ALT-file-utils[toml]"
```
## Quick Start
### Atomic File Writing
```python
from alt_file_utils import atomic_write
# Write text file atomically
with atomic_write('output.txt') as f:
f.write('Hello, World!')
# File is written to a temporary location
# On successful completion, file is atomically moved to 'output.txt'
# On exception, temporary file is cleaned up automatically
```
### Safe JSON Operations
```python
from alt_file_utils import safe_json_dump, safe_json_load
# Write JSON safely with atomic write
data = {'name': 'example', 'value': 42}
safe_json_dump(data, 'data.json', indent=2)
# Read JSON with error handling
loaded_data = safe_json_load('data.json')
```
### Retry Mechanism
```python
from alt_file_utils import retry_on_failure
import time
@retry_on_failure(max_attempts=3, delay=1.0)
def flaky_file_operation():
# This will retry up to 3 times with 1 second delay
with open('important.txt', 'r') as f:
return f.read()
```
### Safe File Operations
```python
from alt_file_utils import (
safe_file_read,
safe_file_write,
safe_copy,
safe_delete,
ensure_directory
)
# Read file safely
content = safe_file_read('input.txt')
# Write file safely with atomic operation
safe_file_write('Hello!', 'output.txt')
# Copy file safely
safe_copy('source.txt', 'destination.txt', overwrite=True)
# Delete file safely (missing_ok=True by default)
safe_delete('temp.txt')
# Ensure directory exists
ensure_directory('path/to/directory')
```
### Temporary Directory
```python
from alt_file_utils import temporary_directory
# Create and clean up temporary directory
with temporary_directory(prefix='myapp_') as temp_dir:
temp_file = temp_dir / 'temp.txt'
temp_file.write_text('Temporary data')
# Do work with temporary files
# Directory and all contents are automatically cleaned up
```
### File Information
```python
from alt_file_utils import get_file_size, is_file_locked
# Get file size
size = get_file_size('large_file.bin')
print(f"File size: {size} bytes")
# Check if file is locked (platform-agnostic)
if is_file_locked('database.db'):
print("File is currently locked")
```
## Error Handling
The library provides specific exceptions for different error cases:
```python
from alt_file_utils import (
FileReadError,
FileWriteError,
FileParseError,
FileOperationError
)
try:
data = safe_json_load('config.json')
except FileReadError:
# File doesn't exist or can't be read
pass
except FileParseError:
# File exists but JSON is invalid
pass
```
## Advanced Usage
### Custom Retry Logic
```python
from alt_file_utils import retry_on_failure
# Customize retry behavior
@retry_on_failure(
max_attempts=5,
delay=0.5,
exceptions=(IOError, OSError, TimeoutError)
)
def custom_operation():
# Your code here
pass
```
### YAML Support
```python
from alt_file_utils import safe_yaml_dump, safe_yaml_load
# Write YAML safely
config = {
'database': {
'host': 'localhost',
'port': 5432
}
}
safe_yaml_dump(config, 'config.yaml')
# Read YAML safely
loaded_config = safe_yaml_load('config.yaml')
```
### TOML Support
```python
from alt_file_utils import safe_toml_load
# Read TOML safely (write not supported by tomli)
settings = safe_toml_load('pyproject.toml')
```
## Development
```bash
# Clone the repository
git clone https://github.com/Avilir/ALT-file-utils.git
cd ALT-file-utils
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run type checks
mypy src
# Run linting
ruff check src tests
# Format code
black src tests
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Author
- **Avi Layani** - [GitHub](https://github.com/Avilir)
## See Also
- [ALT-time-utils](https://pypi.org/project/ALT-time-utils/) - Time utilities
- [ALT-error-handling](https://pypi.org/project/ALT-error-handling/) - Error handling utilities
Raw data
{
"_id": null,
"home_page": null,
"name": "ALT-file-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Avi Layani <alayani@redhat.com>",
"keywords": "file, io, atomic, write, utilities, yaml, json, toml",
"author": null,
"author_email": "Avi Layani <alayani@redhat.com>",
"download_url": "https://files.pythonhosted.org/packages/4e/c5/821ba56631868ca2051ba1a8876591e2413e1d861dfb2475e7fdcc88acee/alt_file_utils-0.1.0.tar.gz",
"platform": null,
"description": "# ALT-file-utils\n\n[](https://badge.fury.io/py/ALT-file-utils)\n[](https://pypi.org/project/ALT-file-utils/)\n[](https://opensource.org/licenses/MIT)\n\nRobust file I/O utilities for Python with atomic writes, retries, and comprehensive error handling.\n\n## Features\n\n- \ud83d\udd12 **Atomic file writes** - Prevents corruption by writing to temp files and atomically replacing\n- \ud83d\udd04 **Automatic retries** - Configurable retry logic for transient failures\n- \ud83d\udee1\ufe0f **Comprehensive error handling** - Detailed exceptions for different failure modes\n- \ud83d\udcc1 **Safe file operations** - Read, write, copy, delete with proper error handling\n- \ud83d\udd27 **Multiple format support** - JSON, YAML, TOML with safe loading/dumping\n- \ud83c\udf10 **Cross-platform** - Works on Windows, macOS, and Linux\n- \ud83d\udc0d **Type hints** - Full typing support for better IDE integration\n\n## Installation\n\n```bash\npip install ALT-file-utils\n```\n\nFor TOML support on Python < 3.11:\n```bash\npip install \"ALT-file-utils[toml]\"\n```\n\n## Quick Start\n\n### Atomic File Writing\n\n```python\nfrom alt_file_utils import atomic_write\n\n# Write text file atomically\nwith atomic_write('output.txt') as f:\n f.write('Hello, World!')\n # File is written to a temporary location\n# On successful completion, file is atomically moved to 'output.txt'\n# On exception, temporary file is cleaned up automatically\n```\n\n### Safe JSON Operations\n\n```python\nfrom alt_file_utils import safe_json_dump, safe_json_load\n\n# Write JSON safely with atomic write\ndata = {'name': 'example', 'value': 42}\nsafe_json_dump(data, 'data.json', indent=2)\n\n# Read JSON with error handling\nloaded_data = safe_json_load('data.json')\n```\n\n### Retry Mechanism\n\n```python\nfrom alt_file_utils import retry_on_failure\nimport time\n\n@retry_on_failure(max_attempts=3, delay=1.0)\ndef flaky_file_operation():\n # This will retry up to 3 times with 1 second delay\n with open('important.txt', 'r') as f:\n return f.read()\n```\n\n### Safe File Operations\n\n```python\nfrom alt_file_utils import (\n safe_file_read, \n safe_file_write,\n safe_copy,\n safe_delete,\n ensure_directory\n)\n\n# Read file safely\ncontent = safe_file_read('input.txt')\n\n# Write file safely with atomic operation\nsafe_file_write('Hello!', 'output.txt')\n\n# Copy file safely\nsafe_copy('source.txt', 'destination.txt', overwrite=True)\n\n# Delete file safely (missing_ok=True by default)\nsafe_delete('temp.txt')\n\n# Ensure directory exists\nensure_directory('path/to/directory')\n```\n\n### Temporary Directory\n\n```python\nfrom alt_file_utils import temporary_directory\n\n# Create and clean up temporary directory\nwith temporary_directory(prefix='myapp_') as temp_dir:\n temp_file = temp_dir / 'temp.txt'\n temp_file.write_text('Temporary data')\n # Do work with temporary files\n# Directory and all contents are automatically cleaned up\n```\n\n### File Information\n\n```python\nfrom alt_file_utils import get_file_size, is_file_locked\n\n# Get file size\nsize = get_file_size('large_file.bin')\nprint(f\"File size: {size} bytes\")\n\n# Check if file is locked (platform-agnostic)\nif is_file_locked('database.db'):\n print(\"File is currently locked\")\n```\n\n## Error Handling\n\nThe library provides specific exceptions for different error cases:\n\n```python\nfrom alt_file_utils import (\n FileReadError,\n FileWriteError,\n FileParseError,\n FileOperationError\n)\n\ntry:\n data = safe_json_load('config.json')\nexcept FileReadError:\n # File doesn't exist or can't be read\n pass\nexcept FileParseError:\n # File exists but JSON is invalid\n pass\n```\n\n## Advanced Usage\n\n### Custom Retry Logic\n\n```python\nfrom alt_file_utils import retry_on_failure\n\n# Customize retry behavior\n@retry_on_failure(\n max_attempts=5,\n delay=0.5,\n exceptions=(IOError, OSError, TimeoutError)\n)\ndef custom_operation():\n # Your code here\n pass\n```\n\n### YAML Support\n\n```python\nfrom alt_file_utils import safe_yaml_dump, safe_yaml_load\n\n# Write YAML safely\nconfig = {\n 'database': {\n 'host': 'localhost',\n 'port': 5432\n }\n}\nsafe_yaml_dump(config, 'config.yaml')\n\n# Read YAML safely\nloaded_config = safe_yaml_load('config.yaml')\n```\n\n### TOML Support\n\n```python\nfrom alt_file_utils import safe_toml_load\n\n# Read TOML safely (write not supported by tomli)\nsettings = safe_toml_load('pyproject.toml')\n```\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/Avilir/ALT-file-utils.git\ncd ALT-file-utils\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run type checks\nmypy src\n\n# Run linting\nruff check src tests\n\n# Format code\nblack src tests\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Author\n\n- **Avi Layani** - [GitHub](https://github.com/Avilir)\n\n## See Also\n\n- [ALT-time-utils](https://pypi.org/project/ALT-time-utils/) - Time utilities\n- [ALT-error-handling](https://pypi.org/project/ALT-error-handling/) - Error handling utilities\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Robust file I/O utilities with atomic writes, retries, and comprehensive error handling",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Avilir/ALT-file-utils/issues",
"Homepage": "https://github.com/Avilir/ALT-file-utils",
"Repository": "https://github.com/Avilir/ALT-file-utils"
},
"split_keywords": [
"file",
" io",
" atomic",
" write",
" utilities",
" yaml",
" json",
" toml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ec128d716fe8eb2bab827d9deeb2c491238b7fdebf7109b6aca3e5796837947e",
"md5": "7d1b88420c05b2f01ddbdaa1aedf8c88",
"sha256": "dbdce7e06b72942db89e130a62c028d6db61d4fe1b11d4e836239d0256398abd"
},
"downloads": -1,
"filename": "alt_file_utils-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d1b88420c05b2f01ddbdaa1aedf8c88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9981,
"upload_time": "2025-09-08T07:20:18",
"upload_time_iso_8601": "2025-09-08T07:20:18.354843Z",
"url": "https://files.pythonhosted.org/packages/ec/12/8d716fe8eb2bab827d9deeb2c491238b7fdebf7109b6aca3e5796837947e/alt_file_utils-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4ec5821ba56631868ca2051ba1a8876591e2413e1d861dfb2475e7fdcc88acee",
"md5": "099a8fde3d15dbf5b76c744ff7dff63b",
"sha256": "ba5cba91c99e515ec1c4790430357da53478959d61d7e9d88e8d55dc9c0e7bb1"
},
"downloads": -1,
"filename": "alt_file_utils-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "099a8fde3d15dbf5b76c744ff7dff63b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12580,
"upload_time": "2025-09-08T07:20:19",
"upload_time_iso_8601": "2025-09-08T07:20:19.713347Z",
"url": "https://files.pythonhosted.org/packages/4e/c5/821ba56631868ca2051ba1a8876591e2413e1d861dfb2475e7fdcc88acee/alt_file_utils-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 07:20:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Avilir",
"github_project": "ALT-file-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "alt-file-utils"
}
