API Reference

This section contains the complete API documentation for tzst, providing detailed information about classes, functions, and exceptions.

Overview

The tzst library provides both high-level convenience functions and a comprehensive class-based API for working with .tzst/.tar.zst archives. The library is designed with security, performance, and ease of use in mind.

Main Components

  • Core API: Core functionality including TzstArchive class and convenience functions for archive operations

  • CLI API: Command-line interface functions and utilities for batch operations

  • Exceptions API: Custom exception classes for comprehensive error handling and debugging

Architecture Overview

The tzst library follows a layered architecture:

  1. High-Level API: Convenience functions for common operations

  2. Class-Based API: TzstArchive class for advanced control

  3. CLI Interface: Command-line tools for interactive and scripted use

  4. Exception System: Comprehensive error handling for robust applications

Quick Reference

Core Classes

TzstArchive

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

The main class for archive manipulation with context manager support and comprehensive functionality.

Convenience Functions

create_archive

Create a new .tzst archive with atomic file operations.

extract_archive

Extract files from a .tzst archive.

list_archive

List contents of a .tzst archive.

test_archive

Test the integrity of a .tzst archive.

High-level functions that provide simple interfaces for common archive operations.

CLI Functions

main

Main entry point for the tzst command-line interface.

create_parser

Create and configure the command-line argument parser.

print_banner

Print the version and copyright banner.

format_size

Format file size in human-readable format.

validate_compression_level

Validate and return compression level.

Command-line interface utilities for interactive and batch operations.

Exception Classes

TzstError

Base exception for all tzst operations.

TzstArchiveError

Exception raised when archive operations fail.

TzstCompressionError

Exception raised when compression operations fail.

TzstDecompressionError

Exception raised when decompression operations fail.

Exception hierarchy for comprehensive error handling and debugging support.

Key Features

Security First

  • Built-in path traversal protection

  • Multiple security filter options

  • Safe extraction by default

High Performance

  • Zstandard compression with configurable levels

  • Streaming support for large archives

  • Memory-efficient operations

Developer Friendly

  • Clean, Pythonic API

  • Comprehensive error handling

  • Context manager support

  • Extensive documentation and examples

Cross-Platform

  • Works on Windows, macOS, and Linux

  • Consistent behavior across platforms

  • Native performance optimizations