Files
pytdxdata/docs/dataframe.md
T
openbotandopenbot-coder 8c25feca18 perf(frames): DataFrame 转换提速近一倍(24万行 K 线 894ms → 462ms) (#13)
- 普通列改 list(map(attrgetter(name), rows)):取值在 C 层,不再每格建 Python 帧
- trading_date 按时间字段缓存(24万行常只有 1~2 个键):218ms → 33ms
- IntEnum 归一化从每格判断改为按列判断、需要时才整列转
- 补 3 项逐字段等价测试(多市场多时段 trading_date、分时 day_offset、全列比对)
- docs/dataframe.md 性能一节改为实测数据 + 何时该用 DataFrame 出口

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-29 18:33:07 +08:00

143 lines
7.4 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.
# DataFrame 输出(pandas / polars)
0.7.0 起,`TdxData` 可以**直接把表格型接口的返回值变成 DataFrame**,不用再自己 `[asdict(x) for x in rows]`。
设计上只有一条开关,就是构造参数 `df`:
```python
from pytdxdata import TdxData, KlinePeriod
# 默认:df=None,行为和 0.6.x 完全一致,返回 list[dataclass]
async with TdxData() as td:
bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=240) # list[SecurityBar]
# 要 DataFrame 就在构造时声明一次后端
async with TdxData(df="polars") as td:
df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240) # polars.DataFrame
async with TdxData(df="pandas") as td:
df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240) # pandas.DataFrame
```
## 安装
pandas / polars 都是**可选依赖**——`pytdxdata` 的 `dependencies` 仍然是空的,不想用 DataFrame 的人一点额外开销都不用付。
```bash
pip install "pytdxdata[polars]" # 只要 polars
pip install "pytdxdata[pandas]" # 只要 pandas
pip install "pytdxdata[dataframe]" # 两个都要
```
没装就 `TdxData(df="polars")`,会在**构造时**直接报错,而不是等到第一次查询:
```
FrameBackendError: 未安装 polars,无法输出 DataFrame。请执行:pip install pytdxdata[polars]
```
`df` 取值非法(比如 `df="numpy"`)抛 `ValueError`,并列出可用值。
## 三个口径约定
### 1. 时间列:`datetime` 替换拆开的年月日时分
原始模型为了解析性能把时间拆成 `year/month/day/hour/minute`。DataFrame 里再这么摆,用的人第一件事就是自己拼时间戳——所以直接给一列 `datetime`:
| 模型 | 原始字段 | DataFrame 里的列 |
|---|---|---|
| `SecurityBar` / `IndexBar` | `year month day hour minute` | `datetime`(+ `trading_date`) |
| `MinuteBar` | `date hour minute day_offset` | `datetime`(+ `trading_date`) |
| `XdxrRecord` | `year month day` | `date` |
- `datetime` 的 dtype:polars 是 `Datetime('us')`,pandas 是 `datetime64[ns]`。
- `trading_date` 是 `YYYY-MM-DD` 字符串,**按交易日聚合要用它**:美股一个交易日横跨两个北京自然日(21:30→次日 04:00),凌晨段的 `datetime` 属于次日,但 `trading_date` 归属前一交易日。
- 除权记录的 `date` 是「日」不是「时刻」,值为当日 00:00,仍用 datetime 类型以便排序比较。
- `TransactionRecord.time` 只有 `HH:MM:SS`、**协议里没有日期**,所以逐笔不生成 `datetime`,`time` 原样保留。
### 2. 嵌套字段:能定型的定型,不能定型的 JSON 化
| 字段 | DataFrame 里的形态 |
|---|---|
| `SecurityQuote.bid` / `ask`(五档) | 展开成 `bid1_price` `bid1_vol` … `ask5_price` `ask5_vol` 共 **10 列**,缺档为 `None` |
| `fields`(A股字段位 / EX 额外字段) | **JSON 字符串**列;空字典给 `None`(不会看到一列 `"{}"`) |
| `TdxBlock.codes`(成分股列表) | 保持列表(polars 为 `List(Str)`,pandas 为 object),需要时 `.explode()` |
`fields` 之所以不展开:键集随市场和通道变化,展开会让列数失控。
### 3. 特殊容器会被展开成一张表
| 接口 | 原始返回 | DataFrame 形态 |
|---|---|---|
| `get_indicators` | `list[IndicatorSet]` | bars 列 + 每个指标一列,按长度对齐(不足补 `None`),`symbol` 取自 `IndicatorSet.symbol` |
| `get_index_trade_stats` | `IndexTradeStats` | `minutes` 展开成行,并补 `index` / `date` 两个常量列 |
| `get_index_trade_stats_multi` | `list[IndexTradeStats]` | 同上,多个指数纵向拼接 |
| `get_kline_batch` / `get_minute_batch` | `dict[标的, list[...]]` | 各标的分块纵向拼接成一张表(`symbol`/`code` 列本来就在行里) |
| `get_board_ranking` / `get_board_change_ranking` | `list[dict]` | 按首次出现顺序取键并集作为列名 |
## 哪些接口不受影响
`df` 只作用于**表格型返回**。下面这些原样返回,不转 DataFrame:
| 返回类型 | 接口 |
|---|---|
| `bytes` | `get_file` `get_block_info` `get_report_file` `download_file` `get_financial_records` |
| `int` | `get_security_count` `get_goods_count` |
| `dict` | `decimal_point_status` `get_board_summary` `get_industry_map` |
| 单个对象 | `get_server_info` `get_market_stat` `get_symbol_info` |
| `tuple` | `get_price_limits` `get_kline_offset` |
| `list[float]` / `list[str]` | `get_chart_sampling` `get_goods_chart_sampling` `get_financial_file_list` |
理由是单行表没有意义,而 `bytes`/`int` 根本不是表格数据。
## 空结果
查不到数据时返回的是**列名齐全的空 DataFrame**(列由模型定义推出,不依赖是否拿到行):
```python
async with TdxData(df="polars") as td:
df = await td.get_xdxr("sz000001") # 假设当天无除权
df.height, df.columns # 0, ['market', 'code', 'date', ...]
```
⚠️ 空表只保证**列名**正确,dtype 由后端自行推断(polars 可能全为 `Null`,pandas 为 object)。
## 语义提醒
DataFrame 只是换了个容器,**下面这些口径不会因为转成 DataFrame 而变化**:
- 股票/ETF 的 `vol` 是「手」,日线是「股」;可转债 `vol` 手=10 张,`amount/vol` 是均价 **×10**;指数逐笔 `vol` 是百元。
- 指数和 ETF/LOF 的 `trade_count` 不是笔数(见 `TransactionRecord.trade_count_available`)。
- 深市 `399xxx` 的 `amount` 是全板块口径,不要拿去校验成分合计。
- K 线的 `settle`(结算价)列只有 **EX 通道的期货/期权日线**有值,其余行全为 `None`;
同一批 EX 标的中,期货/期权的 `amount` 恒 `0.0`(`0x23FF` 帧内没有成交额),
港股主板/基金的 `vol` 单位是「手」(`amount/vol` 是均价的 100 倍)。
细节见 [数据模型](api/models.md) 与 [常见问题](faq.md)。
## 性能
先说结论:**`df=` 只影响出参那一层,取数、连接池、缓存完全不变**,但转换本身不是免费的——
结果集越大越明显。实测(缓存已热、同一台机器、Windows / Python 3.13):
| 场景 | `df=None` | `df="polars"` | `df="pandas"` |
|---|---|---|---|
| 全市场报价 5,225 只 | 66 ms | 117 ms(+51) | 124 ms(+58) |
| 1,000 只 × 240 根 1 分钟(24 万行) | 1,386 ms | 1,768 ms(+383) | 1,976 ms(+590) |
| 单只 × 240 根 1 分钟 | 1 ms | 2 ms | 2 ms |
只看转换层本身(不碰网络):5,225 行报价 → polars **51 ms** / pandas **62 ms**;
24 万行 K 线 → polars **444 ms** / pandas **585 ms**。
几个要点:
- **小结果无感**:单只 K 线、单只报价这类常见调用只多 1 ms 左右。
- **大结果按行数线性增长**:每行约 2~3 µs(12 列)。全市场 1 分钟线(约 125 万行)
转换约 2.3 s(polars)/ 3.1 s(pandas)——如果你的链路是「全市场分钟线直落库」,
这笔开销通常远小于下游写入,但如果只是做筛选/聚合,建议先拿 `df=None` 的 list 算完再转。
- **polars 比 pandas 快 25~30%**(同数据、同机器),大结果更明显。
- **转换是列式采集**:列计划按模型缓存(含交易日列的按时间字段缓存),
普通列走 C 层取值,不做逐行 `asdict()`。
- **`df=None` 时完全不经过这一层**:装饰器直接透传,零额外开销。
- **缓存命中也要转**:磁盘/内存缓存里存的是 dataclass 记录,DataFrame 是每次调用现建的
——高频轮询同一批数据时,这笔转换开销每次都会付。