The doFolder library is a comprehensive Python package designed to provide an object-oriented abstraction layer for file system operations. Built upon Python’s standard pathlib module, it offers a robust and platform-independent approach to file and directory management with enhanced functionality for modern Python applications.
The library addresses common limitations in traditional file system manipulation by providing a unified interface that abstracts platform-specific details while maintaining full compatibility across Windows, macOS, and Linux environments.
Core API Documentation
The doFolder library is structured around several key architectural components:
The library implements a high-level abstraction that encapsulates file system entities as Python objects, providing intuitive methods for manipulation and querying.
Built on Python’s pathlib, the path management system ensures robust handling of file system paths across different operating systems.
A comprehensive error handling system that provides configurable behavior for common file system operation scenarios.
Specialized interfaces for handling different types of file content, including binary data, text, and structured formats like JSON.
Python 3.8 or higher
Cross-platform compatibility (Windows, macOS, Linux)
The library can be installed using the Python Package Index:
pip install doFolder
For development installations or bleeding-edge features, the library can be installed directly from the source repository.
The doFolder library treats file system entities as first-class objects, each with their own properties, methods, and behaviors. This approach provides several advantages:
Encapsulation: File system operations are encapsulated within appropriate object methods
State Management: Objects maintain their own state and can cache frequently-accessed information
Type Safety: Full type annotations ensure better IDE support and runtime error detection
File ClassRepresents individual files in the file system. Provides methods for content manipulation, metadata access, and file-specific operations.
Directory ClassRepresents directories and provides methods for directory traversal, content listing, and hierarchical operations.
Path ClassAn enhanced path representation that extends Python’s pathlib with additional utility methods.
The File class provides a comprehensive interface for file manipulation:
from doFolder import File
# Instantiate a file object
document = File("document.txt")
# Access file properties
file_size = document.state.st_size
modification_time = document.state.st_mtime
# Content operations
content = document.content # Returns bytes
document.content = b"New content"
# Structured data operations
data = {"key": "value"}
document.saveAsJson(data)
loaded_data = document.loadAsJson()
The Directory class facilitates directory-level operations:
from doFolder import Directory, ItemType
# Create directory object
workspace = Directory("./workspace")
# Create nested structures
workspace.create("src/main", ItemType.DIR)
workspace.create("tests/unit", ItemType.DIR)
# File creation within directories
main_file = workspace.create("src/main.py", ItemType.FILE)
# Directory traversal
for item in workspace.recursiveTraversal():
print(f"Processing: {item.path}")
The library implements a sophisticated error handling system through the UnExistsMode enumeration:
from doFolder import File, UnExistsMode
# Configure error handling behavior
strict_file = File("critical.txt", unExistsMode=UnExistsMode.ERROR)
lenient_file = File("optional.txt", unExistsMode=UnExistsMode.WARN)
silent_file = File("cache.txt", unExistsMode=UnExistsMode.IGNORE)
auto_create = File("log.txt", unExistsMode=UnExistsMode.CREATE)
The library provides sophisticated comparison capabilities for both individual files and entire directory structures:
from doFolder import compare
from doFolder.compare import getDifference
# File comparison
result = compare.compare(file1, file2)
# Directory comparison with detailed difference analysis
differences = getDifference(source_dir, target_dir)
Built-in hashing functionality supports content integrity verification:
from doFolder import File
critical_file = File("important_data.bin")
# Generate hash for integrity checking
original_hash = critical_file.hash()
# After operations, verify integrity
if critical_file.hash() == original_hash:
print("File integrity maintained")
The doFolder library version 2.x introduces several architectural improvements while maintaining backward compatibility. Key changes include:
The Folder class has been renamed to Directory for improved semantic clarity. The original Folder class remains available for backward compatibility.
Full type annotations have been added throughout the library, improving IDE support and enabling static type checking.
The underlying path handling system now utilizes Python’s standard pathlib module for improved robustness and performance.
Existing code using version 1.x remains functional:
# Legacy code continues to work
from doFolder import Folder
legacy_folder = Folder("./data")
# Recommended approach for new code
from doFolder import Directory
modern_directory = Directory("./data")
The doFolder project follows standard open-source development practices. Contributions are welcomed through the project’s GitHub repository at https://github.com/kuankuan2007/do-folder.
All contributions must include appropriate unit tests
Code must conform to the project’s established style guidelines
New features should include corresponding documentation updates
Bug reports should include minimal reproduction cases
This software is distributed under the MulanPSL-2.0 License. The complete license text is available in the project repository and governs all use, modification, and distribution of the software.