release: v0.5.0(文档站 + README 瘦身 + AI 助手技能)
新增 - 文档站(MkDocs + Material + mkdocstrings),push main 自动构建并部署 GitHub Pages - SKILL.md:面向 AI 编程助手的技能文件(三条必守约定 / 枚举取值表 / 任务→方法决策表 / 9 条陷阱) - docs/ai.md:文档站的「AI 助手接入」页 - tests/test_check_docs.py(10 项):漂移检查器自身的自测 变更 - README 361 → 125 行,只保留入口层;CLI 手册 / API 表 / 通道路由 / 架构树 / 扩展市场 / easy-tdx 对比 / Changelog 全部移交文档站与 CHANGELOG.md - README 相对链接改为绝对 URL(PyPI 渲染不重写相对链接,原本在 PyPI 页面全 404) - check_docs.py 扩展为两档:MUST_LIST_ALL(须列全)+ MUST_NOT_BE_STALE(只需无过时引用), 并把 SKILL.md / README / llms.txt / 教程类页面纳入;白名单放行 config 的模块级函数 - 版本号 0.4.0 → 0.5.0;包元数据 Documentation 指向文档站 - uv.lock 同步 修复 - ExMarket 成员数 52 → 46(实测 IntEnum 成员数),4 处文档同步更正 - docs/ai.md 的 3 处相对链接 + CHANGELOG 的 SKILL.md 链接(会导致 mkdocs --strict 失败) - README 标注的测试数量 85 → 109(pytest 实际收集用例数)
This commit is contained in:
1 parent
c4dd61665b
commit
1bee6b0fc7
14 files changed
+516
-321
No files matched your search
+30
-5
@@ -2,17 +2,41 @@
|
|||||||
|
|
||||||
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
|
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
|
||||||
|
|
||||||
## [Unreleased]
|
## [0.5.0] - 2026-09-15
|
||||||
|
|
||||||
### 新增
|
### 新增
|
||||||
|
|
||||||
- **文档站**(MkDocs + Material,自动部署到 <https://openbot-coder.github.io/pytdxdata/>)
|
- **文档站**(MkDocs + Material + `mkdocstrings`),每次 push 自动构建并部署到
|
||||||
- [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) — 面向 LLM 的结构化摘要,供 AI 助手快速建立项目心智模型
|
<https://openbot-coder.github.io/pytdxdata/>
|
||||||
|
- **[`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md)** — 面向 AI 编程助手的技能文件:三条必守约定、枚举取值表、
|
||||||
|
「想做什么 → 用哪个方法」决策表、9 条真实陷阱
|
||||||
|
- [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) — 面向 LLM 的结构化摘要,随站点发布到根路径
|
||||||
- `CHANGELOG.md` 独立成文件(此前内嵌在 README 中)
|
- `CHANGELOG.md` 独立成文件(此前内嵌在 README 中)
|
||||||
|
- `scripts/check_docs.py` + CI 步骤 — **文档漂移检查**:代码有而文档漏写、或文档引用了已删除的方法,都会 fail
|
||||||
|
- `tests/test_check_docs.py`(10 项)— 漂移检查器自身的自测
|
||||||
|
|
||||||
### 变更
|
### 变更
|
||||||
|
|
||||||
- README 瘦身为「入口层」:只保留定位、安装、30 秒上手、特性与目录,深层内容迁入文档站
|
- **README 瘦身为「入口层」**:361 → 129 行。只保留定位 / 安装 / 30 秒上手 / 特性 / 文档导航 / 免责声明;
|
||||||
|
CLI 手册、API 表、通道路由、架构树、扩展市场、easy-tdx 对比、Changelog 全部移交文档站与 `CHANGELOG.md`
|
||||||
|
- API 文档改由 `mkdocstrings` **从 docstring 实时生成**,不再手抄(根治漂移)
|
||||||
|
- 漂移检查扩展为两档:`MUST_LIST_ALL`(须列全所有公开方法)+ `MUST_NOT_BE_STALE`(只需无过时引用),
|
||||||
|
并把 `SKILL.md` / `README.md` / `llms.txt` / 教程类页面一并纳入
|
||||||
|
- 包元数据 `Documentation` 由仓库首页改指文档站
|
||||||
|
- 测试用例 **99 → 109**
|
||||||
|
|
||||||
|
### 文档
|
||||||
|
|
||||||
|
- 新增文档站 19 页:快速开始 / 场景示例 / CLI / FAQ / 贡献指南 / 更新日志 /
|
||||||
|
API 参考(总览·TdxData·枚举·模型·指标·解析器)/ 深入原理(架构·协议·三池路由·缓存)
|
||||||
|
- 明确口径:`TdxData` 公开方法共 **53 个**(= 51 个数据方法 + `start` / `close`),
|
||||||
|
此前各处笼统写的「51 个公开方法」不严,已统一更正
|
||||||
|
|
||||||
|
### 修复
|
||||||
|
|
||||||
|
- 修正**中文标题锚点被默认 slugify 剥光**导致跨页深链接全部失效的问题
|
||||||
|
(改用 `pymdownx.slugs.slugify`,并给被引用的标题加显式 ASCII id;`--strict` 不会报这个错,只能靠锚点检查兜住)
|
||||||
|
- README 中标注的测试数量(85)与 pytest 实际收集数不符,已更正为 109 个用例
|
||||||
|
|
||||||
## [0.4.0] - 2026-09-15
|
## [0.4.0] - 2026-09-15
|
||||||
|
|
||||||
@@ -73,7 +97,8 @@
|
|||||||
|
|
||||||
- 初始版本:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页 + 双通道(标准 / MAC)+ 扩展市场(港股 / 美股 / 期货 / 期权)
|
- 初始版本:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页 + 双通道(标准 / MAC)+ 扩展市场(港股 / 美股 / 期货 / 期权)
|
||||||
|
|
||||||
[Unreleased]: https://github.com/openbot-coder/pytdxdata/compare/v0.4.0...HEAD
|
[Unreleased]: https://github.com/openbot-coder/pytdxdata/compare/v0.5.0...HEAD
|
||||||
|
[0.5.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.4.0...v0.5.0
|
||||||
[0.4.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.2...v0.4.0
|
[0.4.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.2...v0.4.0
|
||||||
[0.3.2]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.1...v0.3.2
|
[0.3.2]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.1...v0.3.2
|
||||||
[0.3.1]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.0...v0.3.1
|
[0.3.1]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.0...v0.3.1
|
||||||
|
|||||||
@@ -6,23 +6,11 @@
|
|||||||
[](https://github.com/openbot-coder/pytdxdata/blob/main/LICENSE)
|
[](https://github.com/openbot-coder/pytdxdata/blob/main/LICENSE)
|
||||||
[](https://pypi.org/project/pytdxdata/)
|
[](https://pypi.org/project/pytdxdata/)
|
||||||
|
|
||||||
通达信(TongDaXin)行情数据客户端:**动态连接池 + 双层TTL缓存 + 3连接并发分页**(纯 asyncio,零运行时依赖)。
|
通达信(TongDaXin)行情数据客户端:**动态连接池 + 双层 TTL 缓存 + 多连接并发分页**,纯 asyncio、**零运行时依赖**。
|
||||||
|
|
||||||
**A股(沪/深/北) + 港股 + 美股 + 期货 + 期权**,一套接口全市场。
|
**A股(沪/深/北) + 港股 + 美股 + 期货 + 期权**,一套接口全市场。
|
||||||
|
|
||||||
参照 [easy-tdx](https://github.com/handsomejustin/easy_tdx) 重新实现,解决其三大短板(无连接池、串行分页、单连接单锁),协议层独立实现(不依赖 easy-tdx 包,仅参照其字节级格式)。
|
📖 **完整文档:<https://openbot-coder.github.io/pytdxdata/>**
|
||||||
|
|
||||||
## 特性
|
|
||||||
|
|
||||||
| 特性 | 说明 |
|
|
||||||
|------|------|
|
|
||||||
| 🧩 动态连接池 | 启动时对服务器**真实K线探测**选优(剔除握手正常但数据返回空的坏节点),按等待队列/空闲时长动态扩缩容,健康分(失败×0.5/成功+0.2/冷却120s)+EWMA延迟选路,跨服务器故障转移 |
|
|
||||||
| 🗄️ 双层TTL缓存 | 内存LRU + 磁盘SQLite(WAL),TTL分级:报价5s / 分钟K线60s / 日线当天 / 复权K线1天 / **历史逐笔永久**;single-flight 并发同键去重(只回源一次);缓存"已解析记录"(重复请求0网络0解析) |
|
|
||||||
| ⚡ 并发分页 | 单请求拆N页(每页显式start偏移→无状态可并行),多连接并行拉取、按序拼接、失败换连接重试;1分钟K线走 MAC 单连接串行分页(避免多服务器数据空洞) |
|
|
||||||
| 🔀 双通道整合 | 标准通道(经典行情)+ MAC通道(逐笔/复权/1分钟K线),按命令自动选路 |
|
|
||||||
| 📦 零重型依赖 | 纯 asyncio + stdlib(socket/zlib/struct/sqlite3),返回 `list[dataclass]`,pandas 由调用方按需转换 |
|
|
||||||
| 🚀 批量下载 | `get_kline_batch` / `get_minute_batch` — 多股票自动并发,连接池分配不同服务器 |
|
|
||||||
| 📄 服务器文件解析 | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*.zip` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制 |
|
|
||||||
|
|
||||||
## 安装
|
## 安装
|
||||||
|
|
||||||
@@ -30,331 +18,108 @@
|
|||||||
pip install pytdxdata # 或 uv add pytdxdata
|
pip install pytdxdata # 或 uv add pytdxdata
|
||||||
```
|
```
|
||||||
|
|
||||||
从源码开发:
|
可选异步加速:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone <repo-url>
|
pip install "pytdxdata[uvloop]"
|
||||||
cd pytdxdata
|
|
||||||
uv sync # 创建虚拟环境 + 安装CLI
|
|
||||||
uv run python -c "import pytdxdata"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
可选加速(uvloop):
|
## 30 秒上手
|
||||||
|
|
||||||
```bash
|
|
||||||
uv add --optional uvloop uvloop
|
|
||||||
```
|
|
||||||
|
|
||||||
> 注:数据来自通达信公开行情服务器(无需账号),服务器清单由 `server_probe.py` 导入时自动探测可用性与延时,存于 `servers.json`。
|
|
||||||
|
|
||||||
## CLI 命令行工具
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pip install -e . # 或 uv sync,注册 tdx 命令
|
|
||||||
|
|
||||||
tdx quotes sz000001 # 行情报价(五档) / hk00700 / usAAPL
|
|
||||||
tdx kline sz000001 --period day --count 30 --adjust qfq
|
|
||||||
tdx kline cffex:IFL0 --count 30 # 期货K线(hk/us/zz/dl/shf/cffex/gz)
|
|
||||||
tdx transactions sz000001 --count 50 # 逐笔(含成交笔数)
|
|
||||||
tdx minute sz000001 # 分时
|
|
||||||
tdx index 000001 --count 30 # 指数K线
|
|
||||||
tdx board list / members 881001 / ranking / change --days 5
|
|
||||||
tdx info sz000001 # 个股快照
|
|
||||||
tdx list --market sz --count 100 # 证券列表
|
|
||||||
tdx auction sz000001 / unusual / xdxr / finance / flow
|
|
||||||
tdx block block_gn.dat --limit 10 # 板块文件下载+解析(成分股)
|
|
||||||
tdx industry 600000 --search 银行 # 行业分类下载+解析(tdxhy.cfg)
|
|
||||||
tdx financial-list # 历史专业财报文件索引(gpcw.txt)
|
|
||||||
tdx financial gpcw20260331.zip # 历史专业财报记录下载+解析
|
|
||||||
tdx server-info / market-stat
|
|
||||||
```
|
|
||||||
|
|
||||||
## 快速开始
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import asyncio
|
import asyncio
|
||||||
from pytdxdata import TdxData
|
from pytdxdata import TdxData
|
||||||
from pytdxdata.models import KlinePeriod, Market, Adjust
|
from pytdxdata.models import Market, KlinePeriod, Adjust
|
||||||
|
|
||||||
async def main():
|
async def main():
|
||||||
async with TdxData() as td: # 自动建标准池(52台)+MAC池(3台)+缓存
|
async with TdxData() as td: # 自动建连接池 + 缓存
|
||||||
# 日K线(count>800 自动3连接并发分页)
|
# 日K线(count 超过单页大小会自动多连接并发分页)
|
||||||
bars = await td.get_kline(1, "600000", KlinePeriod.DAY, count=2400)
|
bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
|
||||||
# 分钟K线(复权走MAC通道)
|
# 前复权(自动走 MAC 通道)
|
||||||
m1 = await td.get_kline(0, "300308", KlinePeriod.MIN_1, count=240)
|
qfq = await td.get_kline(Market.SZ, "300308", KlinePeriod.DAY,
|
||||||
# 五档报价(TTL 5s 缓存,重复请求0网络)
|
count=500, adjust=Adjust.QFQ)
|
||||||
q = await td.get_quotes([(1, "600000"), (0, "000001")])
|
# 五档报价(传 (market, code) 元组列表,>80 只自动切批)
|
||||||
# 逐笔成交(MAC通道,含 trade_count=成交笔数,支持历史回溯)
|
quotes = await td.get_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
|
||||||
t = await td.get_transactions(0, "000001", date=20260811)
|
# 逐笔成交(MAC 通道,支持历史日期)
|
||||||
total_trades = sum(r.trade_count for r in t) # 当天总成交笔数
|
ticks = await td.get_transactions(Market.SZ, "000001", date=20260811)
|
||||||
# 证券列表/数量
|
print(bars[-1].close, quotes[0].price, len(ticks))
|
||||||
n = await td.get_security_count(0)
|
|
||||||
lst = await td.get_security_list(1, start=0, count=1000)
|
|
||||||
# 分时/除权除息/财务
|
|
||||||
minute = await td.get_minute(1, "600000")
|
|
||||||
xdxr = await td.get_xdxr(1, "600000")
|
|
||||||
fin = await td.get_finance(1, "600000")
|
|
||||||
|
|
||||||
asyncio.run(main())
|
asyncio.run(main())
|
||||||
```
|
```
|
||||||
|
|
||||||
## API 参考
|
返回的是标准库 `dataclass` 组成的 `list`(库本身不依赖 pandas)。要 DataFrame 一行转:
|
||||||
|
|
||||||
统一入口 `TdxData`(`async with TdxData() as td:` 自动 start/close)。
|
```python
|
||||||
|
from dataclasses import asdict
|
||||||
|
import pandas as pd
|
||||||
|
df = pd.DataFrame([asdict(b) for b in bars])
|
||||||
|
```
|
||||||
|
|
||||||
> 完整接口清单(每个方法的参数 / 返回值 / 通道)见 [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md)。
|
## 特性
|
||||||
|
|
||||||
### 连接管理
|
| 特性 | 说明 |
|
||||||
|
|
||||||
| 方法 | 说明 |
|
|
||||||
|------|------|
|
|------|------|
|
||||||
| `start()` / `close()` | 启动(服务器探测+预建连接+缓存)/ 关闭 |
|
| 🧩 动态连接池 | 启动时对服务器**真实 K 线探测**选优(剔除握手正常但数据为空的坏节点),健康分 + EWMA 延迟选路,跨服务器故障转移 |
|
||||||
| `__aenter__` / `__aexit__` | 异步上下文管理器 |
|
| 🗄️ 双层 TTL 缓存 | 内存 LRU + 磁盘 SQLite(WAL),TTL 分级;single-flight 并发同键去重;缓存**已解析记录**(重复请求 0 网络 0 解析) |
|
||||||
|
| ⚡ 并发分页 | 单请求拆 N 页(显式 start 偏移 → 无状态可并行)并行拉取、按序拼接、失败换连接重试 |
|
||||||
|
| 🔀 双通道整合 | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1 分钟 K 线),按命令自动选路 |
|
||||||
|
| 📦 零重型依赖 | 纯 asyncio + stdlib(socket / zlib / struct / sqlite3) |
|
||||||
|
| 📊 全市场覆盖 | A股、港股、美股、期货、期权(46 个扩展市场) |
|
||||||
|
| 📄 服务器文件解析 | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 财报 `gpcw*.zip` **下载即解析**成 dataclass |
|
||||||
|
| 🤖 AI 助手友好 | 内置 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 与 [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) |
|
||||||
|
|
||||||
### 行情接口
|
## 文档导航
|
||||||
|
|
||||||
| 方法 | 返回 | 说明 |
|
| 我想… | 去哪 |
|
||||||
|------|------|------|
|
|------|------|
|
||||||
| `get_kline(market, code, period, *, start, count, adjust)` | `list[SecurityBar]` | K线(count>800自动并发分页;adjust≠NONE走MAC复权;88/000/399指数走指数命令) |
|
| 装好跑起来 | [快速开始](https://openbot-coder.github.io/pytdxdata/getting-started/) |
|
||||||
| `get_index_kline(market, code, period, *, start, count)` | `list[SecurityBar]` | 指数K线(多涨跌家数字段已处理) |
|
| 抄场景代码(转 DataFrame / 批量下载 / 离线板块快照) | [场景示例](https://openbot-coder.github.io/pytdxdata/cookbook/) |
|
||||||
| `get_quotes(stocks)` | `list[SecurityQuote]` | 五档报价(>80只自动切批,缓存键=规范化股票集) |
|
| 查方法签名与参数 | [TdxData 方法](https://openbot-coder.github.io/pytdxdata/api/tdxdata/) — 由 docstring 自动生成 |
|
||||||
| `get_transactions(market, code, *, date, start, count)` | `list[TransactionRecord]` | **逐笔成交(MAC,含 trade_count 成交笔数)**,支持历史回溯 |
|
| 搞清枚举该填几 | [枚举速查](https://openbot-coder.github.io/pytdxdata/api/enums/) |
|
||||||
| `get_minute(market, code, *, date)` | `list[MinuteBar]` | 分时(今日/历史,MAC通道) |
|
| 看协议二进制格式、三池路由、缓存策略 | [深入原理](https://openbot-coder.github.io/pytdxdata/internals/architecture/) |
|
||||||
| `get_kline_batch(stocks, period, *, start, count, adjust, concurrency)` | `dict[str, list[SecurityBar]]` | **批量K线**(多股票自动并发,连接池分配不同服务器) |
|
| 用命令行 | [命令行工具](https://openbot-coder.github.io/pytdxdata/cli/) |
|
||||||
| `get_minute_batch(stocks, *, date, concurrency)` | `dict[str, list[MinuteBar]]` | **批量分时**(多股票自动并发) |
|
| 完整接口清单(51 个数据方法) | [`docs/API_REFERENCE.md`](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/) |
|
||||||
| `get_security_count(market)` | `int` | 市场证券数量 |
|
| 版本变更 | [`CHANGELOG.md`](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md) |
|
||||||
| `get_security_list(market, *, start, count)` | `list[SecurityInfo]` | 证券列表(count=None=全部,先查总数分页) |
|
|
||||||
| `get_security_list_all(market)` | `list[SecurityInfo]` | 全市场列表(缓存1天) |
|
|
||||||
| `get_xdxr(market, code)` | `list[XdxrRecord]` | 除权除息历史(标准) |
|
|
||||||
| `get_finance(market, code)` | `FinanceRecord \| None` | 财务快照(标准) |
|
|
||||||
|
|
||||||
### 板块/竞价/异动(MAC)
|
> 本 README 只做**入口层**。深度内容一律在文档站,避免两处维护造成漂移。
|
||||||
|
|
||||||
| 方法 | 返回 | 说明 |
|
## 给 AI 助手用
|
||||||
|------|------|------|
|
|
||||||
| `get_board_list(board_type, count)` | `list[BoardInfo]` | 板块列表(0=全部 1=行业 2=概念) |
|
|
||||||
| `get_board_members(board_symbol, count, sort_type)` | `list[MemberQuote]` | 板块成分股报价(自定义字段) |
|
|
||||||
| `get_board_summary(board_symbol)` | `dict` | 板块汇总(成分数/成交额/主力净流入/涨跌家数) |
|
|
||||||
| `get_board_ranking(board_type, top_n)` | `list[dict]` | 板块涨跌幅排行 |
|
|
||||||
| `get_board_change_ranking(board_type, days, top_n)` | `list[dict]` | 板块N日涨跌幅排行(板块指数K线) |
|
|
||||||
| `get_belong_board(market, code)` | `list[BelongBoard]` | 个股所属板块 |
|
|
||||||
| `get_auction(market, code)` | `list[AuctionItem]` | 集合竞价 |
|
|
||||||
| `get_unusual(market, start, count)` | `list[UnusualItem]` | 市场异动 |
|
|
||||||
| `get_capital_flow(market, code)` | `CapitalFlow` | 资金流向 |
|
|
||||||
|
|
||||||
### 快照/服务器/扩展(MAC)
|
仓库根的 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 是一份可直接加载的技能:三条必守约定、`KlinePeriod` 等枚举取值表、
|
||||||
|
「想做什么 → 用哪个方法」决策表、以及 9 条真实陷阱。AI 编程助手读完就能一次写对,不必翻源码。
|
||||||
|
|
||||||
| 方法 | 返回 | 说明 |
|
```bash
|
||||||
|------|------|------|
|
# 丢进你所用 AI 助手的 skills 目录即可
|
||||||
| `get_symbol_info(market, code)` | `SymbolSnapshot` | 个股特征快照 |
|
curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \
|
||||||
| `get_stock_quotes(stocks, bits)` | `list[MemberQuote]` | MAC自定义字段报价 |
|
https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md
|
||||||
| `get_stock_quotes_list(category, count)` | `list[MemberQuote]` | 市场分类报价列表(0沪A/6全A/8科创/14创业) |
|
|
||||||
| `get_stock_kline_with_indicators(market, code, indicators, ...)` | `dict` | K线+指标(MACD/KDJ/RSI/BOLL/MA/EMA) |
|
|
||||||
| `get_goods_list(market, start, count)` | `list[GoodsItem]` | 扩展市场商品(期货/期权) |
|
|
||||||
| `get_server_info()` | `ServerInfo` | 服务器交易时段 |
|
|
||||||
| `get_kline_offset(offset, count)` | `tuple[int,int]` | K线偏移 |
|
|
||||||
| `get_chart_sampling(market, code)` | `list[float]` | 分时采样(扩展市场命令,A股不适用) |
|
|
||||||
|
|
||||||
### 文件/信息(标准+MAC)
|
|
||||||
|
|
||||||
| 方法 | 返回 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `get_company_info_category/content(...)` | `list` / `str` | F10公司信息(标准) |
|
|
||||||
| `get_block_info(filename)` | `bytes` | 板块文件下载(标准) |
|
|
||||||
| `get_report_file(filename)` | `bytes` | 报告/财务文件下载(标准) |
|
|
||||||
| `get_financial_file_list()` | `list[str]` | 财务文件列表(tdxfin/gpcw.txt,原始行) |
|
|
||||||
| `get_financial_records(filename)` | `bytes` | 财务文件内容(gpcw*.zip,原始字节) |
|
|
||||||
| **`get_block_parsed(filename)`** | `list[TdxBlock]` | 板块文件**下载+解析**:板块名/类别/成分股代码 |
|
|
||||||
| **`get_industry_map()`** | `dict[str, IndustryInfo]` | tdxhy.cfg **下载+解析**:通达信行业+申万行业 |
|
|
||||||
| **`get_financial_file_infos()`** | `list[FinancialFileInfo]` | gpcw.txt **下载+解析**:文件名/MD5/大小 |
|
|
||||||
| **`get_financial_records_parsed(filename)`** | `list[FinancialRecord]` | gpcw*.zip **解压+解析**:每股原始字段 |
|
|
||||||
| `get_file_meta(filename)` / `download_file(filename)` | `FileMeta` / `bytes` | 远程文件(MAC) |
|
|
||||||
| `get_price_limits(market, code, name, pre_close, listed_days)` | `tuple` | 涨跌停价(本地计算) |
|
|
||||||
| `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数/总额/市值/涨跌停数) |
|
|
||||||
|
|
||||||
### 数据模型(dataclass)
|
|
||||||
|
|
||||||
| 模型 | 关键字段 |
|
|
||||||
|------|---------|
|
|
||||||
| `SecurityBar` | market/code/open/high/low/close/vol/amount/year/month/day/hour/minute + `datetime`属性 |
|
|
||||||
| `SecurityQuote` | price/pre_close/OHLC/vol/amount/s_vol/b_vol/`bid[5]`/`ask[5]`/server_time/trading_status |
|
|
||||||
| `TransactionRecord` | time/price/vol/`trade_count`/bs_flag |
|
|
||||||
| `SecurityInfo` | code/name(GBK)/volunit/decimal_point/pre_close |
|
|
||||||
| `XdxrRecord` | category/分红送转/缩股/行权等(除权除息) |
|
|
||||||
| `MinuteBar` | price/vol |
|
|
||||||
| `FinanceRecord` | 股本/资产/营收/利润(万元/万股,最新快照) |
|
|
||||||
| `TdxBlock` | name/category/count/`codes`(板块成分,block_*.dat) |
|
|
||||||
| `IndustryInfo` | code/tdx_industry/sw_industry(tdxhy.cfg) |
|
|
||||||
| `FinancialFileInfo` | filename/hash/filesize(gpcw.txt) |
|
|
||||||
| `FinancialRecord` | code/market/report_date/`fields`(历史专业财报) |
|
|
||||||
|
|
||||||
### 枚举
|
|
||||||
|
|
||||||
- `Market`:SZ=0 / SH=1 / **BJ=2**(北交所)
|
|
||||||
- `KlinePeriod`:MIN_5=0 / MIN_15=1 / MIN_30=2 / MIN_60=3 / **DAY=4** / WEEK=5 / MONTH=6 / MIN_1=7 / MIN_3=8 / YEAR=9 / SEASON=10(**与通达信协议字节一致**)
|
|
||||||
- `Adjust`:NONE / QFQ(前复权)/ HFQ(后复权)
|
|
||||||
|
|
||||||
## 通道路由
|
|
||||||
|
|
||||||
| 命令 | 默认通道 | 说明 |
|
|
||||||
|------|---------|------|
|
|
||||||
| K线(复权) | **MAC** | 支持QFQ/HFQ |
|
|
||||||
| K线(MIN_1不复权) | **MAC** | 0x122E,串行分页,避免多服务器数据空洞 |
|
|
||||||
| K线(其他周期不复权)/指数 | 标准 | 价格小数位规则已验证 |
|
|
||||||
| 报价 | 标准 | 股票2位/指数ETF转债3位 |
|
|
||||||
| **逐笔成交** | **MAC** | 含trade_count,支持历史日期 |
|
|
||||||
| **分时** | **MAC** | 0x122D,完整历史分时 |
|
|
||||||
| 列表/数量/除权/财务 | 标准 | 仅标准通道提供 |
|
|
||||||
|
|
||||||
## 架构
|
|
||||||
|
|
||||||
```
|
|
||||||
src/pytdxdata/
|
|
||||||
├── api.py # 统一接口 TdxData(对外唯一入口)
|
|
||||||
├── router.py # 标准/MAC 通道选路
|
|
||||||
├── config.py # 服务器清单加载(servers.json + 环境变量覆盖)
|
|
||||||
├── protocol/ # 独立协议层(帧/变长整数/差分还原/自定义浮点/命令)
|
|
||||||
│ └── commands/ # kline/quotes/list/transaction/minute/xdxr/finance/mac
|
|
||||||
├── pool/ # 动态连接池(connection/health/pool)
|
|
||||||
├── cache/ # 双层TTL缓存(key/ttl/memory/disk/manager)
|
|
||||||
├── scheduler/ # 并发分页调度器(Paginator,3连接并行)
|
|
||||||
├── models/ # dataclass 模型 + 枚举
|
|
||||||
└── codec/ # 缓存载荷序列化(pickle+zlib)+ 服务器文件解析(板块/行业/财报)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 扩展市场(EX通道:港股/美股/期货/期权)
|
## 示例
|
||||||
|
|
||||||
`get_kline` 的 market 参数接受 `ExMarket` 枚举(港股/美股/期货/期权等52个市场):
|
- [`examples/quickstart.py`](https://github.com/openbot-coder/pytdxdata/blob/main/examples/quickstart.py) — 报价 / K线 / 分时 / 板块
|
||||||
|
- [`examples/server_files.py`](https://github.com/openbot-coder/pytdxdata/blob/main/examples/server_files.py) — 板块 / 行业 / 财报 下载 + 解析
|
||||||
|
|
||||||
```python
|
## 开发
|
||||||
from pytdxdata.models import ExMarket, KlinePeriod
|
|
||||||
|
|
||||||
# 港股(HK_MAIN_BOARD=31,代码5位)
|
```bash
|
||||||
bars = await td.get_kline(ExMarket.HK_MAIN_BOARD, '00700', KlinePeriod.DAY, count=700)
|
uv sync # 建虚拟环境 + 注册 tdx 命令
|
||||||
# 美股(US_STOCK=74)
|
uv run pytest tests/ # 109 个测试用例(协议 / 池 / 缓存 / 分页 / API / 文件解析 / CLI / 文档漂移)
|
||||||
bars = await td.get_kline(ExMarket.US_STOCK, 'AAPL', KlinePeriod.DAY, count=700)
|
uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings)
|
||||||
# 期货(CFFEX=47 / 郑28 / 大29 / 上30,合约如 IFL0/rb2610)
|
uv run mkdocs serve # 本地预览文档站
|
||||||
bars = await td.get_kline(ExMarket.CFFEX_FUTURES, 'IFL0', KlinePeriod.DAY, count=700)
|
|
||||||
# 股票期权(沪8/深9,合约代码8位)
|
|
||||||
bars = await td.get_kline(ExMarket.SH_STOCK_OPTION, '10010971', KlinePeriod.DAY, count=700)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
- 端口 7727,统一走 **pytdx EX 协议**(0x23FF K线 / 0x23FA 报价 / 0x23F4 市场列表)
|
|
||||||
- 4台EX服务器:MAC EX 2台(116.205.135.205 / 121.37.232.167,0x2454 login)+ pytdx EX 2台(通达信扩展市场 116.205.143.214 / 国泰君安 103.221.142.82,0x2454 setup)
|
|
||||||
- EX 辅助接口:get_goods_list / get_goods_count / get_goods_quotes / get_goods_tick_chart / get_goods_transaction 等
|
|
||||||
- 实测:腾讯00700=466.6 / AAPL=332.8 / IFL0=4683.2 / 沪期权10010971=0.192
|
|
||||||
- 美股/港股期权:通达信协议无数据(美股期权可用 CBOE 公开接口,见 quantdata/scripts/import/cboe_options.py)
|
|
||||||
|
|
||||||
## 服务器文件:板块 / 行业 / 财报
|
|
||||||
|
|
||||||
通达信服务器上除了行情,还有一批**静态文件**(板块成分、行业分类、历史专业财报)。
|
|
||||||
pytdxdata 提供「**下载 + 解析**」一步到位:既保留原始 `bytes` 通道,也提供解析成 dataclass 的方法。
|
|
||||||
|
|
||||||
```python
|
|
||||||
async with TdxData() as td:
|
|
||||||
# ① 板块文件(block_zs.dat 行业 / block_gn.dat 概念 / block_fg.dat 风格)
|
|
||||||
blocks = await td.get_block_parsed("block_gn.dat")
|
|
||||||
for b in blocks:
|
|
||||||
print(b.name, b.category, b.count, b.codes[:5])
|
|
||||||
|
|
||||||
# ② 行业分类(tdxhy.cfg → 通达信行业 + 申万行业)
|
|
||||||
hy = await td.get_industry_map() # {6位代码: IndustryInfo}
|
|
||||||
print(hy["600000"].tdx_industry, hy["600000"].sw_industry)
|
|
||||||
|
|
||||||
# ③ 历史专业财报(gpcw.txt 索引 + gpcw*.zip 解压解析)
|
|
||||||
infos = await td.get_financial_file_infos() # 文件名 / MD5 / 大小
|
|
||||||
records = await td.get_financial_records_parsed(infos[-1].filename)
|
|
||||||
print(records[0].code, records[0].report_date, records[0].fields[:4])
|
|
||||||
```
|
|
||||||
|
|
||||||
| 方法 | 返回 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `get_block_parsed(filename)` | `list[TdxBlock]` | 板块成分:板块名 / 类别 / 成分股代码 |
|
|
||||||
| `get_industry_map()` | `dict[str, IndustryInfo]` | 通达信行业 + 申万行业(GBK 解析) |
|
|
||||||
| `get_financial_file_infos()` | `list[FinancialFileInfo]` | gpcw 文件索引(文件名 / MD5 / 大小) |
|
|
||||||
| `get_financial_records_parsed(filename)` | `list[FinancialRecord]` | 解压 zip + 解析每股原始字段 |
|
|
||||||
|
|
||||||
不解析的原始字节通道仍保留(向后兼容):`get_block_info()` / `get_report_file()` /
|
|
||||||
`get_financial_file_list()` / `get_financial_records()`。
|
|
||||||
|
|
||||||
> 解析器集中在 `codec/`(`block.py` / `industry.py` / `financial.py`),纯标准库(struct / zipfile),
|
|
||||||
> 可脱网单测;也可直接 `from pytdxdata.codec import parse_block_dat` 单独复用。
|
|
||||||
|
|
||||||
## 与 easy-tdx 对比
|
|
||||||
|
|
||||||
| 维度 | easy-tdx | pytdxdata |
|
|
||||||
|------|----------|----------|
|
|
||||||
| 并发分页 | ❌ 串行 while 循环 | ✅ 3连接并行 |
|
|
||||||
| 连接池 | ❌ 单连接单锁 | ✅ 动态池+故障转移 |
|
|
||||||
| 缓存 | 仅证券列表(1天) | ✅ 双层TTL+single-flight |
|
|
||||||
| 数据正确性 | 基准 | ✅ K线6字段/报价7字段逐字段一致(实测) |
|
|
||||||
| 2400根日K耗时 | 0.31s | **0.16s(1.97x)** |
|
|
||||||
| 缓存命中重取 | — | 0.016s(0网络) |
|
|
||||||
| 接口覆盖 | 基准 | **36/36 全覆盖** |
|
|
||||||
| 依赖 | pandas等 | 零运行时依赖 |
|
|
||||||
|
|
||||||
> 实测环境:Windows 11 / Python 3.13 / 同一批通达信服务器(2026-08 实测)。
|
|
||||||
|
|
||||||
## 已知限制
|
## 已知限制
|
||||||
|
|
||||||
- 标准通道K线 `count<100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避
|
- 行情来自通达信公开服务器,**15 分钟延时**;需实时数据请使用券商行情
|
||||||
- 标准当日逐笔的笔数字段协议中有但 easy-tdx 模型丢弃(pytdxdata 已显式解析);历史逐笔无笔数字段
|
- 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避
|
||||||
- 报价价格小数位按品种推断(股票2位/指数ETF转债3位),同代码不同市场含义不同(SH 000001=指数 vs SZ 000001=股票)
|
- 港股 / 美股期权在通达信协议内无数据
|
||||||
- 行情数据来自通达信公开服务器,**15分钟延时**;需实时数据请使用券商行情
|
|
||||||
- 港股/美股/期货/期权数据走通达信 EX 通道(7727),部分市场(美股/港股期权)协议内无数据
|
|
||||||
- 服务器可用性随时间变化,可用 `python -m pytdxdata.server_probe` 重新探测
|
- 服务器可用性随时间变化,可用 `python -m pytdxdata.server_probe` 重新探测
|
||||||
|
|
||||||
## 免责声明
|
## 免责声明
|
||||||
|
|
||||||
本包仅用于**技术研究与教育目的**。行情数据来自通达信公开接口,不保证实时性与准确性;作者不对任何投资决策负责。使用前请遵守通达信服务条款及相关法律法规。
|
本包仅用于**技术研究与教育目的**。行情数据来自通达信公开接口,不保证实时性与准确性;
|
||||||
|
作者不对任何投资决策负责。使用前请遵守通达信服务条款及相关法律法规。
|
||||||
|
|
||||||
## 测试
|
## License
|
||||||
|
|
||||||
```bash
|
[MIT](https://github.com/openbot-coder/pytdxdata/blob/main/LICENSE)
|
||||||
uv run pytest tests/ # 85个测试:协议/池/缓存/分页/API/文件解析/CLI
|
|
||||||
```
|
|
||||||
|
|
||||||
## 目录
|
|
||||||
|
|
||||||
- `docs/API_REFERENCE.md` — 完整对外接口清单(Python API / 数据模型 / 枚举 / CLI)
|
|
||||||
- `examples/quickstart.py` — 快速上手(报价 / K线 / 分时 / 板块)
|
|
||||||
- `examples/server_files.py` — 服务器文件下载 + 解析(板块 / 行业 / 财报)
|
|
||||||
|
|
||||||
## Changelog
|
|
||||||
|
|
||||||
### v0.4.0 (2026-09-15)
|
|
||||||
|
|
||||||
- **新增「服务器文件下载 + 解析」能力**(对齐并超越 easy-tdx 的文件解析):
|
|
||||||
- `get_block_parsed(filename)` — 板块 `block_zs/gn/fg.dat` → `TdxBlock` 列表(板块名 / 类别 / 成分股代码)
|
|
||||||
- `get_industry_map()` — `tdxhy.cfg` → `{代码: IndustryInfo}`(通达信行业 + 申万行业)
|
|
||||||
- `get_financial_file_infos()` — `tdxfin/gpcw.txt` → `FinancialFileInfo` 列表(文件名 / MD5 / 大小)
|
|
||||||
- `get_financial_records_parsed(filename)` — `gpcw*.zip` 解压 + 解析 → `FinancialRecord` 列表(每股原始字段)
|
|
||||||
- **新增解析器** `codec/block.py`、`codec/industry.py`、`codec/financial.py`(纯标准库,脱网可单测)
|
|
||||||
- **新增模型** `TdxBlock` / `IndustryInfo` / `FinancialFileInfo` / `FinancialRecord`
|
|
||||||
- 修复财报索引市场字段解析(`<6s1c1L` → `<6sBL`,市场 0=深 / 1=沪 正确,此前恒判深市)
|
|
||||||
- 公开异步方法 47 → **51**,新增接口全部向后兼容(原 `bytes` 方法保留)
|
|
||||||
- **CLI 新增 4 个命令**:`tdx block` / `tdx industry` / `tdx financial-list` / `tdx financial`
|
|
||||||
- 新增 `tests/test_cli_files.py`(11 项 CLI 离线测试,FakeTD 桩)
|
|
||||||
- README 与 `docs/API_REFERENCE.md` 同步更新
|
|
||||||
|
|
||||||
### v0.3.2 (2026-08-17)
|
|
||||||
|
|
||||||
- **新增** `get_kline_batch(stocks, period, ...)` — 批量K线接口,多股票自动并发下载,连接池分配不同服务器
|
|
||||||
- **新增** `get_minute_batch(stocks, ...)` — 批量分时接口,多股票自动并发下载
|
|
||||||
|
|
||||||
### v0.3.1 (2026-08-17)
|
|
||||||
|
|
||||||
- **`get_kline(MIN_1)` 切换为 MAC 通道** (0x122E),解决标准通道 1 分钟K线深度不足问题
|
|
||||||
- **修复 MAC K线并发分页数据空洞** — 并发分页器将不同页面分配到不同服务器,当服务器数据深度不一致时 `stop_when_short` 会导致非确定性数据丢失;改用**单连接串行分页**(`_fetch_mac_kline_serial`,start 动态偏移,与 easy-tdx 一致)
|
|
||||||
- 路由更新:`router.py` 中 `KlinePeriod.MIN_1` 强制路由到 MAC 通道
|
|
||||||
- 标准通道其他周期(MIN_5/15/30/60/DAY/WEEK/MONTH)不受影响
|
|
||||||
|
|
||||||
### v0.3.0 (2026-08-17)
|
|
||||||
|
|
||||||
- **`get_minute` 切换为 MAC 通道** (0x122D `MacTickChartCmd`),历史分时数据稳定返回完整 240 条(09:30~14:59)
|
|
||||||
- 新增 `protocol/commands/mac_tick.py` — MAC 单日分时图命令
|
|
||||||
- 移除不再使用的 `GetHistoryMinuteTimeDataCmd` 导入
|
|
||||||
|
|
||||||
### v0.2.2 及之前
|
|
||||||
|
|
||||||
- 初始版本:动态连接池 + 双层TTL缓存 + 3连接并发分页 + 双通道(标准/MAC)+ 扩展市场(港股/美股/期货/期权)
|
|
||||||
@@ -0,0 +1,191 @@
|
|||||||
|
---
|
||||||
|
name: pytdxdata
|
||||||
|
description: 用 pytdxdata 拉取通达信行情数据——A股(沪/深/北)、港股、美股、期货、期权的 K线 / 报价 / 逐笔 / 分时 / 板块 / 除权 / 财报文件。触发词:通达信数据、tdx 行情、A股日线下载、分钟K线、批量拉K线、板块成分股、行业分类、港股美股行情、pytdx、easy-tdx、pytdxdata。
|
||||||
|
---
|
||||||
|
|
||||||
|
# pytdxdata 使用技能
|
||||||
|
|
||||||
|
`pytdxdata` 是通达信公开行情服务器的纯 asyncio 客户端:动态连接池 + 双层 TTL 缓存 + 多连接并发分页,**零运行时依赖**。
|
||||||
|
本技能让你一次写对——重点是那三条一眼看不出来的约定,以及一张必须背下来的枚举表。
|
||||||
|
|
||||||
|
> 需要精确签名时查 <https://openbot-coder.github.io/pytdxdata/api/tdxdata/>(由 docstring 实时生成,不可能过期)。
|
||||||
|
|
||||||
|
## 三条必守约定
|
||||||
|
|
||||||
|
**1. 唯一入口是 `TdxData`,且必须 `async with`**
|
||||||
|
|
||||||
|
```python
|
||||||
|
from pytdxdata import TdxData
|
||||||
|
|
||||||
|
async with TdxData() as td: # 自动 start(探测服务器 + 预建连接 + 建缓存)
|
||||||
|
bars = await td.get_kline(...)
|
||||||
|
# 退出即 close
|
||||||
|
```
|
||||||
|
|
||||||
|
不要直接 `await TdxData().get_kline(...)`——没 `start()` 就没有连接池。
|
||||||
|
|
||||||
|
**2. `market` 传的是整数枚举值,不是字符串**
|
||||||
|
|
||||||
|
这是最高频的错误来源。**不要传 `"sh"` / `"SH"` / `"1"`**,要用枚举(它就是 `IntEnum`,所以传 `1` 也能跑,但可读性差):
|
||||||
|
|
||||||
|
```python
|
||||||
|
from pytdxdata.models import Market, KlinePeriod, Adjust
|
||||||
|
|
||||||
|
await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. 返回 `list[dataclass]`,不是 DataFrame**
|
||||||
|
|
||||||
|
库刻意不依赖 pandas。要 DataFrame 自己转一行:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from dataclasses import asdict
|
||||||
|
import pandas as pd
|
||||||
|
df = pd.DataFrame([asdict(b) for b in bars])
|
||||||
|
```
|
||||||
|
|
||||||
|
## 安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install pytdxdata # 或 uv add pytdxdata
|
||||||
|
```
|
||||||
|
|
||||||
|
## 可运行模板
|
||||||
|
|
||||||
|
```python
|
||||||
|
import asyncio
|
||||||
|
from pytdxdata import TdxData
|
||||||
|
from pytdxdata.models import Market, KlinePeriod, Adjust
|
||||||
|
|
||||||
|
async def main():
|
||||||
|
async with TdxData() as td:
|
||||||
|
# 日K线,240 根(count 超过单页大小会自动多连接并发分页)
|
||||||
|
bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
|
||||||
|
print(bars[-1].close, bars[-1].datetime)
|
||||||
|
|
||||||
|
# 前复权日线(复权自动走 MAC 通道)
|
||||||
|
qfq = await td.get_kline(Market.SZ, "300308", KlinePeriod.DAY,
|
||||||
|
count=500, adjust=Adjust.QFQ)
|
||||||
|
|
||||||
|
# 五档报价:入参是 (market, code) 元组列表,一次可传多只(>80 只自动切批)
|
||||||
|
quotes = await td.get_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
|
||||||
|
print(quotes[0].price, quotes[0].bid[0], quotes[0].ask[0])
|
||||||
|
|
||||||
|
# 逐笔成交(MAC 通道,支持历史日期,含 trade_count 成交笔数)
|
||||||
|
ticks = await td.get_transactions(Market.SZ, "000001", date=20260811)
|
||||||
|
print(sum(r.trade_count for r in ticks)) # 当日总成交笔数
|
||||||
|
|
||||||
|
# 分时(MAC 通道,今日或历史)
|
||||||
|
minute = await td.get_minute(Market.SH, "600000")
|
||||||
|
|
||||||
|
# 批量 K 线:多股票自动并发,池子会分配到不同服务器
|
||||||
|
batch = await td.get_kline_batch(
|
||||||
|
[(Market.SH, "600000"), (Market.SZ, "000001")],
|
||||||
|
KlinePeriod.DAY, count=240,
|
||||||
|
) # -> {"600000": [...], "000001": [...]}
|
||||||
|
|
||||||
|
asyncio.run(main())
|
||||||
|
```
|
||||||
|
|
||||||
|
## 枚举取值表(别猜,对照着填)
|
||||||
|
|
||||||
|
**`Market`** — A 股市场
|
||||||
|
|
||||||
|
| 值 | 名称 | 含义 |
|
||||||
|
|---|---|---|
|
||||||
|
| 0 | `SZ` | 深市 |
|
||||||
|
| 1 | `SH` | 沪市 |
|
||||||
|
| 2 | `BJ` | 北交所 |
|
||||||
|
|
||||||
|
**`KlinePeriod`** — 周期编码,**与通达信协议字节一致,不是顺序编号**
|
||||||
|
|
||||||
|
| 值 | 名称 | | 值 | 名称 |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| 0 | `MIN_5` | | 7 | `MIN_1` |
|
||||||
|
| 1 | `MIN_15` | | 8 | `MIN_3` |
|
||||||
|
| 2 | `MIN_30` | | 9 | `YEAR` |
|
||||||
|
| 3 | `MIN_60` | | 10 | `SEASON` |
|
||||||
|
| 4 | `DAY` | | 11 | `YEAR_ALT` |
|
||||||
|
| 5 | `WEEK` | | | |
|
||||||
|
| 6 | `MONTH` | | | |
|
||||||
|
|
||||||
|
⚠️ **`DAY=4` 不是 0**,`MIN_1=7` 也不是 0。凭直觉填 `0` 会拿到 5 分钟线。
|
||||||
|
|
||||||
|
**`Adjust`** — 复权方式
|
||||||
|
|
||||||
|
| 值 | 名称 | 含义 |
|
||||||
|
|---|---|---|
|
||||||
|
| 0 | `NONE` | 不复权 |
|
||||||
|
| 1 | `QFQ` | 前复权 |
|
||||||
|
| 2 | `HFQ` | 后复权 |
|
||||||
|
|
||||||
|
**`ExMarket`** — 扩展市场(港股 / 美股 / 期货 / 期权,共 46 个成员,走独立 EX 通道)
|
||||||
|
|
||||||
|
常用几个:`HK_MAIN_BOARD=31`、`US_STOCK=74`、`CFFEX_FUTURES=47`、`SH_STOCK_OPTION=8`、`SZ_STOCK_OPTION=9`。
|
||||||
|
完整表见 <https://openbot-coder.github.io/pytdxdata/api/enums/>。
|
||||||
|
|
||||||
|
```python
|
||||||
|
from pytdxdata.models import ExMarket
|
||||||
|
|
||||||
|
await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700) # 港股,5 位代码
|
||||||
|
await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700) # 美股,ticker
|
||||||
|
await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700) # 期货合约
|
||||||
|
```
|
||||||
|
|
||||||
|
## 想做什么 → 用哪个方法
|
||||||
|
|
||||||
|
| 需求 | 方法 |
|
||||||
|
|---|---|
|
||||||
|
| 日/周/月/分钟 K 线 | `get_kline(market, code, period, *, count, adjust)` |
|
||||||
|
| 增量更新(从某天往后) | `get_kline_since(market, code, period, since, adjust)` |
|
||||||
|
| 一次拉多只股票 K 线 | `get_kline_batch(stocks, period, *, count, adjust, concurrency)` |
|
||||||
|
| 指数 K 线 | `get_index_kline(market, code, period, *, count)` |
|
||||||
|
| K 线 + MACD/KDJ/RSI/BOLL | `get_stock_kline_with_indicators(market, code, indicators, ...)` |
|
||||||
|
| 实时五档报价 | `get_quotes(stocks)` |
|
||||||
|
| 逐笔成交 | `get_transactions(market, code, *, date)` |
|
||||||
|
| 分时图 | `get_minute(market, code, *, date)` |
|
||||||
|
| 全市场股票列表 | `get_security_list_all(market)`(缓存 1 天) |
|
||||||
|
| 除权除息 / 财务快照 | `get_xdxr(...)` / `get_finance(...)` |
|
||||||
|
| 板块列表 / 成分股 / 涨跌排行 | `get_board_list` / `get_board_members` / `get_board_ranking` |
|
||||||
|
| 个股所属板块 | `get_belong_board(market, code)` |
|
||||||
|
| 集合竞价 / 异动 / 资金流 | `get_auction` / `get_unusual` / `get_capital_flow` |
|
||||||
|
| **板块成分文件**(离线快照) | `get_block_parsed("block_gn.dat")` |
|
||||||
|
| **行业分类**(通达信 + 申万) | `get_industry_map()` |
|
||||||
|
| **历史专业财报**(gpcw 全字段) | `get_financial_file_infos()` + `get_financial_records_parsed(fn)` |
|
||||||
|
| 涨跌停价 | `get_price_limits(market, code, name, pre_close, listed_days)`(本地算,无网络) |
|
||||||
|
| 全市场涨跌家数/成交额 | `get_market_stat()` |
|
||||||
|
|
||||||
|
## 通道与数据特性(影响你能拿到什么)
|
||||||
|
|
||||||
|
库内部有**标准通道**和 **MAC 通道**两条链路,会**按命令自动选路**,你不用管。但有几件事必须知道:
|
||||||
|
|
||||||
|
- **数据有 15 分钟延时**(通达信公开服务器特性)。要实时数据请用券商行情。
|
||||||
|
- **复权 K 线与 1 分钟 K 线走 MAC 通道**。`get_kline(..., adjust=Adjust.QFQ)` 自动切换。
|
||||||
|
- **`count` 很大时会自动多连接并发分页**,无需手动翻页。但标准通道 K 线 `count < 100` 部分服务器会返回空——内部已强制 `min_page=100` 规避。
|
||||||
|
- **`get_quotes` 一次 >80 只自动切批**;而 MAC 的 `get_stock_quotes` 上限就是 80 只/次。
|
||||||
|
- **历史逐笔没有笔数字段**,只有当日逐笔的 `trade_count` 有效。
|
||||||
|
- 板块文件(`block_*.dat`)/ 行业(`tdxhy.cfg`)/ 财报(`gpcw*.zip`)是**服务器上的静态文件**,解析后是普通 dataclass,**落 JSON 后完全脱网可用**——适合做离线快照。
|
||||||
|
|
||||||
|
## 陷阱清单
|
||||||
|
|
||||||
|
| 坑 | 后果 | 正确做法 |
|
||||||
|
|---|---|---|
|
||||||
|
| `market` 传 `"sh"` 字符串 | 直接报错或路由到错误市场 | 用 `Market.SH` 枚举 |
|
||||||
|
| 以为 `KlinePeriod.DAY == 0` | 拿到的是 5 分钟线 | `DAY=4`,对照上面的表 |
|
||||||
|
| 忘了 `async with` / `start()` | 无连接池,运行时报错 | 一律 `async with TdxData() as td:` |
|
||||||
|
| 等在返回值上找 `.to_dataframe()` | 不存在 | `pd.DataFrame([asdict(x) for x in bars])` |
|
||||||
|
| 把 `close` 当成分 | 数值差 100 倍 | 价格单位是**元**(float) |
|
||||||
|
| `SH 000001` 当成平安银行 | 拿到的是上证指数 | **代码不唯一**:`(Market.SH, "000001")`=上证指数,`(Market.SZ, "000001")`=平安银行 |
|
||||||
|
| 用 `get_block_info` 又自己拆二进制 | 白写解析器 | 用 `get_block_parsed`,已经解析好了 |
|
||||||
|
| 循环里逐个 `await get_kline` | 慢 | 用 `get_kline_batch` 让它并发 |
|
||||||
|
| 依赖实时性做信号 | 数据是 15 分钟前的 | 换券商实时源 |
|
||||||
|
|
||||||
|
## 深入参考
|
||||||
|
|
||||||
|
- 文档站:<https://openbot-coder.github.io/pytdxdata/>
|
||||||
|
- 完整方法签名(自动生成):<https://openbot-coder.github.io/pytdxdata/api/tdxdata/>
|
||||||
|
- 场景示例 / 离线解析配方:<https://openbot-coder.github.io/pytdxdata/cookbook/>
|
||||||
|
- 给 LLM 的速查摘要:<https://openbot-coder.github.io/pytdxdata/llms.txt>
|
||||||
|
- 命令行等价物:`tdx quotes sz000001`、`tdx kline sz000001 --period day --count 30`、`tdx block block_gn.dat`(`tdx --help` 看全部)
|
||||||
|
|
||||||
|
> 数据来自通达信公开接口,仅供技术研究与教育用途,不构成投资建议。
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# pytdxdata 对外接口清单
|
# pytdxdata 对外接口清单
|
||||||
|
|
||||||
> 以 `src/pytdxdata` 源码为准整理(v0.4.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
|
> 以 `src/pytdxdata` 源码为准整理(v0.5.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
|
||||||
>
|
>
|
||||||
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
|
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
|
||||||
|
|
||||||
@@ -144,7 +144,7 @@ from pytdxdata import (
|
|||||||
| `Market` | SZ=0 / SH=1 / BJ=2 |
|
| `Market` | SZ=0 / SH=1 / BJ=2 |
|
||||||
| `KlinePeriod` | MIN_5=0 / MIN_15=1 / MIN_30=2 / MIN_60=3 / DAY=4 / WEEK=5 / MONTH=6 / MIN_1=7 / MIN_3=8 / YEAR=9 / SEASON=10 / YEAR_ALT=11(`is_minute` 属性) |
|
| `KlinePeriod` | MIN_5=0 / MIN_15=1 / MIN_30=2 / MIN_60=3 / DAY=4 / WEEK=5 / MONTH=6 / MIN_1=7 / MIN_3=8 / YEAR=9 / SEASON=10 / YEAR_ALT=11(`is_minute` 属性) |
|
||||||
| `Adjust` | NONE=0 / QFQ=1 / HFQ=2 |
|
| `Adjust` | NONE=0 / QFQ=1 / HFQ=2 |
|
||||||
| `ExMarket` | 52 个扩展市场:HK_MAIN_BOARD=31 / US_STOCK=74 / CFFEX_FUTURES=47 / ZZ_FUTURES=28 / DL_FUTURES=29 / SH_FUTURES=30 / GZ_FUTURES=66 / SH_STOCK_OPTION=8 / SZ_STOCK_OPTION=9 等 |
|
| `ExMarket` | 46 个扩展市场:HK_MAIN_BOARD=31 / US_STOCK=74 / CFFEX_FUTURES=47 / ZZ_FUTURES=28 / DL_FUTURES=29 / SH_FUTURES=30 / GZ_FUTURES=66 / SH_STOCK_OPTION=8 / SZ_STOCK_OPTION=9 等 |
|
||||||
|
|
||||||
**dataclass(均为 `@dataclass(slots=True)`)**
|
**dataclass(均为 `@dataclass(slots=True)`)**
|
||||||
|
|
||||||
|
|||||||
+67
@@ -0,0 +1,67 @@
|
|||||||
|
# AI 助手接入
|
||||||
|
|
||||||
|
pytdxdata 的枚举取值**完全没有直觉**(`KlinePeriod.DAY` 是 `4` 不是 `0`),
|
||||||
|
所以 AI 助手凭常识写代码**几乎必错**。为此项目提供两条 AI 通道,分工不同:
|
||||||
|
|
||||||
|
| 文件 | 面向 | 内容 |
|
||||||
|
|---|---|---|
|
||||||
|
| [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) | AI 爬虫 / 问答型模型 | 心智模型、能力分组、关键陷阱,自动随站点发布 |
|
||||||
|
| [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) | AI **编程**助手 | 必守约定、枚举取值表、可运行模板、任务→方法决策表、9 条陷阱 |
|
||||||
|
|
||||||
|
`llms.txt` 解决「这个库能干什么」,`SKILL.md` 解决「代码该怎么写对」。
|
||||||
|
|
||||||
|
## 装载 SKILL.md
|
||||||
|
|
||||||
|
把文件放进你所用的 AI 助手的 skills 目录即可:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# WorkBuddy / Claude Code 风格
|
||||||
|
mkdir -p ~/.workbuddy/skills/pytdxdata
|
||||||
|
curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md \
|
||||||
|
https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md
|
||||||
|
```
|
||||||
|
|
||||||
|
也可以直接在提示词里附上该文件的 URL,或把它作为项目级 skill 放进你的仓库。
|
||||||
|
|
||||||
|
## 里面有什么
|
||||||
|
|
||||||
|
- **三条必守约定** —— 唯一入口是 `TdxData` 且必须 `async with`;`market` 是整数枚举而不是字符串;
|
||||||
|
返回值是 `list[dataclass]` 而不是 DataFrame
|
||||||
|
- **枚举取值表** —— `Market` / `KlinePeriod` / `Adjust` / `ExMarket` 的准确取值
|
||||||
|
- **可运行模板** —— K 线、复权、报价、逐笔、分时、批量,全部是能直接跑的代码
|
||||||
|
- **「想做什么 → 用哪个方法」决策表** —— 21 个常见需求的直接映射
|
||||||
|
- **9 条真实陷阱** —— 每条都注明后果和正确做法(如 `SH 000001` 是上证指数、`SZ 000001` 才是平安银行)
|
||||||
|
|
||||||
|
## 为什么值得让 AI 读
|
||||||
|
|
||||||
|
同一个 6 位代码在不同市场含义不同、枚举值与直觉完全脱节、复权/1 分钟线会静默切换通道——
|
||||||
|
这些都不是「读一眼签名就能猜到」的信息。不加载技能,AI 通常会写出:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# ❌ 三种典型错误
|
||||||
|
await td.get_kline("sh", "600000", 0, count=240) # market 传字符串;0 是 5 分钟线不是日线
|
||||||
|
td.get_kline(1, "600000", KlinePeriod.DAY) # 忘了 await,且没在 async with 内
|
||||||
|
df = bars.to_dataframe() # 返回值是 list[dataclass],没有这个方法
|
||||||
|
```
|
||||||
|
|
||||||
|
装载技能后这类错误基本消失。
|
||||||
|
|
||||||
|
## 给文档/模型作者的提示
|
||||||
|
|
||||||
|
改接口后请同步这几处(CI 会自动校验漂移):
|
||||||
|
|
||||||
|
- 手写清单(必须列全):[`docs/api/index.md`](api/index.md)、[`docs/API_REFERENCE.md`](API_REFERENCE.md)
|
||||||
|
- 入口与教程(只要求无过时引用):`SKILL.md`、`README.md`、`llms.txt`、`getting-started`、`cookbook`、`faq`、`cli`
|
||||||
|
|
||||||
|
校验命令:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/check_docs.py # 退出码 1 = 存在漂移
|
||||||
|
python scripts/check_docs.py --list # 打印全部公开方法名
|
||||||
|
```
|
||||||
|
|
||||||
|
## 下一步
|
||||||
|
|
||||||
|
- [接口总览](api/index.md) — 有哪些能力
|
||||||
|
- [TdxData 方法](api/tdxdata.md) — 完整签名(docstring 自动生成)
|
||||||
|
- [枚举速查](api/enums.md) — 参数到底该填几
|
||||||
+1
-1
@@ -92,7 +92,7 @@
|
|||||||
|
|
||||||
??? question "支持哪些市场?"
|
??? question "支持哪些市场?"
|
||||||
**标准通道**:沪 / 深 / 北(A 股)、指数、ETF、可转债。
|
**标准通道**:沪 / 深 / 北(A 股)、指数、ETF、可转债。
|
||||||
**EX 通道**:港股、美股、期货、期权等 **52 个市场**,完整清单见 [枚举速查](api/enums.md#exmarket)。
|
**EX 通道**:港股、美股、期货、期权等 **46 个市场**,完整清单见 [枚举速查](api/enums.md#exmarket)。
|
||||||
|
|
||||||
??? question "美股期权 / 港股期权能拿吗?"
|
??? question "美股期权 / 港股期权能拿吗?"
|
||||||
不能。通达信协议内**无美股 / 港股期权数据**。
|
不能。通达信协议内**无美股 / 港股期权数据**。
|
||||||
|
|||||||
+10
-1
@@ -70,10 +70,18 @@ asyncio.run(main())
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
51 个公开方法,从 docstring 实时生成,不会过期。
|
51 个数据方法(另有 `start` / `close`),从 docstring 实时生成,不会过期。
|
||||||
|
|
||||||
[:octicons-arrow-right-24: API 参考](api/index.md)
|
[:octicons-arrow-right-24: API 参考](api/index.md)
|
||||||
|
|
||||||
|
- **让 AI 助手写对代码**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
枚举取值反直觉,AI 凭常识几乎必错。装载 `SKILL.md` 就能一次写对。
|
||||||
|
|
||||||
|
[:octicons-arrow-right-24: AI 助手接入](ai.md)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
## 设计取舍
|
## 设计取舍
|
||||||
@@ -127,6 +135,7 @@ asyncio.run(main())
|
|||||||
- [连接池与缓存](internals/cache-pool.md)
|
- [连接池与缓存](internals/cache-pool.md)
|
||||||
|
|
||||||
- **其他**
|
- **其他**
|
||||||
|
- [AI 助手接入](ai.md)
|
||||||
- [常见问题](faq.md)
|
- [常见问题](faq.md)
|
||||||
- [更新日志](changelog.md)
|
- [更新日志](changelog.md)
|
||||||
- [参与贡献](contributing.md)
|
- [参与贡献](contributing.md)
|
||||||
|
|||||||
@@ -100,6 +100,7 @@ tdx financial gpcw20260331.zip --limit 5
|
|||||||
|
|
||||||
## 可选
|
## 可选
|
||||||
|
|
||||||
|
- [SKILL.md](https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md):面向 AI **编程**助手的技能文件(必守约定 / 枚举取值表 / 决策表 / 陷阱清单),比本文件更适合指导写代码
|
||||||
- [完整接口清单](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/):手工维护的全量清单,含参数默认值
|
- [完整接口清单](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/):手工维护的全量清单,含参数默认值
|
||||||
- [更新日志](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md)
|
- [更新日志](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md)
|
||||||
- [GitHub 仓库](https://github.com/openbot-coder/pytdxdata)
|
- [GitHub 仓库](https://github.com/openbot-coder/pytdxdata)
|
||||||
|
|||||||
@@ -60,6 +60,7 @@ nav:
|
|||||||
- 协议与命令: internals/protocol.md
|
- 协议与命令: internals/protocol.md
|
||||||
- 通道与数据源: internals/routing.md
|
- 通道与数据源: internals/routing.md
|
||||||
- 连接池与缓存: internals/cache-pool.md
|
- 连接池与缓存: internals/cache-pool.md
|
||||||
|
- AI 助手接入: ai.md
|
||||||
- 其他:
|
- 其他:
|
||||||
- 常见问题: faq.md
|
- 常见问题: faq.md
|
||||||
- 更新日志: changelog.md
|
- 更新日志: changelog.md
|
||||||
|
|||||||
+2
-2
@@ -1,6 +1,6 @@
|
|||||||
[project]
|
[project]
|
||||||
name = "pytdxdata"
|
name = "pytdxdata"
|
||||||
version = "0.4.0"
|
version = "0.5.0"
|
||||||
description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权"
|
description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权"
|
||||||
readme = "README.md"
|
readme = "README.md"
|
||||||
requires-python = ">=3.11"
|
requires-python = ">=3.11"
|
||||||
@@ -27,7 +27,7 @@ dependencies = []
|
|||||||
[project.urls]
|
[project.urls]
|
||||||
Homepage = "https://github.com/openbot-coder/pytdxdata"
|
Homepage = "https://github.com/openbot-coder/pytdxdata"
|
||||||
Repository = "https://github.com/openbot-coder/pytdxdata"
|
Repository = "https://github.com/openbot-coder/pytdxdata"
|
||||||
Documentation = "https://github.com/openbot-coder/pytdxdata#readme"
|
Documentation = "https://openbot-coder.github.io/pytdxdata/"
|
||||||
|
|
||||||
[project.optional-dependencies]
|
[project.optional-dependencies]
|
||||||
uvloop = ["uvloop>=0.21"]
|
uvloop = ["uvloop>=0.21"]
|
||||||
|
|||||||
+69
-5
@@ -7,7 +7,10 @@
|
|||||||
2. **过时**:文档里提到、代码里已不存在的方法
|
2. **过时**:文档里提到、代码里已不存在的方法
|
||||||
|
|
||||||
`docs/api/tdxdata.md` 由 mkdocstrings 自动生成,不在检查范围内(它不可能漂移)。
|
`docs/api/tdxdata.md` 由 mkdocstrings 自动生成,不在检查范围内(它不可能漂移)。
|
||||||
本脚本只管那些**手写**的接口清单。
|
本脚本只管那些**手写**的接口清单,分两档:
|
||||||
|
|
||||||
|
- `MUST_LIST_ALL`:必须列全所有公开方法(漏写也报错)
|
||||||
|
- `MUST_NOT_BE_STALE`:入口 / 教程 / 精选清单,只要求「不提到已删除的方法」
|
||||||
|
|
||||||
用法::
|
用法::
|
||||||
|
|
||||||
@@ -25,13 +28,28 @@ from pathlib import Path
|
|||||||
|
|
||||||
ROOT = Path(__file__).resolve().parent.parent
|
ROOT = Path(__file__).resolve().parent.parent
|
||||||
API_FILE = ROOT / "src" / "pytdxdata" / "api.py"
|
API_FILE = ROOT / "src" / "pytdxdata" / "api.py"
|
||||||
|
PKG_DIR = ROOT / "src" / "pytdxdata"
|
||||||
|
|
||||||
# 需要与代码保持一致的手写文档
|
# 必须**列全**所有公开方法的文档(漏写 = 漂移)
|
||||||
MUST_LIST_ALL = [
|
MUST_LIST_ALL = [
|
||||||
ROOT / "docs" / "api" / "index.md",
|
ROOT / "docs" / "api" / "index.md",
|
||||||
ROOT / "docs" / "API_REFERENCE.md",
|
ROOT / "docs" / "API_REFERENCE.md",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
# 只需**不提到已删除的方法**的文档:
|
||||||
|
# 这些是入口 / 教程 / 精选清单,本来就不要求列全,但绝不能引用已不存在的方法
|
||||||
|
MUST_NOT_BE_STALE = [
|
||||||
|
ROOT / "SKILL.md",
|
||||||
|
ROOT / "README.md",
|
||||||
|
ROOT / "docs" / "llms.txt",
|
||||||
|
ROOT / "docs" / "index.md",
|
||||||
|
ROOT / "docs" / "getting-started.md",
|
||||||
|
ROOT / "docs" / "cookbook.md",
|
||||||
|
ROOT / "docs" / "faq.md",
|
||||||
|
ROOT / "docs" / "cli.md",
|
||||||
|
ROOT / "docs" / "ai.md",
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
def collect_api_methods(path: Path) -> tuple[set[str], set[str]]:
|
def collect_api_methods(path: Path) -> tuple[set[str], set[str]]:
|
||||||
"""返回 (全部公开方法, 非 async 的公开方法)。"""
|
"""返回 (全部公开方法, 非 async 的公开方法)。"""
|
||||||
@@ -58,8 +76,39 @@ def mentioned_in(text: str, name: str) -> bool:
|
|||||||
|
|
||||||
|
|
||||||
def collect_doc_references(text: str) -> set[str]:
|
def collect_doc_references(text: str) -> set[str]:
|
||||||
"""抽取文档中以反引号标注的疑似方法名。"""
|
"""抽取文档中以反引号标注的疑似方法名。
|
||||||
return set(re.findall(r"`((?:get|download)_[a-z0-9_]+)`", text))
|
|
||||||
|
同时覆盖两种写法:`` `get_kline` `` 与 `` `get_kline(market, code, ...)` ``。
|
||||||
|
"""
|
||||||
|
return set(
|
||||||
|
re.findall(r"`((?:get|download)_[a-z0-9_]+)\s*(?:\([^`()]*\))?`", text)
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def collect_package_symbols() -> set[str]:
|
||||||
|
"""收集包内所有模块级公开函数 / 类名,以及 ``__all__`` 导出的名字。
|
||||||
|
|
||||||
|
文档里会合法地引用 `config.get_standard_hosts` 这类**模块级**函数,
|
||||||
|
不把它们纳入白名单就会被误判成「引用了已删除的方法」。
|
||||||
|
"""
|
||||||
|
names: set[str] = set()
|
||||||
|
for path in PKG_DIR.rglob("*.py"):
|
||||||
|
try:
|
||||||
|
tree = ast.parse(path.read_text(encoding="utf-8"))
|
||||||
|
except SyntaxError: # pragma: no cover - 语法错误交给 CI 的测试去抓
|
||||||
|
continue
|
||||||
|
for node in tree.body:
|
||||||
|
if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
|
||||||
|
if not node.name.startswith("_"):
|
||||||
|
names.add(node.name)
|
||||||
|
elif isinstance(node, ast.Assign):
|
||||||
|
for target in node.targets:
|
||||||
|
if isinstance(target, ast.Name) and target.id == "__all__":
|
||||||
|
try:
|
||||||
|
names.update(str(x) for x in ast.literal_eval(node.value))
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
pass
|
||||||
|
return names
|
||||||
|
|
||||||
|
|
||||||
def main() -> int:
|
def main() -> int:
|
||||||
@@ -76,6 +125,9 @@ def main() -> int:
|
|||||||
|
|
||||||
print(f"api.py: TdxData 公开方法 {len(methods)} 个(含 start/close 生命周期)")
|
print(f"api.py: TdxData 公开方法 {len(methods)} 个(含 start/close 生命周期)")
|
||||||
|
|
||||||
|
# 「已删除」判定要排除包内其它公开符号(config 的模块级函数等),否则误报
|
||||||
|
known = methods | collect_package_symbols()
|
||||||
|
|
||||||
problems: list[str] = []
|
problems: list[str] = []
|
||||||
|
|
||||||
if sync_methods:
|
if sync_methods:
|
||||||
@@ -98,13 +150,25 @@ def main() -> int:
|
|||||||
f"{rel} 漏写 {len(missing)} 个方法: " + ", ".join(missing)
|
f"{rel} 漏写 {len(missing)} 个方法: " + ", ".join(missing)
|
||||||
)
|
)
|
||||||
|
|
||||||
stale = sorted(n for n in collect_doc_references(text) if n not in methods)
|
stale = sorted(n for n in collect_doc_references(text) if n not in known)
|
||||||
if stale:
|
if stale:
|
||||||
problems.append(f"{rel} 提到已不存在的方法: " + ", ".join(stale))
|
problems.append(f"{rel} 提到已不存在的方法: " + ", ".join(stale))
|
||||||
|
|
||||||
if not missing and not stale:
|
if not missing and not stale:
|
||||||
print(f" [OK] {rel}")
|
print(f" [OK] {rel}")
|
||||||
|
|
||||||
|
for doc in MUST_NOT_BE_STALE:
|
||||||
|
if not doc.exists():
|
||||||
|
continue
|
||||||
|
|
||||||
|
rel = doc.relative_to(ROOT).as_posix()
|
||||||
|
text = doc.read_text(encoding="utf-8")
|
||||||
|
stale = sorted(n for n in collect_doc_references(text) if n not in known)
|
||||||
|
if stale:
|
||||||
|
problems.append(f"{rel} 提到已不存在的方法: " + ", ".join(stale))
|
||||||
|
else:
|
||||||
|
print(f" [OK] {rel}(无过时引用)")
|
||||||
|
|
||||||
if problems:
|
if problems:
|
||||||
print("\n[FAIL] 文档漂移:")
|
print("\n[FAIL] 文档漂移:")
|
||||||
for p in problems:
|
for p in problems:
|
||||||
|
|||||||
@@ -16,7 +16,7 @@ from .models import (
|
|||||||
XdxrRecord,
|
XdxrRecord,
|
||||||
)
|
)
|
||||||
|
|
||||||
__version__ = "0.4.0"
|
__version__ = "0.5.0"
|
||||||
__all__ = [
|
__all__ = [
|
||||||
"TdxData",
|
"TdxData",
|
||||||
"Market",
|
"Market",
|
||||||
|
|||||||
@@ -0,0 +1,72 @@
|
|||||||
|
"""`scripts/check_docs.py` 的自测。
|
||||||
|
|
||||||
|
防漂移脚本本身也需要被验证——一个永远返回 0 的检查等于没有检查。
|
||||||
|
这里锁定三类行为:反引号抽取规则、词边界、以及「包内模块级符号不算已删除」。
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import importlib.util
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
ROOT = Path(__file__).resolve().parent.parent
|
||||||
|
SCRIPT = ROOT / "scripts" / "check_docs.py"
|
||||||
|
|
||||||
|
|
||||||
|
def _load_check_docs():
|
||||||
|
spec = importlib.util.spec_from_file_location("_check_docs", SCRIPT)
|
||||||
|
assert spec and spec.loader
|
||||||
|
module = importlib.util.module_from_spec(spec)
|
||||||
|
sys.modules["_check_docs"] = module
|
||||||
|
spec.loader.exec_module(module)
|
||||||
|
return module
|
||||||
|
|
||||||
|
|
||||||
|
cd = _load_check_docs()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
("text", "expected"),
|
||||||
|
[
|
||||||
|
# 裸方法名
|
||||||
|
("`get_kline`", {"get_kline"}),
|
||||||
|
# 带签名的写法(README / API_REFERENCE 里大量出现)
|
||||||
|
("`get_kline(market, code, period)`", {"get_kline"}),
|
||||||
|
("`download_file(filename, filesize)`", {"download_file"}),
|
||||||
|
# 同一行多个
|
||||||
|
("`get_quotes(stocks)` 和 `get_minute`", {"get_quotes", "get_minute"}),
|
||||||
|
# 带对象前缀的不是方法引用
|
||||||
|
("`td.get_kline(1, '600000')`", set()),
|
||||||
|
# 非 get_/download_ 前缀不匹配
|
||||||
|
("`list[SecurityBar]`", set()),
|
||||||
|
# 没有反引号就不是引用
|
||||||
|
("get_kline 没有反引号", set()),
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_collect_doc_references(text: str, expected: set[str]) -> None:
|
||||||
|
assert cd.collect_doc_references(text) == expected
|
||||||
|
|
||||||
|
|
||||||
|
def test_mentioned_in_respects_word_boundary() -> None:
|
||||||
|
"""`get_kline` 不应误匹配 `get_kline_batch`。"""
|
||||||
|
assert not cd.mentioned_in("用 `get_kline_batch` 批量拉取", "get_kline")
|
||||||
|
assert cd.mentioned_in("用 `get_kline(m, c, p)` 拉取", "get_kline")
|
||||||
|
|
||||||
|
|
||||||
|
def test_package_level_functions_are_known_symbols() -> None:
|
||||||
|
"""config.py 的模块级函数必须被纳入白名单,否则会被误报成「已删除」。"""
|
||||||
|
known = cd.collect_api_methods(cd.API_FILE)[0] | cd.collect_package_symbols()
|
||||||
|
for name in (
|
||||||
|
"get_standard_hosts",
|
||||||
|
"get_mac_hosts",
|
||||||
|
"get_ex_hosts",
|
||||||
|
"get_ex_handshakes",
|
||||||
|
):
|
||||||
|
assert name in known
|
||||||
|
|
||||||
|
|
||||||
|
def test_repository_docs_are_in_sync() -> None:
|
||||||
|
"""仓库当前状态必须无漂移(等价于 CI 里那一步)。"""
|
||||||
|
assert cd.main() == 0
|
||||||
Reference in new issue
Block a user