Files
pytdxdata/SKILL.md
T
openbotandopenbot-coder 04e0c57569 feat: DataFrame 直出(df="polars"/"pandas")+ 0.7.0 (#12)
* 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>
2026-10-28 18:22:13 +08:00

15 KiB
Raw Blame History

name, description
name description
pytdxdata 用 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

from pytdxdata import TdxData

async with TdxData() as td:      # 自动 start(探测服务器 + 预建连接 + 建缓存)
    bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
# 退出即 close

不要直接 await TdxData().get_bars(...)——没 start() 就没有连接池。

2. 标的写法是字符串,不是元组

这是 v0.6 的最重要变化。不要传 (Market.SH, "600000") 元组,用字符串:

# 旧写法(deprecated,会发出 DeprecationWarning):
bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)

# 新写法(推荐):
bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
# 港股/美股/期货也一样:
bars = await td.get_bars(["hk00700", "usAAPL", "cffex:IFL0"], KlinePeriod.DAY, count=240)

3. 返回 list[dataclass],不是 DataFrame

库刻意不依赖 pandas。要 DataFrame 自己转一行:

from dataclasses import asdict
import pandas as pd
df = pd.DataFrame([asdict(b) for b in bars])

安装

pip install pytdxdata        # 或 uv add pytdxdata
pip install "pytdxdata[polars]"   # 需要 DataFrame 输出时才装(可选 extras)

可运行模板

import asyncio
from pytdxdata import TdxData
from pytdxdata.models import KlinePeriod, Adjust

async def main():
    async with TdxData() as td:
        # 日K线,240 根(count 超过单页大小会自动多连接并发分页)
        bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
        print(bars[-1].close, bars[-1].datetime)

        # 前复权日线(复权自动走 MAC 通道)
        qfq = await td.get_bars(["sz300308"], KlinePeriod.DAY,
                                 count=500, adjust=Adjust.QFQ)

        # 跨市场报价:A股+港股+美股一次拿全
        quotes = await td.get_quotes(["sz000001", "hk00700", "usAAPL"])
        print(quotes[0].price, quotes[1].name, quotes[2].amount)

        # 逐笔成交(MAC 通道,支持历史日期,含 trade_count 成交笔数)
        ticks = await td.get_ticks(["sz000001"], date=20260811)
        print(sum(r.trade_count for r in ticks))

        # 分时(MAC 通道,今日或历史)
        minutes = await td.get_minutes(["sz000001"])

        # 批量 K 线:≥16 只自动走「多连接 × 单连接流水线」,池子把标的摊到多台服务器
        batch = await td.get_bars(
            ["sz000001", "sh600000"],
            KlinePeriod.DAY, count=240,
        )  # 平铺返回,每条带 .symbol 字段

        # 全市场盘中实时:只拉已经走完的根数(10:00 → 30 根),5,200 只 1~2 秒
        from datetime import datetime
        live = await td.get_bars(
            [s.symbol for s in await td.get_universe("sh")],
            KlinePeriod.MIN_1, start_date=datetime.now(),
        )
        # pipeline=1 可关闭批量路径,退回逐只并发(结果一致,只是慢)

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 通道)

v0.6 起统一接口用字符串前缀指定扩展市场,一般不再需要 ExMarket:

await td.get_bars("hk00700", KlinePeriod.DAY, count=700)      # 港股(5 位代码)
await td.get_bars("usAAPL", KlinePeriod.DAY, count=700)       # 美股(ticker)
await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700)   # 期货合约

常用前缀:hk / us / cffex / shf / dl / zz / gz;完整表见 https://openbot-coder.github.io/pytdxdata/api/enums/。

想做什么 → 用哪个方法

需求 方法
全市场标的清单(A股+港股+期货…;北交所返回空) get_universe(market=None)
日/周/月/分钟 K 线(任意市场) get_bars(symbols, period, *, count, adjust, start_date, end_date)
K 线 + MACD/KDJ/RSI/BOLL get_indicators(symbols, indicators, ...)
实时五档报价(A股)/ 基础报价(港股/美股/期货) get_quotes(symbols, *, fields=None, pipeline=True)
逐笔成交(任意市场) get_ticks(symbols, *, date)
分时图 / 缩略采样 get_minutes(symbols, *, date, sampling=True)
全市场股票列表(缓存 1 天) get_universe("sz") / get_universe("sh")
北交所全量代码 拿不到:清单命令对 market=2 无响应(27 台全测)。北交所标的仍可直接查 bj920992
除权除息 / 财务快照 get_xdxr(symbols) / get_finance(symbols)
F10 公司资料 get_f10(symbol, section)
板块列表 / 成分股 / 涨跌排行 get_boards / get_board_members / get_board_ranking
指数的成交量 + 成交笔数(每分钟曲线) get_index_trade_stats(index, date) → .cum_trade_count()
指数成分股 get_index_members(index)(裸 000001 按指数语义解析)
个股所属板块 get_board_of(symbols)
集合竞价 / 异动 / 资金流 get_auction / get_unusual / get_capital_flow
个股特征快照 get_snapshot(symbols)
板块成分文件(离线快照) get_block_parsed("block_gn.dat")
行业分类(通达信 + 申万) get_industry_map()
历史专业财报(gpcw 全字段) get_financial_file_infos() + get_financial_records_parsed(fn)
涨跌停价 get_price_limits(symbol, name, pre_close, listed_days)(本地算,无网络)
全市场涨跌家数/成交额 get_market_stat()

通道与数据特性(影响你能拿到什么)

库内部有标准通道和 MAC 通道两条链路,会按命令自动选路,你不用管。但有几件事必须知道:

  • 数据有 15 分钟延时(通达信公开服务器特性)。要实时数据请用券商行情。
  • 复权 K 线与 1 分钟 K 线走 MAC 通道。get_bars(..., adjust=Adjust.QFQ) 自动切换。
  • K 线时间戳统一为北京时间(v0.6.2 起)。美股原始报文里日期是美东交易日、时分是北京时间(两个时区拼在一起),库已自动归一化,bar.datetime 可直接排序 / 比较 / 过滤。但美股一个交易日横跨两个北京自然日,按交易日聚合(分钟线合成日线、日内统计)必须用 bar.trading_date。
  • count 很大时会自动多连接并发分页,无需手动翻页。但标准通道 K 线 count < 100 部分服务器会返回空——内部已强制 min_page=100 规避。
  • get_quotes 一次 >80 只自动切批;走 MAC 字段位通道(fields=)时上限为 80 只/次。
  • 全市场报价用默认参数即可,别自己写循环。get_quotes(全部A股) 内部会切 66 片并走单连接流水线(一条连接连发多个分片、只付一次往返)+ 工作窃取调度,5,227 只实测 p50 325ms(老版本串行 3.5s)。自己 for 循环逐只/逐片调会把流水线优势全部丢掉。
    • 想更保守可 concurrency=11(每台 1 连接),代价 p50 457ms。
    • 个别服务器不支持流水线时自动降级逐片,结果不受影响。
  • 可转债(110/111/113/118/123/127/128)三样都是真的:价格、vol(手=10 张)、trade_count(真实笔数,3631 条切片 / 20443 笔量级)全部可用,Σvol 与日线 vol 1:1 相等。 ⚠️ 唯一要小心的是 日线 amount / vol 不等于均价,而是均价的 10 倍(vol 单位是手=10 张)。算可转债均价用 amount / vol / 10,或直接用 Σ(price×vol) / Σvol——后者跨品种都成立,最稳。 对照:股票/ETF 的 Σ逐笔vol / 日线vol = 0.01(逐笔手、日线股),而 amount/vol 恰好就是均价。
  • 指数本身没有成交笔数。get_ticks("sh000001") 的 trade_count 是「当时均价×1000」、vol 单位是百元(成交额/100)。要笔数只能用 get_index_trade_stats(index)(成分股逐笔累加,2230 只约 36-60 s)。北交所成分无笔数字段,该方法会返回 trade_count_available=False。
  • ETF / LOF 也没有成交笔数。get_ticks("sh510310") 的 trade_count 是「价格×1000」(货币 ETF 恒为 0)。判定用 symbols.has_order_count(market, code),读记录时看 TransactionRecord.trade_count_available——为 False 时 trade_count 已被置 0,不要求和/求均值。注意沪市 501x/502x/506x 实测有真实笔数,不能按「5 开头=基金」一刀切。
  • 历史逐笔有笔数(MAC 0x122F 支持历史日期,实测可回溯最近 5 个交易日;更早返回空)。
  • 小数位表不用手动管,但可以手动刷。start() 会检查当日缓存并后台同步一次(SecurityInfo.decimal_point 权威值);要强制刷新用 await td.sync_decimal_points(),看同步状态用 await td.decimal_point_status()。PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1 可关闭后台同步。
  • 板块文件(block_*.dat)/ 行业(tdxhy.cfg)/ 财报(gpcw*.zip)是服务器上的静态文件,解析后是普通 dataclass,落 JSON 后完全脱网可用——适合做离线快照。

DataFrame 输出(v0.7+)

表格型方法可以直出 DataFrame,唯一开关是构造参数 df,不要在调用处传 df=True(没有这个参数):

async with TdxData(df="polars") as td:      # 或 df="pandas"
    df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
事项 说明
安装 pip install "pytdxdata[polars]" / [pandas] / [dataframe];核心包仍零依赖
df=None(默认) 行为与 0.6.x 完全一致,返回 list[dataclass]
报错 df 取值非法 → ValueError;包没装 → FrameBackendError(启动即失败,不拖到第一次查询)
时间列 year/month/day/hour/minute 被 datetime 替换,另带 trading_date;XdxrRecord 给 date
嵌套 bid/ask 展开成 bid1_price…ask5_vol 共 10 列;fields 字典 JSON 化成字符串列;codes 保持列表
特殊容器 get_indicators → bars+指标合并;get_index_trade_stats(_multi) → minutes 展开 + index/date 列;get_kline_batch / get_minute_batch → 纵向拼接成一张表
不受影响 bytes / int / dict / 单对象 / tuple / list[float] 类返回原样(get_file、get_security_count、get_server_info、get_price_limits 等)
空结果 列名齐全的空表;dtype 只由后端推断

完整口径见 DataFrame 输出。

陷阱清单

坑 后果 正确做法
统一方法(get_quotes/get_bars…)传 (Market.SH, "600000") 元组或市场号 v0.6 起直接报错 用字符串 "sh600000"
旧别名(get_kline/get_transactions…)传 (market, code) 能跑,但发出 DeprecationWarning 迁移到统一方法 + 字符串
忘了 async with / start() 无连接池,运行时报错 一律 async with TdxData() as td:
KlinePeriod.DAY == 0 拿到的是 5 分钟线 DAY=4,对照枚举表
等在返回值上找 .to_dataframe() 不存在 pd.DataFrame([asdict(x) for x in bars])
把 close 当成分 数值差 100 倍 价格单位是元(float)
sh000001 当成平安银行 拿到的是上证指数 代码不唯一:sh000001=上证指数,sz000001=平安银行
用 get_block_info 又自己拆二进制 白写解析器 用 get_block_parsed,已经解析好了
循环里逐个 await get_bars 慢 用列表传多个标的,自动并发
港股/美股五档 bid/ask 没有(协议不支持) fields 字段位通道有 name 但无五档
美股分钟线用 datetime.date() 分组做日聚合 一个交易日被拆成两天(美股跨北京零点) 用 bar.trading_date;bar.datetime 是归一化后的北京时间
拿指数逐笔的 trade_count 当笔数 拿到的是「均价×1000」,数值荒谬 用 get_index_trade_stats(index) 由成分累加
拿 ETF/LOF 逐笔的 trade_count 当笔数 拿到的是「价格×1000」(sh510310 显示 3994 笔) 看 trade_count_available,或 symbols.has_order_count()
拿深市 399xxx 的 amount 校验成分合计 比值 0.43,误以为数据错 深市指数 amount 是全板块口径(sz399001=深市全部 5081 亿),不是样本股
在期货/期权 K 线上取 amount 恒 0.0,误以为解析坏了 EX 0x23FF 帧内没有成交额(协议限制);结算价看 bar.settle,成交额改用 get_quotes
用港股主板的 amount / vol 当均价 差 100 倍 港股主板/基金的 vol 单位是手(=100 股),要 amount/vol/100;港股创业板/美股才是股
依赖实时性做信号 数据是 15 分钟前的 换券商实时源
手动改包内 servers.json / 写死 IP 容器只读、升级被覆盖、快节点捞不回来 日常靠内置的当日测速缓存自动选路;要强制指定就用 PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS 环境变量

深入参考

数据来自通达信公开接口,仅供技术研究与教育用途,不构成投资建议。