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.

class doFolder.compare.Difference(path1: Path, path2: Path, diffType: DifferenceType)

Bases: object

Represents a detected difference between two file system paths during comparison operations.

This class serves as the base structure for reporting discrepancies found during file system comparisons. It encapsulates the paths being compared and the specific type of difference detected, providing a standardized way to represent comparison results throughout the library.

diffType: DifferenceType
path1: Path
path2: Path
toFlat() → Tuple[Difference, ...]

Converts the difference structure to a flat tuple representation.

This method provides a uniform interface for flattening difference hierarchies, enabling consistent processing of both simple differences and complex directory difference trees. For basic Difference objects, returns a single-element tuple.

Returns:

A tuple containing this difference instance.

Return type:

_tt.Tuple[Difference,…]

class doFolder.compare.DirectoryDifference(path1: ~pathlib.Path, path2: ~pathlib.Path, diffType: ~doFolder.enums.DifferenceType, sub: ~typing.Tuple[~doFolder.compare.Difference, ...] = <factory>)

Bases: Difference

Specialized difference class for directory comparisons with hierarchical sub-differences.

This class extends the base Difference class to handle complex directory comparison results where differences may exist at multiple levels within the directory structure. It maintains a collection of sub-differences representing discrepancies found in contained files and subdirectories, enabling comprehensive directory tree analysis and reporting.

sub: Tuple[Difference, ...]
toFlat() → Tuple[Difference, ...]

Recursively flattens the directory difference hierarchy into a linear tuple.

This method traverses the entire sub-difference tree and converts it into a flat structure, making it easier to process all differences sequentially. The method includes the current directory difference followed by all flattened sub-differences in depth-first order.

Returns:

A flattened tuple containing this difference and all sub-differences.

Return type:

_tt.Tuple[Difference,…]

doFolder.compare.compare(item1: str | Path | File | Directory, item2: str | Path | File | Directory, compareMode: CompareModeFlag | CompareMode = CompareMode.TIMETAG_AND_SIZE) → bool

High-level interface for comparing two file system items with flexible input types.

This function provides the primary public API for file system comparisons, accepting various path-like inputs and converting them to appropriate file system objects. It supports multiple comparison strategies and provides sensible defaults for common use cases while maintaining flexibility for advanced scenarios.

Parameters:

  • item1 (FileSystemItemLike) – First item, accepting File, Directory, or path-like objects.

  • item2 (FileSystemItemLike) – Second item, accepting File, Directory, or path-like objects.

  • compareMode (_tt.CompareModeItem) – Comparison strategy, defaults to timestamp and size validation.

Returns:

True if items satisfy the specified comparison criteria, False otherwise.

Return type:

bool

doFolder.compare.getDifference(item1: str | Path | File | Directory, item2: str | Path | File | Directory, compareMode: CompareModeFlag | CompareMode = CompareMode.TIMETAG_AND_SIZE) → Difference | None

Public API for comprehensive difference analysis between file system items.

This function provides detailed difference reporting for file system comparisons, returning structured objects that describe the specific nature of discrepancies found. Unlike the simple boolean comparison function, this provides actionable information about what differs between the compared items, supporting detailed analysis and reporting workflows.

Parameters:

  • item1 (FileSystemItemLike) – First item, accepting various path-like representations.

  • item2 (FileSystemItemLike) – Second item, accepting various path-like representations.

  • compareMode (_tt.CompareModeItem) – Comparison methodology, defaults to timestamp and size analysis.

Returns:

Detailed difference object, hierarchical DirectoryDifference, or None if identical.

Return type:

CompareResult