FastDD

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

安装

从 PyPI 安装：

pip install fastdd
fastdd --version
fastdd --help

也可以使用独立环境：

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。

使用

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

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

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

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

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

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

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

彩色输出：

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；查看失败数以判断被监控任务结果。

开发与验证

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

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