stouputils.backup module#

This module provides utilities for backup management.

  • backup_cli: Main entry point for command line usage

  • 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

  • limit_backups: Limits the number of delta backups by consolidating the oldest ones

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

  • extract_hash_from_zipinfo: Extracts the stored hash from a ZipInfo object’s comment

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

  • is_file_in_any_previous_backup: Checks if a file with the same hash exists in any previous backup

stouputils backup examples
backup_cli() → None[source]#

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

# Limit the number of delta backups to 5
python -m stouputils.backup limit 5 /path/to/backups
create_delta_backup(
source_path: str,
destination_folder: str,
exclude_patterns: list[str] | None = None,
) → None[source]#

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[source]#

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'
limit_backups(
max_backups: int,
backup_folder: str,
keep_oldest: bool = True,
) → None[source]#

Limits the number of delta backups by consolidating the oldest ones.

If the number of backups exceeds max_backups, the oldest backups are consolidated into a single backup file, then deleted, until the count is within the limit.

Parameters:

  • max_backups (int) – Maximum number of delta backups to keep

  • backup_folder (str) – Path to the folder containing backups

  • keep_oldest (bool) – If True, never delete the oldest backup (default: True)

Examples:

> limit_backups(5, "/path/to/backups")
[INFO HH:MM:SS] Limiting backups
[INFO HH:MM:SS] Consolidated 3 oldest backups into '/path/to/backups/consolidated_YYYY_MM_DD-HH_MM_SS.zip'
[INFO HH:MM:SS] Deleted 3 old backups
get_file_hash(file_path: str) → str | None[source]#

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[source]#

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]][source]#

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[source]#

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