doFolder package

Module contents

doFolder - A One Stop File System Management Library

doFolder is a powerful, intuitive, and cross-platform file system management library that provides a high-level, object-oriented interface for working with files and directories. It simplifies common file operations such as creating, moving, copying, deleting, and comparing files and directories while offering advanced features like hashing, content manipulation, and directory tree operations.

Key Features:

  • Object-oriented Design: Work with files and directories as Python objects

  • Cross-platform Compatibility: Seamlessly works on Windows, macOS, and Linux

  • Advanced Path Handling: Built on Python’s pathlib for robust path management

  • File Operations: Create, move, copy, delete, and modify files and directories

  • Content Management: Read and write file content with encoding support

  • Directory Tree Operations: Navigate and manipulate directory structures

  • File Comparison: Compare files and directories with various comparison modes

  • Hash Support: Generate and verify file hashes for integrity checking

  • Error Handling: Comprehensive error modes for different use cases

  • Type Safety: Full type hints for better IDE support and code reliability

Quick Start:
>>> import doFolder
>>>
>>> # Create directory and file objects
>>> project_dir = doFolder.Directory("./my_project")
>>> config_file = doFolder.File("./my_project/config.json")
>>>
>>> # Create a new file in the directory
>>> new_file = project_dir.create("readme.txt", doFolder.ItemType.FILE)
>>>
>>> # Write content to the file
>>> new_file.content = "Hello, World!".encode("utf-8")
>>>
>>> # Create a subdirectory
>>> sub_dir = project_dir.create("data", doFolder.ItemType.DIR)
>>>
>>> # Copy and move files
>>> backup_file = new_file.copy("./backup/")
>>> new_file.move("./archive/")
Main Classes:

  • File: Represents a file in the file system with methods for content manipulation, copying, moving, and deletion.

  • Directory: Represents a directory with methods for creating, listing, and managing contained files and subdirectories.

  • Path: Enhanced path handling with additional utility methods.

Enums and Types:

  • ItemType: Enumeration for file system item types (FILE, DIR).

  • UnExistsMode: Defines behavior when a path doesn’t exist (WARN, ERROR, IGNORE, CREATE).

Utility Functions:

  • createItem(): Factory function to create File or Directory objects based on path type.

  • isDir(): Type guard to check if an item is a directory.

Advanced Features:

  • File Comparison: The compare module provides comprehensive comparison capabilities for files and directories.

  • Hash Operations: Built-in support for file hashing and verification.

  • Flexible Error Handling: Configurable error modes for different scenarios.

  • Path Utilities: Advanced path manipulation and formatting functions.

copyright:

  1. 2023-2025 by kuankuan2007.

license:

MulanPSL-2.0, see LICENSE for more details.

Submodules

doFolder.compare module

Advanced file system comparison module for doFolder.

This module provides comprehensive comparison capabilities for files and directories, supporting multiple comparison strategies including content comparison, timestamp validation, and size verification. It enables deep recursive directory comparison and provides detailed difference reporting through structured data classes. The module optimizes performance through configurable comparison modes and chunked file reading for large files.

Key Features:

  • Multi-mode file comparison (content, size, timestamp)

  • Recursive directory structure comparison

  • Detailed difference detection and classification

  • Memory-efficient chunked file content comparison

  • Flexible comparison strategy configuration

  • Hierarchical difference reporting with flattening support

Added in version 2.2.0.

doFolder.enums module

Enumeration definitions for doFolder file system operations and configurations.

This module defines comprehensive enums that control behavior across the doFolder library, including error handling modes, file system item types, comparison strategies, and hash recalculation policies.

doFolder.exception module

This module defines custom exceptions, warnings, and utilities for handling file system path-related errors and unexpected situations in the doFolder package. Provides comprehensive error handling with configurable behavior modes.

doFolder.fileSystem module

File system operations module for doFolder.

This module provides comprehensive classes and functions for managing files and directories. It includes the main FileSystemItemBase abstract class and its concrete implementations File and Directory, along with utility functions for creating and identifying file system items.

Main classes: - FileSystemItemBase: Abstract base class for all file system items - File: Represents files with read/write/JSON operations - Directory: Represents directories with creation/traversal operations

Main functions: - createItem(): Factory function to create File or Directory objects - isFile()/isDir(): Type checking functions

doFolder.globalType module

Global Type Definitions and Aliases

This module provides type aliases and ensures compatibility with Python’s static type system across different Python versions. It is commonly imported as _tt in other modules for type hinting purposes.

Key type aliases:

  • Pathable: str or Path objects for filesystem paths

  • RelativePathable: Relative paths (str, Path, or path components)

  • CompareModeItem: Comparison mode specifications

Uses typing_extensions for backward compatibility with older Python versions.

doFolder.hashing module

This module provides comprehensive functionality for calculating cryptographic hashes of files and byte content with support for caching, chunked reading, and multithreaded processing.

The module is designed to handle both small and large files efficiently, automatically choosing between in-memory and streaming approaches based on file size thresholds.

It provides the underlying support for the File.hash method.

Added in version 2.2.3.

doFolder.path module

This module provides utility functions for handling and formatting paths within the doFolder package.