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>
This commit is contained in:
1 parent
2cf3657f4b
commit
04e0c57569
24 files changed
+3022
-496
No files matched your search
+32
-8
@@ -1,6 +1,6 @@
|
||||
# pytdxdata 对外接口清单
|
||||
|
||||
> 以 `src/pytdxdata` 源码为准整理(v0.6.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
|
||||
> 以 `src/pytdxdata` 源码为准整理(v0.7.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
|
||||
>
|
||||
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
|
||||
|
||||
@@ -28,8 +28,9 @@ from pytdxdata import (
|
||||
| `cache_dir` | None | 磁盘缓存目录;None=仅内存缓存 |
|
||||
| `default_adjust` | `Adjust.NONE` | 默认复权方式 |
|
||||
| `max_inflight` | 64 | single-flight 并发上限 |
|
||||
| `pool_min` / `pool_max` | 3 / 12 | 动态池上下限 |
|
||||
| `mac_pool_cap` | 4 | 单台 MAC 服务器连接上限 |
|
||||
| `pool_min` / `pool_max` | 3 / 24 | 动态池上下限 |
|
||||
| `mac_pool_cap` / `std_pool_cap` / `ex_pool_cap` | 4 / 4 / 2 | 单台服务器连接上限 |
|
||||
| `df` | None | **DataFrame 后端**:`None`=返回 `list[dataclass]`(0.6.x 行为)、`"polars"`、`"pandas"`。需先装 extra:`pip install pytdxdata[polars]`,详见 [DataFrame 输出](dataframe.md) |
|
||||
|
||||
生命周期:
|
||||
|
||||
@@ -41,6 +42,10 @@ from pytdxdata import (
|
||||
|
||||
### 2.1 统一接口(v0.6+ 推荐){#unified}
|
||||
|
||||
> **DataFrame(v0.7+)**:本节的表格型方法在 `TdxData(df="polars")` / `df="pandas"` 时
|
||||
> 直接返回 DataFrame;`df=None`(默认)返回下表的 `list[...]`。列口径、时间列替换规则、
|
||||
> 不受影响的接口清单见 [DataFrame 输出](dataframe.md)。
|
||||
|
||||
以下方法在 v0.6 新增,标的一律用字符串(`sz000001` / `hk00700` / `usAAPL` / `cffex:IFL0`)。
|
||||
|
||||
#### 标的清单
|
||||
@@ -64,7 +69,7 @@ from pytdxdata import (
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_bars(symbols, period=DAY, *, start=0, count=800, adjust=None, start_date=None, end_date=None, concurrency=6)` | `list[SecurityBar]` | 跨市场 K 线(自动判指数、复权走 MAC、并发分页、日期区间二分) |
|
||||
| `get_bars(symbols, period=DAY, *, start=0, count=800, adjust=None, start_date=None, end_date=None, concurrency=6, pipeline=None)` | `list[SecurityBar]` | 跨市场 K 线(自动判指数、复权走 MAC、并发分页;日期区间贴最新走倒推、历史中段走二分)。**≥16 只自动走多连接流水线**:`pipeline` 为每条连接的在途请求数(默认按单请求字节自适应 8~32,传 `1` 关闭),全市场 1 分钟 K 线取当天 43.6s → 5s 级 |
|
||||
| `get_indicators(symbols, indicators, *, period=DAY, count=30, adjust=None, params=None)` | `list[IndicatorSet]` | K 线+技术指标(MACD/KDJ/RSI/BOLL/MA/EMA) |
|
||||
|
||||
#### 逐笔与分时
|
||||
@@ -91,7 +96,7 @@ from pytdxdata import (
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_kline(market, code, period, *, start=0, count=800, adjust=None, start_date=None, end_date=None)` | `list[SecurityBar]` | 主接口;count>页自动并发分页;复权走 MAC;支持日期区间(二分定位) |
|
||||
| `get_kline(market, code, period, *, start=0, count=800, adjust=None, start_date=None, end_date=None)` | `list[SecurityBar]` | 主接口;count>页自动并发分页;复权走 MAC;支持日期区间(贴最新倒推 / 中段二分) |
|
||||
| `get_kline_since(market, code, period, since, adjust=None)` | `list[SecurityBar]` | 增量便捷方法(≥since,含当天) |
|
||||
| `get_kline_batch(stocks, period, *, start=0, count=800, adjust=None, concurrency=6)` | `dict[str, list[SecurityBar]]` | 多股票并发,返回 {code: bars} |
|
||||
| `get_index_kline(market, code, period, *, start=0, count=800)` | `list[SecurityBar]` | 指数K线(含涨跌家数字段) |
|
||||
@@ -199,7 +204,7 @@ from pytdxdata import (
|
||||
|
||||
| 模型 | 关键字段 |
|
||||
|------|---------|
|
||||
| `SecurityBar` | market/code/open/high/low/close/vol/amount/year/month/day/hour/minute + `datetime` 属性 |
|
||||
| `SecurityBar` | market/code/open/high/low/close/vol/amount/year/month/day/hour/minute/symbol/**settle** + `datetime` 属性(`settle` 结算价仅 EX 期货/期权日线有值,其余为 `None`) |
|
||||
| `IndexBar` | 继承 `SecurityBar`(指数K线) |
|
||||
| `SecurityQuote` | price/pre_close/OHLC/vol/amount/s_vol/b_vol/`bid[5]`/`ask[5]`/server_time/trading_status/cur_vol/rise_speed/limit_up/limit_down/decimal_point/open_amount |
|
||||
| `SecurityInfo` | market/code/name/volunit/decimal_point/pre_close |
|
||||
@@ -232,8 +237,18 @@ from pytdxdata import (
|
||||
| 股票 / ETF / LOF | 手(= 100 股) | 股 | **0.01** | 均价 ✓ |
|
||||
| 可转债(110/111/113/118/123/127/128) | 手(= 10 张) | **手** | **1.0** | 均价 **×10** ⚠️ |
|
||||
| 指数 | 百元(成交额/100) | 手 | — | 无意义(`amount` 是全板块口径) |
|
||||
| 港股主板 31 / 港股基金 49 | — | **手(= 100 股)** | — | 均价 **×100** ⚠️ |
|
||||
| 港股创业板 48 / 新三板 44 / 美股 74 | — | 股 | — | 均价 ✓ |
|
||||
| 期货 / 期权(EX 全市场) | — | 手/张 | — | **`amount` 恒 0.0**(帧内无成交额,见下) |
|
||||
|
||||
算均价:股票 `amount / vol`;可转债 `amount / vol / 10`;跨品种统一用 `Σ(price×vol) / Σvol`。
|
||||
算均价:股票 `amount / vol`;可转债 `amount / vol / 10`;港股主板/基金 `amount / vol / 100`;跨品种统一用 `Σ(price×vol) / Σvol`。
|
||||
|
||||
> ⚠️ **EX 通道(0x23FF)的成交额不是全市场都有的**。一条记录 32B = 4B 时间 + 28B 行情,
|
||||
> 28B 里只有**一个** 4B 槽位可复用,语义按市场分两类:
|
||||
> 权益类(港股主板/创业板/基金、新三板、美股)该槽位是**成交额**,`amount` 正常;
|
||||
> 期货期权类该槽位是**结算价**(体现在 `SecurityBar.settle`,日线才有值),
|
||||
> `amount` 恒 **0.0** —— 这是协议限制,不是解析漏读,要成交额请改用 `get_quotes` 或其它源。
|
||||
> 港股指数(27)/ 中证指数(62)该槽位语义未明,同样保守返回 `0.0`。
|
||||
|
||||
> 可转债的价格标度、分时、逐笔已全量校验(16 只当日 + 8 只历史日):分时末价 / 快照现价、`Σvol / 日线vol`、逐笔 VWAP vs `amount/(vol×10)` 比值均为 **1.000000**。
|
||||
|
||||
@@ -320,4 +335,13 @@ CLI 开关:`--discover`(三种协议全测并据实修正 `protocols`,同
|
||||
| 逐笔成交 / 分时 | MAC |
|
||||
| 列表 / 数量 / 除权 / 财务 | 标准 |
|
||||
| 板块 / 竞价 / 异动 / 快照 / 资金流 / 服务器 / 分类报价 | MAC |
|
||||
| 港股 / 美股 / 期货 / 期权 | EX(端口 7727) |
|
||||
| 港股 / 美股 / 期货 / 期权 | EX(端口 7727,`0x23FF`) |
|
||||
|
||||
> EX 通道的 K 线(`0x23FF`)字段口径与 A 股不同,见「量纲对照」下的注:
|
||||
> 权益类市场(港股/美股/新三板)有 `amount`;期货期权有 `settle`(结算价)但**没有** `amount`。
|
||||
|
||||
**多标的 K 线(`get_bars` 传 ≥16 只)额外走「批量流水线」**:按上表选池后,
|
||||
多条连接并行、每条连接一次下发 `pipeline` 条请求(默认自适应 8~32),把 N 次往返
|
||||
折叠成 `N/pipeline` 次。只用实测最快的 12 台服务器(池里 24 台全用会被慢节点拖长尾)。
|
||||
`start_date=今天` 时只拉已走过的根数(10:00 → 30 根),盘中实时刷新因此只要 1~2 秒。
|
||||
流水线失败时该批自动交回逐只重试,不会丢数据。
|
||||
+1
-1
@@ -26,7 +26,7 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md \
|
||||
## 里面有什么
|
||||
|
||||
- **三条必守约定** —— 唯一入口是 `TdxData` 且必须 `async with`;标的是字符串(如 `sh600000`)
|
||||
而不是 `(market, code)` 元组;返回值是 `list[dataclass]` 而不是 DataFrame
|
||||
而不是 `(market, code)` 元组;默认返回 `list[dataclass]`(要 DataFrame 得用 `TdxData(df="polars")` 显式声明后端)
|
||||
- **枚举取值表** —— `Market` / `KlinePeriod` / `Adjust` / `ExMarket` 的准确取值
|
||||
- **可运行模板** —— K 线、复权、报价、逐笔、分时、批量,全部是能直接跑的代码
|
||||
- **「想做什么 → 用哪个方法」决策表** —— 18 个常见需求的直接映射
|
||||
|
||||
+10
-2
@@ -2,8 +2,16 @@
|
||||
|
||||
全部数据模型位于 `pytdxdata.models`,统一为 `@dataclass(slots=True)`。
|
||||
|
||||
选择 dataclass 而不是 pandas DataFrame 是刻意的:**零依赖 + 零转换开销**,
|
||||
需要 DataFrame 时你自己转(一行的事,见 [场景示例 → 转成 pandas](../cookbook.md#to-pandas))。
|
||||
默认(`df=None`)所有接口返回这些 dataclass —— **零依赖 + 零转换开销**。
|
||||
不想要 dataclass 就直接开 DataFrame 出口,不用自己 `asdict` 再建表:
|
||||
|
||||
```python
|
||||
async with TdxData(df="polars") as td: # 或 df="pandas"
|
||||
df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
|
||||
```
|
||||
|
||||
列口径(时间列合并、五档展开、`fields` JSON 化)见 [DataFrame 输出](../dataframe.md);
|
||||
两者是同一份数据,只是容器不同,**量纲与语义完全一致**。
|
||||
|
||||
## 导入方式
|
||||
|
||||
|
||||
+12
-1
@@ -196,7 +196,18 @@ async def ex_markets():
|
||||
|
||||
## 转成 pandas {#to-pandas}
|
||||
|
||||
包本身不带 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
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
# 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)。
|
||||
|
||||
## 性能
|
||||
|
||||
转换是**列式采集**:按模型预先算好列计划,一次遍历填满所有列,不做逐行 `asdict()`。
|
||||
5,227 只 A 股报价转 polars 约 20~40ms,相对一次全市场查询(约 300ms)可以忽略。
|
||||
|
||||
`df=None` 时**完全不经过这层**(装饰器直接透传),零额外开销。
|
||||
+21
-1
@@ -35,6 +35,23 @@
|
||||
|
||||
安装后即可使用 `tdx` 命令行工具(见 [CLI 手册](cli.md))。
|
||||
|
||||
### 可选:DataFrame 后端(0.7.0+)
|
||||
|
||||
想让表格型接口**直接返回 DataFrame**,需要额外装一个后端。核心包依旧零依赖,不装就完全不受影响:
|
||||
|
||||
```bash
|
||||
pip install "pytdxdata[polars]" # 只要 polars
|
||||
pip install "pytdxdata[pandas]" # 只要 pandas
|
||||
pip install "pytdxdata[dataframe]" # 两个都要
|
||||
```
|
||||
|
||||
装上之后在构造时声明一次即可,详见 [DataFrame 输出](dataframe.md):
|
||||
|
||||
```python
|
||||
async with TdxData(df="polars") as td: # 或 df="pandas"
|
||||
df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
|
||||
```
|
||||
|
||||
### 可选:uvloop 加速
|
||||
|
||||
Linux / macOS 上可选用 `uvloop` 替换默认事件循环(Windows 不支持):
|
||||
@@ -63,8 +80,11 @@ asyncio.run(main())
|
||||
| `cache_dir` | `None` | 磁盘缓存目录;**`None` = 仅内存缓存**(进程退出即失效) |
|
||||
| `default_adjust` | `Adjust.NONE` | 默认复权方式,可被单次调用覆盖 |
|
||||
| `max_inflight` | `64` | single-flight 并发上限(同键请求合并) |
|
||||
| `pool_min` / `pool_max` | `3` / `12` | 动态连接池上下限 |
|
||||
| `pool_min` / `pool_max` | `3` / `24` | 动态连接池上下限 |
|
||||
| `mac_pool_cap` | `4` | 单台 MAC 服务器连接数上限 |
|
||||
| `std_pool_cap` | `4` | 单台标准服务器连接数上限 |
|
||||
| `ex_pool_cap` | `2` | 单台 EX 服务器连接数上限(EX 主机较少且较慢,压太高收益为负) |
|
||||
| `df` | `None` | 表格型接口的返回形态:`None` = `list[dataclass]`(与 0.6.x 一致);`"polars"` / `"pandas"` = 直接返回 DataFrame。见 [DataFrame 输出](dataframe.md) |
|
||||
|
||||
### 典型配置
|
||||
|
||||
|
||||
+13
-3
@@ -35,8 +35,9 @@ asyncio.run(main())
|
||||
| ⚡ **并发分页** | 把大请求拆成显式 `start` 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 |
|
||||
| 🔀 **双通道整合** | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 |
|
||||
| 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制;文件名与索引不一致时自动纠正 |
|
||||
| 🚀 **批量下载** | `get_bars` / `get_minutes` 传标的列表即多股票并发,连接池自动分配到不同服务器 |
|
||||
| 📦 **零重型依赖** | 返回 `list[dataclass]`,pandas / polars 由调用方按需转换 |
|
||||
| 🚀 **批量下载** | `get_bars` / `get_minutes` 传标的列表即多股票并发,连接池自动分配到不同服务器;K 线走「多连接 × 单连接流水线」,全市场 5,225 只 1 分钟线取当天 **5~8 秒**(盘中增量 1~2 秒) |
|
||||
| 🐼 **DataFrame 直出** | `TdxData(df="polars")` / `df="pandas"` 让 42 个表格型接口直接返回 DataFrame;时间列自动合并成 `datetime`,五档报价自动展开。后端是可选 extras,**核心包仍零依赖** |
|
||||
| 📦 **零重型依赖** | 默认返回 `list[dataclass]`,行为与 0.6.x 完全一致,转不转 DataFrame 由你决定 |
|
||||
|
||||
## 从这里开始
|
||||
|
||||
@@ -66,11 +67,19 @@ asyncio.run(main())
|
||||
|
||||
[:octicons-arrow-right-24: Cookbook](cookbook.md)
|
||||
|
||||
- **直接要 DataFrame**
|
||||
|
||||
---
|
||||
|
||||
`TdxData(df="polars")` 一行开关,42 个表格型接口直接出表,不用自己 `asdict`。
|
||||
|
||||
[:octicons-arrow-right-24: DataFrame 输出](dataframe.md)
|
||||
|
||||
- **查接口签名**
|
||||
|
||||
---
|
||||
|
||||
28 个统一方法(+ 33 个 deprecated 别名),从 docstring 实时生成,不会过期。
|
||||
35 个统一方法(+ 33 个 deprecated 别名),从 docstring 实时生成,不会过期。
|
||||
|
||||
[:octicons-arrow-right-24: API 参考](api/index.md)
|
||||
|
||||
@@ -122,6 +131,7 @@ asyncio.run(main())
|
||||
- [安装与配置](getting-started.md)
|
||||
- [场景示例](cookbook.md)
|
||||
- [命令行工具](cli.md)
|
||||
- [DataFrame 输出](dataframe.md)
|
||||
|
||||
- **参考**
|
||||
- [接口总览](api/index.md)
|
||||
|
||||
+25
-1
@@ -45,7 +45,13 @@ asyncio.run(main())
|
||||
标的一律用字符串;以下均为 v0.6 统一接口,跨市场自动选路。
|
||||
|
||||
- **标的清单**:`get_universe`(A股 + 港股 + 美股 + 期货/期权)。⚠️ 北交所(`market="bj"`)清单**协议不支持**,返回空列表(`0x053E` 对 market=2 无响应,27 台服务器全测);但北交所**标的本身可用** —— 报价/K线/逐笔直接传 `bj920992` 这类代码正常
|
||||
- **K 线**:`get_bars`(自动并发分页、支持复权与日期区间、多标的并发)
|
||||
- **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` 决定,
|
||||
@@ -63,6 +69,24 @@ asyncio.run(main())
|
||||
> 旧的分通道/市场方法(`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 只由后端推断。
|
||||
|
||||
## 服务器与配置
|
||||
|
||||
服务器主机来源有一条优先级链(各协议独立):环境变量 → **当日测速缓存** → 包内清单
|
||||
|
||||
Reference in new issue
Block a user