Files
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

8.6 KiB
Raw Permalink Blame History

场景示例

每个片段都是完整可跑的。共同前提:

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

全市场日线批量落库

传多标的时,连接池会把不同股票分配到不同服务器——这正是它比逐个 await 快的原因。

async def dump_all_daily():
    async with TdxData(cache_dir=Path("./tdx_cache")) as td:
        infos = await td.get_universe("sz")                    # 缓存 1 天
        symbols = [i.symbol for i in infos]                    # ["sz000001", ...]

        bars = await td.get_bars(
            symbols,
            KlinePeriod.DAY,
            count=800,
            adjust=Adjust.QFQ,
            concurrency=12,
        )
        got = {b.symbol for b in bars}
        print(f"{len(got)} / {len(symbols)} 只拿到数据")

        # bars 是扁平 list[SecurityBar](按标的/时间排序),落库 / 写 parquet 都行
        if bars:
            print(bars[-1].symbol, bars[-1].datetime, bars[-1].close)

!!! tip "分页与并发的取舍" concurrency 不是越大越好。单台服务器有连接上限,concurrency 超过 pool_max × 服务器数 之后只会排队。实践值:8~16。

分钟线增量更新

只拉「上次之后」的部分,用 get_bars(start_date=...) 省掉全量重拉。

async def update_minute(symbol: str, last_dt):
    async with TdxData(cache_dir=Path("./tdx_cache")) as td:
        rows = await td.get_bars(symbol, KlinePeriod.MIN_1, start_date=last_dt)
        return [r for r in rows if r.datetime > last_dt]

!!! warning "1 分钟 K 线走 MAC 单连接串行分页" 这是刻意设计:并发分页会把不同页分到不同服务器,而各服务器历史深度不一致, 拼接后会出现非确定性数据空洞。所以 MIN_1 强制单连接串行(见 通道与数据源)。

报价轮询

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 分钟延时数据,别拿它做实时交易决策。

板块轮动 / 领涨股

async def sector_rotation():
    async with TdxData() as td:
        # 近 5 日概念板块涨幅排行
        top = await td.get_board_change_ranking(kind="concept", 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))

个股所属板块(反向查询)

async def belong(symbol: str):
    async with TdxData() as td:
        for b in await td.get_board_of(symbol):
            print(b)

逐笔复盘

async def review_transactions(symbol: str, ymd: int):
    async with TdxData() as td:
        rows = await td.get_ticks(symbol, 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}")

财务因子快照

async def finance_snapshot(symbols):
    async with TdxData() as td:
        for fin in await td.get_finance(symbols):   # 标准通道,最新快照
            print(fin.symbol, fin)

历史专业财报(gpcw*,含多报告期)走文件接口。

!!! warning "索引里的文件名与服务器实际不一致" tdxfin/gpcw.txt 索引里写的是 gpcwYYYYMMDD.zip,但服务器实际只提供未压缩的 tdxfin/gpcwYYYYMMDD.dat —— 这些差异已由 get_financial_records_parsed() 内部处理, 直接把索引里的 filename 传进去即可。

另外索引里**含有尚未生成的占位条目**(`filesize` 只有百来字节),取它们会得到空列表。
想拿最新一期可用数据,先按体积过滤:

```python
usable = [fi for fi in infos if fi.filesize > 500_000]   # 排除占位条目
records = await td.get_financial_records_parsed(usable[0].filename)
```
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])

行业分类映射

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)

板块成分(离线解析)

get_block_parsed 拿到的是纯 dataclass,落成本地 JSON 后完全脱网可用—— 适合做「板块成分快照」的定时任务。

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"
        )

港股 / 美股 / 期货 / 期权

async def ex_markets():
    async with TdxData() as td:
        hk = await td.get_bars("hk00700", KlinePeriod.DAY, count=700)
        us = await td.get_bars("usAAPL", KlinePeriod.DAY, count=700)
        fut = await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700)
        opt = await td.get_bars("sh_stock_option:10010971", KlinePeriod.DAY, count=700)
        print(len(hk), len(us), len(fut), len(opt))

        # 港股全量逐笔(自动翻页,≤50 页 / 9 万条)
        ticks = await td.get_ticks("hk00700", count=None)
        print(len(ticks))

转成 pandas

0.7.0 起不用自己转了 —— 构造时声明一次后端,表格型接口直接返回 DataFrame:

async with TdxData(df="pandas") as td:        # 或 df="polars"
    df = await td.get_bars("sh600000", KlinePeriod.DAY, count=800)
df = df.set_index("datetime")                  # 时间列已经合并好了

需要 pip install "pytdxdata[pandas]"(或 [polars] / [dataframe]),细节见 DataFrame 输出。

如果只想对某一处手动转、不想受影响全局,仍可用 dataclass 自己拼:

import pandas as pd

async def to_dataframe(symbol: str):
    async with TdxData() as td:
        bars = await td.get_bars(symbol, 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" 池与缓存都挂在实例上,每请求新建 = 每请求重建连接池 + 缓存全部失效。

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/{symbol}")
async def kline(symbol: str, request: Request):
    td = request.app.state.td
    bars = await td.get_bars(symbol, KlinePeriod.DAY, count=30)
    return [{"dt": str(b.datetime), "close": b.close} for b in bars]

下一步