tzst Documentation

Welcome to tzst, the next-generation Python library engineered for modern archive management, leveraging cutting-edge Zstandard compression to deliver superior performance, security, and reliability.

Contents:

• Quick Start Guide
  • Installation
  • Basic Usage
  • Advanced Features
  • Error Handling
  • Next Steps
  • Read an Existing Archive
  • Common Patterns
  • Further Learning
• Performance Guide
  • Performance Tips
  • Comparison with Other Tools
  • Benchmarking Examples
  • Best Practices
  • Hardware Considerations
  • Integration with Build Systems
• Examples
  • Table of Contents
  • Basic Operations
  • Command Line Usage
  • Advanced Archive Creation
  • Flexible Extraction
  • Security and Filtering
  • Performance Optimization
  • Error Handling
  • Real-World Scenarios
  • Integration Examples
• API Reference
  • Core API
  • CLI API
  • Exceptions API
  • Overview
  • Key Features
• Development Guide
  • Setting up Development Environment
  • Running Tests
  • Code Quality
  • Documentation
  • Project Structure
  • Contributing Workflow
  • Development Tips
  • Release Process
  • Getting Help
  • Code of Conduct
  • Recognition
• Index

What is tzst?

tzst is a modern Python library built exclusively for Python 3.12+ that provides comprehensive support for creating, extracting, and managing .tzst and .tar.zst archives. It combines the proven reliability of the tar format with the superior compression efficiency of Zstandard (zstd) to deliver:

• Superior Performance: Fast compression and decompression with excellent compression ratios

• Enterprise-Grade Security: Safe extraction with built-in protections against path traversal attacks

• Memory Efficiency: Streaming mode for handling large archives with minimal memory usage

• Cross-Platform Compatibility: Works seamlessly on Windows, macOS, and Linux

• Developer-Friendly: Clean, Pythonic API with comprehensive error handling

Key Features

Advanced Compression

• Zstandard Compression: Best-in-class compression algorithm with configurable levels (1-22)

• Multiple Extensions: Support for both .tzst and .tar.zst file extensions

• Streaming Support: Memory-efficient processing for large archives

Security First

• Safe by Default: Uses ‘data’ filter for secure extraction without dangerous path traversal

• Multiple Filter Options: Choose from ‘data’, ‘tar’, or ‘fully_trusted’ filters based on your security needs

• Atomic Operations: All file operations use temporary files with atomic moves to prevent corruption

Dual Interfaces

• Command Line: Intuitive CLI with comprehensive options for batch operations

• Python API: Clean, object-oriented interface for programmatic use

• Convenience Functions: High-level functions for common operations

High Performance

• Optimized I/O: Efficient buffering and streaming for large files

• Conflict Resolution: Intelligent handling of file conflicts during extraction

• Cross-Platform: Native performance on all major operating systems

Quick Example

from tzst import TzstArchive, create_archive, extract_archive

# Create an archive
create_archive("backup.tzst", ["documents/", "photos/"], compression_level=5)

# Extract an archive
extract_archive("backup.tzst", "restore/")

# Work with archives programmatically
with TzstArchive("data.tzst", "r") as archive:
    contents = archive.list(verbose=True)
    archive.extract("important.txt", "output/")
    is_valid = archive.test()

Installation

From PyPI

pip install tzst

From GitHub Releases

Download platform-specific standalone executables from GitHub Releases - no Python installation required!

Supported Platforms

Platform	Architecture	File
Linux	x86_64	tzst-{version}-linux-amd64.zip
Linux	ARM64	tzst-{version}-linux-arm64.zip
Windows	x64	tzst-{version}-windows-amd64.zip
Windows	ARM64	tzst-{version}-windows-arm64.zip
macOS	Intel	tzst-{version}-darwin-amd64.zip
macOS	Apple Silicon	tzst-{version}-darwin-arm64.zip

Installation Steps

1. Download the appropriate archive for your platform from the latest releases page

2. Extract the archive to get the tzst executable (or tzst.exe on Windows)

3. Move the executable to a directory in your PATH:

   • Linux/macOS: sudo mv tzst /usr/local/bin/

   • Windows: Add the directory containing tzst.exe to your PATH environment variable

4. Verify installation: tzst --help

Benefits of Binary Installation

• No Python required - Standalone executable

• Faster startup - No Python interpreter overhead

• Easy deployment - Single file distribution

• Consistent behavior - Bundled dependencies

Using uvx (No Installation)

Run tzst directly without installation using uvx:

uvx tzst --help
uvx tzst a archive.tzst file1.txt file2.txt directory/
uvx tzst x archive.tzst

Perfect for one-time usage, testing, CI/CD pipelines, and isolated environments.

From Source

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install .

Getting Started

For a quick introduction, see the Quick Start Guide guide. For comprehensive usage examples, explore the Examples section.

Installation Options

1. PyPI Installation: pip install tzst

2. Standalone Binaries: Download from GitHub Releases

3. uvx (No Installation): Run directly with uvx tzst

4. From Source: Clone and install from repository

API Documentation

Complete API documentation is available in the API Reference section, covering:

• Core API: Main classes and functions

• CLI API: Command-line interface

• Exceptions API: Error handling

Development

For comprehensive development information, see the Development Guide guide, which covers:

• Setting up development environment

• Running tests and code quality checks

• Documentation building

• Contributing workflow and guidelines

• Project structure and best practices

Quick Start

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]
pytest

Contributing

We welcome contributions! Please read our Contributing Guide for:

• Development setup and project structure

• Code style guidelines and best practices

• Testing requirements and writing tests

• Pull request process and review workflow

Types of Contributions Welcome

• Bug fixes - Fix issues in existing functionality

• Features - Add new capabilities to the library

• Documentation - Improve or add documentation

• Tests - Add or improve test coverage

• Performance - Optimize existing code

• Security - Address security vulnerabilities

Acknowledgments

• Meta Zstandard for the excellent compression algorithm

• python-zstandard for Python bindings

• The Python community for inspiration and feedback

License

Copyright © 2025 Xi Xu. All rights reserved.

Licensed under the BSD 3-Clause license.

Documentation Guide

1. Quick Start Guide - Get up and running quickly with basic examples

2. Performance Guide - Performance optimization guide and comparisons

3. Examples - Comprehensive usage examples and patterns

4. API Reference - Complete API reference documentation

5. Development Guide - Development and contribution guidelines

6. Index - Index of all documented items

Requirements

• Python 3.12 or higher

• zstandard >= 0.19.0