在处理文件归档和压缩时，我们经常需要一个既高效又可靠的工具。今天，我向大家介绍一个令人兴奋的 Python 新成员：tzst。这是一个专为 Python 3.12+ 设计的下一代归档管理库，它充分利用了 Zstandard (zstd) 这种前沿的压缩算法，旨在提供卓越的性能、坚如磐石的安全性以及企业级的可靠性。

codecov CodeQL CI/CD PyPI - Version PyPI - Downloads GitHub License Sponsor

如果您厌倦了传统归档工具的性能瓶颈或安全顾虑，或者正在为您的 Python 项目寻找一个现代化的归档解决方案，那么 tzst 绝对值得您关注。

🚀 tzst 的核心特性

tzst 不仅仅是一个简单的压缩工具，它提供了一系列精心设计的功能，使其在众多工具中脱颖而出：

  • 🗜️ 高效压缩：基于 Zstandard，tzst 提供了出色的压缩比和惊人的压缩/解压速度。这意味着您可以节省存储空间，同时减少处理时间。
  • 📁 Tar 兼容性：它能够创建使用 Zstandard 压缩的标准 tar 归档文件 (.tar.zst)，确保了良好的兼容性。当然，它也支持自定义的 .tzst 扩展名。
  • 💻 强大的命令行界面 (CLI)：tzst 提供了一个直观且功能全面的命令行工具，支持流式处理、详细输出、压缩级别控制等，方便日常使用和脚本集成。
  • 🐍 简洁的 Python API：除了 CLI，tzst 还提供了清晰、符合 Python 风格的 API，让开发者可以轻松地在自己的 Python 应用中集成归档功能。
  • 🌍 跨平台支持：无论您使用的是 Windows、macOS 还是 Linux，tzst 都能提供一致的体验。
  • 💾 内存高效：特别设计的流式处理模式 (streaming mode) 使得处理大型归档文件时内存占用极小，非常适合资源受限的环境或超大文件的操作。
  • ⚡ 原子操作：在创建归档时，tzst 默认采用原子文件操作。这意味着归档首先在临时文件中创建，成功后再移动到最终位置，确保了即使在操作被意外中断（如断电或程序崩溃）时，也不会留下损坏或不完整的归档文件。
  • 🔒 默认安全：在提取归档时，tzst 默认使用 ‘data’ 安全过滤器。这是最安全的选项，它会阻止提取包含绝对路径、尝试目录遍历（如 ../../..）或包含危险文件类型（如设备文件、符号链接到外部的链接）的归档成员，有效防范恶意归档带来的风险。
  • 🚨 增强的错误处理：提供清晰、易懂的错误信息，并在可能的情况下给出有用的建议或替代方案。

📥 安装与快速上手

安装 tzst 非常简单。您可以根据自己的需求选择不同的安装方式：

1. 通过 PyPI

对于大多数 Python 用户，这是最便捷的方式：

pip install tzst

2. 从 GitHub Releases 下载独立可执行文件

如果您需要在没有 Python 环境或不希望安装 Python 依赖的系统上使用 tzst 的 CLI 功能，可以从存储库的 GitHub Releases 页面下载预编译的独立可执行文件。支持 Linux (x86_64, ARM64), Windows (x64, ARM64) 和 macOS (Intel, Apple Silicon) 平台。

3. 从源码安装

对于开发者或希望获取最新代码的用户：

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install .
# 或者开发模式安装
pip install -e .[dev]

快速上手示例

命令行使用

注意：下载独立二进制文件可获得最佳性能且无需 Python 环境。也可使用 uvx tzst 免安装运行，详见 uv 文档。

# 📁 创建一个归档文件，将 file1.txt, file2.txt 和 directory/ 目录压缩进去
tzst a my_archive.tzst file1.txt file2.txt directory/

# 📤 提取 my_archive.tzst 中的所有内容到当前目录
tzst x my_archive.tzst

# 📋 列出 my_archive.tzst 中的内容
tzst l my_archive.tzst

# 🧪 测试 my_archive.tzst 的完整性
tzst t my_archive.tzst

Python API 使用

from tzst import create_archive, extract_archive, list_archive, test_archive

# 文件和目录列表
files_to_archive = ["file1.txt", "file2.txt", "directory/"]
archive_path = "my_api_archive.tzst"
extract_to_path = "extracted_content/"

# 创建归档
create_archive(archive_path, files_to_archive, compression_level=5)
print(f"归档 '{archive_path}' 创建成功。")

# 列出归档内容
print(f"\n'{archive_path}' 中的内容:")
contents = list_archive(archive_path, verbose=True)
for item in contents:
    print(f"- {item['name']} (大小: {item['size']} 字节, 类型: {'文件' if item['is_file'] else '目录'})")

# 测试归档完整性
if test_archive(archive_path):
    print(f"\n归档 '{archive_path}' 完整性测试通过。")
else:
    print(f"\n归档 '{archive_path}' 已损坏！")

# 提取归档
extract_archive(archive_path, extract_to_path)
print(f"\n归档已提取到 '{extract_to_path}'。")

💡 为什么选择 tzst？

  • 现代 Python 支持：专为 Python 3.12+ 设计，充分利用新版 Python 的特性。
  • Zstandard 的威力：Zstandard 提供了比传统 gzip 更高的压缩比和更快的解压速度，同时在压缩速度上也通常优于 xz。
  • 安全可靠：默认的安全过滤器和原子操作为您的数据提供了多一重保障。
  • 易用性：无论是 CLI 还是 Python API，都力求简洁直观，易于上手。

🔧 深入了解

tzst 的 README.md 和文档中有更多关于高级特性（如不同压缩级别的影响、流式处理的细节、安全过滤器的不同选项 data, tar, fully_trusted）的详细信息。

例如，tzst 的流式处理模式对于处理G级别甚至T级别的大型归档文件非常有用，因为它不需要将整个文件读入内存。CLI 中可以通过 --streaming 参数启用，Python API 中 TzstArchive 初始化时可以传入 streaming=True 参数。

🤝 贡献与支持

tzst 是一个开源存储库，欢迎社区的贡献。如果您在使用过程中遇到任何问题，或者有功能建议，可以通过存储库的 GitHub Issues 页面提交。如果您有兴趣贡献代码、文档或参与测试，请查阅存储库的 CONTRIBUTING.md 文件。

总结

对于追求高效、安全、现代化的 Python 开发者来说，tzst 提供了一个出色的归档解决方案。凭借其对 Zstandard 的优秀集成、强大的功能集以及对开发者友好的 API 和 CLI，tzst 有潜力成为您工具箱中的得力助手。

不妨从 pip install tzst 开始，体验一下 tzst 带来的便捷与高效吧！