tzst/README.zh.md

Tip

欢迎加入“Xget 开源与 AI 交流群”，一起交流开源项目、AI 应用、工程实践、效率工具和独立开发；如果你也在做产品、写代码、折腾项目或者对开源和 AI 感兴趣，欢迎进群认识更多认真做事、乐于分享的朋友。

🇺🇸 English | 🇨🇳 汉语 | 🇪🇸 español | 🇯🇵 日本語 | 🇦🇪 العربية | 🇷🇺 русский | 🇩🇪 Deutsch | 🇫🇷 français | 🇰🇷 한국어 | 🇧🇷 português

tzst 是一个面向现代归档管理的新一代 Python 库，利用前沿的 Zstandard 压缩技术，提供卓越的性能、安全性和可靠性。专为 Python 3.12+ 打造，这个企业级解决方案结合原子操作、流式处理效率和精心设计的 API，重新定义了开发者在生产环境中处理 .tzst/.tar.zst 归档文件的方式。🚀

技术深度解析文章已发布：《深入解析 tzst：一个基于 Zstandard 的现代 Python 归档库》。

✨ 功能特性

• 🗜️ 高效压缩：采用 Zstandard 压缩算法，实现优异的压缩率和速度
• 📁 Tar 兼容性：创建符合标准的 tar 归档并使用 Zstandard 压缩
• 💻 命令行界面：直观的 CLI，支持流式处理和全面选项
• 🐍 Python API：简洁、符合 Python 风格的编程接口
• 🌍 跨平台支持：兼容 Windows、macOS 和 Linux
• 📂 多扩展名支持：同时支持 .tzst 和 .tar.zst 扩展名
• 💾 内存高效：流模式可高效处理大型归档文件
• ⚡ 原子操作：安全的文件操作，中断时自动清理
• 🔒 默认安全：提取时使用 'data' 过滤器确保最高安全性
• 🚨 增强的错误处理：清晰的错误信息和实用建议

📥 安装指南

从 GitHub Releases 安装

下载无需 Python 环境的独立可执行文件：

支持平台

平台	架构	文件
🐧 Linux	x86_64	tzst-{版本}-linux-amd64.zip
🐧 Linux	ARM64	tzst-{版本}-linux-arm64.zip
🪟 Windows	x64	tzst-{版本}-windows-amd64.zip
🪟 Windows	ARM64	tzst-{版本}-windows-arm64.zip
🍎 macOS	Intel	tzst-{版本}-darwin-amd64.zip
🍎 macOS	Apple Silicon	tzst-{版本}-darwin-arm64.zip

🛠️ 安装步骤

1. 📥 下载：从最新发布页面下载适合您平台的压缩包
2. 📦 解压：解压获取 tzst 可执行文件（Windows 为 tzst.exe）
3. 📂 移动：将可执行文件添加到 PATH 环境变量：
   • 🐧 Linux/macOS：sudo mv tzst /usr/local/bin/
   • 🪟 Windows：将包含 tzst.exe 的目录添加到 PATH
4. ✅ 验证：运行 tzst --help 确认安装成功

🎯 二进制安装优势

• ✅ 无需 Python - 独立可执行文件
• ✅ 启动更快 - 无 Python 解释器开销
• ✅ 易于部署 - 单文件分发
• ✅ 行为一致 - 依赖项已打包

📦 通过 PyPI 安装

使用 pip：

pip install tzst

或使用 uv（推荐）：

uv tool install tzst

🔧 从源码安装

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

🚀 开发环境安装

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

🚀 快速开始

💻 命令行使用

# 📁 创建归档
tzst a archive.tzst file1.txt file2.txt directory/

# 📤 提取归档
tzst x archive.tzst

# 📋 列出归档内容
tzst l archive.tzst

# 🧪 测试归档完整性
tzst t archive.tzst

🐍 Python API 使用

from tzst import create_archive, extract_archive, list_archive

# 创建归档
create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"])

# 提取归档
extract_archive("archive.tzst", "output_dir/")

# 列出归档内容
contents = list_archive("archive.tzst", verbose=True)
for item in contents:
    print(f"{item['name']}: {item['size']} bytes")

💻 命令行接口

📁 归档操作

➕ 创建归档

# 基本用法
tzst a archive.tzst file1.txt file2.txt

# 指定压缩级别 (1-22, 默认: 3)
tzst a archive.tzst files/ -l 15

# 等效命令
tzst add archive.tzst files/
tzst create archive.tzst files/

📤 提取归档

# 完整目录结构提取
tzst x archive.tzst

# 提取到指定目录
tzst x archive.tzst -o output_dir/

# 提取特定文件
tzst x archive.tzst file1.txt dir/file2.txt

# 扁平化提取（无目录结构）
tzst e archive.tzst -o output_dir/

# 大文件使用流模式
tzst x archive.tzst --streaming -o output_dir/

📋 列出内容

# 简单列表
tzst l archive.tzst

# 详细列表
tzst l archive.tzst -v

# 大文件使用流模式
tzst l archive.tzst --streaming -v

🧪 测试完整性

# 测试归档完整性
tzst t archive.tzst

# 流模式测试
tzst t archive.tzst --streaming

📊 命令参考

命令	等效命令	描述	是否支持流模式
a	add, create	创建或添加文件到归档	不支持
x	extract	完整路径提取	✓ --streaming
e	extract-flat	扁平化提取	✓ --streaming
l	list	列出归档内容	✓ --streaming
t	test	测试归档完整性	✓ --streaming

⚙️ CLI 选项

• -v, --verbose：启用详细输出
• -o, --output DIR：指定输出目录（提取命令）
• -l, --level LEVEL：设置压缩级别 1-22（创建命令）
• --streaming：启用流模式实现内存高效处理
• --filter FILTER：提取安全过滤器（data/tar/fully_trusted）
• --no-atomic：禁用原子文件操作（不推荐）

🔒 安全过滤器

# 最高安全性提取（默认）
tzst x archive.tzst --filter data

# 标准tar兼容性提取
tzst x archive.tzst --filter tar

# 完全信任模式（危险 - 仅适用于可信归档）
tzst x archive.tzst --filter fully_trusted

🔐 安全过滤器选项：

• data (默认)：最安全。阻止危险文件、绝对路径和提取目录外路径
• tar：标准 tar 兼容性。阻止绝对路径和目录遍历
• fully_trusted：无安全限制。仅适用于完全可信的归档

🐍 Python API

📦 TzstArchive 类

from tzst import TzstArchive

# 创建新归档
with TzstArchive("archive.tzst", "w", compression_level=5) as archive:
    archive.add("file.txt")
    archive.add("directory/", recursive=True)

# 读取现有归档
with TzstArchive("archive.tzst", "r") as archive:
    # 列出内容
    contents = archive.list(verbose=True)
    
    # 安全提取
    archive.extract("file.txt", "output/", filter="data")
    
    # 测试完整性
    is_valid = archive.test()

# 大文件使用流模式
with TzstArchive("large_archive.tzst", "r", streaming=True) as archive:
    archive.extract(path="output/")

⚠️ 重要限制：

• ❌ 不支持追加模式：需创建新归档或重建整个归档

🎯 便捷函数

📁 create_archive()

from tzst import create_archive

# 原子操作创建（默认）
create_archive(
    archive_path="backup.tzst",
    files=["documents/", "photos/", "config.txt"],
    compression_level=10
)

📤 extract_archive()

from tzst import extract_archive

# 安全提取（默认：'data'过滤器）
extract_archive("backup.tzst", "restore_dir/")

# 提取特定文件
extract_archive("backup.tzst", "restore_dir/", members=["config.txt"])

# 扁平化提取
extract_archive("backup.tzst", "restore_dir/", flatten=True)

# 大文件使用流模式
extract_archive("large_backup.tzst", "restore_dir/", streaming=True)

📋 list_archive()

from tzst import list_archive

# 简单列表
file_list = list_archive("backup.tzst")

# 详细列表
file_details = list_archive("backup.tzst", verbose=True)

# 大文件使用流模式
large_list = list_archive("large_backup.tzst", streaming=True)

🧪 test_archive()

from tzst import test_archive

# 基本完整性测试
if test_archive("backup.tzst"):
    print("Archive is valid")

# 流模式测试
if test_archive("large_backup.tzst", streaming=True):
    print("Large archive is valid")

🔧 高级功能

📂 文件扩展名

库自动处理文件扩展名并智能标准化：

• .tzst - tar + zstandard 归档主扩展名
• .tar.zst - 替代标准扩展名
• 打开现有归档时自动检测
• 创建归档时自动添加扩展名

# 以下创建方式均有效
create_archive("backup.tzst", files)      # 创建 backup.tzst
create_archive("backup.tar.zst", files)  # 创建 backup.tar.zst  
create_archive("backup", files)          # 创建 backup.tzst
create_archive("backup.txt", files)      # 创建 backup.tzst (标准化)

🗜️ 压缩级别

Zstandard 压缩级别范围从 1（最快）到 22（最佳压缩）：

• 级别 1-3：快速压缩，文件较大
• 级别 3（默认）：速度与压缩率的良好平衡
• 级别 10-15：更好的压缩率，速度较慢
• 级别 20-22：最高压缩率，速度显著变慢

🌊 流模式

使用流模式实现大归档文件的内存高效处理：

✅ 优势：

• 显著降低内存使用
• 对内存无法容纳的大文件性能更好
• 资源自动清理

🎯 适用场景：

• 大于 100MB 的归档文件
• 内存有限的环境
• 处理包含多个大文件的归档

# 示例：处理大型备份归档
from tzst import extract_archive, list_archive, test_archive

large_archive = "backup_500gb.tzst"

# 内存高效操作
is_valid = test_archive(large_archive, streaming=True)
contents = list_archive(large_archive, streaming=True, verbose=True)
extract_archive(large_archive, "restore_dir/", streaming=True)

⚡ 原子操作

所有文件创建操作默认使用原子操作：

• 归档先在临时文件创建，然后原子移动
• 进程中断时自动清理
• 无损坏或不完整归档风险
• 跨平台兼容

# 默认启用原子操作
create_archive("important.tzst", files)  # 中断时安全

# 可禁用（不推荐）
create_archive("test.tzst", files, use_temp_file=False)

🚨 错误处理

from tzst import TzstArchive
from tzst.exceptions import (
    TzstError,
    TzstArchiveError,
    TzstCompressionError,
    TzstDecompressionError,
    TzstFileNotFoundError
)

try:
    with TzstArchive("archive.tzst", "r") as archive:
        archive.extract()
except TzstDecompressionError:
    print("Failed to decompress archive")
except TzstFileNotFoundError:
    print("Archive file not found")
except KeyboardInterrupt:
    print("Operation interrupted by user")
    # Cleanup handled automatically

🚀 性能与对比

💡 性能优化建议

1. 🗜️ 压缩级别：级别 3 适用于大多数场景
2. 🌊 流模式：归档大于 100MB 时使用
3. 📦 批量操作：单次会话添加多个文件
4. 📄 文件类型：已压缩文件不会进一步压缩

🆚 与其他工具对比

对比 tar + gzip：

• ✅ 更好的压缩率
• ⚡ 更快的解压速度
• 🔄 现代算法

对比 tar + xz：

• 🚀 显著更快的压缩速度
• 📊 相似的压缩率
• ⚖️ 更好的速度/压缩率平衡

对比 zip：

• 🗜️ 更好的压缩率
• 🔐 保留 Unix 权限和元数据
• 🌊 更好的流处理支持

📋 系统要求

• 🐍 Python 3.12 或更高版本（已测试 3.12-3.14）
• 📦 zstandard >= 0.19.0

🛠️ 开发指南

🚀 设置开发环境

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

🧪 运行测试

# 带覆盖率的测试
pytest --cov=tzst --cov-report=html

# 简化命令 (覆盖配置在 pyproject.toml)
pytest

✨ 代码质量

# 代码检查
ruff check src tests

# 代码格式化
ruff format src tests

🤝 贡献指南

欢迎贡献！请阅读贡献指南了解：

• 开发设置和项目结构
• 代码风格指南和最佳实践
• 测试要求和编写测试
• PR流程和审核规范

🚀 贡献者快速入门

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

🎯 欢迎贡献类型

• 🐛 缺陷修复 - 修复现有功能问题
• ✨ 新功能 - 扩展库的功能
• 📚 文档 - 改进或新增文档
• 🧪 测试 - 增加或改进测试覆盖
• ⚡ 性能 - 优化现有代码
• 🔒 安全 - 修复安全漏洞

🙏 致谢

• Meta Zstandard 提供的优秀压缩算法
• python-zstandard 的 Python 绑定
• Python 社区的宝贵反馈和启发

📄 许可证

版权所有 © Xi Xu。保留所有权利。

采用 BSD 3-Clause 许可证授权。