- 新增 MkDocs + Material 文档站(19 页):入门、CLI、场景示例、FAQ、 Contributing、Changelog、API 参考(mkdocstrings 自动渲染)、内部原理 (架构 / 协议 / 三池路由 / 缓存) - 新增 docs/llms.txt:面向 LLM 的结构化摘要(枚举取值、方法速查、常见陷阱) - 新增 scripts/check_docs.py:校验文档与 api.py 公开方法清单是否漂移 - 新增根 CHANGELOG.md 作为版本记录唯一来源,docs/changelog.md 用 snippet 引入 - 新增 .github/workflows/docs.yml:push main 自动构建并部署 GitHub Pages - 修正文档口径:TdxData 公开方法 53 个(51 数据方法 + start/close); API_REFERENCE 版本号 v0.3.2 -> v0.4.0 - pyproject.toml 新增 docs 依赖组;.gitignore 忽略 site/
4.4 KiB
参与贡献
欢迎 Issue / PR。这个项目对「数据正确性」的要求高于「功能数量」——一个算错的字段比没有这个字段糟糕得多。
开发环境
git clone git@github.com:openbot-coder/pytdxdata.git
cd pytdxdata
uv sync # 建虚拟环境 + 安装 CLI + 装测试依赖
要求 Python ≥ 3.11。项目用 uv 管理依赖和构建,构建后端是 uv_build。
跑测试
.venv/Scripts/python.exe -m pytest tests/ -q # Windows
.venv/bin/python -m pytest tests/ -q # Linux / macOS
!!! danger "不要用 uv run pytest(Windows)"
Windows 上会报 uv trampoline failed to canonicalize script path。直接调 venv 里的解释器。
!!! warning "Windows 上异步测试会卡死"
根因是 asyncio 建事件循环时用到的回环 socketpair 被本地代理 / 安全软件拦截。
详见 常见问题 → 开发与测试。
因此**CI 在 Linux 上跑首轮异步验证**;Windows 侧只能做同步驱动验证。
现有测试全部是 mock 驱动、不连网络 的离线测试(tests/test_api.py 里的
FakeApiConn / FakePool 就是为这个准备的)。新增功能请沿用这个模式,
不要把真实网络请求写进单测。
代码约定
| 约定 | 说明 |
|---|---|
| 数据模型 | 全部 @dataclass(slots=True),集中在 models/__init__.py(无子模块) |
| 解析器 | 统一放 codec/,纯标准库(struct / zipfile),做到脱网可单测 |
| API 兼容性 | 保持向后兼容。新增能力用新方法名(如 get_block_parsed),不改旧方法签名或返回值 |
| 类型注解 | 全部公开接口必须有完整注解(Typing :: Typed) |
| 依赖 | 运行时不加新依赖是本项目的核心卖点,PR 里请勿引入 |
新增一个行情接口的完整步骤
protocol/commands/<域>.py— 实现命令类(帧组装 + 响应解析)router.py— 若需要按命令选通道,在这里登记models/__init__.py— 加返回的 dataclass / 枚举api.py— 加TdxData公开方法cli.py— 可选,加子命令tests/— 离线测试(构造字节流 → 断言解析结果)- 文档 — 更新
docs/api/index.md的方法表 +docs/API_REFERENCE.md
第 7 步别漏。历史上已经发生过「加了方法但文档没跟上」的漂移。
文档
文档站是 MkDocs + Material,配置在 mkdocs.yml,源文件在 docs/。
uv sync --group docs
uv run mkdocs serve # http://127.0.0.1:8000 实时预览
uv run mkdocs build # 产出到 site/
| 内容类型 | 写到哪 |
|---|---|
| 30 秒能看懂的东西、特性表、徽章 | README.md(保持精简) |
| 教程、场景示例、CLI 用法、原理 | docs/ 对应页面 |
| 每个方法的参数 / 返回值 | docs/api/(从 docstring 自动生成,不要手写) |
| 版本变更 | CHANGELOG.md(唯一来源,文档站通过 snippet 引入) |
!!! tip "API 文档不要手抄"
docs/api/tdxdata.md 这类页面用 mkdocstrings 直接从 api.py 的 docstring 渲染。
你只要把 docstring 写好,文档就自动是对的。手抄签名一定会漂移。
提交与发布
分支模型:develop → PR → main。
git checkout -b feat/xxx
# ... 改代码 ...
.venv/Scripts/python.exe -m pytest tests/ -q
git commit -m "feat: xxx"
git push origin feat/xxx
发布流程(维护者)
- 改
pyproject.toml+src/pytdxdata/__init__.py的版本号 uv lock—— 同步uv.lock,否则 CI 的uv sync --locked会失败- 提交并 push 到
main - 打标签并推送:
git tag v0.5.0 git push origin v0.5.0
推 tag 会自动触发 GitHub Actions:test → build(含版本号一致性校验)→ OIDC 免密钥发布到 PyPI。
不需要本地 token,也不需要 twine。
!!! warning "tag 已推送但发布失败时" 同名 tag 不能直接重推(push 无变化,workflow 不会触发)。先删再推:
```bash
git push --delete origin v0.5.0
git tag -d v0.5.0 && git tag v0.5.0
git push origin v0.5.0
```
或直接手动触发:`gh workflow run release.yml --ref v0.5.0`
文档站由 .github/workflows/docs.yml 在 push main 时自动部署到
https://openbot-coder.github.io/pytdxdata/。