按「数据类型」合并同类查询接口:一个数据类型 = 一个方法,跨市场自动选路。 - 28 个统一接口(get_universe/get_quotes/get_bars/get_indicators/get_ticks/ get_minutes/get_f10/get_file/get_boards/get_board_of/get_snapshot 等), 标的统一字符串写法(sz000001 / hk00700 / usAAPL / cffex:IFL0); 同名旧方法不再兼容 (market, code) 元组。 - 旧 51 个按通道/市场分裂的接口:33 个保留为 deprecated 别名(1.0 移除), 18 个同名升级为统一接口。公开方法共 63 个。 - 新增库层标的解析 pytdxdata.symbols;数据模型追加 symbol/name/fields 兜底字段。 - 修复:分页器连接泄漏、日期区间 K线返回 0 条(偏移方向探测)、池子全冷却死等。 - 文档/README/SKILL/llms.txt 全量同步;新增 docs/refactor-audit.md 审查报告。 - 测试 127 个用例全绿(含 tests/test_all_interfaces.py 全 63 方法回归)。
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.6.0 git push origin v0.6.0
推 tag 会自动触发 GitHub Actions:test → build(含版本号一致性校验)→ OIDC 免密钥发布到 PyPI。
不需要本地 token,也不需要 twine。
!!! warning "tag 已推送但发布失败时" 同名 tag 不能直接重推(push 无变化,workflow 不会触发)。先删再推:
```bash
git push --delete origin v0.6.0
git tag -d v0.6.0 && git tag v0.6.0
git push origin v0.6.0
```
或直接手动触发:`gh workflow run release.yml --ref v0.6.0`
文档站由 .github/workflows/docs.yml 在 push main 时自动部署到
https://openbot-coder.github.io/pytdxdata/。