* feat: DataFrame 直出(df="polars"/"pandas")+ 版本 0.7.0 TdxData 新增构造参数 df: - None(默认)→ 行为与 0.6.x 完全一致,返回 list[dataclass] - "polars"/"pandas" → 42 个表格型接口直接返回 DataFrame 转换层 src/pytdxdata/frames.py: - 列计划按模型缓存,列式采集(不做逐行 asdict) - 时间列替换:year/month/day/hour/minute → datetime + trading_date;Xdxr 给 date - 嵌套定型:bid/ask 展开 10 列、fields 字典 JSON 化、codes 保持列表 - 容器展开:get_indicators 合并指标、get_index_trade_stats 展开 minutes、 get_kline_batch/get_minute_batch 纵向拼接 - ContextVar 层次标记:批量/别名方法内层不二次转换,并发互不干扰 - 后端惰性加载:缺包抛 FrameBackendError(带安装命令),构造时即失败 依赖:新增 extras pandas/polars/dataframe,核心包仍零依赖;dev 组加 pandas+polars 测试:tests/test_frames.py 40 项(双后端×双格式);全量 401 项通过 文档:新增 docs/dataframe.md,同步 API_REFERENCE/SKILL/llms.txt/README/mkdocs * perf(kline): 按日期取K线贴最新时走倒推,1分钟 4.2s → 82ms 问题:start_date/end_date 一律走「探总根数 + 二分定位」。1 分钟 K 线历史 二十万根量级 = 6 次翻倍探测 + 2 次方向探测 + 两次各 ~18 次跳转,共 36+ 次 串行往返。「取今天」这个最常见的调用要 4.2 秒。 改法(_bars_backtrack 快路径): - 右端离最新不超过 _BACKTRACK_GRACE(10 天) 时,直接 start=0, count=N 拿最新 N 根再裁剪;N 按时间跨度估(_BARS_PER_DAY),一天内一次命中, 不够才翻倍,放大到 _BACKTRACK_MAX_BARS 仍不够则回落二分 - 历史中段仍走二分,结果口径完全一致(已逐条比对基准) 两个关键细节: - 偏移方向是通道级属性而非标的属性,首次探测后缓存在实例上 (_kline_dir_cache)——全市场 5,225 只批量只付一次探测成本 - K线 hour/minute 是周期**结束**时刻,最新一根可能比 now() 略大(14:29 那根还在走),「右端贴最新」必须留周期容差,否则 end_date=now() 被误判 成历史中段 实测(1 分钟,冷启动): 取今天 4,208ms → 82ms 2天前~now 2,211ms → 75ms 最近3天 2,000ms+ → 239ms 历史中段 1,512ms → 285ms 全市场5225只取今天 32.1s(1,140,699 根,精确当天口径) 注:route_for 让 MIN_1 一律走 MAC(0x122E),所以按通道做方向缓存而不是按 「标准/扩展」写死分支。 测试:新增 tests/test_kline_date.py 6 项(倒推次数上界、结束时刻容差、 中段回落二分、未来区间、反向通道、与 count 路径口径一致);全量 407 项通过 * perf(kline): 全市场1分钟K线改多连接流水线抓取(43.6s → 5~7s,盘中 2s) 瓶颈其实是**往返次数**不是带宽:单只K线一请求一标的,串行 33ms/只 ≈ 1 个 RTT。 同一台服务器 16 连接 × 深度 8 实测能跑 5.2 MB/s(此前「单 IP 限流 1.5MB/s」 是浅流水下的假象)。 - get_bars 新增 pipeline 参数(None=按单请求字节自适应 8~32,1=关闭走逐只) - 多标的(≥16 只)走 _bulk_bars:多连接 work-stealing + 单连接 execute_pipeline - 只用实测最快的 12 台:池里 24 台全用反而被慢节点拖长尾 - 盘中按交易时段只拉已走过的根数(10:00 → 35 根,数据量差 7 倍) - 标准通道(日线不复权)同样走批量:全市场 49~72s → 13s - 修 pipeline 失败时队列剩余标的静默丢失(实测 20 只只回 16 只) - 修 test_future_range_returns_empty_quickly 时间炸弹(固定日期会漂进 _BACKTRACK_GRACE) - conftest 关闭后台测速 task,避免污染「往返次数」类断言 实测(5,225 只):count=2 → 2.7s;count=35 → 2.2s;count=240 → 6.9s。 逐根一致性 30/30 相同。新增 tests/test_bulk_kline.py 12 项,合计 419 项全绿。 * test: 批量K线测试的时间锚点改用真实 now(CI 是 UTC,固定日期会漂到别的时段分支) * fix(ex): EX 通道 K 线回填成交额与结算价(0x23FF 槽位按市场分两类) 报告:EX 通道 get_bars 返回的 SecurityBar.amount 恒为 0.0。 定位属实,但实际情况比报告更细 —— 32B 记录里那 28B 行情只有**一个** 4B 槽位 可复用,语义按市场分两类(全市场实测,用 成交额/(close×vol) 逐条校验): | 市场 | 槽位5 | 槽位6 | 槽位7 | |---|---|---|---| | 港股主板31/港股基金49 | 成交额(f) | 量(手=100股) | 未知 | | 港股创业板48/新三板44/美股74 | 成交额(f) | 量(股) | 0 | | 期货/期权 7/8/9/47… | 持仓量(I) | 量 | 结算价(f) | 改前 amount 硬编码 0.0、第 7 个 float 用 `_` 丢弃 —— 于是港股/美股/新三板 明明帧内有成交额却全为 0,期货期权的结算价也拿不到。 - 新增 SecurityBar.settle(结算价,float|None):仅 EX 期货/期权日线有值, 分钟线该槽位恒 0 已归一化为 None,其它通道恒 None。 - 权益类市场回填真实 amount;港股主板/基金的 vol 单位是手(=100股), amount/vol 是均价的 100 倍,已写进模型注释与量纲表。 - 期货/期权的 amount 仍是 0.0(帧内确实没有成交额,协议限制), 已在 SecurityBar / API_REFERENCE / llms.txt / SKILL.md 写清, 避免使用者再按旧文档判断成调用方 bug。 - 港股指数27/中证指数62 该槽位量级对不上(既非额也非结算价),保守保持 0.0。 - SecurityBar.__setstate__ 兜底旧磁盘缓存:缓存键无 schema 版本,升级后读旧 pickle 缺 settle 槽位,默认反序列化不补默认值 → AttributeError,已容错; EX K 线缓存键额外加 @v2,让 amount 恒 0 的旧缓存自然失效。 - K 线 DataFrame 因此多一列 settle(0.7.0 未发布,列清单同步更新)。 测试:tests/test_ex_bars_fields.py 16 项(解析层双布局、日内 settle 归零、 API 透传、旧 pickle 兼容);全套 435 项通过。 * docs: 0.7.0 全站口径同步(DataFrame 出口 + EX 成交额限制 + 构造参数表) - 首页:特性表补「DataFrame 直出」与 K 线批量性能,导航新增 DataFrame 卡片, 统一方法数按实测修正为 35(+33 别名 = 68 个公开方法) - 安装页:补 extras(polars/pandas/dataframe)与 df 用法;构造参数表补 df / std_pool_cap / ex_pool_cap,并把 pool_max 默认值从 12 修正为 24(实际值) - 场景示例:`转成 pandas` 一节改为先推 df= 开关,手动转换降级为局部场景 - 数据模型页:不再说「刻意不提供 DataFrame」,改为 dataclass 与 DataFrame 是同一份数据、两种容器 - AI 接入页:返回值约定补 `df=` 开关的说法 - README:K 线列注释补 settle;已知限制补 EX 通道成交额/结算价的协议口径 - CHANGELOG:新增「升级」小节(升级命令、旧缓存无需清理) --------- Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
160 lines
12 KiB
Plaintext
160 lines
12 KiB
Plaintext
# 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
|
||
|
||
async def main():
|
||
async with TdxData() as td: # 自动探测服务器、建连接池、初始化缓存
|
||
bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=2400)
|
||
print(bars[-1].datetime, bars[-1].close)
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
## 心智模型(AI 必读)
|
||
|
||
1. **入口只有一个类**:`TdxData`。所有数据获取都是它的公开异步方法(v0.6 起为 **28 个统一方法**,
|
||
另有 33 个 deprecated 别名与 `start()` / `close()` 生命周期方法),必须在 `async with` 内使用。
|
||
2. **标的用字符串**,形如 `sz000001` / `sh600000` / `hk00700` / `usAAPL` / `cffex:IFL0`。
|
||
同一个 6 位代码在不同市场含义不同:`sh000001` 是上证指数,`sz000001` 是平安银行;
|
||
裸 6 位数字(如 `000001`)视为沪市指数。统一接口不再接受 `(market, code)` 元组。
|
||
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 服务)应只创建一个实例,
|
||
不要每请求新建,否则等于每请求重建连接池且缓存全部失效。
|
||
|
||
## 主要能力分组(统一接口)
|
||
|
||
标的一律用字符串;以下均为 v0.6 统一接口,跨市场自动选路。
|
||
|
||
- **标的清单**:`get_universe`(A股 + 港股 + 美股 + 期货/期权)。⚠️ 北交所(`market="bj"`)清单**协议不支持**,返回空列表(`0x053E` 对 market=2 无响应,27 台服务器全测);但北交所**标的本身可用** —— 报价/K线/逐笔直接传 `bj920992` 这类代码正常
|
||
- **K 线**:`get_bars`(自动并发分页、支持复权与日期区间、多标的并发)。传 ≥16 只时自动走
|
||
**多连接流水线**(`pipeline` 默认自适应 8~32,传 `1` 关闭),全市场 5,200 只 1 分钟 K 线
|
||
取当天 43.6s → 5s 级;`start_date=今天` 盘中只拉已走过的根数(10:00 → 30 根),实时刷新 1~2 秒
|
||
- ⚠️ **EX 通道(港股/美股/期货/期权)的 `amount` 不是全有的**:`0x23FF` 帧内只有一个 4B 槽位可复用,
|
||
权益类(港股主板 31/创业板 48/基金 49、新三板 44、美股 74)装**成交额**(`amount` 正常),
|
||
期货期权装**结算价**(见 `SecurityBar.settle`,日线才有值)→ 它们 `amount` 恒 **0.0**,
|
||
是协议限制而非解析漏读;港股主板/基金的 `vol` 单位是**手(=100 股)**,`amount/vol` 是均价的 100 倍
|
||
- **技术指标**:`get_indicators`(K线 + MACD/KDJ/RSI/BOLL/MA/EMA)
|
||
- **报价**:`get_quotes`(五档,>80 只自动切批;**单连接流水线**默认开启,全市场 5,200 只 A股 ~0.33s)、`get_snapshot`(个股特征)、`get_market_stat`
|
||
- 价格标度:协议给的是整数,真实价 = `整数 / 10**小数位`。小数位由 `price_decimal_digits` 决定,
|
||
优先用**权威表**(证券清单自带的 `SecurityInfo.decimal_point`,`start()` 每日后台同步一次,
|
||
也可 `await td.sync_decimal_points()` 强制刷新),未同步时退回静态前缀规则。
|
||
债券/回购是 **4 位**、沪市 B 股 3 位 —— 这里错过两次(整批价格差 100 倍/10 倍)。
|
||
- **逐笔 / 分时**:`get_ticks`(含 `trade_count`,支持历史日期,返回按时间升序;`vol`/`trade_count` 为约 3 秒切片增量而非累计;已剔除 `bs_flag=8` 竞价委托;**指数**的 `vol` 是百元、`trade_count` 是均价×1000;**可转债**的 `vol` 是手=10 张、`trade_count` 是真实笔数,故日线 `amount/vol` 是均价的 **10 倍**,算均价要再 /10)、`get_minutes`(`sampling=True` 取缩略采样;`hour` 恒为合法时钟值 0~23,美股一个交易日跨两个北京自然日,按交易日聚合用 `MinuteBar.trading_date`、取时刻用 `MinuteBar.datetime`)
|
||
- **财务 / 除权**:`get_finance`(最新快照)、`get_xdxr`、`get_price_limits`(本地计算涨跌停)
|
||
- **F10**:`get_f10`(公司资料目录 + 正文)
|
||
- **板块**:`get_boards`、`get_board_members`、`get_board_of`、`get_board_summary`、
|
||
`get_board_ranking`、`get_board_change_ranking`
|
||
- **服务器文件(下载 + 解析一步到位)**:`get_file`(原始字节)、`get_block_parsed`(板块成分)、
|
||
`get_industry_map`(通达信+申万行业)、`get_financial_file_infos`、`get_financial_records_parsed`(历史专业财报)
|
||
|
||
> 旧的分通道/市场方法(`get_kline` / `get_transactions` / `get_goods_*` 等共 33 个)保留为
|
||
> deprecated 别名,1.0 移除;完整对照见[接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/)与 CHANGELOG。
|
||
|
||
## DataFrame 输出(v0.7+)
|
||
|
||
表格型接口可以直出 pandas / polars DataFrame,开关只有构造参数 `df`:
|
||
|
||
```python
|
||
from pytdxdata import TdxData
|
||
|
||
async with TdxData(df="polars") as td: # 或 df="pandas";df=None(默认)= list[dataclass]
|
||
df = await td.get_bars("sh600000", count=240)
|
||
```
|
||
|
||
- 需先装 extra:`pip install "pytdxdata[polars]"` / `[pandas]` / `[dataframe]`。**核心包仍零依赖**。
|
||
- `df=None` 时行为与 0.6.x 完全一致(装饰器直接透传,零开销);`df` 非法抛 `ValueError`,包没装抛 `FrameBackendError`(带安装命令)。
|
||
- 列口径:**时间列替换**拆开的 `year/month/day/hour/minute` → `datetime`(+ `trading_date`);`bid`/`ask` 五档展开成 10 列;`fields` 字典 JSON 化成字符串列(空字典给 `None`);`TdxBlock.codes` 保持列表。
|
||
- `get_indicators` → bars + 指标合并成一张表;`get_index_trade_stats(_multi)` → `minutes` 展开并补 `index`/`date` 常量列;`get_kline_batch`/`get_minute_batch` → 各标的纵向拼接成一张表。
|
||
- **不受影响**:`bytes`/`int`/`dict`/单对象/`tuple`/`list[float]`/`list[str]` 类接口原样返回(如 `get_file`、`get_security_count`、`get_server_info`)。
|
||
- 空结果返回**列名齐全的空表**,但 dtype 只由后端推断。
|
||
|
||
## 服务器与配置
|
||
|
||
服务器主机来源有一条优先级链(各协议独立):环境变量 → **当日测速缓存** → 包内清单
|
||
`fast_pool` → 包内清单 → 代码内置常量。
|
||
|
||
- `TdxData.start()` 会在**当日首次启动**后台触发一次全量测速,用**真实 K 线命令**判定可达
|
||
(不是只握手),结果按延迟升序写入**用户级缓存**(Windows `%LOCALAPPDATA%\pytdxdata`、
|
||
macOS `~/Library/Caches/pytdxdata`、Linux `$XDG_CACHE_HOME/pytdxdata`),当天复用、不再重测。
|
||
- 该操作对调用方**完全无感**:后台执行、不打印、不阻塞 `start()`、失败静默降级。
|
||
运行时**绝不改写包内 `servers.json`**。
|
||
- 环境变量:`PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS` / `…_EX_HOSTS`(逗号分隔,手工指定,最高优先)、
|
||
`PYPYTDX_DATA_CACHE_DIR`(覆盖缓存目录)、`PYPYTDX_DATA_DISABLE_PROBE=1`(关闭测速)。
|
||
|
||
## 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 通道**,标准通道不提供复权数据。
|
||
- **K 线 `datetime` 统一为北京时间**(v0.6.2 起)。美股原始报文的日期分量是美东交易日、
|
||
时分分量是北京时间,库已自动归一化,`bar.datetime` 可直接排序 / 比较 / 过滤。
|
||
但**美股一个交易日横跨两个北京自然日**:按交易日聚合(分钟线合成日线、日内统计)
|
||
用 `bar.trading_date`,不要用 `bar.datetime.date()`。`bar.is_us` 判定美股。
|
||
- **标准通道部分服务器在 `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/)
|
||
|
||
## 可选
|
||
|
||
- [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/refactor-audit/):统一接口 / 废弃别名全清单 + 数据一致性与遗漏对账
|
||
- [更新日志](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md)
|
||
- [GitHub 仓库](https://github.com/openbot-coder/pytdxdata)
|
||
- [PyPI](https://pypi.org/project/pytdxdata/)
|