dazzle-filekit 0.2.2

Cross-platform file operations toolkit with path handling, verification, and metadata preservation

dazzle-filekit

Cross-platform file operations with path handling, verification, and metadata preservation.

A Python toolkit for reliable file operations across Windows, Linux, and macOS. Handles path normalization between Git Bash, WSL, and native formats, file verification with multiple hash algorithms, and metadata-preserving copy/move operations.

Features

• Cross-Platform Paths - Normalize between Git Bash (/c/...), WSL (/mnt/c/...), and native Windows/Unix paths
• File Operations - Copy, move, and manage files with metadata preservation
• File Verification - Calculate and verify file hashes (MD5, SHA1, SHA256, SHA512)
• Disk Space Checking - Pre-flight space verification before operations
• Platform Support - Windows, Linux, macOS, and BSD with platform-specific optimizations
• UNC Path Support - Optional integration with unctools for Windows UNC path handling

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

# Windows UNC path support
pip install dazzle-filekit[unctools]

# Development tools
pip install dazzle-filekit[dev]

Quick Start

Cross-Platform Path Handling

from dazzle_filekit import (
    normalize_cross_platform_path,
    resolve_cross_platform_path,
    path_exists_cross_platform,
)

# Convert Git Bash style paths to native format
# On Windows: /c/Users/foo -> C:\Users\foo
# On Unix: C:\Users\foo -> /c/Users/foo
path = normalize_cross_platform_path("/c/Users/foo/file.txt")

# Also handles WSL paths: /mnt/c/Users/...
path = normalize_cross_platform_path("/mnt/c/Users/foo/file.txt")

# Resolve with probing: if the normalized path doesn't exist,
# tries alternate platform formats (WSL, MSYS, Windows)
path = resolve_cross_platform_path("/mnt/c/Users/foo/file.txt")

# Check if a cross-platform path exists (uses resolve internally)
if path_exists_cross_platform("/c/Users/foo/file.txt"):
    print("File exists!")

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, create_symlink

# 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']}")

# Create symbolic link (cross-platform)
success = create_symlink("/path/to/target", "/path/to/link")

# Force replace existing link
success = create_symlink("/new/target", "/path/to/link", force=True)

Disk Space Checking

from dazzle_filekit import get_disk_usage, check_disk_space, ensure_disk_space

# Get disk usage statistics
usage = get_disk_usage("/path/to/check")
print(f"Total: {usage.total}, Free: {usage.free}, Used: {usage.used_percent:.1f}%")

# Check if space is available for an operation
has_space, required, available, message = check_disk_space(
    "/destination",
    required_bytes=1_000_000_000,  # 1GB
    safety_margin=0.1  # 10% extra margin
)

# Check space for a list of source files
has_space, message = ensure_disk_space(
    dest_path="/destination",
    source_paths=["/path/to/file1.zip", "/path/to/dir/"]
)

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

Cross-Platform Utilities

• normalize_cross_platform_path(path) - Normalize Git Bash/WSL/Windows paths to native format
• resolve_cross_platform_path(path) - Normalize and probe alternate platform formats if path not found
• path_exists_cross_platform(path) - Check path existence across formats
• is_windows() / is_unix() - Platform detection

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
• create_symlink(target, link, force) - Create symbolic link with cross-platform support

Disk Space Functions

• get_disk_usage(path) - Get disk usage statistics (total, used, free)
• check_disk_space(dest, required, margin) - Check if space is sufficient
• calculate_total_size(paths) - Calculate total size of files/directories
• ensure_disk_space(dest, sources, margin) - Verify space for copy operation

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) / load_hashes_from_file(hash_file) - Hash persistence
• compare_directories(dir1, dir2) - Compare directory contents
• verify_copied_files(src_dir, dst_dir) - Verify copy operation

Platform Support

See docs/platform-support.md for the full platform support matrix and platform-specific features.

Platform	Status
Windows 10/11	Tested
Linux	Tested
WSL / WSL2	Tested
macOS	Expected to work
BSD	Expected to work

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
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
• preserve - File preservation with manifest tracking and restoration
• dazzle-tree-lib - Tree structure utilities