tzst/docs/quickstart.md

myst

myst

html_meta description keywords og:title og:description twitter:title twitter:description og:type og:image og:url twitter:card twitter:image Quick start guide for tzst - Learn how to install and use the Python tar.zst archive library in minutes tzst tutorial, Python archive tutorial, tar.zst guide, Zstandard compression guide tzst Quick Start Guide Learn how to install and use tzst for Python tar.zst archive management in minutes tzst Quick Start Guide Learn how to install and use tzst for Python tar.zst archive management in minutes website https://tzst.xi-xu.me/_static/tzst-square-logo.png https://tzst.xi-xu.me/ summary_large_image https://tzst.xi-xu.me/_static/tzst-square-logo.png

Quick Start Guide

This guide will get you up and running with tzst in just a few minutes.

(installation)=

Installation

Choose your preferred installation method:

From GitHub Releases

Download standalone executables that don't require Python installation:

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

From PyPI

Using pip:

pip install tzst

Or using uv (recommended):

uv tool install tzst

From Source

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

Development Installation

This project uses modern Python packaging standards:

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

(basic-usage)=

Basic Usage

Command Line Interface

Note

: Download the standalone binary for the best performance and no Python dependency. Alternatively, use uvx tzst for running without installation. See uv documentation for details.

The CLI provides four main operations:

# Create an archive
tzst a archive.tzst file1.txt file2.txt directory/

# Extract an archive  
tzst x archive.tzst

# List archive contents
tzst l archive.tzst

# Test archive integrity
tzst t archive.tzst

Command Reference

Command	Aliases	Description	Streaming Support
a	add, create	Create or add to archive	N/A
x	extract	Extract with full paths	--streaming
e	extract-flat	Extract without directory structure	--streaming
l	list	List archive contents	--streaming
t	test	Test archive integrity	--streaming

CLI Options

• -v, --verbose: Enable verbose output
• -o, --output DIR: Specify output directory (extract commands)
• -l, --level LEVEL: Set compression level 1-22 (create command)
• --streaming: Enable streaming mode for memory-efficient processing
• --filter FILTER: Security filter for extraction (data/tar/fully_trusted)
• --no-atomic: Disable atomic file operations (not recommended)

Create Archives

# Create archive with default compression (level 3)
tzst a backup.tzst documents/ photos/

# Create with high compression
tzst a backup.tzst documents/ photos/ --compression-level 9

# Create from current directory
tzst a project.tzst .

# Specify different output location
tzst a /backups/data.tzst /home/user/important/

Extract Archives

# Extract to current directory
tzst x backup.tzst

# Extract to specific directory
tzst x backup.tzst --output /restore/

# Extract specific files only
tzst x backup.tzst documents/report.pdf photos/vacation.jpg

# Extract with conflict resolution
tzst x backup.tzst --conflict-resolution skip

List Contents

# Simple listing
tzst l backup.tzst

# Detailed listing with file info
tzst l backup.tzst --verbose

# Stream large archives efficiently
tzst l huge-archive.tzst --streaming

Python API

Quick Start

from tzst import create_archive, extract_archive, list_archive, test_archive

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

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

# List contents
contents = list_archive("backup.tzst", verbose=True)
for item in contents:
    print(f"{item['name']} - {item['size']} bytes")

# Test integrity
is_valid = test_archive("backup.tzst")
print(f"Archive is {'valid' if is_valid else 'corrupted'}")

Using the TzstArchive Class

from tzst import TzstArchive

# Create a new archive
with TzstArchive("data.tzst", "w", compression_level=6) as archive:
    archive.add("file.txt")
    archive.add("directory/", recursive=True)
    
    # Add with custom archive name
    archive.add("config/prod.yaml", arcname="config.yaml")

# Read an existing archive
with TzstArchive("data.tzst", "r") as archive:
    # List contents
    contents = archive.list(verbose=True)
    for item in contents:
        print(f"{item['name']} - {item['size']} bytes")
    
    # Test integrity
    is_valid = archive.test()
    print(f"Archive is {'valid' if is_valid else 'corrupted'}")
    
    # Extract specific files
    archive.extract("file.txt", "output/")
    
    # Extract all files
    archive.extractall("restore/")

Advanced Features

Security and Filtering

from tzst import extract_archive

# Safe extraction with built-in security (default)
extract_archive("untrusted.tzst", "safe-output/", filter="data")

# For trusted archives with special features
extract_archive("trusted.tzst", "output/", filter="tar")

Security Filters

tzst provides three security filter options for extraction:

from tzst import extract_archive

# Extract with maximum security (default)
extract_archive("archive.tzst", "output/", filter="data")

# Extract with standard tar compatibility
extract_archive("archive.tzst", "output/", filter="tar")

# Extract with full trust (dangerous - only for trusted archives)
extract_archive("archive.tzst", "output/", filter="fully_trusted")

Security Filter Options:

• data (default): Most secure. Blocks dangerous files, absolute paths, and paths outside extraction directory
• tar: Standard tar compatibility. Blocks absolute paths and directory traversal
• fully_trusted: No security restrictions. Only use with completely trusted archives

Conflict Resolution

from tzst import extract_archive, ConflictResolution

# Skip existing files
extract_archive("archive.tzst", "output/",
                conflict_resolution=ConflictResolution.SKIP_ALL)

# Auto-rename conflicting files
extract_archive("archive.tzst", "output/",
                conflict_resolution=ConflictResolution.AUTO_RENAME_ALL)

Performance Optimization

from tzst import create_archive, extract_archive

# Create with different compression levels
create_archive("fast.tzst", files, compression_level=1)    # Fastest
create_archive("balanced.tzst", files, compression_level=6) # Balanced
create_archive("best.tzst", files, compression_level=22)   # Best compression

# Memory-efficient operations for large archives
extract_archive("huge-archive.tzst", "output/", streaming=True)

Streaming Mode

For large archives (>100MB), use streaming mode to reduce memory usage:

# Memory-efficient operations
with TzstArchive("large-archive.tzst", "r", streaming=True) as archive:
    contents = archive.list()
    archive.extractall("output/")
    is_valid = archive.test()

Note: Streaming mode has limitations - you cannot extract specific files or use random access operations.

File Extensions

The library automatically handles file extensions with intelligent normalization:

• .tzst - Primary extension for tar+zstandard archives
• .tar.zst - Alternative standard extension
• Auto-detection when opening existing archives
• Automatic extension addition when creating archives

from tzst import create_archive

# These all create valid archives
create_archive("backup.tzst", files)      # Creates backup.tzst
create_archive("backup.tar.zst", files)  # Creates backup.tar.zst  
create_archive("backup", files)          # Creates backup.tzst
create_archive("backup.txt", files)      # Creates backup.tzst (normalized)

Atomic Operations

All file creation operations use atomic file operations by default:

• Archives created in temporary files first, then atomically moved
• Automatic cleanup if process is interrupted
• No risk of corrupted or incomplete archives
• Cross-platform compatibility

# Atomic operations enabled by default
create_archive("important.tzst", files)  # Safe from interruption

# Can be disabled if needed (not recommended)
create_archive("test.tzst", files, use_temp_file=False)

Error Handling

from tzst import create_archive, TzstArchiveError, TzstCompressionError

try:
    create_archive("backup.tzst", ["documents/"])
except TzstCompressionError as e:
    print(f"Compression failed: {e}")
except TzstArchiveError as e:
    print(f"Archive operation failed: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Next Steps

• Explore comprehensive {doc}examples for real-world scenarios
• Check the {doc}api/index for detailed API documentation
• See advanced features like atomic operations and custom filters
• Learn about integration with web frameworks and automation tools

Read an Existing Archive

with TzstArchive("data.tzst", "r") as archive:
    # List contents
    contents = archive.list(verbose=True)
    
    # Extract specific file
    archive.extract("file.txt", "output/")
    
    # Test integrity
    is_valid = archive.test()
    
    # Get raw member information
    members = archive.getmembers()

Common Patterns

Backup Script

#!/usr/bin/env python3
from pathlib import Path
from datetime import datetime
from tzst import create_archive

def create_backup():
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    backup_name = f"backup_{timestamp}.tzst"
    
    # Backup important directories
    directories = ["documents/", "projects/", "config/"]
    
    print(f"Creating backup: {backup_name}")
    create_archive(backup_name, directories, compression_level=6)
    print(f"Backup created: {Path(backup_name).stat().st_size / 1024 / 1024:.1f} MB")

if __name__ == "__main__":
    create_backup()

Archive Verification

from tzst import test_archive, list_archive

def verify_archive(archive_path):
    print(f"Verifying {archive_path}...")
    
    # Test integrity
    if not test_archive(archive_path):
        print("Archive is corrupted!")
        return False
    
    # List contents
    contents = list_archive(archive_path, verbose=True)
    total_size = sum(item['size'] for item in contents if item['is_file'])
    file_count = sum(1 for item in contents if item['is_file'])
    print(f"Archive is valid")
    print(f"Files: {file_count}")
    print(f"Total size: {total_size / 1024 / 1024:.1f} MB")
    
    return True

Further Learning

• Explore {doc}examples for more advanced usage patterns
• Check {doc}performance for detailed performance guidance
• Refer to the {doc}api/index for complete API documentation