# pytar

**Repository Path**: alittlesir/pytar

## Basic Information

- **Project Name**: pytar
- **Description**: tar的python版本，第一版纯ai实现
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 项目结构

```
├── setup.cfg            # 包元数据（名称、版本、依赖、入口点）
├── setup.py             # 安装脚本
├── run_tests.py         # 测试运行入口
├── pytar/               # 核心包
│   ├── __init__.py      # 包入口，暴露公共 API
│   ├── tarformat.py     # tar 格式定义（对应 tar.h）
│   │                    #   - BLOCKSIZE / RECORDSIZE 常量
│   │                    #   - TarHeader dataclass（ustar/GNU/PAX header 读写）
│   │                    #   - 八进制/base-256 编解码
│   │                    #   - TarMember（成员元数据）
│   ├── xheader.py       # PAX 扩展头部（对应 xheader.c）
│   │                    #   - encode/decode PAX records
│   │                    #   - 构建全局/本地 PAX 头块
│   ├── buffer.py        # 归档 I/O 缓冲层（对应 buffer.c）
│   │                    #   - ArchiveBuffer（读写、blocking_factor）
│   │                    #   - 压缩支持：gzip / bz2 / lzma(xz) / zstd / lz4
│   │                    #   - open_archive() 上下文管理器
│   ├── list.py          # 读取/列出成员（对应 list.c）
│   │                    #   - ArchiveReader（迭代 TarMember）
│   │                    #   - list_archive() 便捷函数
│   ├── create.py        # 创建归档（对应 create.c）
│   │                    #   - Creator（递归遍历、稀疏文件、排除规则）
│   │                    #   - create_archive() 便捷函数
│   ├── extract.py       # 解档（对应 extract.c）
│   │                    #   - Extractor（覆盖策略、权限、时间戳、安全检查）
│   │                    #   - extract_archive() 便捷函数
│   ├── compare.py       # 归档对比（对应 compare.c）
│   ├── delete.py        # 删除成员（对应 delete.c）
│   ├── update.py        # 追加/更新成员（对应 update.c）
│   └── cli.py           # 命令行接口（对应 tar.c 参数处理）
│                        #   - GNU 风格长/短选项，旧式无破折号标志
│                        #   - 完整子命令：-c/-x/-t/-r/-u/-d/--delete/-A
└── tests/
    ├── __init__.py
    └── test_pytar.py    # 36 个测试用例，覆盖所有核心模块
```

## 功能覆盖

| 功能 | C 源文件 | Python 模块 | 状态 |
|------|---------|------------|------|
| tar 格式定义（ustar/GNU/PAX） | tar.h | tarformat.py | ✅ |
| PAX 扩展头部 | xheader.c | xheader.py | ✅ |
| 归档 I/O 缓冲 | buffer.c | buffer.py | ✅ |
| 归档列表/读取 | list.c | list.py | ✅ |
| 归档创建 | create.c | create.py | ✅ |
| 归档解档 | extract.c | extract.py | ✅ |
| 归档对比 | compare.c | compare.py | ✅ |
| 成员删除 | delete.c | delete.py | ✅ |
| 成员追加/更新 | update.c | update.py | ✅ |
| 命令行接口 | tar.c | cli.py | ✅ |

## 压缩格式支持

- gzip（`-z`）
- bzip2（`-j`）
- xz/lzma（`-J`）
- zstd（`--zstd`，需安装 `zstandard`）
- lz4（`--lz4`，需安装 `lz4`）
- 自动检测（`-a`，根据后缀名）

## 测试结果

```
Ran 36 tests in 0.089s
OK  (36/36 全部通过)
```

测试覆盖：
- `TestArchiveBuffer`：EOF、多块读写、skip
- `TestTarHeaderRoundTrip`：普通文件、目录、软链接、长文件名
- `TestOctalCodec`：小值、零值、空格填充、大值（base-256）、溢出
- `TestStringCodec`：编解码、截断
- `TestChecksum`：有效头部、坏校验和、零块
- `TestPaxHeader`：单记录、多记录、Unicode、空记录
- `TestCreateListExtract`：完整归档/解档回路、gzip 压缩、--strip-components
- `TestDelete`：删除成员
- `TestSecurity`：绝对路径过滤、`..` 拒绝、strip-components 安全
- `TestCLI`：help、version、旧式标志、无子命令错误、完整创建/列出流程

## 使用方式

```bash
cd d:/github/tar/pytar

# 安装
pip install -e .

# 创建归档
pytar -czf archive.tar.gz mydir/

# 列出内容
pytar -tzf archive.tar.gz

# 解档
pytar -xzf archive.tar.gz -C /dest/

# 删除成员
pytar --delete -f archive.tar memberfile
```