* 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>
156 lines
6.4 KiB
Markdown
156 lines
6.4 KiB
Markdown
# pytdxdata
|
||
|
||
[](https://github.com/openbot-coder/pytdxdata/actions/workflows/ci.yml)
|
||
[](https://pypi.org/project/pytdxdata/)
|
||
[](https://pypi.org/project/pytdxdata/)
|
||
[](https://github.com/openbot-coder/pytdxdata/blob/main/LICENSE)
|
||
|
||
通达信(TongDaXin)行情数据客户端:**动态连接池 + 双层 TTL 缓存 + 3 连接并发分页**。
|
||
|
||
纯 `asyncio` 实现,**零运行时依赖**(只用 stdlib);**A股(沪/深/北) + 港股 + 美股 + 期货 + 期权**,一套接口全市场。
|
||
|
||
```bash
|
||
pip install pytdxdata
|
||
```
|
||
|
||
```python
|
||
import asyncio
|
||
from pytdxdata import TdxData
|
||
from pytdxdata.models import KlinePeriod
|
||
|
||
async def main():
|
||
async with TdxData() as td: # 自动探测服务器 + 建池 + 建缓存
|
||
bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=2400)
|
||
print(bars[-1].datetime, bars[-1].close)
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
## 特性
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| 🧩 **动态连接池** | 启动时对服务器真实 K 线探测选优(剔除握手正常但返回空数据的坏节点);健康分(失败 ×0.5 / 成功 +0.2 / 冷却 120s)+ EWMA 延迟选路;按等待队列与空闲时长动态扩缩容;跨服务器故障转移 |
|
||
| 🗄️ **双层 TTL 缓存** | 内存 LRU + 磁盘 SQLite(WAL);TTL 分级:报价 5s / 分钟K线 60s / 日线当天 / 复权K线 1天 / 历史逐笔永久;`single-flight` 同键并发去重;缓存「已解析记录」,重复请求 0 网络 0 解析 |
|
||
| ⚡ **并发分页** | 把大请求拆成显式 `start` 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 |
|
||
| 🔀 **双通道整合** | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 |
|
||
| 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制;文件名与索引不一致时自动纠正 |
|
||
| 🚀 **批量下载** | `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 由你决定 |
|
||
|
||
## 从这里开始
|
||
|
||
<div class="grid cards" markdown>
|
||
|
||
- **装好并跑通**
|
||
|
||
---
|
||
|
||
安装、构造参数、缓存目录、第一个脚本。
|
||
|
||
[:octicons-arrow-right-24: 安装与配置](getting-started.md)
|
||
|
||
- **命令行直接拿数据**
|
||
|
||
---
|
||
|
||
19 个子命令,不写代码也能拉行情、板块、财报。
|
||
|
||
[:octicons-arrow-right-24: CLI 手册](cli.md)
|
||
|
||
- **场景示例**
|
||
|
||
---
|
||
|
||
全市场批量落库、分钟线增量、报价轮询、板块轮动、逐笔复盘。
|
||
|
||
[:octicons-arrow-right-24: Cookbook](cookbook.md)
|
||
|
||
- **直接要 DataFrame**
|
||
|
||
---
|
||
|
||
`TdxData(df="polars")` 一行开关,42 个表格型接口直接出表,不用自己 `asdict`。
|
||
|
||
[:octicons-arrow-right-24: DataFrame 输出](dataframe.md)
|
||
|
||
- **查接口签名**
|
||
|
||
---
|
||
|
||
35 个统一方法(+ 33 个 deprecated 别名),从 docstring 实时生成,不会过期。
|
||
|
||
[:octicons-arrow-right-24: API 参考](api/index.md)
|
||
|
||
- **让 AI 助手写对代码**
|
||
|
||
---
|
||
|
||
枚举取值反直觉,AI 凭常识几乎必错。装载 `SKILL.md` 就能一次写对。
|
||
|
||
[:octicons-arrow-right-24: AI 助手接入](ai.md)
|
||
|
||
</div>
|
||
|
||
## 设计取舍
|
||
|
||
参照 [easy-tdx](https://github.com/handsomejustin/easy_tdx) 重新实现,解决其三大短板(无连接池、串行分页、单连接单锁)。
|
||
协议层**独立实现**——不依赖 easy-tdx 包,仅参照其字节级格式。
|
||
|
||
| 维度 | easy-tdx | pytdxdata |
|
||
|------|----------|-----------|
|
||
| 并发分页 | ❌ 串行 while 循环 | ✅ 3 连接并行 |
|
||
| 连接池 | ❌ 单连接单锁 | ✅ 动态池 + 故障转移 |
|
||
| 缓存 | 仅证券列表(1天) | ✅ 双层 TTL + single-flight |
|
||
| 数据正确性 | 基准 | ✅ K线 6 字段 / 报价 7 字段逐字段一致(实测) |
|
||
| 2400 根日K耗时 | 0.31s | **0.16s(1.97x)** |
|
||
| 缓存命中重取 | — | 0.016s(0 网络) |
|
||
| 依赖 | pandas 等 | 零运行时依赖 |
|
||
|
||
> 实测环境:Windows 11 / Python 3.13 / 同一批通达信服务器(2026-08)。
|
||
|
||
## 数据来源与限制
|
||
|
||
- 行情来自通达信**公开**行情服务器(无需账号),**15 分钟延时**;需实时数据请使用券商行情
|
||
- 服务器清单由 `python -m pytdxdata.server_probe` 探测生成;运行时**当日首次启动会自动在后台测速并缓存**
|
||
(对调用方无感,当天不再重测),可用性随时间变化
|
||
- 港股 / 美股 / 期货 / 期权走通达信 EX 通道(端口 7727),部分市场(美股期权、港股期权)协议内无数据
|
||
|
||
完整清单见 [常见问题](faq.md)。
|
||
|
||
!!! warning "免责声明"
|
||
本包仅用于**技术研究与教育目的**。行情数据来自通达信公开接口,不保证实时性与准确性;
|
||
作者不对任何投资决策负责。使用前请遵守通达信服务条款及相关法律法规。
|
||
|
||
## 目录
|
||
|
||
<div class="grid cards" markdown>
|
||
|
||
- **快速开始**
|
||
- [安装与配置](getting-started.md)
|
||
- [场景示例](cookbook.md)
|
||
- [命令行工具](cli.md)
|
||
- [DataFrame 输出](dataframe.md)
|
||
|
||
- **参考**
|
||
- [接口总览](api/index.md)
|
||
- [枚举速查](api/enums.md)
|
||
- [数据模型](api/models.md)
|
||
- [完整接口清单](API_REFERENCE.md)
|
||
|
||
- **深入原理**
|
||
- [架构总览](internals/architecture.md)
|
||
- [协议与命令](internals/protocol.md)
|
||
- [通道与数据源](internals/routing.md)
|
||
- [连接池与缓存](internals/cache-pool.md)
|
||
|
||
- **其他**
|
||
- [AI 助手接入](ai.md)
|
||
- [常见问题](faq.md)
|
||
- [更新日志](changelog.md)
|
||
- [接口重构审查](refactor-audit.md)
|
||
- [参与贡献](contributing.md)
|
||
|
||
</div>
|