tzst/docs/api/exceptions.md

Exceptions API

Custom exception classes used by tzst for comprehensive error handling and debugging.

.. automodule:: tzst.exceptions
   :members:
   :undoc-members:
   :show-inheritance:

Overview

The tzst library provides a comprehensive hierarchy of exceptions to help identify and handle different types of errors that may occur during archive operations. All exceptions inherit from the base TzstError class, making it easy to catch all tzst-related errors with a single exception handler.

Exception Hierarchy

TzstError (base exception)
├── TzstArchiveError (archive operation failures)
├── TzstCompressionError (compression failures)
└── TzstDecompressionError (decompression failures)

Exception Classes

Base Exception

TzstError

.. autoexception:: tzst.exceptions.TzstError
   :members:
   :show-inheritance:

The base exception class for all tzst operations. Catch this exception to handle any tzst-related error in your application.

Usage:

from tzst import create_archive, TzstError

try:
    create_archive("backup.tzst", ["files/"])
except TzstError as e:
    print(f"tzst operation failed: {e}")

Archive Operation Exceptions

TzstArchiveError

.. autoexception:: tzst.exceptions.TzstArchiveError
   :members:
   :show-inheritance:

Raised when archive operations fail, such as:

• Archive file cannot be opened or created
• File permissions prevent archive access
• Archive structure is malformed
• Tar operations fail within the archive
• Atomic file operations fail during creation

Common Scenarios:

• Invalid archive file path
• Insufficient disk space
• File permission errors
• Corrupt archive structure

Compression Exceptions

TzstCompressionError

.. autoexception:: tzst.exceptions.TzstCompressionError
   :members:
   :show-inheritance:

Raised when compression operations fail, including:

• Invalid compression level is specified
• Disk space is insufficient during compression
• Input data cannot be compressed due to corruption
• Zstandard compression encounters an internal error

Common Scenarios:

• Compression level out of range (1-22)
• Insufficient disk space during compression
• Source file corruption
• Zstandard library errors

Decompression Exceptions

TzstDecompressionError

.. autoexception:: tzst.exceptions.TzstDecompressionError
   :members:
   :show-inheritance:

Raised when decompression operations fail, such as:

• Archive file is corrupted or incomplete
• Archive was not created with zstandard compression
• Decompression buffer overflows or underflows
• Archive format is invalid or unsupported

Common Scenarios:

• Corrupted or truncated archive files
• Non-zstandard compressed archives
• Invalid tar structure within archive
• Archive format version mismatches

Error Handling Best Practices

Basic Error Handling

from tzst import create_archive, TzstArchiveError, TzstCompressionError

try:
    create_archive("backup.tzst", ["documents/"])
except TzstCompressionError as e:
    print(f"Compression failed: {e}")
except TzstArchiveError as e:
    print(f"Archive operation failed: {e}")

Comprehensive Error Handling

from tzst import extract_archive, TzstError

try:
    extract_archive("backup.tzst", "restore/")
except TzstError as e:
    # Catch any tzst-related error
    print(f"Operation failed: {e}")
    # Perform cleanup or fallback operations

Specific Exception Handling

from tzst import TzstArchive, TzstDecompressionError, TzstArchiveError

def safe_extract(archive_path, output_dir):
    try:
        with TzstArchive(archive_path, "r") as archive:
            # Test integrity first
            if not archive.test():
                print("Archive integrity check failed")
                return False
            
            # Extract files
            archive.extractall(output_dir)
            return True
            
    except TzstDecompressionError as e:
        print(f"Archive is corrupted or invalid: {e}")
        return False
    except TzstArchiveError as e:
        print(f"Archive operation failed: {e}")
        return False
    except FileNotFoundError:        print(f"Archive file not found: {archive_path}")
        return False
    except PermissionError:
        print(f"Permission denied accessing: {archive_path}")
        return False

Logging Integration

import logging
from tzst import test_archive, TzstDecompressionError, TzstError

logger = logging.getLogger(__name__)

def verify_archive(archive_path):
    """Verify archive integrity with comprehensive logging."""
    try:
        if test_archive(archive_path):
            logger.info(f"Archive {archive_path} is valid")
            return True
    except TzstDecompressionError as e:
        logger.error(f"Archive {archive_path} is corrupted: {e}")
    except TzstError as e:
        logger.error(f"tzst error for {archive_path}: {e}")
    except Exception as e:
        logger.error(f"Unexpected error testing {archive_path}: {e}")
    
    return False

Error Recovery Patterns

from tzst import create_archive, extract_archive, TzstError
from pathlib import Path
import tempfile
import shutil

def robust_backup_and_restore(source_dir, backup_path, restore_dir):
    """Robust backup with error recovery and validation."""
    temp_backup = None
    
    try:
        # Create backup with temporary file for atomicity
        with tempfile.NamedTemporaryFile(suffix='.tzst', delete=False) as temp_file:
            temp_backup = Path(temp_file.name)
        
        # Create archive
        create_archive(temp_backup, [source_dir], compression_level=6)
        
        # Verify archive before moving to final location
        if not test_archive(temp_backup):
            raise TzstArchiveError("Created archive failed integrity check")
        
        # Move to final location atomically
        shutil.move(temp_backup, backup_path)
        temp_backup = None  # Successfully moved
        
        # Test restoration
        extract_archive(backup_path, restore_dir)
        
        print(f"Backup and restore completed successfully")
        return True
        
    except TzstError as e:
        print(f"tzst operation failed: {e}")
        # Cleanup and recovery logic
        if restore_dir.exists():
            shutil.rmtree(restore_dir)
        return False
          except Exception as e:
        print(f"Unexpected error: {e}")
        return False
        
    finally:
        # Cleanup temporary files
        if temp_backup and temp_backup.exists():
            temp_backup.unlink()