xixu-me/tzst

0 Fork 0

Files

T

xixu-me b5f7fa8dca Enhance documentation with SEO metadata and layout

Added a new custom layout template for SEO and social media meta tags. Updated multiple documentation files with metadata for improved search engine optimization and social sharing. Enhanced Sphinx configuration with additional HTML options and meta tags.

2025-06-06 17:50:43 +08:00

4.0 KiB

Raw Blame History

html_meta

description	keywords	og:title	og:description	twitter:title	twitter:description
tzst Core API - TzstArchive class and convenience functions for tar.zst archive operations	tzst core API, TzstArchive, Python archive class, tar.zst functions	tzst Core API Reference	Core API documentation for tzst - TzstArchive class and convenience functions	tzst Core API Reference	Core API documentation for tzst - TzstArchive class and convenience functions

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.