xixu-me
e5ad0336f3
Introduces CLAUDE.md to provide architecture overview, development commands, code quality checks, build instructions, key features, and testing patterns for the tzst Python library. This file is intended to guide contributors and AI assistants working with the repository.
76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Development installation with dev dependencies
|
|
pip install -e .[dev]
|
|
|
|
# Run tests
|
|
pytest
|
|
pytest --cov=tzst --cov-report=html # with coverage
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Check code quality
|
|
ruff check src tests
|
|
|
|
# Format code
|
|
ruff format src tests
|
|
```
|
|
|
|
### Building and Distribution
|
|
|
|
```bash
|
|
# 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
|