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

+3 -1
View File
@@ -1,6 +1,8 @@
# pytdxdata 对外接口清单
> 以 `src/pytdxdata` 源码为准整理(v0.3.2)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
> 以 `src/pytdxdata` 源码为准整理(v0.4.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
>
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
## 一、包级导出
+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) — 组合用法
+1
View File
@@ -0,0 +1 @@
--8<-- "CHANGELOG.md"
+125
View File
@@ -0,0 +1,125 @@
# 命令行工具
安装后自带 `tdx` 命令(等同 `python -m pytdxdata.cli`)。**19 个子命令**,覆盖全部主要能力,适合快速验证、脚本管道和临时取数。
```bash
tdx --help # 查看全部子命令
tdx <cmd> --help # 查看单个子命令参数
```
## 标的写法
几乎所有取行情的命令都接受同一个标的语法:
| 写法 | 含义 | 示例 |
|---|---|---|
| `sz000001` | 深市 | 平安银行 |
| `sh600000` | 沪市 | 浦发银行 |
| `bj920992` | 北交所 | — |
| `hk00700` | 港股 | 腾讯控股 |
| `usAAPL` | 美股 | 苹果 |
| `cffex:IFL0` | 期货(交易所前缀) | 中金所股指 |
| `000001` | **6 位纯数字 = 指数** | 上证指数 |
期货交易所前缀:`cffex:` 中金 / `shf:` 上期 / `zz:` 郑商 / `dl:` 大商 / `hk:` 港交所 / `gz:` 广期所。
## 行情
```bash
tdx quotes sz000001 sh600000 hk00700 # 五档报价(可多标的)
tdx info sz000001 # 个股特征快照
tdx market-stat # 全市场统计(涨跌家数/总额/市值/涨跌停数)
```
## K 线
```bash
tdx kline sz000001 --period day --count 30 --adjust qfq
tdx kline sz000001 --period min1 --count 240
tdx kline cffex:IFL0 --count 30 # 期货
tdx index 000001 --count 30 # 指数
```
| 选项 | 默认 | 说明 |
|---|---|---|
| `--period` | `day` | `min1` / `min3` / `min5` / `min15` / `min30` / `min60` / `day` / `week` / `month` / `season` / `year` |
| `--count` | `30` | 条数;`>800` 自动并发分页 |
| `--start` | `0` | 起始偏移(0 = 最新) |
| `--adjust` | `none` | `none` / `qfq`(前复权)/ `hfq`(后复权) |
## 逐笔与分时
```bash
tdx transactions sz000001 --count 50 # 今日逐笔(含成交笔数)
tdx transactions sz000001 --date 20260811 --count 50 # 历史逐笔
tdx minute sz000001 # 今日分时
tdx minute sz000001 --date 20260811 # 历史分时
```
## 板块
```bash
tdx board list --type 1 # 板块列表(0=全部 1=行业 2=概念)
tdx board members 881001 --count 30 # 板块成分股报价
tdx board ranking --type 1 --top 10 # 板块涨跌幅排行
tdx board change --type 1 --days 5 --top 10 # 板块 N 日涨跌幅排行
```
## 证券列表
```bash
tdx list --market sz --count 100 # 市场证券列表(--market sz/sh/bj)
```
## 其他标准通道数据
```bash
tdx xdxr sz000001 # 除权除息历史
tdx finance sz000001 # 财务快照
tdx auction sz000001 # 集合竞价
tdx flow sz000001 # 资金流向
tdx unusual --market sh --count 30 # 市场异动
tdx server-info # 服务器交易时段
```
## 服务器文件(板块 / 行业 / 财报)
这四个命令是 **下载 + 解析一步到位** 的,不需要自己拆二进制格式。
```bash
# 板块文件(block_zs.dat 行业 / block_gn.dat 概念 / block_fg.dat 风格)
tdx block block_gn.dat --limit 10 # 列出板块与成分股数量
tdx block block_gn.dat --limit 3 --codes # 额外打印成分股代码
# 行业分类(tdxhy.cfg)
tdx industry 600000 000001 --search 银行 # 指定代码 / 关键词搜索
tdx industry --limit 30 # 只看前 30 条
# 历史专业财报
tdx financial-list # 索引:文件名 / MD5 / 大小(gpcw.txt)
tdx financial gpcw20260331.zip --limit 5 # 下载 + 解压 + 解析
tdx financial gpcw20260331.zip --code 600000 --fields 8 # 只取指定股票、打印更多字段
```
## 组合用法
CLI 输出是纯文本,适合直接进管道:
```bash
# 把科创板全部股票代码喂给循环
tdx list --market sh --count 2000 | grep '^68' | head -20 | while read code; do
tdx kline "sh${code}" --count 5
done
# 快速扫一遍概念板块涨幅榜
tdx board ranking --type 2 --top 30
```
!!! tip "什么时候该用 CLI,什么时候该写代码"
- **临时看数 / 验证连通性 / shell 脚本** → CLI
- **批量拉取、落库、回测** → 用 Python API,CLI 每次调用都要重建连接池,批量场景开销大
## 下一步
- [场景示例](cookbook.md) — Python API 的批量用法
- [接口总览](api/index.md) — CLI 背后的方法
+116
View File
@@ -0,0 +1,116 @@
# 参与贡献
欢迎 Issue / PR。这个项目对「数据正确性」的要求高于「功能数量」——一个算错的字段比没有这个字段糟糕得多。
## 开发环境
```bash
git clone git@github.com:openbot-coder/pytdxdata.git
cd pytdxdata
uv sync # 建虚拟环境 + 安装 CLI + 装测试依赖
```
要求 Python **≥ 3.11**。项目用 `uv` 管理依赖和构建,构建后端是 `uv_build`。
## 跑测试
```bash
.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` 被本地代理 / 安全软件拦截。
详见 [常见问题 → 开发与测试](faq.md)。
因此**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 里请勿引入 |
### 新增一个行情接口的完整步骤
1. `protocol/commands/<域>.py` — 实现命令类(帧组装 + 响应解析)
2. `router.py` — 若需要按命令选通道,在这里登记
3. `models/__init__.py` — 加返回的 dataclass / 枚举
4. `api.py` — 加 `TdxData` 公开方法
5. `cli.py` — 可选,加子命令
6. `tests/` — 离线测试(构造字节流 → 断言解析结果)
7. 文档 — 更新 `docs/api/index.md` 的方法表 + `docs/API_REFERENCE.md`
> 第 7 步别漏。历史上已经发生过「加了方法但文档没跟上」的漂移。
## 文档
文档站是 MkDocs + Material,配置在 `mkdocs.yml`,源文件在 `docs/`。
```bash
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`。
```bash
git checkout -b feat/xxx
# ... 改代码 ...
.venv/Scripts/python.exe -m pytest tests/ -q
git commit -m "feat: xxx"
git push origin feat/xxx
```
### 发布流程(维护者)
1. 改 `pyproject.toml` + `src/pytdxdata/__init__.py` 的版本号
2. **`uv lock`** —— 同步 `uv.lock`,否则 CI 的 `uv sync --locked` 会失败
3. 提交并 push 到 `main`
4. 打标签并推送:
```bash
git tag v0.5.0
git push origin v0.5.0
```
推 tag 会自动触发 GitHub Actions:**test → build(含版本号一致性校验)→ OIDC 免密钥发布到 PyPI**。
不需要本地 token,也不需要 `twine`。
!!! warning "tag 已推送但发布失败时"
同名 tag **不能直接重推**(push 无变化,workflow 不会触发)。先删再推:
```bash
git push --delete origin v0.5.0
git tag -d v0.5.0 && git tag v0.5.0
git push origin v0.5.0
```
或直接手动触发:`gh workflow run release.yml --ref v0.5.0`
文档站由 `.github/workflows/docs.yml` 在 push `main` 时自动部署到
<https://openbot-coder.github.io/pytdxdata/>。
+232
View File
@@ -0,0 +1,232 @@
# 场景示例
每个片段都是完整可跑的。共同前提:
```python
import asyncio
from pathlib import Path
from pytdxdata import TdxData
from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market
```
## 全市场日线批量落库
连接池会把不同股票分配到不同服务器,这是 `*_batch` 存在的意义。
```python
async def dump_all_daily():
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
codes = await td.get_security_list_all(Market.SZ) # 缓存 1 天
symbols = [(Market.SZ, s.code) for s in codes]
bars = await td.get_kline_batch(
symbols,
KlinePeriod.DAY,
count=800,
adjust=Adjust.QFQ,
concurrency=12,
)
print(f"{len(bars)} / {len(symbols)} 只拿到数据")
for code, rows in bars.items():
if not rows:
continue
# 落库 / 写 parquet 都行,这里只演示
print(code, len(rows), rows[-1].datetime, rows[-1].close)
```
!!! tip "分页与并发的取舍"
`concurrency` 不是越大越好。单台服务器有连接上限,`concurrency` 超过 `pool_max × 服务器数`
之后只会排队。实践值:**8~16**。
## 分钟线增量更新
只拉「上次之后」的部分,用 `get_kline_since` 省掉全量重拉。
```python
async def update_minute(code: str, last_dt):
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
rows = await td.get_kline_since(Market.SZ, code, KlinePeriod.MIN_1, since=last_dt)
return [r for r in rows if r.datetime > last_dt]
```
!!! warning "1 分钟 K 线走 MAC 单连接串行分页"
这是刻意设计:并发分页会把不同页分到不同服务器,而各服务器**历史深度不一致**,
拼接后会出现**非确定性数据空洞**。所以 `MIN_1` 强制单连接串行(见 [通道与数据源](internals/routing.md))。
## 报价轮询
```python
async def poll_quotes(symbols, interval=5.0):
async with TdxData() as td:
while True:
quotes = await td.get_quotes(symbols) # >80 只自动切批;缓存 TTL 5s
for q in quotes:
print(q.code, q.price, q.bid[0], q.ask[0])
await asyncio.sleep(interval)
```
> 缓存 TTL 与轮询间隔对齐时,重复轮询几乎 0 网络开销。但注意通达信公开源本身是
> **15 分钟延时**数据,别拿它做实时交易决策。
## 板块轮动 / 领涨股
```python
async def sector_rotation():
async with TdxData() as td:
# 近 5 日概念板块涨幅排行
top = await td.get_board_change_ranking(board_type=2, days=5, top_n=10)
for row in top:
print(row)
# 拿第一名板块的成分股
symbol = top[0]["symbol"] if "symbol" in top[0] else "881001"
members = await td.get_board_members(symbol, count=20)
for m in members[:5]:
print(m.code, m.name, m.fields)
# 板块资金汇总
print(await td.get_board_summary(symbol))
```
## 个股所属板块(反向查询)
```python
async def belong(code: str):
async with TdxData() as td:
for b in await td.get_belong_board(Market.SH, code):
print(b)
```
## 逐笔复盘
```python
async def review_transactions(code: str, ymd: int):
async with TdxData() as td:
rows = await td.get_transactions(Market.SZ, code, date=ymd, count=2000)
total = sum(r.trade_count or 0 for r in rows)
buy = sum(r.vol for r in rows if r.bs_flag == 0) # 主动买
sell = sum(r.vol for r in rows if r.bs_flag == 1) # 主动卖
print(f"{ymd} 总成交笔数={total} 主动买={buy} 主动卖={sell}")
```
## 财务因子快照
```python
async def finance_snapshot(codes):
async with TdxData() as td:
for mkt, code in codes:
fin = await td.get_finance(mkt, code) # 标准通道,最新快照
if fin:
print(code, fin)
```
历史专业财报(`gpcw*.zip`,含多报告期)走文件接口:
```python
async def history_financials(code: str):
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
infos = await td.get_financial_file_infos() # 索引
records = await td.get_financial_records_parsed(infos[-1].filename)
row = next((r for r in records if r.code == code), None)
if row:
print(row.report_date, row.fields[:8])
```
## 行业分类映射
```python
async def industry_lookup(codes):
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
hy = await td.get_industry_map() # {6位代码: IndustryInfo}
for c in codes:
info = hy.get(c)
if info:
print(c, info.tdx_industry, info.sw_industry)
```
## 板块成分(离线解析) {#offline-block-snapshot}
`get_block_parsed` 拿到的是纯 dataclass,落成本地 JSON 后**完全脱网可用**——
适合做「板块成分快照」的定时任务。
```python
import json
async def snapshot_blocks():
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
all_blocks = []
for fn in ("block_zs.dat", "block_gn.dat", "block_fg.dat"):
for b in await td.get_block_parsed(fn):
all_blocks.append({
"name": b.name,
"category": b.category,
"codes": b.codes,
})
Path("blocks.json").write_text(
json.dumps(all_blocks, ensure_ascii=False), encoding="utf-8"
)
```
## 港股 / 美股 / 期货 / 期权
```python
async def ex_markets():
async with TdxData() as td:
hk = await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)
us = await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)
fut = await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700)
opt = await td.get_kline(ExMarket.SH_STOCK_OPTION, "10010971", KlinePeriod.DAY, count=700)
print(len(hk), len(us), len(fut), len(opt))
# 港股全量逐笔(自动翻页,≤50 页 / 9 万条)
ticks = await td.get_goods_transaction_all(ExMarket.HK_MAIN_BOARD, "00700")
print(len(ticks))
```
## 转成 pandas {#to-pandas}
包本身不带 pandas 依赖,但转换是一行的事:
```python
import pandas as pd
async def to_dataframe(code: str):
async with TdxData() as td:
bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=800)
df = pd.DataFrame([{
"dt": b.datetime, "open": b.open, "high": b.high,
"low": b.low, "close": b.close, "vol": b.vol, "amount": b.amount,
} for b in bars])
return df.set_index("dt")
```
## 长驻服务(FastAPI)
!!! danger "不要每次请求都新建 TdxData"
池与缓存都挂在实例上,每请求新建 = 每请求重建连接池 + 缓存全部失效。
```python
from contextlib import asynccontextmanager
from pathlib import Path
from fastapi import FastAPI, Request
@asynccontextmanager
async def lifespan(app: FastAPI):
async with TdxData(cache_dir=Path("./tdx_cache"), pool_min=4, pool_max=16) as td:
app.state.td = td
yield
app = FastAPI(lifespan=lifespan)
@app.get("/kline/{code}")
async def kline(code: str, request: Request):
td = request.app.state.td
bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=30)
return [{"dt": str(b.datetime), "close": b.close} for b in bars]
```
## 下一步
- [接口总览](api/index.md) — 全部方法
- [连接池与缓存](internals/cache-pool.md) — 调优 `pool_min` / `pool_max` / TTL
+153
View File
@@ -0,0 +1,153 @@
# 常见问题
## 数据与来源
??? question "数据是实时的吗?"
不是。行情来自通达信**公开**行情服务器,本身是 **15 分钟延时**数据。
需要实时数据请使用券商行情(迅投 QMT / 兴业 SMT-Q / 同花顺 等)。
本项目定位是**历史数据与研究**——日线、分钟线、逐笔、财报这些历史数据是完整且稳定的。
??? question "需要账号吗?要付费吗?"
不需要。通达信公开行情服务器无需注册,直接 TCP 连接即可。本项目也不收任何费用。
??? question "为什么 SHA 000001 和 SZ 000001 完全不一样?"
同一个 6 位代码在不同市场里是**不同标的**:
| 市场 | 代码 | 标的 |
|---|---|---|
| SH | `000001` | 上证指数 |
| SZ | `000001` | 平安银行 |
代码不唯一,**市场 + 代码**才唯一。这也是为什么所有接口的第一个参数都是 `market`。
??? question "为什么报价格式有时候是 2 位小数,有时候是 3 位?"
价格小数位按**品种**推断:股票 2 位,指数 / ETF / 可转债 3 位。
模型里的 `decimal_point` 字段就存了这个信息,需要自己格式化时以它为准。
## 连接与网络
??? question "连不上服务器 / 全部超时怎么办?"
服务器可用性会随时间变化(下线、换 IP、封禁)。按顺序排查:
1. 重新探测:`python -m pytdxdata.server_probe`
2. 手工指定清单绕过探测结果:
```python
async with TdxData(standard_servers=[("1.2.3.4", 7709)]) as td: ...
```
3. 检查出口网络策略——标准 / MAC 端口 **7709**、EX 端口 **7727** 需要放通。
4. 若在用代理软件,注意有些本地代理会劫持回环 TCP,导致 asyncio 建事件循环都卡住
(见下方「在 Windows 上测试卡死」)。
??? question "公司网络 / 代理环境下失败"
通达信协议是裸 TCP,不走 HTTP 代理。如果环境强制走代理,需要把 `7709` / `7727`
配成直连(bypass)。云服务器上常见问题是安全组只放通了 80/443。
??? question "连接池要配多大?"
默认 `pool_min=3 / pool_max=12` 覆盖绝大多数场景。经验值:
| 场景 | 建议 |
|---|---|
| 偶发查询、CLI | 默认即可 |
| 批量落库(`*_batch`) | `pool_max=16`、`concurrency=8~16` |
| Web 服务多并发 | `pool_max=24`,并确保单实例复用 |
再大只是排队,不会更快——瓶颈是对端服务器的连接上限。
## 数据正确性
??? question "K 线 `count` 给很小的时候返回空?"
已知问题:标准通道部分服务器在 `count < 100` 时返回空数据。
分页器已强制 `min_page=100` 规避,正常调用不会触发。
若你绕过分页器直接把 `start/count` 传给底层命令,需要自己处理。
??? question "1 分钟 K 线明明能并发,为什么是串行的?"
**刻意设计**。并发分页会把不同页分配到不同服务器,而各服务器的历史深度不一致;
拼接深度不同的分页,`stop_when_short` 会导致**非确定性数据丢失**。
所以 `KlinePeriod.MIN_1` 强制路由到 MAC 通道并**单连接串行分页**。
其他周期(`MIN_5` 及以上)不受影响,仍走并发分页。
??? question "为什么日线数据和券商软件对不上?"
按顺序检查:
1. **复权方式**是否一致 —— 券商常默认前复权,而本包默认 `Adjust.NONE`(不复权)
2. **是否含未收盘的那根** —— 盘中最后一根是动态的
3. 分钟线注意**数据来源深度**不同
??? question "缓存会不会返回过期数据?"
缓存按数据类型分级 TTL,不会返回超出 TTL 的数据:
| 数据类型 | TTL |
|---|---|
| 实时报价 | 5s |
| 分钟 K 线 | 60s |
| 日 K 线 | 当天 |
| 复权 K 线 | 1 天 |
| 历史逐笔 | 永久 |
需要绕开缓存时,用新的 `cache_dir`,或直接不传 `cache_dir`(仅内存缓存)。
## 市场覆盖
??? question "支持哪些市场?"
**标准通道**:沪 / 深 / 北(A 股)、指数、ETF、可转债。
**EX 通道**:港股、美股、期货、期权等 **52 个市场**,完整清单见 [枚举速查](api/enums.md#exmarket)。
??? question "美股期权 / 港股期权能拿吗?"
不能。通达信协议内**无美股 / 港股期权数据**。
美股期权可用 CBOE 公开接口获取。
??? question "数据能存下来离线用吗?"
能。所有方法返回的都是纯 Python `dataclass`,序列化完全自主。
服务器文件类的解析方法(板块 / 行业 / 财报)尤其适合做「快照落盘」——
解析后就是普通 dataclass,落 JSON 后**完全脱网可用**。见 [场景示例](cookbook.md#offline-block-snapshot)。
## 开发与测试
??? question "本机 `uv run pytest` 报 trampoline 错误?"
Windows 上已知问题。直接调 venv 里的解释器:
=== "Windows"
```bash
.venv/Scripts/python.exe -m pytest tests/ -q
```
=== "Linux / macOS"
```bash
.venv/bin/python -m pytest tests/ -q
```
??? question "本地测试卡死 / asyncio 事件循环建不起来?"
**根因**:Windows 上 `asyncio.new_event_loop()` 内部要建一个 `socket.socketpair()`,
走的是回环 TCP;**本地代理软件 / 安全软件会拦截回环连接**,导致建循环永久挂起。
表现:`asyncio.new_event_loop()`、`asyncio.run()`、`pytest-asyncio` 全部挂起。
规避办法(任选):
1. 退出或放行本地代理软件,让 `127.0.0.1` 回环连通;
2. 在 WSL / Linux 环境里跑异步测试;
3. 对不 `await` 真实 Future 的协程,可以同步驱动验证:
```python
coro = some_coroutine()
try:
coro.send(None)
except StopIteration as e:
result = e.value
```
> 这也是 CI 放在 Linux 上跑的原因——Windows 侧无法做首轮异步验证。
??? question "和 pytdx / easy-tdx 什么关系?"
| 项目 | 关系 |
|---|---|
| [easy-tdx](https://github.com/handsomejustin/easy_tdx) | **参照实现**。协议层独立实现,不依赖其包,只参照字节级格式;解决了它无连接池、串行分页、单连接单锁的问题 |
| [pytdx](https://github.com/rainx/pytdx) | 上游生态。本包**不依赖** pytdx,但对 EX 通道(7727)沿用 pytdx 的扩展市场协议 |
## 下一步
- [参与贡献](contributing.md) — 报 bug / 提 PR / 跑测试
- [更新日志](changelog.md) — 每个版本改了什么
+143
View File
@@ -0,0 +1,143 @@
# 安装与配置
## 环境要求
| 项 | 要求 |
|---|---|
| Python | **≥ 3.11**(开发与 CI 覆盖 3.11 / 3.13) |
| 运行时依赖 | **无**(纯 stdlib:`socket` / `ssl` / `zlib` / `struct` / `sqlite3` / `asyncio`) |
| 操作系统 | 任意(Windows / Linux / macOS) |
| 网络 | 需能直连通达信行情服务器(标准/MAC 端口 **7709**,EX 端口 **7727**) |
## 安装
=== "pip"
```bash
pip install pytdxdata
```
=== "uv"
```bash
uv add pytdxdata
```
=== "源码开发"
```bash
git clone git@github.com:openbot-coder/pytdxdata.git
cd pytdxdata
uv sync # 建虚拟环境 + 装 CLI + 装测试依赖
.venv/Scripts/python.exe -c "import pytdxdata" # Windows
# .venv/bin/python -c "import pytdxdata" # Linux / macOS
```
安装后即可使用 `tdx` 命令行工具(见 [CLI 手册](cli.md))。
### 可选:uvloop 加速
Linux / macOS 上可选用 `uvloop` 替换默认事件循环(Windows 不支持):
```bash
uv add --optional uvloop uvloop
```
```python
import uvloop, asyncio
uvloop.install() # 必须在 asyncio.run() 之前
asyncio.run(main())
```
## 构造参数
`TdxData` 全部参数为 **keyword-only**,都有合理默认值——99% 的场景直接 `TdxData()` 即可。
| 参数 | 默认 | 说明 |
|------|------|------|
| `standard_servers` | `None` | 标准通道服务器清单;`None` = 用内置探测结果 |
| `mac_servers` | `None` | MAC 通道服务器清单;`None` = 用内置探测结果 |
| `ex_servers` | `None` | EX 扩展市场服务器清单;`None` = 用内置探测结果 |
| `port` | `7709` | 标准 / MAC 端口(EX 固定 `7727`) |
| `timeout` | `3.0` | 连接超时(秒) |
| `cache_dir` | `None` | 磁盘缓存目录;**`None` = 仅内存缓存**(进程退出即失效) |
| `default_adjust` | `Adjust.NONE` | 默认复权方式,可被单次调用覆盖 |
| `max_inflight` | `64` | single-flight 并发上限(同键请求合并) |
| `pool_min` / `pool_max` | `3` / `12` | 动态连接池上下限 |
| `mac_pool_cap` | `4` | 单台 MAC 服务器连接数上限 |
### 典型配置
=== "最简(仅内存缓存)"
```python
async with TdxData() as td:
...
```
=== "生产(持久化缓存)"
```python
from pathlib import Path
async with TdxData(
cache_dir=Path.home() / ".cache" / "pytdxdata",
pool_min=4,
pool_max=16,
timeout=5.0,
) as td:
...
```
`cache_dir` 下会生成一个 SQLite 文件(WAL 模式)。**同一目录可被多个进程共享**,
适合「定时任务 + 交互式查询」并存的场景。
=== "自建服务器清单"
```python
async with TdxData(
standard_servers=[("1.2.3.4", 7709), ("5.6.7.8", 7709)],
mac_servers=[("9.10.11.12", 7709)],
) as td:
...
```
## 服务器清单
内置清单随包发布(`src/pytdxdata/servers.json`),由探测脚本生成:
```bash
python -m pytdxdata.server_probe # 重新探测并覆盖 servers.json
```
探测逻辑不是简单握手——它会**真实请求一段 K 线**,把「能连上但返回空数据」的坏节点剔除。
服务器可用性会随时间变化,连不上时优先重跑探测。
`pytdxdata.config` 提供读取接口:
```python
from pytdxdata.config import get_standard_hosts, get_mac_hosts, get_ex_hosts
print(len(get_standard_hosts()), len(get_mac_hosts()), len(get_ex_hosts()))
```
## 生命周期
`TdxData` 必须在 `async with` 内使用,或手动 `await td.start()` / `await td.close()`:
```python
async with TdxData() as td: # __aenter__ → start()
...
# __aexit__ → close():关闭全部连接池、flush 缓存
```
!!! tip "长驻进程"
池与缓存都挂在 `TdxData` 实例上。Web 服务 / 常驻任务应该**只创建一个实例并复用**,
不要每次请求都 `TdxData()`——否则等于每请求重建连接池,缓存也失效。
推荐在 FastAPI 的 `lifespan` 里创建并放进依赖。
## 下一步
- [场景示例](cookbook.md) — 看真实用法
- [CLI 手册](cli.md) — 不写代码直接拿数据
- [接口总览](api/index.md) — 完整方法清单
+134
View File
@@ -0,0 +1,134 @@
# pytdxdata
[![CI](https://img.shields.io/github/actions/workflow/status/openbot-coder/pytdxdata/ci.yml?branch=main&label=CI)](https://github.com/openbot-coder/pytdxdata/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/pytdxdata)](https://pypi.org/project/pytdxdata/)
[![Python](https://img.shields.io/pypi/pyversions/pytdxdata)](https://pypi.org/project/pytdxdata/)
[![License](https://img.shields.io/pypi/l/pytdxdata)](https://github.com/openbot-coder/pytdxdata/blob/main/LICENSE)
通达信(TongDaXin)行情数据客户端:**动态连接池 + 双层 TTL 缓存 + 3 连接并发分页**。
纯 `asyncio` 实现,**零运行时依赖**(只用 stdlib);**A股(沪/深/北) + 港股 + 美股 + 期货 + 期权**,一套接口全市场。
```bash
pip install pytdxdata
```
```python
import asyncio
from pytdxdata import TdxData
from pytdxdata.models import KlinePeriod
async def main():
async with TdxData() as td: # 自动探测服务器 + 建池 + 建缓存
bars = await td.get_kline(1, "600000", KlinePeriod.DAY, count=2400)
print(bars[-1].datetime, bars[-1].close)
asyncio.run(main())
```
## 特性
| 特性 | 说明 |
|------|------|
| 🧩 **动态连接池** | 启动时对服务器真实 K 线探测选优(剔除握手正常但返回空数据的坏节点);健康分(失败 ×0.5 / 成功 +0.2 / 冷却 120s)+ EWMA 延迟选路;按等待队列与空闲时长动态扩缩容;跨服务器故障转移 |
| 🗄️ **双层 TTL 缓存** | 内存 LRU + 磁盘 SQLite(WAL);TTL 分级:报价 5s / 分钟K线 60s / 日线当天 / 复权K线 1天 / 历史逐笔永久;`single-flight` 同键并发去重;缓存「已解析记录」,重复请求 0 网络 0 解析 |
| ⚡ **并发分页** | 把大请求拆成显式 `start` 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 |
| 🔀 **双通道整合** | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 |
| 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*.zip` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制 |
| 🚀 **批量下载** | `get_kline_batch` / `get_minute_batch`,多股票自动并发,连接池分配到不同服务器 |
| 📦 **零重型依赖** | 返回 `list[dataclass]`,pandas / polars 由调用方按需转换 |
## 从这里开始
<div class="grid cards" markdown>
- **装好并跑通**
---
安装、构造参数、缓存目录、第一个脚本。
[:octicons-arrow-right-24: 安装与配置](getting-started.md)
- **命令行直接拿数据**
---
19 个子命令,不写代码也能拉行情、板块、财报。
[:octicons-arrow-right-24: CLI 手册](cli.md)
- **场景示例**
---
全市场批量落库、分钟线增量、报价轮询、板块轮动、逐笔复盘。
[:octicons-arrow-right-24: Cookbook](cookbook.md)
- **查接口签名**
---
51 个公开方法,从 docstring 实时生成,不会过期。
[:octicons-arrow-right-24: API 参考](api/index.md)
</div>
## 设计取舍
参照 [easy-tdx](https://github.com/handsomejustin/easy_tdx) 重新实现,解决其三大短板(无连接池、串行分页、单连接单锁)。
协议层**独立实现**——不依赖 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 网络) |
| 依赖 | pandas 等 | 零运行时依赖 |
> 实测环境:Windows 11 / Python 3.13 / 同一批通达信服务器(2026-08)。
## 数据来源与限制
- 行情来自通达信**公开**行情服务器(无需账号),**15 分钟延时**;需实时数据请使用券商行情
- 服务器清单由 `python -m pytdxdata.server_probe` 探测生成,可用性随时间变化
- 港股 / 美股 / 期货 / 期权走通达信 EX 通道(端口 7727),部分市场(美股期权、港股期权)协议内无数据
完整清单见 [常见问题](faq.md)。
!!! warning "免责声明"
本包仅用于**技术研究与教育目的**。行情数据来自通达信公开接口,不保证实时性与准确性;
作者不对任何投资决策负责。使用前请遵守通达信服务条款及相关法律法规。
## 目录
<div class="grid cards" markdown>
- **快速开始**
- [安装与配置](getting-started.md)
- [场景示例](cookbook.md)
- [命令行工具](cli.md)
- **参考**
- [接口总览](api/index.md)
- [枚举速查](api/enums.md)
- [数据模型](api/models.md)
- [完整接口清单](API_REFERENCE.md)
- **深入原理**
- [架构总览](internals/architecture.md)
- [协议与命令](internals/protocol.md)
- [通道与数据源](internals/routing.md)
- [连接池与缓存](internals/cache-pool.md)
- **其他**
- [常见问题](faq.md)
- [更新日志](changelog.md)
- [参与贡献](contributing.md)
</div>
+108
View File
@@ -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) — 性能来自哪里
+113
View File
@@ -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) — 缓存与超时的排查
+102
View File
@@ -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) — 哪个命令走哪条通道
+80
View File
@@ -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) — 通道底下的字节格式
+106
View File
@@ -0,0 +1,106 @@
# pytdxdata
> 通达信(TongDaXin)行情数据客户端:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页。纯 asyncio,零运行时依赖,覆盖 A股(沪/深/北)/港股/美股/期货/期权。
pytdxdata 是一个 Python 库,从通达信**公开**行情服务器直接读取行情与服务器文件,无需账号。
面向量化研究与历史数据落库场景(数据为 15 分钟延时,不适合实时交易)。
## 安装与最小可用示例
```bash
pip install pytdxdata # 或 uv add pytdxdata;要求 Python >= 3.11
```
```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=2400)
print(bars[-1].datetime, bars[-1].close)
asyncio.run(main())
```
## 心智模型(AI 必读)
1. **入口只有一个类**:`TdxData`。所有数据获取都是它的公开异步方法(51 个数据方法,
另有 `start()` / `close()` 生命周期方法),必须在 `async with` 内使用。
2. **标的需要「市场 + 代码」两个参数**。同一个 6 位代码在不同市场含义不同:
`(SH, "000001")` 是上证指数,`(SZ, "000001")` 是平安银行。
3. **枚举取值没有直觉,必须用枚举成员,不要写数字字面量**:
- `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
- `Adjust`: NONE=0 / QFQ=1(前复权) / HFQ=2(后复权);**默认 NONE**,很多券商软件默认前复权,对比数据前先对齐
- `ExMarket`: 港股主板 HK_MAIN_BOARD=31 / 美股 US_STOCK=74 / 中金所 CFFEX_FUTURES=47 / 沪股票期权 SH_STOCK_OPTION=8 等,共 46 个成员
4. **返回 `list[dataclass]`**,不是 DataFrame。需要 pandas 自行转换(见 cookbook)。包本身无任何运行时依赖。
5. **实例要复用**:连接池与缓存都挂在 `TdxData` 实例上。长驻进程(Web 服务)应只创建一个实例,
不要每请求新建,否则等于每请求重建连接池且缓存全部失效。
## 主要能力分组
- **K 线**:`get_kline`(主接口,自动并发分页、支持复权与日期区间)、`get_kline_batch`(多股票并发)、
`get_kline_since`(增量)、`get_index_kline`、`get_stock_kline_with_indicators`
- **报价**:`get_quotes`(五档,>80 只自动切批)、`get_stock_quotes_list`、`get_market_stat`
- **逐笔 / 分时**:`get_transactions`(含 `trade_count` 成交笔数,支持历史日期)、`get_minute`、`get_minute_batch`
- **证券列表**:`get_security_count`、`get_security_list`、`get_security_list_all`
- **财务 / 除权**:`get_finance`(最新快照)、`get_xdxr`、`get_price_limits`(本地计算涨跌停)
- **板块**:`get_board_list`、`get_board_members`、`get_board_ranking`、`get_board_change_ranking`、`get_belong_board`
- **服务器文件(下载 + 解析一步到位)**:`get_block_parsed`(板块成分)、`get_industry_map`(通达信+申万行业)、
`get_financial_file_infos`、`get_financial_records_parsed`(历史专业财报)
- **扩展市场**:`get_goods_list`、`get_goods_quotes`、`get_goods_transaction_all` 等,配合 `ExMarket` 使用
- **批量**:`get_kline_batch` / `get_minute_batch`,多股票并发且连接池会分配到不同服务器
## CLI
安装后提供 `tdx` 命令,19 个子命令,不写代码即可取数:
```bash
tdx quotes sz000001 sh600000
tdx kline sz000001 --period day --count 30 --adjust qfq
tdx transactions sz000001 --date 20260811
tdx board rank --type 1 --top 10
tdx block block_gn.dat --limit 10 --codes
tdx industry 600000 --search 银行
tdx financial gpcw20260331.zip --limit 5
```
标的写法:`sz000001` / `sh600000` / `bj920992` / `hk00700` / `usAAPL` / `cffex:IFL0` / `000001`(6 位纯数字=指数)。
## 关键陷阱
- **`KlinePeriod.MIN_1` 走 MAC 通道并单连接串行分页**,这是刻意设计:并发分页在多服务器
历史深度不一致时会产生非确定性数据空洞。不要试图"优化"成并发。
- **复权 K 线走 MAC 通道**,标准通道不提供复权数据。
- **标准通道部分服务器在 `count < 100` 时返回空**,分页器已强制 `min_page=100` 规避。
- **本地 Windows 上 `asyncio.new_event_loop()` 可能永久挂起**,根因是回环 `socket.socketpair()`
被本地代理/安全软件拦截。异步测试请在 Linux/WSL 运行。
- **`FinanceRecord` 与 `FinancialRecord` 不同**:前者是最新一期财务快照(标准通道),
后者是历史多报告期专业财报(服务器文件,字段为原始 float 数组)。
- 美股期权、港股期权在通达信协议内**无数据**。
- 行情为 **15 分钟延时**,不适合实时交易决策。
## 文档
- [首页](https://openbot-coder.github.io/pytdxdata/)
- [安装与配置](https://openbot-coder.github.io/pytdxdata/getting-started/)
- [场景示例](https://openbot-coder.github.io/pytdxdata/cookbook/)
- [CLI 手册](https://openbot-coder.github.io/pytdxdata/cli/)
- [接口总览](https://openbot-coder.github.io/pytdxdata/api/)
- [TdxData 方法签名](https://openbot-coder.github.io/pytdxdata/api/tdxdata/)
- [枚举速查](https://openbot-coder.github.io/pytdxdata/api/enums/)
- [数据模型](https://openbot-coder.github.io/pytdxdata/api/models/)
- [架构总览](https://openbot-coder.github.io/pytdxdata/internals/architecture/)
- [协议与命令](https://openbot-coder.github.io/pytdxdata/internals/protocol/)
- [通道与数据源](https://openbot-coder.github.io/pytdxdata/internals/routing/)
- [连接池与缓存](https://openbot-coder.github.io/pytdxdata/internals/cache-pool/)
- [常见问题](https://openbot-coder.github.io/pytdxdata/faq/)
## 可选
- [完整接口清单](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/):手工维护的全量清单,含参数默认值
- [更新日志](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md)
- [GitHub 仓库](https://github.com/openbot-coder/pytdxdata)
- [PyPI](https://pypi.org/project/pytdxdata/)