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:
openbot-coder committed 2026-09-15 13:57:31 +08:00
1 parent 02ec5b6e33
commit c4dd61665b
26 files changed
+2934 -1

No files matched your search

+63
View File
@@ -0,0 +1,63 @@
# 文件解析器
通达信服务器上除了行情,还有一批**静态文件**:板块成分、行业分类、历史专业财报。
这些文件是自定义二进制格式,本项目把解析器独立成 `pytdxdata.codec` 子模块:
- **纯标准库**(`struct` / `zipfile`),可以脱网单测
- **与网络层解耦**,可以直接拿本地文件字节调用
- 每个解析函数的 docstring 里都写明了**字节格式**,方便对照排错
```python
from pytdxdata.codec import parse_block_dat, parse_tdxhy_cfg, parse_financial_dat
blocks = parse_block_dat(open("block_gn.dat", "rb").read(), "block_gn.dat")
```
## 三类文件
| 文件 | 解析函数 | 产出 | 说明 |
|---|---|---|---|
| `block_zs/gn/fg.dat` | `parse_block_dat` | `list[TdxBlock]` | 板块成分股代码列表 |
| `tdxhy.cfg` | `parse_tdxhy_cfg` | `dict[str, IndustryInfo]` | 通达信行业 + 申万行业 |
| `gpcw.txt` | `parse_financial_file_list` | `list[FinancialFileInfo]` | 财报文件索引(文件名 / MD5 / 大小) |
| `gpcw*.zip` 内 `.dat` | `parse_financial_dat` | `list[FinancialRecord]` | 每股历史财报原始字段 |
!!! note "走网络时用 TdxData 的解析方法"
如果不想自己管下载,直接用封装好的方法(内部就是调这些解析器):
`get_block_parsed()` / `get_industry_map()` / `get_financial_file_infos()` / `get_financial_records_parsed()`
— 见 [接口总览 → 除权 / 财务 / F10 / 文件](index.md#file-methods)。
## 关键细节
**板块类型由文件名推断**,因为文件头里没有可靠的分类字段:
| 文件名包含 | category |
|---|---|
| `zs` | `0` 行业 |
| `gn` | `2` 概念 |
| `fg` | `3` 风格 |
| 其他 | `0` |
**单条板块记录最多 400 只成分股**(代码区 2800 字节 ÷ 每只 7 字节)。
**财报报告期的来源优先级**:文件名 → `.dat` 头部内嵌值。两个都拿不到才为空。
**市场字段**:`0` = 深,`1` = 沪。
> 这里曾经有过一个 bug——上游实现用 `<6s1c1L` 导致市场字段恒判为深市,
> 本包用 `<6sBL` 修正。见 [更新日志](../changelog.md)。
## API
::: pytdxdata.codec
options:
members_order: source
show_root_heading: false
show_root_toc_entry: false
filters:
- "!^_"
## 下一步
- [协议与命令](../internals/protocol.md) — 行情数据的线上协议格式
- [场景示例 → 板块成分离线解析](../cookbook.md#offline-block-snapshot)
+112
View File
@@ -0,0 +1,112 @@
# 枚举速查
!!! danger "先看这里——本项目最容易踩的坑"
通达信的枚举取值**完全没有直觉**:`KlinePeriod.DAY` 是 **4** 不是 0 也不是 3,
`ExMarket.HK_MAIN_BOARD` 是 **31**,`Market.SZ` 是 **0**。
写死数字几乎必错,**请一律使用枚举成员**。
```python
from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market
```
## Market — 普通市场
| 成员 | 值 | 说明 |
|---|---|---|
| `Market.SZ` | `0` | 深圳 |
| `Market.SH` | `1` | 上海 |
| `Market.BJ` | `2` | 北京(北交所) |
!!! warning "代码不唯一"
**市场 + 代码**才唯一。`(SH, "000001")` 是上证指数,`(SZ, "000001")` 是平安银行。
所有接口的第一个参数都是 `market`,就是为了消歧。
## KlinePeriod — K 线周期
| 成员 | 值 | 说明 |
|---|---|---|
| `KlinePeriod.MIN_5` | `0` | 5 分钟 |
| `KlinePeriod.MIN_15` | `1` | 15 分钟 |
| `KlinePeriod.MIN_30` | `2` | 30 分钟 |
| `KlinePeriod.MIN_60` | `3` | 60 分钟 |
| `KlinePeriod.DAY` | `4` | **日线(最常用)** |
| `KlinePeriod.WEEK` | `5` | 周线 |
| `KlinePeriod.MONTH` | `6` | 月线 |
| `KlinePeriod.MIN_1` | `7` | 1 分钟 |
| `KlinePeriod.MIN_3` | `8` | 3 分钟 |
| `KlinePeriod.YEAR` | `9` | 年线 |
| `KlinePeriod.SEASON` | `10` | 季线 |
| `KlinePeriod.YEAR_ALT` | `11` | 另一套年线编码 |
取值**与通达信协议字节一致**(`KlineCategory`)。附带一个属性:
```python
KlinePeriod.MIN_1.is_minute # True
KlinePeriod.DAY.is_minute # False
```
!!! warning "`MIN_1` 会换通道"
`MIN_1` 被强制路由到 **MAC 通道**并采用**单连接串行分页**,
避免并发分页在多服务器深度不一致时产生数据空洞。
详见 [通道与数据源](../internals/routing.md)。
## Adjust — 复权方式
| 成员 | 值 | 说明 |
|---|---|---|
| `Adjust.NONE` | `0` | 不复权(**默认**) |
| `Adjust.QFQ` | `1` | 前复权 |
| `Adjust.HFQ` | `2` | 后复权 |
`adjust != NONE` 时 K 线请求会切到 **MAC 通道**(标准通道不提供复权数据)。
!!! tip "和券商软件对不上,先差这里"
很多券商前端默认前复权,而本包默认 `NONE`。对比数据前先确认两边复权方式一致。
## ExMarket — 扩展市场 {#exmarket}
港股 / 美股 / 期货 / 期权等走通达信 **EX 通道(端口 7727)**,`market` 参数传 `ExMarket` 成员。
### 常用值速查
| 成员 | 值 | 说明 |
|---|---|---|
| `ExMarket.SH_STOCK_OPTION` | `8` | 沪股票期权 |
| `ExMarket.SZ_STOCK_OPTION` | `9` | 深股票期权 |
| `ExMarket.ZZ_FUTURES` | `28` | 郑商所期货 |
| `ExMarket.DL_FUTURES` | `29` | 大商所期货 |
| `ExMarket.SH_FUTURES` | `30` | 上期所期货 |
| `ExMarket.HK_MAIN_BOARD` | `31` | **港股主板(最常用)** |
| `ExMarket.NEEQ` | `44` | 新三板 |
| `ExMarket.CFFEX_FUTURES` | `47` | 中金所期货(股指 / 国债) |
| `ExMarket.HK_GEM` | `48` | 港股创业板 |
| `ExMarket.GZ_FUTURES` | `66` | 广期所期货 |
| `ExMarket.GE_STOCK` | `73` | 德国股票 |
| `ExMarket.US_STOCK` | `74` | **美股(最常用)** |
```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) # 苹果
await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700) # 股指期货
await td.get_kline(ExMarket.SH_STOCK_OPTION, "10010971", KlinePeriod.DAY, count=700)
```
### 完整成员列表
以下由 `mkdocstrings` 从源码实时渲染,**以源码为准**:
::: pytdxdata.models.ExMarket
options:
show_root_heading: false
show_root_toc_entry: false
members_order: source
!!! note "美股期权 / 港股期权不在其中"
通达信协议内**没有**美股、港股期权数据。美股期权需要走 CBOE 公开接口。
## 下一步
- [数据模型](models.md) — 返回对象字段
- [通道与数据源](../internals/routing.md) — 每个枚举对应哪台服务器
+123
View File
@@ -0,0 +1,123 @@
# 接口总览
对外唯一入口是 **`TdxData`** 类,共 **51 个数据方法**
(另有 `start()` / `close()` 两个生命周期方法,以及 `__aenter__` / `__aexit__`)。
所有方法都可以直接 `await`,返回的是标准库 `dataclass` 组成的 `list`,没有自定义容器类型。
```python
from pytdxdata import TdxData
```
!!! tip "签名不用背"
每个方法的完整签名、参数说明、返回值类型都在 **[TdxData 方法](tdxdata.md)** ,
由 `mkdocstrings` **从源码 docstring 实时渲染**——不可能过期。
本页只做「有哪些能力」的地图。
## 生命周期
| 方法 | 说明 |
|------|------|
| `async start()` | 启动:服务器探测 + 预建连接 + 初始化缓存 |
| `async close()` | 关闭全部连接池与缓存 |
| `async with TdxData() as td:` | 上下文管理器,自动 start / close |
## K 线(6)
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_kline(market, code, period, *, start, count, adjust, start_date, end_date)` | `list[SecurityBar]` | 主接口。`count > 页大小` 自动并发分页;复权走 MAC;支持日期区间(内部二分定位) |
| `get_kline_since(market, code, period, since, adjust)` | `list[SecurityBar]` | 增量便捷方法(≥`since`,含当天) |
| `get_kline_batch(stocks, period, *, start, count, adjust, concurrency)` | `dict[str, list[SecurityBar]]` | 多股票并发,返回 `{code: bars}` |
| `get_index_kline(market, code, period, *, start, count)` | `list[SecurityBar]` | 指数 K 线(多涨跌家数字段已处理) |
| `get_stock_kline_with_indicators(market, code, indicators, ...)` | `dict` | K 线 + 技术指标(MACD / KDJ / RSI / BOLL / MA / EMA) |
| `get_kline_offset(offset, count)` | `tuple[int, int]` | K 线偏移信息(MAC) |
## 报价(4)
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_quotes(stocks)` | `list[SecurityQuote]` | 五档报价;`>80` 只自动切批;TTL 5s |
| `get_stock_quotes(stocks, bits)` | `list[MemberQuote]` | MAC 自定义字段报价(≤80 只/次) |
| `get_stock_quotes_list(category, *, start, count, sort_type)` | `list[MemberQuote]` | 市场分类报价列表(0沪A / 6全A / 8科创 / 14创业) |
| `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数 / 总额 / 市值 / 涨跌停数) |
## 逐笔与分时(4)
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_transactions(market, code, *, date, start, count)` | `list[TransactionRecord]` | 逐笔成交(MAC,**含 `trade_count` 成交笔数**),支持历史回溯 |
| `get_minute(market, code, *, date)` | `list[MinuteBar]` | 分时(今日 / 历史,MAC `0x122D`) |
| `get_minute_batch(stocks, *, date, concurrency)` | `dict[str, list[MinuteBar]]` | 批量分时 |
| `get_chart_sampling(market, code)` | `list[float]` | 分时缩略采样(A 股走 MAC `0x254D`) |
## 证券列表(3)
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_security_count(market)` | `int` | 市场证券数量 |
| `get_security_list(market, *, start, count)` | `list[SecurityInfo]` | `count=None` = 全部(先查总数防死循环) |
| `get_security_list_all(market)` | `list[SecurityInfo]` | 全市场列表(高并发一次拉完,缓存 1 天) |
## 除权 / 财务 / F10 / 文件(15) {#file-methods}
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_xdxr(market, code)` | `list[XdxrRecord]` | 除权除息历史(标准) |
| `get_finance(market, code)` | `FinanceRecord \| None` | 财务快照(标准) |
| `get_price_limits(market, code, name, pre_close, listed_days)` | `tuple[float \| None, float \| None]` | 涨跌停价(**本地计算**,无网络) |
| `get_company_info_category(market, code)` | `list` | F10 目录 |
| `get_company_info_content(market, code, filename, offset, length)` | `str` | F10 内容(分块) |
| `get_block_info(filename)` | `bytes` | 板块文件**原始字节** |
| `get_report_file(filename)` | `bytes` | 报告 / 财务文件**原始字节** |
| `get_financial_file_list()` | `list[str]` | 财务文件列表**原始行** |
| `get_financial_records(filename)` | `bytes` | 财务文件内容**原始字节** |
| `get_file_meta(filename)` | `FileMeta` | 远程文件元信息(MAC `0x1215`) |
| `download_file(filename, filesize)` | `bytes` | 下载完整远程文件(MAC `0x1217`,分块) |
| **`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` **解压 + 解析**:每股原始字段 |
!!! note "原始字节通道保留"
返回 `bytes` 的那 4 个方法**保持向后兼容**,解析版是**新增**方法而不是替换。
解析器在 `pytdxdata.codec`,纯标准库,可以脱网单独复用(见 [文件解析器](codec.md))。
## 板块(6)
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_board_list(board_type, count)` | `list[BoardInfo]` | 板块列表(0全部 / 1行业 / 2概念) |
| `get_board_members(board_symbol, count, sort_type)` | `list[MemberQuote]` | 板块成分股报价(如 `881001`) |
| `get_belong_board(market, code)` | `list[BelongBoard]` | 个股所属板块 |
| `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 日涨跌幅排行 |
## 竞价 / 异动 / 快照 / 资金流 / 服务器(5)
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_auction(market, code)` | `list[AuctionItem]` | 集合竞价 |
| `get_unusual(market, start, count)` | `list[UnusualItem]` | 市场异动 |
| `get_symbol_info(market, code)` | `SymbolSnapshot` | 个股特征快照 |
| `get_capital_flow(market, code)` | `CapitalFlow` | 个股资金流向(主力 / 散户 + 5 档) |
| `get_server_info()` | `ServerInfo` | 服务器交易时段 |
## 扩展市场 EX:港股 / 美股 / 期货 / 期权(8)
| 方法 | 返回 | 说明 |
|------|------|------|
| `get_goods_list(market, start, count)` | `list[dict]` | 扩展市场商品列表(`0x23F5`,二分定位市场) |
| `get_goods_count(market)` | `int` | 商品数量(`None` = 全市场) |
| `get_goods_quotes(stocks, bits)` | `list[MemberQuote]` | 扩展市场报价(`0x122B`) |
| `get_goods_quotes_list(market, count)` | `list[MemberQuote]` | 商品列表 + 报价组合 |
| `get_goods_chart_sampling(market, code)` | `list[float]` | 扩展市场分时采样(`0x254D`) |
| `get_goods_tick_chart(market, code, ymd)` | `list[dict]` | 扩展市场分时 tick |
| `get_goods_transaction(market, code, *, ymd, start, count)` | `list[dict]` | 扩展市场逐笔(港股 `0x23FC` / `0x2406`) |
| `get_goods_transaction_all(market, code, ymd)` | `list[dict]` | 港股全量逐笔(自动翻页,≤50 页 / 9 万条) |
## 下一步
- [TdxData 方法](tdxdata.md) — 完整签名(自动生成)
- [枚举速查](enums.md) — 参数到底该填几
- [数据模型](models.md) — 返回对象有哪些字段
+41
View File
@@ -0,0 +1,41 @@
# 技术指标
纯函数实现,**不依赖 pandas / numpy**,输入 `list[float]` 输出 `list[float]`(或元组),
可直接在任意序列上用。也被 `TdxData.get_stock_kline_with_indicators()` 内部调用。
```python
from pytdxdata import indicator
```
## 快速示例
```python
closes = [b.close for b in bars]
macd_line, signal, hist = indicator.macd(closes)
rsi14 = indicator.rsi(closes, period=14)
upper, mid, lower = indicator.boll(closes, period=20, mult=2.0)
```
指标计算前端数据不足时,结果用 `None` 占位,长度与输入一致——**不会截断**,
方便直接和 K 线按下标对齐。
## API
::: pytdxdata.indicator
options:
members_order: source
show_root_heading: false
show_root_toc_entry: false
filters:
- "!^_"
## 与 get_stock_kline_with_indicators 的关系
服务端侧的指标请求走 MAC 通道(`get_stock_kline_with_indicators`,服务端算好返回);
本地侧的指标走本模块。两者不互相依赖:
| 方式 | 位置 | 适用 |
|---|---|---|
| `get_stock_kline_with_indicators(...)` | 服务端计算 | 想少传数据、服务端算子齐全时 |
| `pytdxdata.indicator.*` | 本地计算 | 需要自定义参数、离线复算、和其他数据源混算 |
+80
View File
@@ -0,0 +1,80 @@
# 数据模型
全部数据模型位于 `pytdxdata.models`,统一为 `@dataclass(slots=True)`。
选择 dataclass 而不是 pandas DataFrame 是刻意的:**零依赖 + 零转换开销**,
需要 DataFrame 时你自己转(一行的事,见 [场景示例 → 转成 pandas](../cookbook.md#to-pandas))。
## 导入方式
包级只导出 4 个枚举 + 6 个核心模型:
```python
from pytdxdata import Market, ExMarket, KlinePeriod, Adjust
from pytdxdata import (
SecurityBar, SecurityQuote, TransactionRecord,
MinuteBar, XdxrRecord, FinanceRecord,
)
```
其余模型需要从子模块导入:
```python
from pytdxdata.models import TdxBlock, IndustryInfo, FinancialFileInfo, FinancialRecord
from pytdxdata.models import BoardInfo, MemberQuote, AuctionItem, CapitalFlow
```
## 模型地图
| 模型 | 代表什么 | 从哪来 |
|---|---|---|
| `SecurityBar` | 一根 K 线 | `get_kline` / `get_kline_batch` |
| `IndexBar` | 指数 K 线(继承 `SecurityBar`) | `get_index_kline` |
| `SecurityQuote` | 五档报价快照 | `get_quotes` |
| `SecurityInfo` | 证券列表条目(代码 / 名称 / 前收) | `get_security_list` |
| `TransactionRecord` | 一笔成交 | `get_transactions` |
| `MinuteBar` | 一分钟分时点 | `get_minute` |
| `XdxrRecord` | 一次除权除息事件 | `get_xdxr` |
| `FinanceRecord` | 财务**快照**(最新一期,36 字段) | `get_finance` |
| `FinancialRecord` | 历史专业财报(`gpcw*.zip`,多报告期) | `get_financial_records_parsed` |
| `FinancialFileInfo` | 财报文件索引条目 | `get_financial_file_infos` |
| `TdxBlock` | 一个板块及其成分股 | `get_block_parsed` |
| `IndustryInfo` | 一只股票的行业归属 | `get_industry_map` |
| `BoardInfo` | 板块列表条目(含领涨股) | `get_board_list` |
| `MemberQuote` | 成分股报价(自定义字段) | `get_board_members` / `get_stock_quotes` |
| `BelongBoard` | 个股所属板块 | `get_belong_board` |
| `AuctionItem` | 集合竞价撮合点 | `get_auction` |
| `UnusualItem` | 一笔市场异动 | `get_unusual` |
| `SymbolSnapshot` | 个股特征快照 | `get_symbol_info` |
| `GoodsItem` | 扩展市场商品 | `get_goods_list` |
| `ServerInfo` | 服务器交易时段 | `get_server_info` |
| `CapitalFlow` | 个股资金流向 | `get_capital_flow` |
| `MarketStat` | 全市场统计 | `get_market_stat` |
| `FileMeta` | 远程文件元信息 | `get_file_meta` |
!!! warning "`FinanceRecord` vs `FinancialRecord` 只差一个字母"
但它们完全不同:
| | `FinanceRecord` | `FinancialRecord` |
|---|---|---|
| 来源 | `get_finance()` — 标准通道 | `get_financial_records_parsed()` — 服务器文件 |
| 内容 | **最新一期**财务快照 | **历史多报告期**专业财报 |
| 结构 | 具名属性(`zongguben`、`jingzichan` ...) | `fields: list[float]`,原始字段数组 |
| 单位 | 万元 / 万股 | 原始 float,需自行按字段语义换算 |
## 完整字段定义
以下由 `mkdocstrings` 从源码实时渲染(**以源码为准**):
::: pytdxdata.models
options:
members_order: source
show_root_heading: false
show_root_toc_entry: false
filters:
- "!^_"
## 下一步
- [枚举速查](enums.md) — `market` / `period` 参数取值
- [TdxData 方法](tdxdata.md) — 哪个方法返回哪个模型
+45
View File
@@ -0,0 +1,45 @@
# TdxData 方法签名
> 本页由 `mkdocstrings` **从 `src/pytdxdata/api.py` 的 docstring 实时渲染**。
> 你看到的签名就是当前代码的签名——不需要手动维护,也就不会过期。
## 用法
```python
import asyncio
from pytdxdata import TdxData
from pytdxdata.models import KlinePeriod, Market
async def main():
async with TdxData() as td:
bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
print(bars[-1])
asyncio.run(main())
```
!!! tip "本页太长?"
想看「有哪些能力」的地图,去 [接口总览](index.md)。
本页是完整的签名字典,适合用浏览器 `Ctrl+F` 搜方法名。
## 完整定义
::: pytdxdata.TdxData
options:
members_order: source
group_by_category: true
show_category_heading: true
show_root_heading: true
show_root_full_path: false
show_signature_annotations: true
separate_signature: true
merge_init_into_class: true
docstring_section_style: list
filters:
- "!^_"
## 相关
- [枚举速查](enums.md) — 参数该填哪个成员
- [数据模型](models.md) — 返回值有哪些字段
- [场景示例](../cookbook.md) — 组合用法