跳转至

设计理念

为什么选择 zerodep？

现代 Python 开发中，引入一个功能往往意味着拉入一棵庞大的依赖树。一个 YAML 解析器带来 C 扩展编译链，一个 HTTP 客户端拉入六七个子包。每一个依赖都是潜在的供应链风险、版本冲突和维护负担。

zerodep 采取了不同的思路：每个模块都是一个自包含的单 .py 文件，仅使用 Python 标准库。你只需复制所需的文件到项目中，提交到版本控制，然后开始使用。

核心原则

零外部依赖

每个模块仅依赖 Python 标准库（urllib、json、ast、re、ssl、struct 等）。运行时无需 pip install。这使得 zerodep 模块非常适合：

  • 受限环境 — 隔离网络的服务器、嵌入式系统、最小化容器
  • 引导工具 — 在 pip 可用之前就需要运行的脚本
  • 供应链敏感项目 — 更少的第三方包需要审计

单文件模块

每个模块是一个 .py 文件（偶尔有变体如 aes_python.py）。这意味着：

  • 易于引入 — cp scheduler.py your_project/
  • 易于审计 — 只需阅读一个文件，没有隐藏的包结构
  • 易于版本管理 — 每个模块自带 __version__

正确性优先，性能对等甚至更优

每个模块都与其对标的参考库进行逐一对比测试（PyYAML、httpx、pydantic 等）。先跑正确性测试，再跑基准测试。在实践中，大多数 zerodep 模块实现了性能对等甚至更优——例如 sparse_search 查询速度比 rank-bm25 快 34-132 倍，scheduler 的 cron 解析比同类快 3.6-11.5 倍，AES 模块提供 OpenSSL ctypes 后端，性能与 pycryptodome 对等。查看在线基准测试面板获取最新结果。

模块间显式依赖

部分模块构建在其他模块之上：

模块 依赖
sse httpclient
vcs diff

这些关系通过每个模块源码中的 PEP 723 风格 frontmatter 注释块声明：

# /// zerodep
# version = "0.1.0"
# deps = ["httpclient"]
# ///

CLI 工具在添加模块时会自动解析这些依赖。

适用场景

zerodep 模块适合以下场景：

  • 你只需要一个大型库的单个功能（如 YAML 解析、重试逻辑）
  • 你想出于安全或运维原因最小化依赖树
  • 你在构建只需 Python 即可运行的 CLI 工具或脚本
  • 你工作在无法使用 pip install 的环境中

不适用场景

在以下情况下，建议使用成熟的第三方库：

  • 你需要完整的规范实现（如完整的 YAML 1.2 规范，而非常用子集）
  • 你需要C 扩展级别的性能用于 CPU 密集型热循环，且 OpenSSL ctypes 路径仍不够快
  • 你依赖生态系统集成（如框架需要特定库的 API 或插件接口）

模块生命周期

构想 → 实现 → 正确性测试 → 基准测试 → 文档 → 清单注册
  1. 实现 — 编写单个 .py 文件，包含 # /// zerodep frontmatter
  2. 测试 — 添加 test_<module>_correctness.py，与参考库进行对比测试
  3. 基准 — 添加 test_<module>_benchmark.py，使用 pytest-benchmark
  4. 文档 — 添加模块页面、API 参考和基准测试结果
  5. 注册 — 运行 zerodep manifest 重新生成 manifest.json