stouputils.backup module — stouputils 1.0.18 documentation

# 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