xixu-me/tzst

0 Fork 0

Files

T

google-labs-jules[bot] e2fca92d4b docs: remove year from copyright info in READMEs and docs

Removes the year "2025" from the copyright section in all README files (all languages) and docs/index.md, as requested. The copyright line now reads "Copyright (c) [Author]..." without a specific year.

2025-12-31 17:24:55 +00:00

6.9 KiB

Raw Blame History

myst

html_meta

description	keywords	og:title	og:description	twitter:title	twitter:description	og:type	og:image	og:url	twitter:card	twitter:image
tzst - Next-generation Python library for tar.zst archives with Zstandard compression. Fast, secure, and reliable archive management.	tzst, Python, tar.zst, Zstandard, compression, archive, backup, file management	tzst - Next-Generation Archive Management	Fast, secure, and reliable Python library for tar.zst archives with Zstandard compression	tzst - Next-Generation Archive Management	Fast, secure, and reliable Python library for tar.zst archives with Zstandard compression	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

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.

:maxdepth: 2
:caption: Contents:

quickstart
performance
examples
api/index
development
genindex

:hidden:

404
README

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

For detailed installation instructions, including standalone binaries and source installation, please refer to the {doc}quickstart guide.

# Install from PyPI
pip install tzst

# Or using uv (recommended)
uv tool install tzst

Getting Started

For a quick introduction, see the {doc}quickstart guide. For comprehensive usage examples, explore the {doc}examples section.

API Documentation

Complete API documentation is available in the {doc}api/index section, covering:

{doc}api/core: Main classes and functions
{doc}api/cli: Command-line interface
{doc}api/exceptions: Error handling

Development

For comprehensive development information, see the {doc}development 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

Licensed under the BSD 3-Clause license.

Documentation Guide

{doc}quickstart - Get up and running quickly with basic examples
{doc}performance - Performance optimization guide and comparisons
{doc}examples - Comprehensive usage examples and patterns
{doc}api/index - Complete API reference documentation
{doc}development - Development and contribution guidelines
{ref}genindex - Index of all documented items

Requirements

Python 3.12 or higher
zstandard >= 0.19.0

6.9 KiB Raw Blame History