From 518e90f0ee27e84c1c04bf270f3034ee6967f88e Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Thu, 5 Jun 2025 00:03:31 +0800 Subject: [PATCH] Create README.zh.md --- README.zh.md | 509 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 509 insertions(+) create mode 100644 README.zh.md diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..033939e --- /dev/null +++ b/README.zh.md @@ -0,0 +1,509 @@ +[🇬🇧 English](./README.md) | **🇨🇳 汉语** | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | [🇷🇺 русский](./README.ru.md) | [🇩🇪 Deutsch](./README.de.md) | [🇫🇷 français](./README.fr.md) | [🇰🇷 한국어](./README.ko.md) | [🇧🇷 português](./README.pt.md) + +# tzst + +[![codecov](https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU)](https://codecov.io/gh/xixu-me/tzst) +[![CodeQL](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql) +[![CI/CD](https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/ci.yml) +[![PyPI - Version](https://img.shields.io/pypi/v/tzst)](https://pypi.org/project/tzst/) +[![GitHub License](https://img.shields.io/github/license/xixu-me/tzst)](LICENSE) +[![Sponsor](https://img.shields.io/badge/Sponsor-violet)](https://xi-xu.me/#sponsorships) + +**tzst** 是一个面向现代归档管理的新一代 Python 库，利用前沿的 Zstandard 压缩技术，提供卓越的性能、安全性和可靠性。专为 Python 3.12+ 打造，这个企业级解决方案结合原子操作、流式处理效率和精心设计的 API，重新定义了开发者在生产环境中处理 `.tzst`/`.tar.zst` 归档文件的方式。🚀 + +## ✨ 功能特性 + +- **🗜️ 高效压缩**：采用 Zstandard 压缩算法，实现优异的压缩率和速度 +- **📁 Tar 兼容性**：创建符合标准的 tar 归档并使用 Zstandard 压缩 +- **💻 命令行界面**：直观的 CLI，支持流式处理和全面选项 +- **🐍 Python API**：简洁、符合 Python 风格的编程接口 +- **🌍 跨平台支持**：兼容 Windows、macOS 和 Linux +- **📂 多扩展名支持**：同时支持 `.tzst` 和 `.tar.zst` 扩展名 +- **💾 内存高效**：流模式可高效处理大型归档文件 +- **⚡ 原子操作**：安全的文件操作，中断时自动清理 +- **🔒 默认安全**：提取时使用 'data' 过滤器确保最高安全性 +- **🚨 增强的错误处理**：清晰的错误信息和实用建议 + +## 📥 安装指南 + +### 从 GitHub Releases 安装 + +下载无需 Python 环境的独立可执行文件： + +#### 支持平台 + +| 平台 | 架构 | 文件 | +|------|------|------| +| **🐧 Linux** | x86_64 | `tzst-v{版本}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{版本}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{版本}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{版本}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{版本}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{版本}-macos-arm64.zip` | + +#### 🛠️ 安装步骤 + +1. **📥 下载**：从[最新发布页面](https://github.com/xixu-me/tzst/releases/latest)下载适合您平台的压缩包 +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 安装 + +```bash +pip install tzst +``` + +### 🔧 从源码安装 + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install . +``` + +### 🚀 开发环境安装 + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +## 🚀 快速开始 + +### 💻 命令行使用 + +> **注意**：下载[独立二进制文件](#从-github-releases-安装)可获得最佳性能且无需Python环境。也可使用 `uvx tzst` 免安装运行，详见[uv文档](https://docs.astral.sh/uv/)。 + +```bash +# 📁 创建归档 +tzst a archive.tzst file1.txt file2.txt directory/ + +# 📤 提取归档 +tzst x archive.tzst + +# 📋 列出归档内容 +tzst l archive.tzst + +# 🧪 测试归档完整性 +tzst t archive.tzst +``` + +### 🐍 Python API 使用 + +```python +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") +``` + +## 💻 命令行接口 + +### 📁 归档操作 + +#### ➕ 创建归档 + +```bash +# 基本用法 +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/ +``` + +#### 📤 提取归档 + +```bash +# 完整目录结构提取 +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/ +``` + +#### 📋 列出内容 + +```bash +# 简单列表 +tzst l archive.tzst + +# 详细列表 +tzst l archive.tzst -v + +# 大文件使用流模式 +tzst l archive.tzst --streaming -v +``` + +#### 🧪 测试完整性 + +```bash +# 测试归档完整性 +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`：禁用原子文件操作（不推荐） + +### 🔒 安全过滤器 + +```bash +# 最高安全性提取（默认） +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 类 + +```python +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() + +```python +from tzst import create_archive + +# 原子操作创建（默认） +create_archive( + archive_path="backup.tzst", + files=["documents/", "photos/", "config.txt"], + compression_level=10 +) +``` + +#### 📤 extract_archive() + +```python +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() + +```python +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() + +```python +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` - 替代标准扩展名 +- 打开现有归档时自动检测 +- 创建归档时自动添加扩展名 + +```python +# 以下创建方式均有效 +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的归档文件 +- 内存有限的环境 +- 处理包含多个大文件的归档 + +```python +# 示例：处理大型备份归档 +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) +``` + +### ⚡ 原子操作 + +所有文件创建操作默认使用原子操作： + +- 归档先在临时文件创建，然后原子移动 +- 进程中断时自动清理 +- 无损坏或不完整归档风险 +- 跨平台兼容 + +```python +# 默认启用原子操作 +create_archive("important.tzst", files) # 中断时安全 + +# 可禁用（不推荐） +create_archive("test.tzst", files, use_temp_file=False) +``` + +### 🚨 错误处理 + +```python +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 或更高版本 +- 📦 zstandard >= 0.19.0 + +## 🛠️ 开发指南 + +### 🚀 设置开发环境 + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +### 🧪 运行测试 + +```bash +# 带覆盖率的测试 +pytest --cov=tzst --cov-report=html + +# 简化命令 (覆盖配置在 pyproject.toml) +pytest +``` + +### ✨ 代码质量 + +```bash +# 代码检查 +ruff check src tests + +# 代码格式化 +ruff format src tests +``` + +## 🤝 贡献指南 + +欢迎贡献！请阅读[贡献指南](CONTRIBUTING.md)了解： + +- 开发设置和项目结构 +- 代码风格指南和最佳实践 +- 测试要求和编写测试 +- PR流程和审核规范 + +### 🚀 贡献者快速入门 + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +python -m pytest tests/ +``` + +### 🎯 欢迎贡献类型 + +- 🐛 **缺陷修复** - 修复现有功能问题 +- ✨ **新功能** - 扩展库的功能 +- 📚 **文档** - 改进或新增文档 +- 🧪 **测试** - 增加或改进测试覆盖 +- ⚡ **性能** - 优化现有代码 +- 🔒 **安全** - 修复安全漏洞 + +## 🙏 致谢 + +- [Meta Zstandard](https://github.com/facebook/zstd) 提供的优秀压缩算法 +- [python-zstandard](https://github.com/indygreg/python-zstandard) 的 Python 绑定 +- Python 社区的宝贵反馈和启发 + +## 📄 许可证 + +版权所有 © 2025 [Xi Xu](https://xi-xu.me)。保留所有权利。 + +采用 [BSD 3-Clause](LICENSE) 许可证授权。