tzst/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

tzst is a next-generation Python library for modern archive management using Zstandard compression. It provides both a Python API and a command-line interface for creating, extracting, listing, and testing .tzst/.tar.zst archives. The library focuses on performance, security, and reliability with features like atomic operations, streaming mode for large archives, and security filtering for extraction.

Architecture

The codebase is structured as follows:

• src/tzst/core.py - Core implementation containing the TzstArchive class and convenience functions
• src/tzst/cli.py - Command-line interface built with argparse
• src/tzst/exceptions.py - Custom exception classes
• src/tzst/__init__.py - Public API exports

The library wraps Python's tarfile module with Zstandard compression/decompression streams. It supports both buffered and streaming modes for memory efficiency with large archives.

Commands

Development Environment

# Development installation with dev dependencies
pip install -e .[dev]

# Run tests
pytest
pytest --cov=tzst --cov-report=html  # with coverage

Code Quality

# Check code quality
ruff check src tests

# Format code
ruff format src tests

Building and Distribution

# Build package
python -m build

# Upload to PyPI (requires credentials)
python -m twine upload dist/*

Key Features to Consider

1. Streaming Mode: For archives >100MB, always recommend using streaming mode to reduce memory usage
2. Security Filters: Use 'data' filter by default for extraction to prevent path traversal attacks
3. Atomic Operations: Archive creation uses temporary files by default for safety
4. Conflict Resolution: During extraction, implement proper file conflict resolution strategies
5. Compression Levels: Default to level 3 unless the user has specific performance/size requirements

Testing Patterns

The project uses pytest with comprehensive test coverage including:

• Unit tests in tests/unit/
• Integration tests in tests/integration/
• CLI-specific tests in tests/cli/
• Edge case handling in tests/test_core_edge_cases.py

Common Tasks

• To add functionality: work in src/tzst/core.py following existing patterns
• To modify CLI behavior: update src/tzst/cli.py and adjust argument parsing as needed
• To add new command: extend create_parser() in cli.py and add appropriate handler function
• For error handling: use appropriate TzstError subclasses from exceptions.py