dazzle-filekit

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 project).

Installation

pip install dazzle-filekit

Optional Dependencies

For Windows UNC path support:

pip install dazzle-filekit[unctools]

For development:

pip install dazzle-filekit[dev]

Quick Start

Path Operations

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

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

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

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

git clone https://github.com/DazzleLib/dazzle-filekit.git
cd dazzle-filekit/local
pip install -e ".[dev]"

Run Tests

pytest tests/ -v --cov=dazzle_filekit

Code Formatting

black dazzle_filekit tests
flake8 dazzle_filekit tests

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Like the project?

License

This project is licensed under the MIT License - see the LICENSE file for details.

Part of DazzleLib

dazzle-filekit is part of the DazzleLib ecosystem of Python file manipulation tools.

Related Projects

• UNCtools - Windows UNC path utilities
• dazzle-tree-lib - Tree structure utilities
• preserve - File preservation tool using dazzle-filekit