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, directory tree operations, and comprehensive command-line tools for file system management.

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
Command-line Interface: Comprehensive CLI tools for file operations
High-performance Hashing: Multi-threaded hashing with caching support
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/")
>>>
>>> # Use hashing functionality
>>> file_hash = new_file.hash()  # Default algorithm
>>> sha256_hash = new_file.hash("sha256")  # Specific algorithm
>>>
>>> # Command-line usage examples:
>>> # do-folder compare /path/to/dir1 /path/to/dir2
>>> # do-folder hash -a sha256 file1.txt file2.txt

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.
Command-line Tools: The cli module provides powerful command-line utilities for file comparison, hashing, and other operations.
High-performance Hashing: The hashing module offers multi-threaded hash calculation with caching and various algorithms.
Flexible Error Handling: Configurable error modes for different scenarios.
Path Utilities: Advanced path manipulation and formatting functions.

copyright:

2023-2025 by kuankuan2007.

license:

MulanPSL-2.0, see LICENSE for more details.

Subpackages¶

doFolder.cli package ¶

Command Line Interface (CLI) module for doFolder.

This package provides the command-line interface components for the doFolder file system management tool. It includes subcommands for various operations like comparing directories and files.

Available CLI Functions:

compareCli: Command-line interface for folder/file comparison
mainCli: Main CLI dispatcher for all subcommands

doFolder.fileSystem package ¶

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

Changed in version 2.3.0: fileSystem is now a subpackage, instead of submodule

doFolder.hashing package ¶

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.

Changed in version 2.3.0: hashing is now a subpackage, instead of submodule.

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.env module ¶

Python runtime environment information module for doFolder.

This module provides essential Python runtime environment information and constants used throughout the doFolder library. It exposes Python version details, interpreter path, and runtime features like GIL (Global Interpreter Lock) status for compatibility checking and environment-aware operations.

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

Table of Contents

Previous topic

Next topic

This Page