xixu-me/tzst

0 Fork 0

Files

T

xixu-me abbeab83f1 Update documentation with indexing and references

Added the ':no-index:' directive to CLI, core, and exceptions API documentation to exclude them from indexing. Updated examples documentation to use Sphinx references for better navigation and added section anchors for improved structure.

2025-06-06 17:39:15 +08:00

3.5 KiB

Raw Blame History

Core API

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

.. automodule:: tzst.core
   :members:
   :undoc-members:
   :show-inheritance:
   :no-index:

TzstArchive Class

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

.. autoclass:: tzst.TzstArchive
   :members:
   :undoc-members:
   :show-inheritance:
   :special-members: __init__, __enter__, __exit__

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

.. autofunction:: tzst.create_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

.. autofunction:: tzst.extract_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

.. autofunction:: tzst.list_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

.. autofunction:: tzst.test_archive

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