API Reference

This page provides detailed API documentation for all public classes, functions, and constants in SyncEngine.

Core Classes

SyncEngine

class SyncEngine(client, entries_manager_factory, output=None, state_manager=None, pause_controller=None, concurrency_limits=None, spinner_factory=None, progress_bar_factory=None)

Core sync engine that orchestrates file synchronization.

Parameters:

client (StorageClientProtocol) – Storage API client
entries_manager_factory (Callable) – Factory function that creates FileEntriesManagerProtocol instances
output (OutputHandlerProtocol) – Output handler for displaying progress (optional)
state_manager (SyncStateManager) – State manager for tracking sync history (optional)
pause_controller (SyncPauseController) – Controller for pause/resume/cancel (optional)
concurrency_limits (ConcurrencyLimits) – Concurrency limits for transfers and operations (optional)
spinner_factory (SpinnerFactoryProtocol) – Factory for creating progress spinners (optional)
progress_bar_factory (ProgressBarFactoryProtocol) – Factory for creating progress bars (optional)

sync_pair(pair: SyncPair) → dict[str, int]

Execute synchronization for a sync pair.

Parameters:: pair (SyncPair) – Sync pair to synchronize
Returns:: Dictionary with sync statistics (uploads, downloads, deletes, etc.)
Return type:: dict[str, int]

sync_pairs(pairs: list[SyncPair]) → list[dict[str, int]]

Execute synchronization for multiple sync pairs.

Parameters:: pairs (list[SyncPair]) – List of sync pairs to synchronize
Returns:: List of sync statistics for each pair
Return type:: list[dict[str, int]]

download_folder(destination_path: str, local_path: Path, sync_progress_tracker: SyncProgressTracker | None = None, parallel: bool = False, use_rich_progress: bool = True) → dict[str, int]

Download a folder from destination to local filesystem.

Parameters:

destination_path (str) – Path in destination storage
local_path (Path) – Local path to download to
sync_progress_tracker (SyncProgressTracker) – Optional progress tracker for monitoring download progress (new in v0.2.0)
parallel (bool) – Whether to download files in parallel (default: False)
use_rich_progress (bool) – Whether to display Rich progress bar (default: True, automatically disabled when sync_progress_tracker is provided)

Returns:

Dictionary with download statistics (downloads, errors, etc.)

Return type:

dict[str, int]

Note

When sync_progress_tracker is provided, the Rich progress bar is automatically disabled to avoid UI conflicts. The tracker will emit detailed download events: DOWNLOAD_BATCH_START, DOWNLOAD_FILE_START, DOWNLOAD_FILE_PROGRESS, DOWNLOAD_FILE_COMPLETE, DOWNLOAD_FILE_ERROR, DOWNLOAD_BATCH_COMPLETE.

SyncPair

class SyncPair(source_root, destination_root, source_client, destination_client, mode=SyncMode.TWO_WAY, comparison_mode=ComparisonMode.HASH_THEN_MTIME, ignore_manager=None, conflict_resolution=ConflictResolution.NEWEST_WINS)

Represents a source-destination pair for synchronization.

Parameters:

source_root (str) – Root path of source directory
destination_root (str) – Root path of destination directory
source_client (StorageClientProtocol) – Storage client for source
destination_client (StorageClientProtocol) – Storage client for destination
mode (SyncMode) – Synchronization mode (default: TWO_WAY)
comparison_mode (ComparisonMode) – File comparison mode (default: HASH_THEN_MTIME)
ignore_manager (IgnoreFileManager) – Ignore pattern manager (optional)
conflict_resolution (ConflictResolution) – Conflict resolution strategy (default: NEWEST_WINS)

source_root: Root path of source directory.

destination_root: Root path of destination directory.

mode: Synchronization mode.

comparison_mode: File comparison mode for determining if files are identical.

ignore_manager: Ignore pattern manager.

Enums

SyncMode

class SyncMode

Synchronization modes for different sync strategies.

TWO_WAY: Bidirectional sync. Changes on either side are propagated to the other.

SOURCE_TO_DESTINATION: One-way mirror from source to destination. Destination changes are overwritten.

SOURCE_BACKUP: Upload-only backup. Never deletes from source.

DESTINATION_TO_SOURCE: One-way mirror from destination to source. Source changes are overwritten.

DESTINATION_BACKUP: Download-only backup. Never deletes from destination.

classmethod from_string(value: str) → SyncMode

Parse sync mode from string, supporting abbreviations.

Parameters:: value (str) – Mode string (full name or abbreviation)
Returns:: SyncMode enum value
Return type:: SyncMode
Raises:: ValueError – If mode string is not recognized

Supported abbreviations:

tw → TWO_WAY
std → SOURCE_TO_DESTINATION
sb → SOURCE_BACKUP
dts → DESTINATION_TO_SOURCE
db → DESTINATION_BACKUP

property allows_upload: Check if this mode allows uploading files.

property allows_download: Check if this mode allows downloading files.

property allows_source_delete: Check if this mode allows deleting source files.

property allows_destination_delete: Check if this mode allows deleting destination files.

property is_bidirectional: Check if this mode syncs in both directions.

ComparisonMode

class ComparisonMode

File comparison strategies for determining if files are identical.

HASH_THEN_MTIME: Default balanced mode. Compares hash if available, falls back to mtime. Files considered identical if sizes equal AND (hashes equal OR hash unavailable).

SIZE_ONLY

Size-only comparison. Ignores hash and mtime completely. Files considered identical if sizes equal.

Use when: * Hash is unavailable or unreliable (e.g., encrypted storage) * Mtime is unreliable (e.g., upload time vs original file time)

Behavior with TWO_WAY sync: * Files with different sizes → CONFLICT (cannot determine newer file) * One-way sync uses sync direction to determine which file wins

HASH_ONLY

Strict hash-only comparison. Ignores size and mtime. Files considered identical only if hashes match. Raises error if hash unavailable.

Use when: * Strict content verification required * Mtime is completely unreliable

Behavior with TWO_WAY sync: * Files with different hashes → CONFLICT (cannot determine newer file) * One-way sync uses sync direction to determine which file wins

MTIME_ONLY

Time-only comparison. Ignores size and hash. Files considered identical if mtimes match (±2 second tolerance).

Use when: * Performance critical (skips hash computation) * Timestamps are reliable * Large files where hashing is expensive

SIZE_AND_MTIME

Balanced comparison without hash. Compares both size AND mtime. Files considered identical if size equal AND mtime equal (±2 second tolerance).

Use when: * Hash unavailable but mtime is reliable * Need more accuracy than SIZE_ONLY * Good balance of performance and reliability

SyncAction

class SyncAction

Actions that can be taken for a file during sync.

UPLOAD_NEW: Upload a new file to destination.

UPLOAD_UPDATE: Upload changes to existing destination file.

UPLOAD_RESTORE: Re-upload file that was deleted at destination.

DOWNLOAD_NEW: Download a new file from destination.

DOWNLOAD_UPDATE: Download changes to existing source file.

DOWNLOAD_RESTORE: Re-download file that was deleted at source.

DELETE_SOURCE: Delete file from source.

DELETE_DESTINATION: Delete file from destination.

NO_ACTION: File is already in sync, no action needed.

CONFLICT: Manual resolution required.

State Management

SyncStateManager

class SyncStateManager(state_dir: Path)

Manages persistent sync state across sync sessions.

Parameters:: state_dir (Path) – Directory to store state files

load_source_tree() → SourceTree

Load previous source state.

Returns:: Source tree from last sync
Return type:: SourceTree

load_destination_tree() → DestinationTree

Load previous destination state.

Returns:: Destination tree from last sync
Return type:: DestinationTree

save_source_tree(tree: SourceTree) → None

Save current source state.

Parameters:: tree (SourceTree) – Source tree to save

save_destination_tree(tree: DestinationTree) → None

Save current destination state.

Parameters:: tree (DestinationTree) – Destination tree to save

clear() → None: Clear all saved state.

SourceTree

class SourceTree

Tree structure representing source files.

items: Dictionary mapping paths to SourceItemState.

DestinationTree

class DestinationTree

Tree structure representing destination files.

items: Dictionary mapping paths to DestinationItemState.

Ignore Patterns

IgnoreFileManager

class IgnoreFileManager(patterns: list[str] = None)

Manages gitignore-style ignore patterns.

Parameters:: patterns (list[str]) – Initial list of patterns (optional)

add_pattern(pattern: str) → None

Add an ignore pattern.

Parameters:: pattern (str) – Pattern to add (gitignore syntax)

load_from_file(file_path: Path) → None

Load patterns from a file.

Parameters:: file_path (Path) – Path to ignore file

should_ignore(path: str) → bool

Check if a path should be ignored.

Parameters:: path (str) – Path to check
Returns:: True if path should be ignored
Return type:: bool

clear() → None: Clear all patterns.

IgnoreRule

class IgnoreRule(pattern: str, is_negation: bool = False)

Represents a single ignore pattern rule.

Parameters:

pattern (str) – Pattern string
is_negation (bool) – True if this is a negation rule (!)

matches(path: str) → bool

Check if this rule matches a path.

Parameters:: path (str) – Path to check
Returns:: True if rule matches path
Return type:: bool

Concurrency

ConcurrencyLimits

class ConcurrencyLimits(transfers: int = 5, operations: int = 10)

Concurrency limits for sync operations.

Parameters:

transfers (int) – Maximum concurrent uploads/downloads (default: 5)
operations (int) – Maximum concurrent file operations (default: 10)

transfers: Maximum concurrent uploads/downloads.

operations: Maximum concurrent file operations.

SyncPauseController

class SyncPauseController

Controller for pausing, resuming, and canceling sync operations.

pause() → None: Pause sync operations.

resume() → None: Resume paused sync operations.

cancel() → None: Cancel sync operations.

is_paused() → bool

Check if sync is paused.

Returns:: True if paused
Return type:: bool

is_cancelled() → bool

Check if sync is cancelled.

Returns:: True if cancelled
Return type:: bool

wait_if_paused() → None: Block until sync is resumed or cancelled.

Progress Tracking

SyncProgressTracker

class SyncProgressTracker(callback: Callable[[SyncProgressEvent], None])

Tracks and reports sync progress.

Parameters:: callback (Callable) – Callback function for progress events

on_scan_start() → None: Called when file scanning starts.

on_scan_progress(scanned: int, total: int) → None

Called during file scanning.

Parameters:

scanned (int) – Number of files scanned
total (int) – Total files to scan

on_scan_complete(total: int) → None

Called when file scanning completes.

Parameters:: total (int) – Total files scanned

on_sync_start(total_files: int) → None

Called when sync operations start.

Parameters:: total_files (int) – Total files to sync

on_upload_start(file_path: str, file_size: int) → None

Called when file upload starts.

Parameters:

file_path (str) – Path of file being uploaded
file_size (int) – Size of file in bytes

on_upload_progress(file_path: str, bytes_transferred: int, total_bytes: int) → None

Called during file upload.

Parameters:

file_path (str) – Path of file being uploaded
bytes_transferred (int) – Bytes uploaded so far
total_bytes (int) – Total bytes to upload

on_upload_complete(file_path: str) → None

Called when file upload completes.

Parameters:: file_path (str) – Path of file uploaded

on_download_start(file_path: str, file_size: int) → None

Called when file download starts.

Parameters:

file_path (str) – Path of file being downloaded
file_size (int) – Size of file in bytes

on_download_progress(file_path: str, bytes_transferred: int, total_bytes: int) → None

Called during file download.

Parameters:

file_path (str) – Path of file being downloaded
bytes_transferred (int) – Bytes downloaded so far
total_bytes (int) – Total bytes to download

on_download_complete(file_path: str) → None

Called when file download completes.

Parameters:: file_path (str) – Path of file downloaded

on_download_batch_start(directory: str, num_files: int, total_bytes: int) → None

Called when batch download for a folder starts.

Parameters:

directory (str) – Directory being downloaded
num_files (int) – Number of files to download
total_bytes (int) – Total bytes to download

on_download_file_start(file_path: str, file_size: int) → None

Called when individual file download starts.

Parameters:

file_path (str) – Path of file being downloaded
file_size (int) – Size of file in bytes

on_download_file_progress(file_path: str, bytes_downloaded: int, total_bytes: int) → None

Called during file download with progress updates.

Parameters:

file_path (str) – Path of file being downloaded
bytes_downloaded (int) – Bytes downloaded so far
total_bytes (int) – Total bytes to download

on_download_file_complete(file_path: str) → None

Called when file download completes successfully.

Parameters:: file_path (str) – Path of file downloaded

on_download_file_error(file_path: str, error: Exception) → None

Called when file download fails.

Parameters:

file_path (str) – Path of file that failed
error (Exception) – Error that occurred

on_download_batch_complete(directory: str, num_downloaded: int) → None

Called when batch download completes.

Parameters:

directory (str) – Directory that was downloaded
num_downloaded (int) – Number of files successfully downloaded

create_download_progress_callback(file_path: str) → Callable[[int, int], None]

Create a progress callback for download operations.

Parameters:: file_path (str) – Path of file being downloaded
Returns:: Progress callback function
Return type:: Callable[[int, int], None]

on_sync_complete(stats: dict[str, int]) → None

Called when all sync operations complete.

Parameters:: stats (dict) – Sync statistics

SyncProgressEvent

class SyncProgressEvent

Event types for progress callbacks.

Scan Events:

SCAN_DIR_START: Directory scanning started.

SCAN_DIR_COMPLETE: Directory scanning completed.

Upload Events:

UPLOAD_BATCH_START: Batch upload for a folder started.

UPLOAD_FILE_START: Individual file upload started.

UPLOAD_FILE_PROGRESS: File upload progress update.

UPLOAD_FILE_COMPLETE: File upload completed successfully.

UPLOAD_FILE_ERROR: File upload failed.

UPLOAD_BATCH_COMPLETE: Batch upload completed.

Download Events:

DOWNLOAD_BATCH_START: Batch download for a folder started.

DOWNLOAD_FILE_START: Individual file download started.

DOWNLOAD_FILE_PROGRESS: File download progress update.

DOWNLOAD_FILE_COMPLETE: File download completed successfully.

DOWNLOAD_FILE_ERROR: File download failed.

DOWNLOAD_BATCH_COMPLETE: Batch download completed.

SyncProgressInfo

class SyncProgressInfo

Progress information object passed to callbacks.

event: Event type (SyncProgressEvent enum value).

file_path: File path (for file-specific events).

directory: Directory path (for batch events).

current_file_bytes: Bytes transferred for current file.

current_file_total: Total bytes for current file.

folder_bytes_uploaded: Bytes uploaded in current folder.

folder_bytes_downloaded: Bytes downloaded in current folder.

folder_bytes_total: Total bytes for current folder.

folder_files_uploaded: Files uploaded in current folder.

folder_files_downloaded: Files downloaded in current folder.

total_bytes_uploaded: Total bytes uploaded across all operations.

total_bytes_downloaded: Total bytes downloaded across all operations.

total_files_uploaded: Total files uploaded across all operations.

total_files_downloaded: Total files downloaded across all operations.

error_message: Error message (for error events).

stats: Sync statistics (for sync_complete event).

Configuration

SyncConfig

class SyncConfig

Configuration for sync operations.

chunk_size: Chunk size for uploads in bytes (default: 5MB).

multipart_threshold: File size threshold for multipart uploads in bytes (default: 50MB).

max_retries: Maximum number of retries for failed operations (default: 3).

retry_delay: Delay between retries in seconds (default: 1.0).

load_sync_pairs_from_json(file_path: Path) → list[SyncPair]

Load sync pairs from a JSON configuration file.

Parameters:: file_path (Path) – Path to JSON config file
Returns:: List of configured sync pairs
Return type:: list[SyncPair]
Raises:: SyncConfigError – If config file is invalid

Example JSON format:

{
  "pairs": [
    {
      "source_root": "/home/user/documents",
      "destination_root": "/backup/documents",
      "mode": "twoWay"
    }
  ]
}

Constants

DEFAULT_CHUNK_SIZE: Default chunk size for uploads (5MB).

DEFAULT_MULTIPART_THRESHOLD: Default file size threshold for multipart uploads (50MB).

DEFAULT_MAX_RETRIES: Default maximum number of retries (3).

DEFAULT_RETRY_DELAY: Default delay between retries in seconds (1.0).

DEFAULT_TRANSFERS_LIMIT: Default maximum concurrent transfers (5).

DEFAULT_OPERATIONS_LIMIT: Default maximum concurrent operations (10).

DEFAULT_BATCH_SIZE: Default batch size for operations (100).

DEFAULT_IGNORE_FILE_NAME: Default ignore file name (“.syncignore”).

DEFAULT_STATE_DIR_NAME: Default state directory name (“.sync_state”).

format_size(bytes: int) → str

Format byte size in human-readable form.

Parameters:: bytes (int) – Size in bytes
Returns:: Formatted size string (e.g., “1.5 MB”)
Return type:: str

Example:

>>> format_size(1536)
"1.5 KB"
>>> format_size(5242880)
"5.0 MB"

Exceptions

exception SyncConfigError: Raised when sync configuration is invalid.

exception SyncOperationError: Raised when a sync operation fails.

exception StorageError: Raised when a storage operation fails.

Protocols

See Storage Protocols for detailed protocol documentation.

StorageClientProtocol - Interface for storage backends
FileEntryProtocol - Interface for file/folder metadata
FileEntriesManagerProtocol - Interface for managing file collections
OutputHandlerProtocol - Interface for output handling
SpinnerFactoryProtocol - Interface for progress spinners
ProgressBarFactoryProtocol - Interface for progress bars

Next Steps

Examples - See complete usage examples
Storage Protocols - Learn about implementing storage backends
Core Concepts - Understand core concepts