# dazzle-filekit
[](https://badge.fury.io/py/dazzle-filekit)
[](https://pypi.org/project/dazzle-filekit/)
[](https://opensource.org/licenses/MIT)
**Cross-platform file operations toolkit with path handling, verification, and metadata preservation**
## Features
- **Path Operations**: Cross-platform path handling, normalization, and manipulation
- **File Operations**: Copy, move, and manage files with metadata preservation
- **File Verification**: Calculate and verify file hashes (MD5, SHA1, SHA256, SHA512)
- **Platform Support**: Windows, Linux, and macOS with platform-specific optimizations
- **UNC Path Support**: Optional integration with `unctools` for Windows UNC path handling
- **Metadata Preservation**: Preserve timestamps, permissions, and file attributes
## Why dazzle-filekit?
While Python's standard library (`shutil`, `pathlib`, `os`) provides basic file operations, dazzle-filekit offers:
- **Metadata Preservation**: Automatic preservation of timestamps, permissions, and extended attributes across platforms
- **Hash Verification**: Built-in file verification with multiple hash algorithms (MD5, SHA1, SHA256, SHA512)
- **Cross-Platform Path Handling**: Unified API for handling Windows UNC paths, network drives, and Unix paths
- **Batch Operations**: Process entire directory trees with pattern matching and filtering
- **Safe Operations**: Built-in conflict resolution, unique path generation, and error handling
- **Directory Comparison**: Compare directory contents and verify file integrity across locations
dazzle-filekit was designed for applications requiring reliable file operations with verification, such as backup tools, file synchronization, and data preservation systems (like the [preserve](https://github.com/djdarcy/preserve) project).
## Installation
```bash
pip install dazzle-filekit
```
### Optional Dependencies
For Windows UNC path support:
```bash
pip install dazzle-filekit[unctools]
```
For development:
```bash
pip install dazzle-filekit[dev]
```
## Quick Start
### Path Operations
```python
from dazzle_filekit import normalize_path, find_files, is_unc_path
# Normalize paths (returns Path object)
path = normalize_path("/some/path/../file.txt")
print(path) # PosixPath('/some/file.txt') or WindowsPath('C:/some/file.txt')
# Find files with patterns (returns list of path strings)
files = find_files("/directory", patterns=["*.py", "*.txt"])
# Check UNC paths
if is_unc_path(r"\\server\share"):
print("This is a UNC path")
```
### File Operations
```python
from dazzle_filekit import copy_file, collect_file_metadata
# Copy file with metadata preservation
success = copy_file("source.txt", "dest.txt", preserve_metadata=True)
# Collect file metadata
metadata = collect_file_metadata("file.txt")
print(f"Size: {metadata['size']}, Modified: {metadata['mtime']}")
```
### File Verification
```python
from dazzle_filekit import calculate_file_hash, verify_file_hash
# Calculate hash
hash_value = calculate_file_hash("file.txt", algorithm="sha256")
# Verify hash
is_valid = verify_file_hash("file.txt", expected_hash, algorithm="sha256")
```
## API Reference
### Path Functions
- `normalize_path(path)` - Normalize path to canonical form
- `is_same_file(path1, path2)` - Check if paths refer to same file
- `split_drive_letter(path)` - Split drive letter from path (Windows)
- `is_unc_path(path)` - Check if path is UNC format
- `get_relative_path(path, base)` - Get relative path from base
- `find_files(directory, patterns, exclude)` - Find files matching patterns
- `get_path_type(path)` - Detect path type (unc, network, subst, local)
### File Operations
- `copy_file(src, dst, preserve_metadata)` - Copy file with options
- `move_file(src, dst, preserve_metadata)` - Move file with options
- `collect_file_metadata(path)` - Collect file metadata
- `apply_file_metadata(path, metadata)` - Apply metadata to file
- `create_directory_structure(path)` - Create directory tree
- `remove_file(path)` - Remove file safely
- `remove_directory(path, recursive)` - Remove directory
### Verification Functions
- `calculate_file_hash(path, algorithm)` - Calculate file hash
- `verify_file_hash(path, expected_hash, algorithm)` - Verify hash
- `calculate_directory_hashes(directory, algorithm)` - Hash all files in directory
- `save_hashes_to_file(hashes, output_file)` - Save hashes to file
- `load_hashes_from_file(hash_file)` - Load hashes from file
- `compare_directories(dir1, dir2)` - Compare directory contents
- `verify_copied_files(src_dir, dst_dir)` - Verify copy operation
## Platform Support
### Windows
- Full UNC path support (with `unctools`)
- Network drive detection
- NTFS metadata preservation
- Long path support (>260 characters)
### Linux/Unix
- POSIX permissions preservation
- Symlink handling
- Extended attributes
### macOS
- HFS+ and APFS support
- Extended attributes
- Resource forks (where applicable)
## Configuration
### Logging
```python
from dazzle_filekit import configure_logging, enable_verbose_logging
import logging
# Configure logging level
configure_logging(level=logging.DEBUG, log_file="dazzle-filekit.log")
# Or enable verbose logging
enable_verbose_logging()
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/DazzleLib/dazzle-filekit.git
cd dazzle-filekit/local
pip install -e ".[dev]"
```
### Run Tests
```bash
pytest tests/ -v --cov=dazzle_filekit
```
### Code Formatting
```bash
black dazzle_filekit tests
flake8 dazzle_filekit tests
```
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Like the project?
[](https://www.buymeacoffee.com/djdarcy)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Part of DazzleLib
dazzle-filekit is part of the [DazzleLib](https://github.com/DazzleLib) ecosystem of Python file manipulation tools.
### Related Projects
- [UNCtools](https://github.com/DazzleLib/UNCtools) - Windows UNC path utilities
- [dazzle-tree-lib](https://github.com/DazzleLib/dazzle-tree-lib) - Tree structure utilities
- [preserve](https://github.com/djdarcy/preserve) - File preservation tool using dazzle-filekit
Raw data
{
"_id": null,
"home_page": null,
"name": "dazzle-filekit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "file, operations, path, verification, hash, metadata, cross-platform",
"author": "Dustin",
"author_email": "Dustin Darcy <6962246+djdarcy@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/74/f8/f50ff869ada20927b267c9781fea9c82493add0f42e443839903ce05e8d0/dazzle_filekit-0.1.0.tar.gz",
"platform": null,
"description": "# dazzle-filekit\n\n[](https://badge.fury.io/py/dazzle-filekit)\n[](https://pypi.org/project/dazzle-filekit/)\n[](https://opensource.org/licenses/MIT)\n\n**Cross-platform file operations toolkit with path handling, verification, and metadata preservation**\n\n## Features\n\n- **Path Operations**: Cross-platform path handling, normalization, and manipulation\n- **File Operations**: Copy, move, and manage files with metadata preservation\n- **File Verification**: Calculate and verify file hashes (MD5, SHA1, SHA256, SHA512)\n- **Platform Support**: Windows, Linux, and macOS with platform-specific optimizations\n- **UNC Path Support**: Optional integration with `unctools` for Windows UNC path handling\n- **Metadata Preservation**: Preserve timestamps, permissions, and file attributes\n\n## Why dazzle-filekit?\n\nWhile Python's standard library (`shutil`, `pathlib`, `os`) provides basic file operations, dazzle-filekit offers:\n\n- **Metadata Preservation**: Automatic preservation of timestamps, permissions, and extended attributes across platforms\n- **Hash Verification**: Built-in file verification with multiple hash algorithms (MD5, SHA1, SHA256, SHA512)\n- **Cross-Platform Path Handling**: Unified API for handling Windows UNC paths, network drives, and Unix paths\n- **Batch Operations**: Process entire directory trees with pattern matching and filtering\n- **Safe Operations**: Built-in conflict resolution, unique path generation, and error handling\n- **Directory Comparison**: Compare directory contents and verify file integrity across locations\n\ndazzle-filekit was designed for applications requiring reliable file operations with verification, such as backup tools, file synchronization, and data preservation systems (like the [preserve](https://github.com/djdarcy/preserve) project).\n\n## Installation\n\n```bash\npip install dazzle-filekit\n```\n\n### Optional Dependencies\n\nFor Windows UNC path support:\n```bash\npip install dazzle-filekit[unctools]\n```\n\nFor development:\n```bash\npip install dazzle-filekit[dev]\n```\n\n## Quick Start\n\n### Path Operations\n\n```python\nfrom dazzle_filekit import normalize_path, find_files, is_unc_path\n\n# Normalize paths (returns Path object)\npath = normalize_path(\"/some/path/../file.txt\")\nprint(path) # PosixPath('/some/file.txt') or WindowsPath('C:/some/file.txt')\n\n# Find files with patterns (returns list of path strings)\nfiles = find_files(\"/directory\", patterns=[\"*.py\", \"*.txt\"])\n\n# Check UNC paths\nif is_unc_path(r\"\\\\server\\share\"):\n print(\"This is a UNC path\")\n```\n\n### File Operations\n\n```python\nfrom dazzle_filekit import copy_file, collect_file_metadata\n\n# Copy file with metadata preservation\nsuccess = copy_file(\"source.txt\", \"dest.txt\", preserve_metadata=True)\n\n# Collect file metadata\nmetadata = collect_file_metadata(\"file.txt\")\nprint(f\"Size: {metadata['size']}, Modified: {metadata['mtime']}\")\n```\n\n### File Verification\n\n```python\nfrom dazzle_filekit import calculate_file_hash, verify_file_hash\n\n# Calculate hash\nhash_value = calculate_file_hash(\"file.txt\", algorithm=\"sha256\")\n\n# Verify hash\nis_valid = verify_file_hash(\"file.txt\", expected_hash, algorithm=\"sha256\")\n```\n\n## API Reference\n\n### Path Functions\n\n- `normalize_path(path)` - Normalize path to canonical form\n- `is_same_file(path1, path2)` - Check if paths refer to same file\n- `split_drive_letter(path)` - Split drive letter from path (Windows)\n- `is_unc_path(path)` - Check if path is UNC format\n- `get_relative_path(path, base)` - Get relative path from base\n- `find_files(directory, patterns, exclude)` - Find files matching patterns\n- `get_path_type(path)` - Detect path type (unc, network, subst, local)\n\n### File Operations\n\n- `copy_file(src, dst, preserve_metadata)` - Copy file with options\n- `move_file(src, dst, preserve_metadata)` - Move file with options\n- `collect_file_metadata(path)` - Collect file metadata\n- `apply_file_metadata(path, metadata)` - Apply metadata to file\n- `create_directory_structure(path)` - Create directory tree\n- `remove_file(path)` - Remove file safely\n- `remove_directory(path, recursive)` - Remove directory\n\n### Verification Functions\n\n- `calculate_file_hash(path, algorithm)` - Calculate file hash\n- `verify_file_hash(path, expected_hash, algorithm)` - Verify hash\n- `calculate_directory_hashes(directory, algorithm)` - Hash all files in directory\n- `save_hashes_to_file(hashes, output_file)` - Save hashes to file\n- `load_hashes_from_file(hash_file)` - Load hashes from file\n- `compare_directories(dir1, dir2)` - Compare directory contents\n- `verify_copied_files(src_dir, dst_dir)` - Verify copy operation\n\n## Platform Support\n\n### Windows\n- Full UNC path support (with `unctools`)\n- Network drive detection\n- NTFS metadata preservation\n- Long path support (>260 characters)\n\n### Linux/Unix\n- POSIX permissions preservation\n- Symlink handling\n- Extended attributes\n\n### macOS\n- HFS+ and APFS support\n- Extended attributes\n- Resource forks (where applicable)\n\n## Configuration\n\n### Logging\n\n```python\nfrom dazzle_filekit import configure_logging, enable_verbose_logging\nimport logging\n\n# Configure logging level\nconfigure_logging(level=logging.DEBUG, log_file=\"dazzle-filekit.log\")\n\n# Or enable verbose logging\nenable_verbose_logging()\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/DazzleLib/dazzle-filekit.git\ncd dazzle-filekit/local\npip install -e \".[dev]\"\n```\n\n### Run Tests\n\n```bash\npytest tests/ -v --cov=dazzle_filekit\n```\n\n### Code Formatting\n\n```bash\nblack dazzle_filekit tests\nflake8 dazzle_filekit tests\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nLike the project?\n\n[](https://www.buymeacoffee.com/djdarcy)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Part of DazzleLib\n\ndazzle-filekit is part of the [DazzleLib](https://github.com/DazzleLib) ecosystem of Python file manipulation tools.\n\n### Related Projects\n\n- [UNCtools](https://github.com/DazzleLib/UNCtools) - Windows UNC path utilities\n- [dazzle-tree-lib](https://github.com/DazzleLib/dazzle-tree-lib) - Tree structure utilities\n- [preserve](https://github.com/djdarcy/preserve) - File preservation tool using dazzle-filekit\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cross-platform file operations toolkit with path handling, verification, and metadata preservation",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/DazzleLib/dazzle-filekit/issues",
"Documentation": "https://github.com/DazzleLib/dazzle-filekit#readme",
"Homepage": "https://github.com/DazzleLib/dazzle-filekit",
"Source": "https://github.com/DazzleLib/dazzle-filekit"
},
"split_keywords": [
"file",
" operations",
" path",
" verification",
" hash",
" metadata",
" cross-platform"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7aab9e0745e663b15a765d3b1bd5ebc7b7325c6d3f89f814a0b0265dc5611a5f",
"md5": "2786a40722385d0ca18792b03154ba0e",
"sha256": "f2659d4eb8ddf5b4ac22ed56441b1a6ee95516d2356e8cb76498b3648634612b"
},
"downloads": -1,
"filename": "dazzle_filekit-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2786a40722385d0ca18792b03154ba0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 26692,
"upload_time": "2025-10-28T21:34:34",
"upload_time_iso_8601": "2025-10-28T21:34:34.440914Z",
"url": "https://files.pythonhosted.org/packages/7a/ab/9e0745e663b15a765d3b1bd5ebc7b7325c6d3f89f814a0b0265dc5611a5f/dazzle_filekit-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "74f8f50ff869ada20927b267c9781fea9c82493add0f42e443839903ce05e8d0",
"md5": "2a902d10a3b367ef8345a8a334ad14e8",
"sha256": "b19d15eb181137ff446ed5a647a1dfc6c1e69bb07e2679bc5199061c30ac9c9c"
},
"downloads": -1,
"filename": "dazzle_filekit-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2a902d10a3b367ef8345a8a334ad14e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 25253,
"upload_time": "2025-10-28T21:34:35",
"upload_time_iso_8601": "2025-10-28T21:34:35.705250Z",
"url": "https://files.pythonhosted.org/packages/74/f8/f50ff869ada20927b267c9781fea9c82493add0f42e443839903ce05e8d0/dazzle_filekit-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 21:34:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DazzleLib",
"github_project": "dazzle-filekit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "dazzle-filekit"
}
JSON
