Files
pytdxdata/docs/cookbook.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

254 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 场景示例
每个片段都是完整可跑的。共同前提:
```python
import asyncio
from pathlib import Path
from pytdxdata import TdxData
from pytdxdata.models import Adjust, KlinePeriod
```
## 全市场日线批量落库
传多标的时,连接池会把不同股票分配到不同服务器——这正是它比逐个 `await` 快的原因。
```python
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=...)` 省掉全量重拉。
```python
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` 强制单连接串行(见 [通道与数据源](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(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))
```
## 个股所属板块(反向查询)
```python
async def belong(symbol: str):
async with TdxData() as td:
for b in await td.get_board_of(symbol):
print(b)
```
## 逐笔复盘
```python
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}")
```
## 财务因子快照
```python
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)
```
```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_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 {#to-pandas}
**0.7.0 起不用自己转了** —— 构造时声明一次后端,表格型接口直接返回 DataFrame:
```python
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 输出](dataframe.md)。
如果只想对**某一处**手动转、不想受影响全局,仍可用 dataclass 自己拼:
```python
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"
池与缓存都挂在实例上,每请求新建 = 每请求重建连接池 + 缓存全部失效。
```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/{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]
```
## 下一步
- [接口总览](api/index.md) — 全部方法
- [连接池与缓存](internals/cache-pool.md) — 调优 `pool_min` / `pool_max` / TTL