Create README.zh.md
This commit is contained in:
xixu-me authored and 
GitHub committed
1 parent
194037b87c
commit
518e90f0ee
1 file changed
+509
+509
@@ -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
|
||||||
|
|
||||||
|
[](https://codecov.io/gh/xixu-me/tzst)
|
||||||
|
[](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql)
|
||||||
|
[](https://github.com/xixu-me/tzst/actions/workflows/ci.yml)
|
||||||
|
[](https://pypi.org/project/tzst/)
|
||||||
|
[](LICENSE)
|
||||||
|
[](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) 许可证授权。
|
||||||
Reference in new issue
Block a user