Metadata-Version: 2.4
Name: fastdd
Version: 1.1.0
Summary: Parallel file reader and in-place rewriter with resume and colorful progress
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# FastDD

多线程读取或原地重写文件，支持 SQLite 文件级断点续跑、实时彩色进度、吞吐量、ETA 和后台监控。运行时仅使用 Python 标准库，支持 Python 3.9+，Linux / macOS。

## 安装

从 PyPI 安装：

```bash
pip install fastdd
fastdd --version
fastdd --help
```

也可以使用独立环境：

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install fastdd
```

安装后所有操作均使用 `fastdd`。命令所在的 Python 环境需已激活或在 PATH 中。也可以下载源码后在项目目录运行 `pip install .`，或通过 `pip install /path/to/fastdd-1.1.0-py3-none-any.whl` 安装 wheel。

## 使用

读取目录内的所有普通文件：

```bash
fastdd run /data/dataset --mode read --workers 8 --state /tmp/fastdd-dataset
```

原地读出并写回相同内容：

```bash
fastdd run '/data/batch*' --mode rewrite --workers 8 --chunk-mb 32 --fsync --state /tmp/fastdd-rewrite
```

`rewrite` 会实际写入文件，改变修改时间；请用于处理期间不会被其他程序写入的文件。`--fsync` 在每个文件完成时同步写入。它不是备份或原子替换。

后台运行与监控（日志放在输入目录之外）：

```bash
nohup fastdd run /data/dataset --workers 8 --state /tmp/fastdd-dataset > /tmp/fastdd-dataset.log 2>&1 &
fastdd watch --state /tmp/fastdd-dataset
fastdd watch --state /tmp/fastdd-dataset --once
```

彩色输出：

```bash
fastdd run /data/dataset --state /tmp/fastdd-dataset --color always
fastdd watch --state /tmp/fastdd-dataset --color never
```

默认 `--color auto`：交互终端有颜色，重定向日志无 ANSI 颜色。支持 `NO_COLOR` 环境变量；显式 `--color always` 优先。`--color` 可放在子命令前或后。绿色表示完成、黄色表示扫描/跳过、红色表示错误、青色表示吞吐量与进度。

## 断点与状态

- 重复相同命令和 `--state` 会跳过路径、大小、修改时间与记录一致的已完成文件。
- `read` 和 `rewrite` 分别记录，切换模式不会误跳过。旧版脚本的数据库可以复用路径，但首次升级会重新处理，因为旧记录没有模式信息。
- 使用 `--no-resume` 强制重新处理，例如再次预热可能已经被系统淘汰的缓存。已完成记录不代表数据仍在缓存中。
- Ctrl+C / SIGTERM 在当前 I/O 调用完成后停止；未完成的文件下次从头处理。阻塞中的系统 I/O 可能需要等待。
- 状态保存为 `<state>.sqlite`、`<state>.status.json` 和 `<state>.lock`；当前任务自身的状态文件自动排除。一个状态前缀同时只允许一个任务使用。
- 跳过符号链接，不跟随符号链接目录。扫描进度在扫描结束后显示百分比；完成进度包括跳过和失败文件，是否成功应查看 `Failed` 和退出码。
- 吞吐量按处理的文件字节计算；`rewrite` 同时读写，显示值不是底层存储总 I/O 量。预热效果受操作系统和存储缓存策略影响。
- 默认每个 worker 使用最多 32 MiB 数据块，线程越多不保证越快。

退出码：`0` 成功，`1` 部分文件失败，`2` 参数/启动/状态错误，`130` 任务被中断。`watch` 成功显示状态时返回 `0`；查看失败数以判断被监控任务结果。

## 开发与验证

```bash
pip install -e .
python3 -m unittest discover -s tests -v
```

测试仅操作临时目录，覆盖读写内容、断点模式隔离、状态文件排除、颜色策略、短写处理和中断退出。
