restore_files#

qx_utilities.general.snapshots.restore_files(source, target=None, overwrite=False, filelist=None, _log=None)#

restore_files source=<path to backup folder or archive> [target=<path to target folder>] [overwrite=False] [filelist=None]

Restores files from a backup created by backup_files function. The backup can be in any format (original, gzip, or zip). Files are restored to their original locations or to a specified target directory, with automatic decompression of gzipped files when needed.

Parameters

--source (str):

The path to the backup location. Can be either:

  • A directory containing backed up files and file_list.txt

  • A ZIP archive (.zip file) created with store=zip mode

The backup must contain a valid file_list.txt manifest describing the backup structure and original file locations.

--target (str, default None):

The target directory where files should be restored:

  • If provided: Files are restored relative to this directory path, using the relative paths from file_list.txt

  • If None: Files are restored to their original location as specified in the "source folder" line of file_list.txt

Parent directories are created automatically if they don't exist.

--overwrite (bool or str, default False):

Controls behavior when restored files already exist at target:

  • False: If ANY target files exist, raise an error and do not restore anything. This prevents accidental overwriting.

  • True: Overwrite all existing files with backed up versions.

  • "skip": Only restore files that don't currently exist at the target location. Skip files that already exist without error.

--filelist (list or str, default None):

Optional list of specific files to restore. If not provided, all files from the backup are restored. Can be specified as:

  • List of backup numbers: ['b001', 'b002', 'b005'] - restores only those specific backup entries

  • List of original paths: ['configs/settings.json', 'data/file.txt'] - restores only files matching these exact relative paths

  • Comma-separated string: 'b001, b002, configs/settings.json' - parsed into list of items

  • Single string: 'b001' or 'configs/settings.json'

  • Mixed format: ['b001', 'configs/settings.json'] - matches either backup numbers or original paths

Files not matching any entry in filelist are skipped during restoration.

Backup Format Detection:

The function automatically detects the backup format:

  • ZIP archives: Extracts and reads file_list.txt from the archive

  • Directories: Reads file_list.txt from the directory

  • Invalid backups without file_list.txt generate an error

Manifest File Structure:

The file_list.txt must follow this format:

source folder: /original/path/to/source
store: <original|gzip|zip>
b001: relative/path/file1.txt
b002: relative/path/file2.json
b003: data/file3.csv
Automatic Decompression:

When restoring gzipped backups (store: gzip):

  • Files that were originally uncompressed (without .gz extension) are automatically decompressed during restoration

  • Files that were already compressed (with .gz extension) are copied as-is without decompression

  • Decompression is determined by comparing the original filename in file_list.txt with the backup filename

Restoration Process:

  1. Validate backup source and read file_list.txt

  2. Parse source folder path and store mode from manifest

  3. Determine target directory (provided or from manifest)

  4. Check for existing files based on overwrite mode

  5. Create necessary parent directories

  6. Restore each file: - Remove b[n]_ prefix from backup filename - Decompress if needed (gzip mode only) - Copy to relative path specified in manifest

  7. Report restoration summary

Notes

  • The function preserves the original directory structure from file_list.txt

  • Backup file prefixes (b001_, b002_, etc.) are automatically removed

  • With overwrite="skip", partial restoration is supported

  • For gzip backups, only files that need decompression are unzipped

  • The restore operation is atomic when overwrite=False (all or nothing)

Examples

Restore to original location:

restore_files(source="/path/to/backups/config_backup")

Restore to different location:

restore_files(
    source="/path/to/backups/subject01_data",
    target="/path/to/new/location",
)

Restore from ZIP archive, overwriting existing files:

restore_files(
    source="/path/to/archives/results_2024.zip",
    target="/path/to/restore/location",
    overwrite=True,
)

Restore only missing files:

restore_files(
    source="/path/to/backups/config_backup",
    overwrite="skip",
)