### TZST Quick Start for Contributors

Source: https://github.com/xixu-me/tzst/blob/main/README.md

A streamlined setup guide for contributors to quickly clone the repository, install development dependencies, and run the test suite, enabling them to start contributing to the TZST project efficiently.

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

--------------------------------

### Install and Start Live Reload Server

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Install sphinx-autobuild and start a local development server that automatically rebuilds and refreshes the documentation when files are changed. This is recommended for an efficient development workflow.

```bash
pip install sphinx-autobuild

make livehtml
```

```bash
sphinx-autobuild . _build/html
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Install the necessary Python packages for building the documentation. This is a prerequisite for most documentation tasks.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install tzst using pip or uv

Source: https://github.com/xixu-me/tzst/blob/main/docs/index.md

Shows the commands to install the tzst library from PyPI using pip or uv.

```bash
# Install from PyPI
pip install tzst
```

```bash
# Or using uv (recommended)
uv tool install tzst
```

--------------------------------

### Add Python Code Example

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Demonstrates how to use the TzstArchive class to create a new archive and add files to it. Ensure the tzst library is installed.

```python
from tzst import TzstArchive

with TzstArchive("example.tzst", "w") as archive:
    archive.add("file.txt")
```

--------------------------------

### Install tzst using uv

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Install the tzst tool using uv, a fast Python package installer. This is a recommended alternative to pip.

```bash
uv tool install tzst
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/xixu-me/tzst/blob/main/docs/index.md

Clone the tzst repository, navigate to the project directory, and install the project with development dependencies. Then, run the tests.

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

--------------------------------

### Install tzst from source

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Clone the tzst repository and install it locally using pip. This method is useful for development or when needing the latest code.

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

--------------------------------

### Verify Installation with Pytest

Source: https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md

Run the test suite to verify that the installation was successful.

```bash
python -m pytest tests/
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/xixu-me/tzst/blob/main/CLAUDE.md

Install the library in editable mode with development dependencies included. This is necessary for running tests and contributing to the project.

```bash
pip install -e .[dev]
```

--------------------------------

### Install tzst using pip

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Install the tzst library using pip. This is a standard method for Python package installation.

```bash
pip install tzst
```

--------------------------------

### Commit Message Examples

Source: https://github.com/xixu-me/tzst/blob/main/docs/development.md

Examples demonstrating the conventional commit message format for different types of changes.

```text
feat(core): add streaming compression support
```

```text
fix(cli): handle invalid archive paths gracefully
```

```text
docs(readme): update installation instructions
```

--------------------------------

### Pytest Fixture Usage Example

Source: https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md

Utilize pytest fixtures to provide common test data and setup.

```python
def test_extract_archive(sample_archive_path, temp_dir):
```

--------------------------------

### Build PDF Documentation

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Generate a PDF version of the documentation. This process requires a LaTeX installation to be present on your system.

```bash
make latexpdf
```

--------------------------------

### CLI: Create Archive with Different Options

Source: https://context7.com/xixu-me/tzst/llms.txt

Examples of creating archives using the `tzst a` command. Shows basic usage, setting compression levels, disabling atomic temp-file creation, and enabling machine-readable JSON output.

```bash
# Basic: add files and a directory at default compression level 3
tzst a backup.tzst documents/ photos/ notes.txt
```

```bash
# Compression level 15 (higher = smaller, slower)
tzst a backup.tzst src/ -l 15
```

```bash
# Disable atomic temp-file creation (slightly faster, less safe)
tzst a backup.tzst src/ --no-atomic
```

```bash
# Machine-readable JSON output (useful in CI/scripts)
tzst --json a backup.tzst src/ -l 5
# stdout: {"ok": true, "command": "add", "archive": "backup.tzst",
#          "normalized_archive": "backup.tzst", "added": [...],
#          "compression_level": 5, "atomic": true}
```

--------------------------------

### Clone and Install tzst with Development Dependencies

Source: https://github.com/xixu-me/tzst/blob/main/docs/development.md

Clone the repository and install the project in editable mode with development dependencies. This includes tools like pytest, ruff, coverage, and sphinx.

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

--------------------------------

### Conventional Commit Examples

Source: https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md

Examples of commit messages following the conventional commit format.

```markdown
feat(core): add streaming compression support

fix(cli): handle invalid archive paths gracefully

docs(readme): update installation instructions
```

--------------------------------

### Python Docstring Example

Source: https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md

Illustrates the Google-style docstring format for Python functions, including arguments, return types, and potential exceptions.

```python
def create_archive(
    archive_path: str | Path,
    files: Sequence[str | Path],
    compression_level: int = 3,
) -> None:
    """Create a new tzst archive containing the specified files.
    
    Args:
        archive_path: Path where the archive will be created.
        files: Sequence of file/directory paths to include.
        compression_level: Zstandard compression level (1-22).
        
    Raises:
        TzstArchiveError: If archive creation fails.
        FileNotFoundError: If input files don't exist.
    """

```

--------------------------------

### GitHub Actions for Release Archive

Source: https://github.com/xixu-me/tzst/blob/main/docs/performance.md

Example GitHub Actions workflow step to create a release archive with compression level 9.

```yaml
- name: Create release archive
  run: |
    tzst a release-${{ github.ref_name }}.tzst \
      build/ docs/ \
      --compression-level 9
```

--------------------------------

### tzst Archive Creation Command Line

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Use the `tzst a` command for archive creation. Supports specifying files, directories, and compression levels. `uvx tzst` can be used for running without installation.

```bash
# Create archive
tzst a my-archive.tzst document.pdf photos/ config.json

# With high compression
tzst a high-compression.tzst document.pdf photos/ config.json -l 9
```

```bash
# Basic archive creation
tzst a backup.tzst documents/ photos/
# Or with uvx (no installation needed)
uvx tzst a backup.tzst documents/ photos/

# Create with specific compression level
tzst a backup.tzst documents/ photos/ -l 6
uvx tzst a backup.tzst documents/ photos/ -l 6

# Create from multiple sources
tzst a complete-backup.tzst /home/user/documents /home/user/photos /etc/config

# Create with verbose output
tzst a backup.tzst documents/ photos/ -v
```

--------------------------------

### Using the TzstArchive Class

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Provides examples of using the `TzstArchive` class for more object-oriented control over archive operations, including context management.

```APIDOC
## Using the TzstArchive Class

### Description
This section demonstrates how to use the `TzstArchive` class for creating and reading archives, leveraging Python's context management (`with` statement) for automatic resource handling.

### Class Methods
- `TzstArchive(archive_path, mode, compression_level=None, streaming=False)`: Initializes the archive object.
  - `mode`: 'w' for write, 'r' for read.
- `add(file_path, arcname=None, recursive=False)`: Adds a file or directory to the archive (write mode).
- `list(verbose=False)`: Lists archive contents (read mode).
- `test()`: Tests archive integrity (read mode).
- `extract(member, path='')`: Extracts a specific member (read mode).
- `extractall(path='')`: Extracts all members (read mode).

### Example Usage
```python
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/")
```
```

--------------------------------

### CLI: List Archive Contents

Source: https://context7.com/xixu-me/tzst/llms.txt

Examples of listing archive contents using `tzst l`. Demonstrates simple listing, verbose output with file details, streaming for large archives, and JSON output for programmatic access.

```bash
# Simple listing (names only + summary)
tzst l backup.tzst
```

```bash
# Verbose: shows permissions, size, modification time
tzst l backup.tzst -v
```

```bash
# Streaming for large archives
tzst l large.tzst --streaming -v
```

```bash
# JSON output — returns full contents array and summary block
tzst --json l backup.tzst -v
# stdout: {"ok": true, "command": "list", "contents": [...],
#          "summary": {"files": 42, "directories": 5,
#                      "total_size_bytes": 10240, "total_size_human": "10.0 KB"}}
```

--------------------------------

### Install tzst Package for Development

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Install the tzst package in editable mode. This is required for Sphinx's autodoc feature to correctly import and document the library's components.

```bash
pip install -e ..
```

--------------------------------

### CLI: Extract Archive Flat with Options

Source: https://context7.com/xixu-me/tzst/llms.txt

Shows how to use `tzst e` to extract archive contents without preserving directory structure. Includes examples for flat extraction, streaming, and JSON output with conflict resolution.

```bash
# All files land in output/ with no subdirectories
tzst e backup.tzst -o output/
```

```bash
# Streaming flat extraction
tzst e large.tzst --streaming -o output/
```

```bash
# JSON output
tzst --json e backup.tzst -o output/ --conflict-resolution skip_all
# stdout: {"ok": true, "command": "extract-flat", "flatten": true, ...}
```

--------------------------------

### Link to Documentation Page

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Example of creating an internal cross-reference to another documentation page using the {doc} directive. This helps users navigate between related sections.

```markdown
See the {doc}`quickstart` guide for more information.
```

--------------------------------

### Memory-Efficient Archive Operations with Streaming

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Illustrates how to use streaming mode for memory-efficient processing of large archives. This is beneficial for archives exceeding 100MB or in environments with limited memory. It shows examples for testing, listing contents, and extracting archives.

```python
# Example: Processing a large backup archive
from tzst import extract_archive, list_archive, test_archive

large_archive = "backup_500gb.tzst"

# Memory-efficient operations
is_valid = test_archive(large_archive, streaming=True)
contents = list_archive(large_archive, streaming=True, verbose=True)
extract_archive(large_archive, "restore/", streaming=True)
```

--------------------------------

### Build Documentation Locally (Unix/macOS)

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Build the HTML version of the documentation locally using the make command. The output will be in the _build/html directory.

```bash
make html
```

--------------------------------

### Build Documentation Locally (Windows)

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Build the HTML version of the documentation locally using the make.bat command on Windows. The output will be in the _build/html directory.

```bat
make.bat html
```

--------------------------------

### Build HTML Documentation

Source: https://github.com/xixu-me/tzst/blob/main/docs/development.md

Navigate to the 'docs' directory and use 'make html' to build the project's documentation in HTML format. This command requires Sphinx and its dependencies.

```bash
cd docs
pip install -r requirements.txt
make html
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md

Create a Python virtual environment and activate it for development.

```bash
python -m venv venv
# On Windows
venv\Scripts\activate
# On Unix/macOS
source venv/bin/activate
```

--------------------------------

### Create and Read Archives with TzstArchive

Source: https://github.com/xixu-me/tzst/blob/main/docs/api/core.md

Demonstrates creating a new archive with specified compression and adding files, then reading an existing archive to list contents, test integrity, and extract all files. Uses context manager for resource management.

```python
with TzstArchive("backup.tzst", "w", compression_level=6) as archive:
    archive.add("important_file.txt")
    archive.add("documents/", recursive=True)

with TzstArchive("backup.tzst", "r") as archive:
    contents = archive.list(verbose=True)
    is_valid = archive.test()
    archive.extractall("restore/")
```

--------------------------------

### Create Project Backup with Exclusions

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Create a project backup archive while excluding specified file patterns and directories. Ensure the project path and output archive path are correctly provided.

```python
import os
from tzst import TzstArchive
from pathlib import Path

def backup_project(project_path, output_archive):
    """Create a project backup excluding certain files."""
    project_path = Path(project_path)
    
    # Define exclusion patterns
    exclude_patterns = {
        "*.pyc", "*.pyo", "__pycache__", 
        ".git", ".svn", "node_modules",
        "*.tmp", "*.log", ".DS_Store"
    }
    
    with TzstArchive(output_archive, "w", compression_level=5) as archive:
        for item in project_path.rglob("*"):
            # Skip excluded patterns
            if any(item.match(pattern) for pattern in exclude_patterns):
                continue
                
            # Skip if it's a directory (will be created automatically)
            if item.is_dir():
                continue
                
            # Add file with relative path
            rel_path = item.relative_to(project_path)
            archive.add(str(item), arcname=str(rel_path))
            print(f"Added: {rel_path}")

# Usage
backup_project("/home/user/myproject", "project-clean.tzst")
```

--------------------------------

### Atomic and Direct Archive Creation

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Demonstrates two methods for creating archives: atomic creation using a temporary file (default and safer) and direct creation (faster but not atomic).

```python
from tzst import create_archive

# Safe atomic creation (default behavior)
# Creates in temporary file first, then moves to final location
create_archive("important-data.tzst", ["critical/"], use_temp_file=True)

# Direct creation (faster but not atomic)
create_archive("temp-data.tzst", ["temp/"], use_temp_file=False)
```

--------------------------------

### Serve Built Documentation Locally

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Serve the static HTML files generated by Sphinx using Python's built-in HTTP server. This is useful for testing the final output or for local deployment testing.

```bash
python -m http.server 8000 -d _build/html
```

--------------------------------

### Link to API Class

Source: https://github.com/xixu-me/tzst/blob/main/docs/README.md

Example of creating a cross-reference to a specific class within the API documentation using the {class} directive. This provides direct links to relevant code components.

```markdown
Use the {class}`tzst.TzstArchive` class.
```

--------------------------------

### Clone and Navigate Repository

Source: https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md

Clone the tzst repository and navigate into the project directory.

```bash
git clone https://github.com/xixu-me/tzst.git
cd tzst
```

--------------------------------

### Use Fixtures for Test Data

Source: https://github.com/xixu-me/tzst/blob/main/docs/development.md

Employ pytest fixtures to provide common test data or setup for test functions. This reduces code duplication and makes tests more robust.

```python
def test_extract_archive(sample_archive_path, temp_dir):

```

--------------------------------

### Archive Datasets with tzst

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Archives local dataset files (CSV, Parquet) into a .tzst file. Includes setup for sample data if it doesn't exist. Lists archive contents after creation.

```python
# Cell 1: Setup
import pandas as pd
from tzst import create_archive, extract_archive, list_archive
from pathlib import Path
import matplotlib.pyplot as plt

# Cell 2: Create dataset archive
def archive_datasets(data_dir="./data", archive_name="datasets.tzst"):
    """Archive all dataset files for sharing."""
    data_path = Path(data_dir)
    
    if not data_path.exists():
        print(f"Creating sample data directory: {data_dir}")
        data_path.mkdir(exist_ok=True)
        
        # Create sample datasets
        sample_data = pd.DataFrame({
            'A': range(100),
            'B': range(100, 200),
            'C': range(200, 300)
        })
        
        sample_data.to_csv(data_path / "sample.csv", index=False)
        sample_data.to_parquet(data_path / "sample.parquet")
    
    # Create archive
    create_archive(archive_name, [str(data_path)], compression_level=9)
    
    # Show archive contents
    contents = list_archive(archive_name, verbose=True)
    df = pd.DataFrame(contents)
    
    print(f"Created archive: {archive_name}")
    return df

# Execute
archive_contents = archive_datasets()
display(archive_contents)
```

--------------------------------

### Create a Simple tzst Archive

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Use `create_archive` for basic archive creation. Specify files and directories to include. Supports custom compression levels for optimized storage.

```python
from tzst import create_archive

# Simple archive creation
files_to_archive = ["document.pdf", "photos/", "config.json"]
create_archive("my-archive.tzst", files_to_archive)

# With custom compression level
create_archive("high-compression.tzst", files_to_archive, compression_level=9)
```

--------------------------------

### Create Archive with Compression Level

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Use the 'a' command to create an archive. Specify the compression level between 1 and 22, with 3 as the default.

```bash
tzst a archive.tzst file1.txt file2.txt
```

```bash
tzst a archive.tzst files/ -l 15
```

```bash
tzst add archive.tzst files/
```

```bash
tzst create archive.tzst files/
```

--------------------------------

### tzst Archive Extraction Command Line

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Use `tzst x` or `tzst e` for extraction. Specify the archive, output directory, and conflict resolution. `uvx tzst` can be used for running without installation.

```bash
# Extract to current directory
tzst x backup.tzst
# Or with uvx
uvx 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

# Extract flattening directory structure
tzst e backup.tzst --output flat-restore/
```

--------------------------------

### Custom Security Filter for Extraction

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Implements a custom security filter function to control which members are extracted from an archive. This example allows only regular files and directories, prevents path traversal, and limits file size.

```python
import tarfile
from tzst import TzstArchive
import os

def secure_data_filter(member, path):
    """Custom filter that only allows regular files and directories."""
    # Only allow regular files and directories
    if not (member.isfile() or member.isdir()):
        return None
    
    # Prevent path traversal
    if os.path.isabs(member.name) or ".." in member.name:
        return None
    
    # Limit file size (100MB max)
    if member.isfile() and member.size > 100 * 1024 * 1024:
        return None
    
    return member

# Use custom filter
with TzstArchive("archive.tzst", "r") as archive:
    archive.extractall("secure-output/", filter=secure_data_filter)
```

--------------------------------

### Create TZST Archives with Different File Extensions

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Demonstrates how the `create_archive` function handles various file extensions, normalizing them to `.tzst` for primary and alternative standard extensions, and automatically adding the extension when none is provided or an unrecognized one is used.

```python
# 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)
```

--------------------------------

### Choose Appropriate Security Filters

Source: https://github.com/xixu-me/tzst/blob/main/SECURITY.md

Shows how to select different security filters ('data', 'tar', 'fully_trusted') based on the trust level of the archive.

```python
# For untrusted archives (recommended)
extract_archive("untrusted.tzst", "output/", filter="data")

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

# Only for completely trusted archives (use with caution)
extract_archive("internal.tzst", "output/", filter="fully_trusted")
```

--------------------------------

### Create a tzst archive using CLI

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Create a new .tzst archive from specified files and directories using the tzst command-line interface. Ensure the files/directories exist.

```bash
tzst a archive.tzst file1.txt file2.txt directory/
```

--------------------------------

### Create Daily Backup Script

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Automate daily backups by creating a Python script that archives specified directories with a timestamped filename and compression level.

```python
#!/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()
```

--------------------------------

### List contents of a .tzst archive

Source: https://context7.com/xixu-me/tzst/llms.txt

Use `list_archive` to get information about archive members. Simple mode provides basic details, while verbose mode includes metadata like permissions and timestamps. Supports streaming for large archives.

```python
from tzst import list_archive

# Simple listing
entries = list_archive("backup.tzst")
for entry in entries:
    kind = "FILE" if entry["is_file"] else "DIR "
    print(f"[{kind}] {entry['name']}  ({entry['size']} bytes)")

# Verbose listing with metadata
entries = list_archive("backup.tzst", verbose=True)
for entry in entries:
    if entry["is_file"]:
        print(
            f"{oct(entry['mode'])[-4:]}  "
            f"{entry['size']:>10}  "
            f"{entry['mtime_str']}  "
            f"{entry['name']}"
        )

# Memory-efficient streaming for large archives
entries = list_archive("huge.tzst", streaming=True, verbose=False)
print(f"Total members: {len(entries)}")
total_bytes = sum(e["size"] for e in entries if e["is_file"])
print(f"Total uncompressed size: {total_bytes:,} bytes")
```

--------------------------------

### tzst Archive Inspection Command Line

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Use `tzst l` for listing archive contents, `tzst t` for testing integrity, and `tzst l --streaming` for efficient handling of large archives. `uvx tzst` can be used for running without installation.

```bash
# List archive contents
tzst l backup.tzst
# Or with uvx
uvx tzst l backup.tzst

# List with detailed information
tzst l backup.tzst --verbose

# Test archive integrity
tzst t backup.tzst

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

--------------------------------

### Atomic Archive Creation

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Shows how `create_archive` uses atomic file operations by default, creating archives in temporary files before moving them to their final destination. This ensures data integrity and prevents corruption even if the process is interrupted. An example of disabling this feature is also provided, though it is not recommended.

```python
# 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)
```

--------------------------------

### Upload Package to PyPI

Source: https://github.com/xixu-me/tzst/blob/main/CLAUDE.md

Distribute the built package to the Python Package Index (PyPI). Ensure you have the necessary credentials configured.

```bash
python -m twine upload dist/*
```

--------------------------------

### create_archive()

Source: https://context7.com/xixu-me/tzst/llms.txt

Creates a Zstandard-compressed tar archive from a list of files and directories. Supports atomic operations, custom compression levels, and extension normalization.

```APIDOC
## create_archive()

### Description
Creates a Zstandard-compressed tar archive from a list of files and directories. Uses atomic file operations by default (writes to a temp file then renames) to prevent incomplete archives on interruption. Automatically normalizes the output extension to `.tzst` if not already `.tzst` or `.tar.zst`.

### Method Signature
```python
create_archive(archive_path: str, files: list[str], compression_level: int = 3, use_temp_file: bool = True)
```

### Parameters
- **archive_path** (str) - Required - The path for the output archive file.
- **files** (list[str]) - Required - A list of file and directory paths to include in the archive.
- **compression_level** (int) - Optional - The Zstandard compression level (1-22). Defaults to 3.
- **use_temp_file** (bool) - Optional - If True, uses atomic file operations by writing to a temporary file first. Defaults to True.

### Request Example
```python
from tzst import create_archive

# Basic creation at default compression level 3
create_archive("backup.tzst", ["documents/", "config.json", "data/"])

# High-compression backup (level 15), non-atomic for speed
create_archive(
    archive_path="archive.tar.zst",
    files=["src/", "tests/", "README.md"],
    compression_level=15,
    use_temp_file=False,   # skip atomic temp-file step
)
```

### Error Handling
- `FileNotFoundError`: If an input file or directory does not exist.
- `TzstArchiveError`: For general archive creation failures.
- `KeyboardInterrupt`: In atomic mode, interrupted operations clean up partial files.
```

--------------------------------

### Create a tar.zst archive

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Use the 'a' command to create a new tar.zst archive with specified files and directories.

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

--------------------------------

### Advanced Archive Creation with TzstArchive Class

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

Utilize the `TzstArchive` class for fine-grained control over archive creation. Allows adding individual files, directories recursively, and specifying custom archive names.

```python
from tzst import TzstArchive
from pathlib import Path

# Create archive with fine-grained control
with TzstArchive("project-backup.tzst", "w", compression_level=6) as archive:
    # Add individual files
    archive.add("README.md")
    archive.add("LICENSE")
    
    # Add directories recursively
    archive.add("src/", recursive=True)
    archive.add("tests/", recursive=True)
    
    # Add with custom archive names
    archive.add("config/production.yaml", arcname="config.yaml")
    archive.add("/tmp/build-info.json", arcname="build-info.json")
```

--------------------------------

### CLI: Extract Archive with Options

Source: https://context7.com/xixu-me/tzst/llms.txt

Demonstrates extracting files from an archive using the `tzst x` command. Covers extracting to the current directory, a specific output directory, specific members, and using memory-efficient streaming mode.

```bash
# Extract all to current directory
tzst x backup.tzst
```

```bash
# Extract to a specific output directory
tzst x backup.tzst -o restore/
```

```bash
# Extract specific members only
tzst x backup.tzst documents/report.pdf notes.txt -o restore/
```

```bash
# Memory-efficient streaming mode for archives > 100 MB
tzst x backup.tzst --streaming -o restore/
```

```bash
# Change security filter (default: data — safest)
tzst x backup.tzst --filter tar -o restore/
tzst x internal.tzst --filter fully_trusted -o restore/
```

```bash
# Auto-rename conflicts instead of prompting
tzst x backup.tzst -o restore/ --conflict-resolution auto_rename_all
```

```bash
# JSON output
tzst --json x backup.tzst -o restore/ --conflict-resolution replace
```

--------------------------------

### Use Secure Extraction Defaults

Source: https://github.com/xixu-me/tzst/blob/main/SECURITY.md

Demonstrates using the default secure 'data' filter and explicitly specifying it for untrusted archives.

```python
from tzst import extract_archive

# ✅ Good: Uses secure 'data' filter by default
extract_archive("untrusted.tzst", "output/")

# ✅ Good: Explicitly specify secure filter
extract_archive("untrusted.tzst", "output/", filter="data")
```

--------------------------------

### Create Backup API Endpoint

Source: https://github.com/xixu-me/tzst/blob/main/docs/examples.md

This endpoint allows users to create a backup of specified paths with a given compression level. It returns the created backup file as a downloadable attachment.

```APIDOC
## POST /api/backup

### Description
API endpoint to create backups of specified paths.

### Method
POST

### Endpoint
/api/backup

### Parameters
#### Request Body
- **paths** (array[string]) - Required - An array of paths to be included in the backup.
- **compression_level** (integer) - Optional - The compression level to use (default is 6).

### Request Example
```json
{
  "paths": ["/path/to/dir1", "/path/to/file.txt"],
  "compression_level": 9
}
```

### Response
#### Success Response (200)
Returns a file stream of the created backup archive (.tzst).

#### Error Response (400, 500)
- **error** (string) - Description of the error.
```json
{
  "error": "No paths specified"
}
```
```

--------------------------------

### Create tar.zst archive with default compression

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Create a tar.zst archive using the default compression level (level 3).

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

--------------------------------

### Create tar.zst archive from current directory

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Create a tar.zst archive containing all files and directories from the current working directory.

```bash
# Create from current directory
tzst a project.tzst .
```

--------------------------------

### Python API: Create Archive

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Use the TzstArchive class with mode 'w' to create a new archive. Specify the compression level during initialization. The 'add' method can add files or directories recursively.

```python
from tzst import TzstArchive

# Create a new archive
with TzstArchive("archive.tzst", "w", compression_level=5) as archive:
    archive.add("file.txt")
    archive.add("directory/", recursive=True)
```

--------------------------------

### Format Code with Ruff

Source: https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md

Use Ruff to format the code according to the project's style guidelines.

```bash
ruff format .
```

--------------------------------

### Extract Archive with Options

Source: https://github.com/xixu-me/tzst/blob/main/README.md

Use the 'x' command to extract an archive. Options include specifying an output directory, extracting specific files, or using streaming mode for large archives.

```bash
tzst x archive.tzst
```

```bash
tzst x archive.tzst -o output/
```

```bash
tzst x archive.tzst file1.txt dir/file2.txt
```

```bash
tzst e archive.tzst -o output/
```

```bash
tzst x archive.tzst --streaming -o output/
```

--------------------------------

### Create, Extract, and Manage Archives with tzst

Source: https://github.com/xixu-me/tzst/blob/main/docs/index.md

Demonstrates high-level functions for creating and extracting archives, and programmatic archive manipulation using the TzstArchive class. Imports are required.

```python
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()
```

--------------------------------

### Create a .tzst archive

Source: https://context7.com/xixu-me/tzst/llms.txt

Use `create_archive` to make a Zstandard-compressed tar archive. Atomic operations are default for safety, but can be disabled for speed. Handles extension normalization.

```python
from tzst import create_archive
from tzst.exceptions import TzstArchiveError

# Basic creation at default compression level 3
create_archive("backup.tzst", ["documents/", "config.json", "data/"])

# High-compression backup (level 15), non-atomic for speed
create_archive(
    archive_path="archive.tar.zst",
    files=["src/", "tests/", "README.md"],
    compression_level=15,
    use_temp_file=False,   # skip atomic temp-file step
)

# Error handling
try:
    create_archive("out.tzst", ["missing_dir/"])
except FileNotFoundError as e:
    print(f"Input not found: {e}")
except TzstArchiveError as e:
    print(f"Archive creation failed: {e}")
except KeyboardInterrupt:
    print("Interrupted — no partial archive left on disk (atomic mode cleans up)")
```

--------------------------------

### Perform Batch Operations Efficiently

Source: https://github.com/xixu-me/tzst/blob/main/docs/performance.md

Add multiple files to an archive within a single session using `TzstArchive` for better efficiency compared to creating multiple separate archives.

```python
from tzst import TzstArchive

# Efficient: Single archive session
with TzstArchive("backup.tzst", "w") as archive:
    archive.add("file1.txt")
    archive.add("file2.txt")
    archive.add("directory/", recursive=True)

# Less efficient: Multiple separate operations
create_archive("backup1.tzst", ["file1.txt"])
create_archive("backup2.tzst", ["file2.txt"])
```

--------------------------------

### tzst CLI Main Functions

Source: https://github.com/xixu-me/tzst/blob/main/docs/api/cli.md

Reference for the main entry point and parser creation functions of the tzst CLI.

```APIDOC
## main

### Description
The main entry point for the CLI application. Handles argument parsing, command execution, and comprehensive error reporting.

### Features:
- Robust argument validation and error handling
- Support for all archive operations
- Consistent exit codes for scripting
- User-friendly error messages

### Exit Codes:
- `0`: Success
- `1`: General error (file not found, archive corruption, etc.)
- `2`: Argument parsing error
- `130`: Interrupted by user (Ctrl+C)
```

```APIDOC
## create_parser

### Description
Creates and configures the comprehensive argument parser for the CLI interface.

### Supported Arguments:
- **Global**: `--version`, `--help`
- **Archive Creation**: `-l/--level`, `--no-atomic`
- **Extraction**: `-o/--output`, `--streaming`, `--filter`, `--conflict-resolution`
- **Listing**: `-v/--verbose`, `--streaming`
- **Testing**: `--streaming`
```

--------------------------------

### Create tar.zst archive with specified output location

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Create a tar.zst archive and specify a different directory for the output file.

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

--------------------------------

### Create Archive

Source: https://github.com/xixu-me/tzst/blob/main/docs/api/cli.md

Use the 'a' command to create a new .tzst archive. Specify the archive name followed by the files or directories to include. Supports high compression levels and disabling atomic operations for specific use cases.

```bash
tzst a backup.tzst documents/ photos/
```

```bash
tzst a backup.tzst files/ -l 15 --no-atomic
```

--------------------------------

### Fast Compression for Development Builds

Source: https://github.com/xixu-me/tzst/blob/main/docs/performance.md

Uses compression level 1 for quick compression during frequent development builds.

```python
# Fast compression for frequent builds
create_archive("build-artifacts.tzst", ["build/"], compression_level=1)
```

--------------------------------

### Basic Archive Operations

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Demonstrates fundamental operations like creating, extracting, listing, and testing archives using the top-level functions.

```APIDOC
## Basic Archive Operations

### Description
This section covers the basic usage of the tzst library for common archive operations using standalone functions.

### Functions
- `create_archive(output_path, files, compression_level=5)`: Creates a new archive.
- `extract_archive(archive_path, extract_path, filter='data', conflict_resolution=None, streaming=False)`: Extracts an archive.
- `list_archive(archive_path, verbose=False)`: Lists the contents of an archive.
- `test_archive(archive_path)`: Tests the integrity of an archive.

### Example Usage
```python
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'}")
```
```

--------------------------------

### Run Project Tests

Source: https://github.com/xixu-me/tzst/blob/main/CLAUDE.md

Execute the test suite using pytest. For coverage analysis, use the --cov flag and specify the coverage report format.

```bash
pytest
```

```bash
pytest --cov=tzst --cov-report=html
```

--------------------------------

### Benchmark Compression Levels

Source: https://github.com/xixu-me/tzst/blob/main/docs/performance.md

Compares compression time and output size across various compression levels. Requires files or directories to be compressed.

```python
import time
from pathlib import Path
from tzst import create_archive

def benchmark_compression_levels(files, output_prefix="benchmark"):
    """Compare different compression levels."""
    levels_to_test = [1, 3, 6, 9, 15, 22]
    
    results = []
    for level in levels_to_test:
        output_file = f"{output_prefix}_level_{level}.tzst"
        
        # Measure compression time
        start_time = time.time()
        create_archive(output_file, files, compression_level=level)
        compress_time = time.time() - start_time
        
        # Get file size
        file_size = Path(output_file).stat().st_size
        
        results.append({
            'level': level,
            'time': compress_time,
            'size': file_size,
            'size_mb': file_size / (1024 * 1024)
        })
        
        print(f"Level {level}: {compress_time:.2f}s, {file_size/1024/1024:.1f} MB")
    
    return results

# Example usage
files = ["documents/", "projects/"]
results = benchmark_compression_levels(files)
```

--------------------------------

### Performance Optimization with Compression Levels

Source: https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md

Adjust the 'compression_level' when creating archives to balance speed and compression ratio. Lower levels are faster, higher levels offer better compression.

```python
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)
```

--------------------------------

### Balanced Compression for Backups

Source: https://github.com/xixu-me/tzst/blob/main/docs/performance.md

Uses compression level 6 for a balance between compression ratio and speed for regular backups.

```python
# Balanced compression for regular backups
create_archive("daily-backup.tzst", ["data/"], compression_level=6)
```