stouputils.backup module

This module provides utilities for backup management.

• get_file_hash: Computes the SHA-256 hash of a file

• create_delta_backup: Creates a ZIP delta backup, saving only modified or new files while tracking deleted files

• consolidate_backups: Consolidates the files from the given backup and all previous ones into a new ZIP file

• backup_cli: Main entry point for command line usage

get_file_hash(file_path: str) → str | None

Computes the SHA-256 hash of a file.

Parameters:

file_path (str) – Path to the file

Returns:

SHA-256 hash as a hexadecimal string or None if an error occurs

Return type:

str | None

extract_hash_from_zipinfo(zip_info: ZipInfo) → str | None

Extracts the stored hash from a ZipInfo object’s comment.

Parameters:

zip_info (zipfile.ZipInfo) – The ZipInfo object representing a file in the ZIP

Returns:

The stored hash if available, otherwise None

Return type:

str | None

get_all_previous_backups(backup_folder: str, all_before: str | None = None) → dict[str, dict[str, str]]

Retrieves all previous backups in a folder and maps each backup to a dictionary of file paths and their hashes.

Parameters:

• backup_folder (str) – The folder containing previous backup zip files

• all_before (str | None) – Path to the latest backup ZIP file (If endswith “/latest.zip” or “/”, the latest backup will be used)

Returns:

Dictionary mapping backup file paths to dictionaries of {file_path: file_hash}

Return type:

dict[str, dict[str, str]]

is_file_in_any_previous_backup(file_path: str, file_hash: str, previous_backups: dict[str, dict[str, str]]) → bool

Checks if a file with the same hash exists in any previous backup.

Parameters:

• file_path (str) – The relative path of the file

• file_hash (str) – The SHA-256 hash of the file

• previous_backups (dict[str, dict[str, str]]) – Dictionary mapping backup zip paths to their stored file hashes

Returns:

True if the file exists unchanged in any previous backup, False otherwise

Return type:

bool

create_delta_backup(source_path: str, destination_folder: str, exclude_patterns: list[str] | None = None) → None

Creates a ZIP delta backup, saving only modified or new files while tracking deleted files.

Parameters:

• source_path (str) – Path to the source file or directory to back up

• destination_folder (str) – Path to the folder where the backup will be saved

• exclude_patterns (list[str] | None) – List of glob patterns to exclude from backup

Examples:

> create_delta_backup("/path/to/source", "/path/to/backups", exclude_patterns=["libraries/*", "cache/*"])
[INFO HH:MM:SS] Creating ZIP backup
[INFO HH:MM:SS] Backup created: '/path/to/backups/backup_2025_02_18-10_00_00.zip'

consolidate_backups(zip_path: str, destination_zip: str) → None

Consolidates the files from the given backup and all previous ones into a new ZIP file, ensuring that the most recent version of each file is kept and deleted files are not restored.

Parameters:

• zip_path (str) – Path to the latest backup ZIP file (If endswith “/latest.zip” or “/”, the latest backup will be used)

• destination_zip (str) – Path to the destination ZIP file where the consolidated backup will be saved

Examples:

> consolidate_backups("/path/to/backups/latest.zip", "/path/to/consolidated.zip")
[INFO HH:MM:SS] Consolidating backups
[INFO HH:MM:SS] Consolidated backup created: '/path/to/consolidated.zip'

backup_cli()

Main entry point for command line usage.

Examples:

# Create a delta backup, excluding libraries and cache folders
python -m stouputils.backup delta /path/to/source /path/to/backups -x "libraries/*" "cache/*"

# Consolidate backups into a single file
python -m stouputils.backup consolidate /path/to/backups/latest.zip /path/to/consolidated.zip