docs: 建立 MkDocs 文档站与 AI 层文档
- 新增 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/
This commit is contained in:
1 parent
02ec5b6e33
commit
c4dd61665b
26 files changed
+2934
-1
No files matched your search
@@ -0,0 +1,108 @@
|
||||
# 架构总览
|
||||
|
||||
## 分层
|
||||
|
||||
调用链是单向的,每一层只依赖它下面的一层——想加新接口时先想清楚「这属于哪一层」。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["api.py — TdxData<br/>唯一对外入口,51 个公开方法"] --> B["router.py<br/>按命令选通道"]
|
||||
B --> C["pool/ — 动态连接池<br/>标准池 / MAC 池 / EX 池"]
|
||||
B --> D["scheduler/ — 并发分页调度<br/>Paginator"]
|
||||
C --> E["protocol/ — 协议层<br/>帧 / 变长整数 / 价格 / 日期 / 命令"]
|
||||
E --> F["TCP 通达信服务器<br/>7709 标准+MAC · 7727 EX"]
|
||||
A --> G["cache/ — 双层 TTL 缓存<br/>Memory LRU → Disk SQLite"]
|
||||
A --> H["codec/ — 解析与序列化<br/>缓存载荷 / 服务器文件"]
|
||||
H --> I["models/ — dataclass + 枚举"]
|
||||
```
|
||||
|
||||
## 目录
|
||||
|
||||
```
|
||||
src/pytdxdata/
|
||||
├── api.py # 统一接口 TdxData(对外唯一入口)
|
||||
├── router.py # 标准 / MAC / EX 通道选路
|
||||
├── config.py # 服务器清单加载(servers.json)
|
||||
├── indicator.py # 技术指标(纯函数,无依赖)
|
||||
├── server_probe.py # 服务器探测,可 python -m 运行
|
||||
├── protocol/ # 协议层
|
||||
│ ├── frame.py # 标准帧
|
||||
│ ├── mac_frame.py # MAC 帧
|
||||
│ ├── _binary.py # 变长整数等底层字节工具
|
||||
│ ├── price.py # 自定义浮点价格还原
|
||||
│ ├── volume.py # 成交量差分还原
|
||||
│ ├── datetime_.py # 日期 / 时间编码
|
||||
│ └── commands/ # 16 个命令模块
|
||||
├── pool/ # 连接池
|
||||
│ ├── connection.py # 单连接(含重连)
|
||||
│ ├── pool.py # 标准 / MAC 动态池
|
||||
│ ├── ex_pool.py # EX 池
|
||||
│ ├── health.py # 健康分与选路
|
||||
│ └── probe_cache.py # 探测结果缓存
|
||||
├── scheduler/
|
||||
│ └── paginator.py # 并发分页调度(3 连接并行)
|
||||
├── cache/
|
||||
│ ├── key.py # 缓存键规范化
|
||||
│ ├── ttl.py # TTL 分级策略
|
||||
│ ├── memory.py # 内存 LRU
|
||||
│ ├── disk.py # 磁盘 SQLite(WAL)
|
||||
│ └── manager.py # 两级协同 + single-flight
|
||||
├── models/ # dataclass + 枚举(单文件,无子模块)
|
||||
└── codec/ # 缓存载荷序列化 + 服务器文件解析
|
||||
├── payload.py # 缓存载荷 pickle + zlib
|
||||
├── block.py # 板块 .dat
|
||||
├── industry.py # tdxhy.cfg
|
||||
└── financial.py # gpcw.txt / gpcw*.zip
|
||||
```
|
||||
|
||||
## 一次 `get_kline` 的完整路径
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 调用方
|
||||
participant A as api.py
|
||||
participant C as cache/
|
||||
participant R as router.py
|
||||
participant P as pool/
|
||||
participant S as scheduler/
|
||||
|
||||
U->>A: get_kline(SH, 600000, DAY, count=2400)
|
||||
A->>A: 规范化缓存键
|
||||
A->>C: 查缓存
|
||||
alt 命中
|
||||
C-->>A: list[SecurityBar]
|
||||
A-->>U: 直接返回(0 网络 0 解析)
|
||||
else 未命中
|
||||
A->>C: 登记 single-flight
|
||||
A->>R: 选通道
|
||||
R-->>A: 标准通道
|
||||
A->>S: 分页(count=2400 → 3 页)
|
||||
S->>P: 并发取 3 个连接
|
||||
P->>P: 健康分 + EWMA 延迟选路
|
||||
P-->>S: 3 个连接
|
||||
S->>S: 并行拉取 → 按序拼接
|
||||
S-->>A: 完整 bars
|
||||
A->>C: 写入内存 + 磁盘
|
||||
A-->>U: 返回
|
||||
end
|
||||
```
|
||||
|
||||
关键点:
|
||||
|
||||
- **缓存查在选路之前**——命中就完全不走网络,所以重复请求是 0.016s 量级
|
||||
- **single-flight 在缓存层**——同一个键的并发请求会合并成一次回源,其余等待结果
|
||||
- **分页与选路分离**——`scheduler` 只管拆分与拼接,不知道通道差异;`pool` 只管给连接
|
||||
|
||||
## 三个设计约束
|
||||
|
||||
| 约束 | 原因 |
|
||||
|---|---|
|
||||
| **零运行时依赖** | 用 `socket` / `zlib` / `struct` / `sqlite3` / `asyncio` 全部搞定,避免依赖地狱和版本冲突 |
|
||||
| **返回 `list[dataclass]`** | 不让调用方被 pandas 绑架;需要 DataFrame 自己转一行 |
|
||||
| **API 向后兼容** | 新增能力用新方法名(`get_block_parsed` 而不是改 `get_block_info` 的返回类型),老代码永不失效 |
|
||||
|
||||
## 下一步
|
||||
|
||||
- [协议与命令](protocol.md) — 最底层在做什么
|
||||
- [通道与数据源](routing.md) — 为什么有的请求走不同的服务器
|
||||
- [连接池与缓存](cache-pool.md) — 性能来自哪里
|
||||
@@ -0,0 +1,113 @@
|
||||
# 连接池与缓存
|
||||
|
||||
这个项目相比同类实现快 **约 2 倍**,来源就是这两块。
|
||||
|
||||
## 缓存
|
||||
|
||||
### 两级结构
|
||||
|
||||
```
|
||||
内存 LRU ──miss──▶ 磁盘 SQLite (WAL) ──miss──▶ 回源网络
|
||||
↑ ↑
|
||||
快,进程内 跨进程 / 跨重启持久
|
||||
```
|
||||
|
||||
- **内存层**:进程内 LRU,命中就是字典查找
|
||||
- **磁盘层**:单文件 SQLite,开 WAL 模式,**可多进程共享**
|
||||
- 未传 `cache_dir` 时只有内存层(进程退出即失效)
|
||||
|
||||
### TTL 分级
|
||||
|
||||
不同数据的「新鲜度要求」差了几个数量级,所以 TTL 是分级的:
|
||||
|
||||
| 数据类型 | TTL | 理由 |
|
||||
|---|---|---|
|
||||
| 五档报价 | **5s** | 变化最快 |
|
||||
| 分钟 K 线 | **60s** | 边界处才会新增一根 |
|
||||
| 日 K 线 | **当天** | 当天数据在盘中会变 |
|
||||
| 复权 K 线 | **1 天** | 复权因子一天最多变一次 |
|
||||
| 历史逐笔 | **永久** | 已经成交的不会变 |
|
||||
| 证券列表 | **1 天** | 只有新股上市才变 |
|
||||
|
||||
### 缓存的是「已解析记录」
|
||||
|
||||
缓存里存的是**解析好的 dataclass 对象**(`codec/payload.py` 做 pickle + zlib),
|
||||
不是原始响应字节。所以缓存命中时是 **0 网络 + 0 解析**,只有一次反序列化。
|
||||
|
||||
这也是为什么重复请求能从 0.31s 降到 **0.016s**。
|
||||
|
||||
### single-flight
|
||||
|
||||
同一时刻对**同一个缓存键**的并发请求会自动合并:第一个去回源,其余的等待并共享结果。
|
||||
|
||||
```python
|
||||
# 100 个协程同时请求同一只股票的同一段 K 线
|
||||
# → 只发 1 次网络请求
|
||||
results = await asyncio.gather(*[
|
||||
td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=800)
|
||||
for _ in range(100)
|
||||
])
|
||||
```
|
||||
|
||||
上限由 `max_inflight`(默认 `64`)控制。
|
||||
|
||||
> 缓存键会做**规范化**——`get_quotes` 的键是排序去重后的股票集合,
|
||||
> 所以 `[A, B]` 和 `[B, A]` 共享缓存。
|
||||
|
||||
## 连接池
|
||||
|
||||
### 动态扩缩容
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|---|---|---|
|
||||
| `pool_min` | `3` | 保底连接数 |
|
||||
| `pool_max` | `12` | 上限 |
|
||||
| `mac_pool_cap` | `4` | **单台** MAC 服务器连接上限 |
|
||||
| `timeout` | `3.0` | 连接超时(秒) |
|
||||
|
||||
按**等待队列长度**与**空闲时长**动态扩缩容,不是启动时就拉满。
|
||||
|
||||
### 健康分与选路
|
||||
|
||||
每台服务器维护一个健康分,取连接时按健康分 **+ EWMA 延迟**综合选路:
|
||||
|
||||
| 事件 | 健康分变化 |
|
||||
|---|---|
|
||||
| 请求失败 | **× 0.5** |
|
||||
| 请求成功 | **+ 0.2** |
|
||||
| 连续失败 | 进入 **120s 冷却**,冷却期内不再被选中 |
|
||||
|
||||
失败会**跨服务器故障转移**——重试用的是另一台,而不是同一台重连。
|
||||
|
||||
EWMA(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。
|
||||
|
||||
### 为什么 MAC 池更小
|
||||
|
||||
MAC 通道可用服务器只有数台(见 [通道与数据源](routing.md#server-groups)),
|
||||
所以 `mac_pool_cap` 默认只有 `4`——这是**对端限制**,不是本项目的选择。
|
||||
逐笔 / 分时的并发能力天然弱于日线,原因就在这里。
|
||||
|
||||
## 并发分页
|
||||
|
||||
大请求会被拆成多页,每页带**显式 `start` 偏移**——**无状态,所以可以并行**。
|
||||
多连接并行拉取 → 按序拼接 → 某页失败就换连接重试该页。
|
||||
|
||||
```
|
||||
count=2400 → 3 页 → 3 个连接并行 → 按序拼接
|
||||
```
|
||||
|
||||
两种例外:
|
||||
|
||||
| 场景 | 策略 | 原因 |
|
||||
|---|---|---|
|
||||
| `KlinePeriod.MIN_1` | **单连接串行** | 各服务器历史深度不一致,并发会导致非确定性空洞 |
|
||||
| MAC 通道复权 K 线 | **单连接串行**(`_fetch_mac_kline_serial`) | 同上 |
|
||||
|
||||
!!! tip "调参建议"
|
||||
`concurrency` 超过 `pool_max` 之后只会排队。实践值 **8~16**。
|
||||
MAC 类请求(逐笔 / 分时)并发能力受 `mac_pool_cap` 限制,调大 `concurrency` 无用。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [架构总览](architecture.md) — 这些模块在整体里的位置
|
||||
- [常见问题](../faq.md) — 缓存与超时的排查
|
||||
@@ -0,0 +1,102 @@
|
||||
# 协议与命令
|
||||
|
||||
约 2500 行里最硬的部分。目标是:**不依赖 `pytdx` / `easy-tdx`,自己把线上字节跑通**。
|
||||
|
||||
> 本页讲「要解决什么问题」。**精确的字节布局以 `src/pytdxdata/protocol/` 源码为准**——
|
||||
> 每个命令类里的 `build_request()` / `parse_response()` docstring 都写了实际偏移。
|
||||
|
||||
## 三条协议
|
||||
|
||||
| | 标准通道 | MAC 通道 | EX 通道 |
|
||||
|---|---|---|---|
|
||||
| 端口 | 7709 | 7709 | **7727** |
|
||||
| 帧格式 | 经典 TDX 帧 | MAC 帧(带会话 seq) | pytdx EX 协议 |
|
||||
| 覆盖 | 报价 / K线 / 列表 / 除权 / 财务 | 逐笔 / 分时 / 复权K线 / 板块 / 竞价 / 资金流 | 港股 / 美股 / 期货 / 期权 |
|
||||
| 握手 | 无需登录 | `0x2454` login | `0x2454` setup/login |
|
||||
|
||||
MAC 与标准**共用 7709 端口但协议不同**,所以连接池也分成两个——一条 TCP 连接只能跑一种帧格式。
|
||||
|
||||
## 需要自己还原的编码
|
||||
|
||||
通达信不是「大端小端调对就完事」的协议,这些都得逆出来:
|
||||
|
||||
### 变长整数
|
||||
|
||||
部分字段用可变字节数编码。`protocol/_binary.py` 负责读写。
|
||||
|
||||
### 差分还原
|
||||
|
||||
**成交量(volume)不是直接存的**。它是相对前一条记录的差分,必须按顺序累加还原。
|
||||
这意味着**不能随意乱序或跳读**——分页拼接时必须保证顺序正确。
|
||||
|
||||
### 自定义浮点价格
|
||||
|
||||
价格用一套私有编码而不是 IEEE754。`protocol/price.py` 负责还原。
|
||||
不同**品种**的小数位还不同:股票 2 位,指数 / ETF / 可转债 3 位。
|
||||
模型里的 `decimal_point` 就是这个信息。
|
||||
|
||||
### 日期 / 时间编码
|
||||
|
||||
`protocol/datetime_.py`。K 线里年月日时分是**分开的整数字段**,
|
||||
模型上额外提供了一个 `datetime` 属性做拼装。
|
||||
|
||||
## 命令模块
|
||||
|
||||
`protocol/commands/` 下 16 个模块,按业务域划分:
|
||||
|
||||
| 模块 | 负责 |
|
||||
|---|---|
|
||||
| `base.py` | 命令基类 |
|
||||
| `setup.py` | 连接建立与握手 |
|
||||
| `kline.py` | K 线(标准) |
|
||||
| `quotes.py` | 五档报价 |
|
||||
| `security_list.py` | 证券列表与数量 |
|
||||
| `transaction.py` | 逐笔成交 |
|
||||
| `minute.py` | 分时 |
|
||||
| `xdxr.py` | 除权除息 |
|
||||
| `finance.py` | 财务 |
|
||||
| `mac.py` | MAC 通道通用命令 |
|
||||
| `mac_ext.py` | MAC 扩展(板块 / 竞价 / 异动 / 快照 / 资金流) |
|
||||
| `mac_tick.py` | MAC 单日分时图(`0x122D`) |
|
||||
| `std_ext.py` | 标准通道扩展(F10 / 文件下载) |
|
||||
| `ex_ext.py` | EX 辅助接口 |
|
||||
| `ex_proto.py` | EX 主协议(K线 / 报价 / 市场列表) |
|
||||
|
||||
每个命令类只做两件事:**把参数打成请求字节**、**把响应字节解析成模型**。不做网络、不做缓存。
|
||||
|
||||
## 关键命令码
|
||||
|
||||
排错时对照用:
|
||||
|
||||
| 命令 | 码 | 通道 |
|
||||
|---|---|---|
|
||||
| K 线(标准) | — | 标准 |
|
||||
| K 线(MAC,支持复权) | `0x122E` | MAC |
|
||||
| 分时 | `0x122D` | MAC |
|
||||
| 远程文件元信息 | `0x1215` | MAC |
|
||||
| 远程文件下载 | `0x1217` | MAC |
|
||||
| 分时缩略采样 | `0x254D` | MAC |
|
||||
| 板块文件 | `0x06B9` 系 | 标准 |
|
||||
| EX K 线 | `0x23FF` | EX |
|
||||
| EX 报价 | `0x23FA` | EX |
|
||||
| EX 市场列表 | `0x23F4` / `0x23F5` | EX |
|
||||
| EX 港股逐笔 | `0x23FC` / `0x2406` | EX |
|
||||
| MAC / EX 登录 | `0x2454` | MAC / EX |
|
||||
|
||||
## 踩过的坑
|
||||
|
||||
这些是实际调试中撞出来的,写在这免得重踩:
|
||||
|
||||
| 现象 | 根因 |
|
||||
|---|---|
|
||||
| K 线数据**时有时无** | 标准通道部分服务器在 `count < 100` 时返回空 → 分页器强制 `min_page=100` |
|
||||
| MAC K 线**随机丢数据** | 并发分页把不同页分到深度不一致的服务器,`stop_when_short` 提前截断 → 改单连接串行 |
|
||||
| 1 分钟 K 线**深度不足** | 标准通道给的深度不够 → 切到 MAC `0x122E` |
|
||||
| 分时只有几十条 | 标准通道命令不完整 → 切到 MAC `0x122D`,稳定 240 条 |
|
||||
| 财报**市场字段恒为深市** | 上游用 `<6s1c1L` 解析,`1c` 的类型转换吞掉了市场字节 → 改 `<6sBL` |
|
||||
| 握手正常但**拉不到数据** | 坏节点。服务器探测改为「真实请求一段 K 线」而不是只看握手 |
|
||||
|
||||
## 下一步
|
||||
|
||||
- [文件解析器](../api/codec.md) — 服务器静态文件的字节格式
|
||||
- [通道与数据源](routing.md) — 哪个命令走哪条通道
|
||||
@@ -0,0 +1,80 @@
|
||||
# 通道与数据源
|
||||
|
||||
通达信的不同数据**散落在不同的协议和服务器上**。选路是 `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:` 分支。
|
||||
|
||||
## 三组服务器 {#server-groups}
|
||||
|
||||
`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 线并校验内容:
|
||||
|
||||
```bash
|
||||
python -m pytdxdata.server_probe
|
||||
```
|
||||
|
||||
普通「只 ping 握手」的探测会把这类坏节点放进来,症状是**偶发的空返回**——
|
||||
比直接连不上更难查。所以探测必须校验数据。
|
||||
|
||||
## EX 通道细节
|
||||
|
||||
- 端口固定 **7727**,与标准 / MAC 的 7709 不同
|
||||
- 走 **pytdx EX 协议**(`0x23FF` K线 / `0x23FA` 报价 / `0x23F4` 市场列表)
|
||||
- 合约代码规则与 A 股不同:港股 5 位(`00700`)、美股字母(`AAPL`)、
|
||||
期货带月份(`IFL0` / `rb2610`)、期权 8 位(`10010971`)
|
||||
- 美股期权 / 港股期权**协议内无数据**
|
||||
|
||||
```python
|
||||
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` 的完整成员见 [枚举速查](../api/enums.md#exmarket)。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [连接池与缓存](cache-pool.md) — 选到服务器之后怎么用
|
||||
- [协议与命令](protocol.md) — 通道底下的字节格式
|
||||
Reference in new issue
Block a user