Core API

The core module provides the main functionality for working with tzst archives, including the primary TzstArchive class and high-level convenience functions.

Core functionality for tzst archives.

class tzst.core.ConflictResolution(*values)[source]

Bases: Enum

Enum for conflict resolution strategies.

ASK = 'ask'
AUTO_RENAME = 'auto_rename'
AUTO_RENAME_ALL = 'auto_rename_all'
EXIT = 'exit'
REPLACE = 'replace'
REPLACE_ALL = 'replace_all'
SKIP = 'skip'
SKIP_ALL = 'skip_all'
class tzst.core.ConflictResolutionState(initial_resolution: ConflictResolution | None = None)[source]

Bases: object

State management for conflict resolution during extraction.

__init__(initial_resolution: ConflictResolution | None = None)[source]
property apply_to_all: bool

Check if the current resolution applies to all future conflicts.

property current_resolution: ConflictResolution | None

Get the current resolution state.

should_continue() → bool[source]

Check if extraction should continue.

update_resolution(resolution: ConflictResolution) → None[source]

Update the global resolution state.

class tzst.core.TzstArchive(filename: str | Path, mode: str = 'r', compression_level: int = 3, streaming: bool = False)[source]

Bases: object

A class for handling .tzst/.tar.zst archives.

__enter__()[source]

Enter context manager.

__exit__(exc_type, exc_val, exc_tb)[source]

Exit context manager.

__init__(filename: str | Path, mode: str = 'r', compression_level: int = 3, streaming: bool = False)[source]

Initialize a TzstArchive.

Parameters:

  • filename – Path to the archive file

  • mode – Open mode (‘r’, ‘w’, ‘a’)

  • compression_level – Zstandard compression level (1-22)

  • streaming – If True, use streaming mode for reading (reduces memory usage for very large archives but may limit some tarfile operations that require seeking. Recommended for archives > 100MB)

add(name: str | Path, arcname: str | None = None, recursive: bool = True)[source]

Add a file or directory to the archive.

Parameters:

  • name – Path to file or directory to add

  • arcname – Alternative name for the file in the archive

  • recursive – If True, add directories recursively

See also

create_archive(): Convenience function for creating archives

close()[source]

Close the archive.

extract(member: str | None = None, path: str | Path = '.', set_attrs: bool = True, numeric_owner: bool = False, filter: str | Callable | None = 'data')[source]

Extract files from the archive.

Parameters:

  • member – Specific member to extract (None for all)

  • path – Destination directory

  • set_attrs – Whether to set file attributes

  • numeric_owner – Whether to use numeric owner

  • filter – Extraction filter for security. Can be: - ‘data’: Safe filter for cross-platform data archives (default, recommended) - ‘tar’: Honor most tar features but block dangerous ones - ‘fully_trusted’: Honor all metadata (use only for trusted archives) - None: Use default behavior (may show deprecation warning in Python 3.12+) - callable: Custom filter function

Warning

Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents dangerous security issues like path traversal attacks.

Note

In streaming mode, extracting specific members is not supported. Some extraction operations may be limited due to the sequential nature of streaming mode.

See also

extract_archive(): Convenience function for extracting archives

extractall(path: str | Path = '.', members: list[TarInfo] | None = None, *, numeric_owner: bool = False, filter: str | Callable | None = 'data')[source]

Extract all members from the archive.

Parameters:

  • path – Destination directory (default: current directory)

  • members – Specific members to extract (None for all)

  • numeric_owner – Whether to use numeric owner IDs

  • filter – Extraction filter for security. Can be: - ‘data’: Safe filter for cross-platform data archives - ‘tar’: Honor most tar features but block dangerous ones - ‘fully_trusted’: Honor all metadata (trusted archives only) - None: Use default behavior (may show deprecation warning) - callable: Custom filter function

Warning

Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents dangerous security issues like path traversal attacks.

Note

In streaming mode, extracting specific members is not supported. Some extraction operations may be limited due to the sequential nature of streaming mode.

See also

extract(): Extract a single member from the archive extract_archive(): Convenience function for extracting archives

extractfile(member: str | TarInfo)[source]

Extract a file-like object from the archive.

Parameters:

member – Member name or TarInfo object

Returns:

File-like object or None if member is not a file

getmembers() → list[TarInfo][source]

Get list of all members in the archive.

getnames() → list[str][source]

Get list of all member names in the archive.

list(verbose: bool = False) → list[dict][source]

List contents of the archive.

Parameters:

verbose – Include detailed information

Returns:

List of file information dictionaries

See also

getmembers(): Get TarInfo objects for all archive members getnames(): Get names of all archive members list_archive(): Convenience function for listing archives

open()[source]

Open the archive.

See also

close(): Method to close the archive

test() → bool[source]

Test the integrity of the archive.

Returns:

True if archive is valid, False otherwise

See also

test_archive(): Convenience function for testing archive integrity

tzst.core.create_archive(archive_path: str | Path, files: Sequence[str | Path], compression_level: int = 3, use_temp_file: bool = True) → None[source]

Create a new .tzst archive with atomic file operations.

Parameters:

  • archive_path – Path for the new archive

  • files – List of files/directories to add

  • compression_level – Zstandard compression level (1-22)

  • use_temp_file – If True, create archive in temporary file first, then move to final location for atomic operation

See also

TzstArchive.add(): Method for adding files to an open archive

tzst.core.extract_archive(archive_path: str | Path, extract_path: str | Path = '.', members: list[str] | None = None, flatten: bool = False, streaming: bool = False, filter: str | Callable | None = 'data', conflict_resolution: ConflictResolution | str = ConflictResolution.REPLACE, interactive_callback: Callable[[Path], ConflictResolution] | None = None) → None[source]

Extract files from a .tzst archive.

Parameters:

  • archive_path – Path to the archive

  • extract_path – Destination directory

  • members – Specific members to extract (None for all)

  • flatten – If True, extract without directory structure

  • streaming – If True, use streaming mode (memory efficient for large archives)

  • filter – Extraction filter for security. Can be: - ‘data’: Safe filter for cross-platform data archives (default) - ‘tar’: Honor most tar features but block dangerous ones - ‘fully_trusted’: Honor all metadata (use only for trusted archives) - None: Use default behavior (may show deprecation warning) - callable: Custom filter function

  • conflict_resolution – How to handle file conflicts during extraction

  • interactive_callback – Function to call for interactive conflict resolution

Warning

Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents dangerous security issues like path traversal attacks.

See Also: TzstArchive.extract(): Method for extracting from an open archive

tzst.core.list_archive(archive_path: str | Path, verbose: bool = False, streaming: bool = False) → list[dict][source]

List contents of a .tzst archive.

Parameters:

  • archive_path – Path to the archive

  • verbose – Include detailed information

  • streaming – If True, use streaming mode (memory efficient for large archives)

Returns:

List of file information dictionaries

See also

TzstArchive.list(): Method for listing an open archive

tzst.core.test_archive(archive_path: str | Path, streaming: bool = False) → bool[source]

Test the integrity of a .tzst archive.

Parameters:

  • archive_path – Path to the archive

  • streaming – If True, use streaming mode (memory efficient for large archives)

Returns:

True if archive is valid, False otherwise

See also

TzstArchive.test(): Method for testing an open archive

TzstArchive Class

The main class for handling .tzst/.tar.zst archives with comprehensive functionality for creation, extraction, and manipulation.

class tzst.TzstArchive(filename: str | Path, mode: str = 'r', compression_level: int = 3, streaming: bool = False)[source]

Bases: object

A class for handling .tzst/.tar.zst archives.

__enter__()[source]

Enter context manager.

__exit__(exc_type, exc_val, exc_tb)[source]

Exit context manager.

__init__(filename: str | Path, mode: str = 'r', compression_level: int = 3, streaming: bool = False)[source]

Initialize a TzstArchive.

Parameters:

  • filename – Path to the archive file

  • mode – Open mode (‘r’, ‘w’, ‘a’)

  • compression_level – Zstandard compression level (1-22)

  • streaming – If True, use streaming mode for reading (reduces memory usage for very large archives but may limit some tarfile operations that require seeking. Recommended for archives > 100MB)

add(name: str | Path, arcname: str | None = None, recursive: bool = True)[source]

Add a file or directory to the archive.

Parameters:

  • name – Path to file or directory to add

  • arcname – Alternative name for the file in the archive

  • recursive – If True, add directories recursively

See also

create_archive(): Convenience function for creating archives

close()[source]

Close the archive.

extract(member: str | None = None, path: str | Path = '.', set_attrs: bool = True, numeric_owner: bool = False, filter: str | Callable | None = 'data')[source]

Extract files from the archive.

Parameters:

  • member – Specific member to extract (None for all)

  • path – Destination directory

  • set_attrs – Whether to set file attributes

  • numeric_owner – Whether to use numeric owner

  • filter – Extraction filter for security. Can be: - ‘data’: Safe filter for cross-platform data archives (default, recommended) - ‘tar’: Honor most tar features but block dangerous ones - ‘fully_trusted’: Honor all metadata (use only for trusted archives) - None: Use default behavior (may show deprecation warning in Python 3.12+) - callable: Custom filter function

Warning

Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents dangerous security issues like path traversal attacks.

Note

In streaming mode, extracting specific members is not supported. Some extraction operations may be limited due to the sequential nature of streaming mode.

See also

extract_archive(): Convenience function for extracting archives

extractall(path: str | Path = '.', members: list[TarInfo] | None = None, *, numeric_owner: bool = False, filter: str | Callable | None = 'data')[source]

Extract all members from the archive.

Parameters:

  • path – Destination directory (default: current directory)

  • members – Specific members to extract (None for all)

  • numeric_owner – Whether to use numeric owner IDs

  • filter – Extraction filter for security. Can be: - ‘data’: Safe filter for cross-platform data archives - ‘tar’: Honor most tar features but block dangerous ones - ‘fully_trusted’: Honor all metadata (trusted archives only) - None: Use default behavior (may show deprecation warning) - callable: Custom filter function

Warning

Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents dangerous security issues like path traversal attacks.

Note

In streaming mode, extracting specific members is not supported. Some extraction operations may be limited due to the sequential nature of streaming mode.

See also

extract(): Extract a single member from the archive extract_archive(): Convenience function for extracting archives

extractfile(member: str | TarInfo)[source]

Extract a file-like object from the archive.

Parameters:

member – Member name or TarInfo object

Returns:

File-like object or None if member is not a file

getmembers() → list[TarInfo][source]

Get list of all members in the archive.

getnames() → list[str][source]

Get list of all member names in the archive.

list(verbose: bool = False) → list[dict][source]

List contents of the archive.

Parameters:

verbose – Include detailed information

Returns:

List of file information dictionaries

See also

getmembers(): Get TarInfo objects for all archive members getnames(): Get names of all archive members list_archive(): Convenience function for listing archives

open()[source]

Open the archive.

See also

close(): Method to close the archive

test() → bool[source]

Test the integrity of the archive.

Returns:

True if archive is valid, False otherwise

See also

test_archive(): Convenience function for testing archive integrity

Key Features

  • Context Manager Support: Use with with statements for automatic resource management

  • Multiple Access Modes: Read (‘r’), write (‘w’), and append (‘a’) modes

  • Streaming Support: Memory-efficient processing for large archives

  • Security Features: Built-in protection against path traversal attacks

  • Flexible Extraction: Support for selective extraction and conflict resolution

Usage Examples

# Create a new archive
with TzstArchive("backup.tzst", "w", compression_level=6) as archive:
    archive.add("important_file.txt")
    archive.add("documents/", recursive=True)

# Read an existing archive
with TzstArchive("backup.tzst", "r") as archive:
    contents = archive.list(verbose=True)
    is_valid = archive.test()
    archive.extractall("restore/")

Convenience Functions

High-level functions for common archive operations without needing to instantiate the TzstArchive class directly.

create_archive

tzst.create_archive(archive_path: str | Path, files: Sequence[str | Path], compression_level: int = 3, use_temp_file: bool = True) → None[source]

Create a new .tzst archive with atomic file operations.

Parameters:

  • archive_path – Path for the new archive

  • files – List of files/directories to add

  • compression_level – Zstandard compression level (1-22)

  • use_temp_file – If True, create archive in temporary file first, then move to final location for atomic operation

See also

TzstArchive.add(): Method for adding files to an open archive

Creates a new tzst archive from the specified files and directories.

Key Features:

  • Configurable compression levels (1-22)

  • Atomic creation using temporary files

  • Automatic path validation and normalization

  • Support for both files and directories

extract_archive

tzst.extract_archive(archive_path: str | Path, extract_path: str | Path = '.', members: list[str] | None = None, flatten: bool = False, streaming: bool = False, filter: str | Callable | None = 'data', conflict_resolution: ConflictResolution | str = ConflictResolution.REPLACE, interactive_callback: Callable[[Path], ConflictResolution] | None = None) → None[source]

Extract files from a .tzst archive.

Parameters:

  • archive_path – Path to the archive

  • extract_path – Destination directory

  • members – Specific members to extract (None for all)

  • flatten – If True, extract without directory structure

  • streaming – If True, use streaming mode (memory efficient for large archives)

  • filter – Extraction filter for security. Can be: - ‘data’: Safe filter for cross-platform data archives (default) - ‘tar’: Honor most tar features but block dangerous ones - ‘fully_trusted’: Honor all metadata (use only for trusted archives) - None: Use default behavior (may show deprecation warning) - callable: Custom filter function

  • conflict_resolution – How to handle file conflicts during extraction

  • interactive_callback – Function to call for interactive conflict resolution

Warning

Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents dangerous security issues like path traversal attacks.

See Also: TzstArchive.extract(): Method for extracting from an open archive

Extracts files from a tzst archive with advanced options for handling conflicts and filtering.

Key Features:

  • Selective extraction with member filtering

  • Multiple conflict resolution strategies

  • Flatten option to extract all files to a single directory

  • Streaming mode for memory efficiency

  • Security filters to prevent path traversal attacks

list_archive

tzst.list_archive(archive_path: str | Path, verbose: bool = False, streaming: bool = False) → list[dict][source]

List contents of a .tzst archive.

Parameters:

  • archive_path – Path to the archive

  • verbose – Include detailed information

  • streaming – If True, use streaming mode (memory efficient for large archives)

Returns:

List of file information dictionaries

See also

TzstArchive.list(): Method for listing an open archive

Lists the contents of a tzst archive with optional detailed information.

Returns:

  • List of dictionaries containing file information

  • Each entry includes name, size, modification time, and type

  • Verbose mode provides additional metadata

test_archive

tzst.test_archive(archive_path: str | Path, streaming: bool = False) → bool[source]

Test the integrity of a .tzst archive.

Parameters:

  • archive_path – Path to the archive

  • streaming – If True, use streaming mode (memory efficient for large archives)

Returns:

True if archive is valid, False otherwise

See also

TzstArchive.test(): Method for testing an open archive

Tests the integrity of a tzst archive to verify it can be successfully decompressed.

Returns:

  • True if the archive is valid and can be extracted

  • False if the archive is corrupted or cannot be processed

Enums and Supporting Classes

ConflictResolution

Enumeration for handling file conflicts during extraction:

  • REPLACE: Overwrite existing files

  • SKIP: Skip existing files

  • REPLACE_ALL: Overwrite all existing files without prompting

  • SKIP_ALL: Skip all existing files without prompting

  • AUTO_RENAME: Automatically rename conflicting files

  • AUTO_RENAME_ALL: Automatically rename all conflicting files

  • ASK: Prompt user for each conflict (interactive mode)

  • EXIT: Stop extraction on first conflict

ConflictResolutionState

State management class for tracking conflict resolution decisions during batch operations.