- 新增 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/
3.5 KiB
3.5 KiB
通道与数据源
通达信的不同数据散落在不同的协议和服务器上。选路是 router.py 的职责,
调用方不需要关心——但知道「为什么慢」「为什么某个字段没有」时,这张表是排错起点。
路由表
| 请求 | 通道 | 为什么 |
|---|---|---|
| K 线 — 复权(QFQ / HFQ) | MAC | 复权数据只有 MAC 通道提供 |
K 线 — MIN_1 不复权 |
MAC | 标准通道 1 分钟深度不足;且必须串行分页 |
| K 线 — 其他周期不复权 | 标准 | 价格小数位规则已验证 |
| 指数 K 线 | 标准 | 含涨跌家数等指数专有字段 |
| 五档报价 | 标准 | 标准通道字段更全(含 decimal_point) |
| 逐笔成交 | MAC | 含 trade_count(成交笔数),且支持历史回溯 |
| 分时 | MAC | 标准通道不完整;MAC 0x122D 稳定返回 240 条 |
| 证券列表 / 数量 | 标准 | 仅标准通道提供 |
| 除权除息 / 财务 | 标准 | 仅标准通道提供 |
| 板块 / 竞价 / 异动 / 快照 / 资金流 / 服务器时段 / 分类报价 | MAC | 这些是 MAC 专有命令 |
| 港股 / 美股 / 期货 / 期权 | EX(7727) | 完全不同的协议栈 |
!!! note "只请求,不改语义"
路由是内部实现细节。同一个 get_kline() 调用,传不传 adjust 会走不同通道,
但返回类型和字段完全一致——你不需要写 if adjust: 分支。
三组服务器
src/pytdxdata/servers.json 里维护三份清单,分别对应三个连接池:
| 池 | 数量级 | 用途 |
|---|---|---|
| 标准池 | 数十台 | 报价 / K线 / 列表 / 财务 |
| MAC 池 | 数台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 |
| EX 池 | 4 台 | 港股 / 美股 / 期货 / 期权 |
EX 池内部还要再分两类,因为握手方式不同:
| 类型 | 数量 | 握手 |
|---|---|---|
| MAC EX 服务器 | 2 | 0x2454 login |
| pytdx EX 服务器 | 2(通达信扩展市场 / 国泰君安) | 0x2454 setup |
这就是 config.get_ex_handshakes() 存在的原因——EX 的 4 台机器不是同一种握手。
MAC 池远小于标准池,这也解释了为什么逐笔 / 分时的并发能力天然弱于日线。
为什么这些服务器会被「探测」
服务器列表不是静态配置——通达信节点会下线、换 IP、或者握手正常但返回空数据。
server_probe 的探测逻辑不是只看 TCP 连通性,而是真实请求一段 K 线并校验内容:
python -m pytdxdata.server_probe
普通「只 ping 握手」的探测会把这类坏节点放进来,症状是偶发的空返回—— 比直接连不上更难查。所以探测必须校验数据。
EX 通道细节
- 端口固定 7727,与标准 / MAC 的 7709 不同
- 走 pytdx EX 协议(
0x23FFK线 /0x23FA报价 /0x23F4市场列表) - 合约代码规则与 A 股不同:港股 5 位(
00700)、美股字母(AAPL)、 期货带月份(IFL0/rb2610)、期权 8 位(10010971) - 美股期权 / 港股期权协议内无数据
from pytdxdata.models import ExMarket, KlinePeriod
await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)
await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)
ExMarket 的完整成员见 枚举速查。