8 Commits
Author SHA1 Message Date
openbotandopenbot-coder c9722943e2 chore(release): 0.7.1 (#14)
Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-29 18:38:54 +08:00
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
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
openbotandopenbot-coder 2cf3657f4b fix: get_universe 请求多发 2 字节污染连接(冷启动 12~18s → 1.6s) (#11)
## 根因

GetSecurityListCmd 请求体应为「12 字节命令头 + market(H) + start(H)」= 16 字节,
实现里多塞了一个 H(写死 0),实际发 18 字节。服务端只消费前 16 字节,剩下的
00 00 停在它接收缓冲里,把下一个请求的开头吃掉 —— 同一连接「第一次成功、
第二次起永远无响应」。

对照实验(同一主机、同一命令):
- 18 字节:第 1 次 OK,第 2/3 次全部 ConnectionError
- 16 字节:连发 3 次全部 OK(27 台主机复测,第二次请求 27/27 成功,此前 0/27)

分页器复用连接,等于每页都要先失败重连,冷启动被拖到 12~18s 且常直接报错。

| 场景 | 前 | 后 |
|---|---|---|
| get_universe("sh") 冷(27,534 条/28 页) | 12,267ms | 1,610ms |
| get_universe("sz") 冷(24,460 条/25 页) | 18,260ms | 571ms |
| get_universe() 全市场冷(146,848 条) | 19,085ms | 4,371ms |
| get_universe() 热 | — | 669ms |

## 北交所清单优雅降级

0x053E 对 market=2 在 27 台标准主机上全部无响应(26 台 6s 无回包、1 台立刻拒连),
同市场 0x053D 数量接口正常(389)。原实现重试 2 次×3s 后抛错,连带
get_universe() 整批失败。现直接返回空列表 + WARNING 一次。

北交所标的本身没问题:get_quotes("bj920992")/get_bars/逐笔全正常
(实测 11.79 与日线 close 一致)。

## 优化

- get_universe() 的 EX 全量只取一次(命中缓存也要反序列化 10 万条 ~200ms,
  原先十几个 EX 市场各来一次)
- EX 商品列表改并发翻页(110 页,8 并发)

## 文档 / 测试

- get_universe docstring、API_REFERENCE、llms.txt、SKILL.md 写明北交所限制
- 新增 tests/test_universe.py 7 项:请求长度锁 16 字节、无尾部 padding、
  北交所返回空且不碰连接池、_ex_all 只取一次

## 已知限制(非本次引入)

EX 全量含非证券条目(人员名录),(market, code) 原始数据里就不唯一,
重复出现在同一页内部;属数据源特性,未去重。

版本 0.6.8 → 0.6.9;测试 354 → 361 全通过。

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-23 15:24:17 +08:00
openbotandopenbot-coder dc78d81be8 fix(cli): 价格按品种小数位显示 + 分时时间列改真实时钟 (0.6.8) (#10)
* fix(cli): price decimals per instrument + minute time column

1) 价格按品种小数位显示:可转债 128.892 原被 %8.2f 截成 128.89;
   新增 _price_fmt/_display_dp,宽度随小数位走(%8.2f -> %9.3f)不破坏对齐。
   可转债(沪 110/111/113/118、深 123/127/128)解码是 4 位但报价步长 0.001,
   显示降到 3 位;ETF 3 位、国债/回购 4 位、股票/指数 2 位沿用 price_decimal_digits。
2) tdx minute 时间列原按序号推算(i//60, i%60)打印成 00:00~03:59,
   改用 MinuteBar.hour/minute。
3) cmd_transactions/cmd_minute 改调 get_ticks/get_minutes,消掉 DeprecationWarning。
新增 tests/test_cli_format.py(8 项);全量 354 passed。

* chore: release 0.6.8(CLI 价格小数位 + 分时时间列修复)

- 版本号 0.6.7 -> 0.6.8(pyproject / __init__.py / uv.lock / CHANGELOG 四处对齐)
- CHANGELOG:`[未发布]` -> `[0.6.8] - 2026-10-23`
- docs/cli.md:补「价格小数位按品种适配」对照表 + `tdx minute` 时间列说明

功能改动见 cd8227f(CLI 价格按品种小数位显示、分时时间列改真实时钟、
cmd_transactions/cmd_minute 改调 get_ticks/get_minutes 消 DeprecationWarning)。

实测 `tdx minute sh113708` -> 时间 09:30 起、价格 127.631(3 位);
`tdx transactions sh113708` -> 11:29:47 / 127.141 / 44 手 / 买(4笔)。

测试 354 全通过(310 + 16 + 23 + 5)。

---------

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-23 12:18:23 +08:00
openbotandopenbot-coder 8a78156145 perf: 全市场报价改单连接流水线(3.5s → 0.33s)+ 修复基金笔数口径 (#9)
## 性能:get_quotes 全市场 5,227 只 A股 3.5s → 0.33s

协议硬上限 80 只/请求 → 必须切 66 片;老实现是纯串行 for 循环,
每片一次往返(≈60ms),3.5s 全花在等网络上。

发现通达信响应是自描述长度帧且服务器按序应答,因此同一连接可连发
多条请求只付一次往返:实测单连接流水 66 请求 526ms(串行 7,372ms)。

- TdxConnection.execute_pipeline(cmds):一次下发全部 → 按序读回;中途失败强制断连
- _quotes_std 改工作窃取调度(快台多干,避免被最慢节点拖累)
- DynamicPool.warm(n):并发预建连接(acquire 在全局锁内一次一条,22 并发首拉会多花 5~6s)
- CacheManager.get_or_fetch_obj:回源直接返回对象,省掉冷路径 pickle→unpickle 白烧
- pool_max 默认 12 → 24

调优实测 p50/max:每台 1 连接×深度 6 = 455ms;每台 2 连接×深度 3 = 325ms。
端到端(全默认):首次 783ms、稳态 300~343ms、热缓存 67ms。
正确性:用昨收价交叉比对 30 只零错配,流水线与逐片结果集合完全一致。

## 修复:指数 / ETF / LOF 的 trade_count 不再伪装成笔数

通达信对指数和多数场内基金不提供笔数,那 4 字节里塞的是「价格 × 1000」
(指数是「均价 × 1000」)。旧版直接当笔数用,tdx transactions sh510310
会打印出「3994 笔」这种假数据。

- 新增 TransactionRecord.trade_count_available
- 新增 symbols.has_order_count(market, code) 按品种判定
  (沪市 501x/502x/506x 实测有真实笔数,不能按「5 开头=基金」一刀切)
- 历史通道 0x013001 无笔数字段,同样标记不可用

## 文档:可转债量纲口径

核查可转债分时/逐笔后确认数据本身无缺陷(16 只当日 + 8 只历史日,
分时末价/现价、Σvol/日线vol、逐笔 VWAP 比值均 1.000000),
但 vol 单位是「手」(=10 张)导致 amount/vol 是均价的 10 倍,对外文档缺失。

- SecurityBar / TransactionRecord / MinuteBar 量纲注释补全
- has_order_count 实测表补沪可转债 110/111/113/118、沪 EB 132、深可转债 123/127/128
- API_REFERENCE 新增跨品种量纲对照表;llms.txt / SKILL.md 同步

## 版本

0.6.7

## 测试

306 → 346 全通过(新增 tests/test_pipeline.py 11 项 + 基金笔数相关回归)

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-22 19:41:55 +08:00
openbotandopenbot-coder 2c07400a3a docs: 修正 0.6.6 发布说明里的前缀数(129 -> 179) (#8)
Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-22 16:37:19 +08:00
openbotandopenbot-coder 76644919de feat: 价格小数位改用协议权威值(SecurityInfo.decimal_point) (#7)
0.6.5 用「代码前缀推断 + 全量清单离线校验」修好了债券/回购标度,但同一份证券
清单接口本来就返回 decimal_point,权威值一直没接进取数路径。本次接进来:

- price_decimal_digits:查找顺序改为 权威表 -> 静态前缀规则(兜底)
- decimal_sync(新模块):每日后台同步一次 + 磁盘缓存 + 原子写
- TdxData.sync_decimal_points() / decimal_point_status()
- start() 不阻塞:当日缓存命中直接装表(60ms 零网络),否则挂后台 task
- PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1 关闭

表按三位前缀归并(全量 5 万只 -> 129 条);若某前缀出现混合小数位则自动退化为
逐代码表,只存例外,mixed_prefixes 可观测。

实测:全量 51,982 条权威表与静态规则零分歧;首次同步 50s(后台),
热缓存 60ms。测试 289 -> 306。

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-22 16:25:09 +08:00
41 changed files with 5136 additions and 574 deletions

No files matched your search

+389 -1
View File
@@ -2,6 +2,392 @@
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
## [0.7.1] - 2026-10-29
### 性能
- **DataFrame 转换提速近一倍:24 万行 K 线 894ms → 462ms(polars)/ 1,001ms → 587ms(pandas)**。
0.7.0 的取列实现有两处浪费:每个单元格都套一层 Python 闭包(顺带做 `IntEnum` 判断),
而 `trading_date` 每行都重新格式化三个整数 —— 24 万行里这个值往往只有 **1~2 种**。
| 转换层(不碰网络) | 0.7.0 | 现在 |
|---|---|---|
| 5,225 行报价 → polars | 66 ms | **51 ms** |
| 5,225 行报价 → pandas | 74 ms | **62 ms** |
| 240,000 行 K 线 → polars | 1,038 ms | **444 ms** |
| 240,000 行 K 线 → pandas | 1,234 ms | **585 ms** |
端到端(缓存已热,1,000 只 × 240 根 1 分钟):`df=None` 1,386ms、
polars 1,768ms(原 2,680ms)、pandas 1,976ms(原 2,848ms)。
- 普通列改用 `list(map(attrgetter(name), rows))`:取值发生在 C 层,不再每格建一个 Python 帧。
- `trading_date` 按「时间字段(除 minute 外)」缓存(`_TD_KEYS`):A股/港股/期货一个交易日
一个键,美股靠键里的 `hour` 覆盖凌晨段跨日判断 —— 不依赖 `_US_DAY_SPLIT_HOUR` 的具体取值。
- `IntEnum` 归一化从「每格判断一次」改为「按列判断一次、需要时才整列转」。
- 逐字段等价有测试锁定(`test_every_bar_field_equals_model` 等 3 项),口径零变化。
### 文档
- `docs/dataframe.md` 性能一节改为**实测数据 + 何时该用/不该用 DataFrame 出口**的说明,
并把「缓存命中也要付转换成本」写清。
## [0.7.0] - 2026-10-28
### 新增
- **DataFrame 直出:`TdxData(df="polars")` / `TdxData(df="pandas")`**。
表格型接口不再只能返回 `list[dataclass]`,构造时声明一次后端即可直接拿到 DataFrame:
```python
async with TdxData(df="polars") as td:
df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
```
- 覆盖 **42 个**返回表格数据的方法(33 个 `list[dataclass]`、2 个 `list[dict]`、
2 个批量 `dict[str, list[...]]`、`get_indicators` 与 `get_index_trade_stats(_multi)`),
另含 deprecated 别名(`get_kline` / `get_transactions` / `get_goods_*` 等)。
- **核心包仍然零依赖**:pandas / polars 是可选 extras ——
`pip install "pytdxdata[polars]"` / `[pandas]` / `[dataframe]`。
- `df=None`(默认)**行为与 0.6.x 完全一致**,且装饰器直接透传,零额外开销。
- 取值非法抛 `ValueError` 并列出可用值;后端未安装抛 `FrameBackendError`(继承 `ImportError`,
`e.name` 为缺的包名,消息里带安装命令)——**在构造时就失败**,不会拖到第一次查询。
- **列口径**(三条约定,一次定死):
| 约定 | 说明 |
|---|---|
| 时间列替换 | `SecurityBar`/`IndexBar`/`MinuteBar` 的 `year/month/day/hour/minute` 不再单列输出,统一给 `datetime`(polars `Datetime('us')` / pandas `datetime64[ns]`)与 `trading_date`;`XdxrRecord` 给 `date` |
| 嵌套定型 | `SecurityQuote.bid`/`ask` 展开成 `bid1_price`…`ask5_vol` 共 10 列(缺档 `None`);`fields` 字典 JSON 化成字符串列(空字典给 `None`);`TdxBlock.codes` 保持列表 |
| 容器展开 | `get_indicators` → bars + 各指标一列(长度不足补 `None`);`get_index_trade_stats(_multi)` → `minutes` 展开并补 `index`/`date` 常量列;`get_kline_batch`/`get_minute_batch` → 各标的纵向拼接成一张表 |
- **嵌套调用不二次转换**:`get_kline_batch` 这类方法内部还会调 `get_bars`,
用 `ContextVar`(按 task 隔离)记录层次,内层一律返回原始 `list`,只有最外层那次才转 DataFrame。
并发调用互不干扰。
### 性能
- **按日期区间取 K 线:右端贴最新时改走「倒推」,1 分钟 K 线 4.2s → 82ms(51 倍)**。
原先 `start_date` / `end_date` 一律走「探总根数 → 二分定位偏移」。1 分钟 K 线历史总量
二十万根量级,等于 6 次翻倍探测 + 2 次方向探测 + **两次各 ~18 次**跳转,共 36+ 次串行往返。
而「取今天」「增量到最新」这类占绝对多数的调用,右端本来就贴着最新,根本不需要二分。
| 场景(1 分钟,冷启动) | 优化前 | 优化后 |
|---|---|---|
| 单只「取今天」 | 4,208 ms | **82 ms** |
| 单只「2 天前 ~ now」 | 2,211 ms | **75 ms** |
| 单只「取最近 3 天」 | 2,000 ms+ | **239 ms** |
| 单只「历史中段(5~3 天前)」 | 1,512 ms | 285 ms |
| 全市场 5,225 只「取今天」 | — | 32.1 s(1,140,699 根,**精确当天口径**) |
做法:右端离最新不超过 `_BACKTRACK_GRACE`(10 天,覆盖长假)时,直接
`start=0, count=N` 拿最新 N 根再裁剪 —— N 按时间跨度估算(`_BARS_PER_DAY`),
一天内一次就命中,不够才翻倍。历史中段仍走二分,结果完全一致。
偏移方向是**通道级属性**(与具体标的无关),首次探测后缓存在实例上:
全市场 5,225 只批量调用只付一次探测成本,不会每只探两遍。
- **多标的 K 线改「多连接 × 单连接流水线」抓取,全市场 1 分钟 K 线 43.6s → 5s 级
(盘中增量 1.5s)**。
单只 K 线是「一请求一标的」,5,000 只就是 5,000 次往返。实测单连接串行 **33ms/只
≈ 恰好一个 RTT** —— 瓶颈是**往返次数,不是带宽**(此前「单 IP 限流 1.5MB/s」的
结论是浅流水下的假象:同一台服务器 16 连接 × 深度 8 实测能跑到 5.2 MB/s)。
做法:同一连接连续下发 `pipeline` 条请求(协议帧自描述长度且服务器**按序应答**,
无需等前一个回来),再叠加多台服务器并行(每台 1 连接,尊重 `per_server_cap`)。
| 场景(全市场 5,225 只,1 分钟) | 优化前(逐只 `concurrency=6`) | 优化后 |
|---|---|---|
| 取当天全天(240 根) | 43.6 s | **5~8 s** |
| 盘中 10:00(35 根) | 15 s+ | **~2 s** |
| 盘中增量(最新 2 根) | 12 s+ | **~1.5 s** |
- 流水深度默认**自适应**(`pipeline=None`):按单请求字节数把在途量控制在 ~60KB,
夹在 8~32 之间 —— 取 240 根用深度 8,只取最新 2 根用深度 32。
实测过深反而更慢(24 台 depth=64 比 depth=8 慢一倍,服务器会攒够一批才回)。
- 服务器**只取最快的 12 台**:池里 24 台全用反而被慢节点拖长尾
(`count=2` 全市场:24 台 2.95s / 12 台 1.45s)。
- **盘中只拉已走过的根数**:`start_date=今天` 时按交易时段折算(10:00 → 30 根,
而不是 240 根),数据量直接差 8 倍。收盘后回到一整天的量级。
- 标准通道(日线不复权)同样走批量:全市场日线 240 根 49~72s → **~10s**。
- 流水线中途失败时该批**交回逐只重试**(流水线失败意味着响应流已错配、连接作废),
连接全挂时队列里剩下的标的也一并回退 —— 不会静默少数据(新增测试覆盖)。
- `pipeline=1` 可关闭批量路径,行为与旧版逐只路径一致。
- **修正「右端是否贴最新」的时间戳比较**:`0x122E` 返回的 `hour/minute` 是**该周期的
结束时刻**,最新一根可能比 `datetime.now()` 略大(14:29 那根此刻还在走)。
原先没有容差,`end_date=datetime.now()` 这类最自然的写法会被误判成「历史中段」而走慢路径。
### 修复
- **EX 通道 K 线的 `amount` 恒为 0.0,且末位字段(结算价)被解包丢弃**。
`0x23FF` 一条记录 32B = 4B 时间戳 + **28B 行情**,这 28B 只有**一个** 4B 槽位可复用,
语义按市场分两类(全市场实测,用 `成交额 / (close × vol)` 逐条校验):
| 市场 | 槽位 5 | 槽位 6 | 槽位 7 | 校验 |
|---|---|---|---|---|
| 港股主板 31 / 港股基金 49 | **成交额**(f) | 成交量(手=100 股) | 未知 | 额/(c·vol) = **100.0** |
| 港股创业板 48 / 新三板 44 / 美股 74 | **成交额**(f) | 成交量(股) | 0 | 额/(c·vol) ≈ **1.0** |
| 期货 / 期权(7/8/9/47…) | 持仓量(I) | 成交量 | **结算价**(f) | 与 CFFEX 官网日结逐日相符 |
改动前:`amount` 被硬编码成 `0.0`、第 7 个 float 用 `_` 丢弃 —— 于是港股/美股/新三板
**明明帧内有成交额却全是 0**,期货期权的结算价也拿不到(用户只能换源)。
- 新增 `SecurityBar.settle`(结算价,`float | None`)。仅 EX 期货/期权**日线**有值,
分钟线该槽位恒 0 已归一化为 `None`;其它通道恒 `None`。
- 权益类市场的 `amount` 回填真实成交额。⚠️ 港股主板/基金的 `vol` 单位是**手(=100 股)**,
`amount/vol` 是均价的 **100 倍**。
- 期货/期权的 `amount` **仍是 0.0** —— 帧内确实没有成交额,这是协议限制,已在
`SecurityBar` 与文档中写清,避免使用者再按文档误判为调用方 bug。
- 港股指数 27 / 中证指数 62 该槽位量级对不上(既非成交额也非结算价),保守保持 `0.0`。
- `SecurityBar.__setstate__` 兜底旧磁盘缓存:缓存键没有 schema 版本,升级后读旧 pickle
会缺 `settle` 槽位,默认反序列化不补默认值 → 直接 `AttributeError`,已容错。
EX K 线缓存键额外加 `@v2` 标记,让 `amount` 恒 0 的旧缓存自然失效。
### 兼容性
- 无破坏性变更。不传 `df` 时所有方法签名、返回类型、行为与 0.6.9 完全相同。
- 空结果返回**列名齐全的空表**(列由模型定义推出),dtype 由后端自行推断。
- `SecurityBar` 新增可选字段 `settle`(默认 `None`):K 线 DataFrame 因此多一列 `settle`,
位置参数构造的老代码不受影响。
### 升级
```bash
pip install -U pytdxdata # 只要 dataclass
pip install -U "pytdxdata[polars]" # 想直出 DataFrame
```
- **磁盘缓存不需要手动清**:`SecurityBar` 的 `settle` 由 `__setstate__` 兜底补默认值,
旧缓存照常可读;EX K 线缓存键已带 `@v2`,`amount` 恒 0 的旧记录会自动失效重取。
- 新参数 `pipeline`(`get_bars`)默认自适应,**不传就是最优**;只有想显式退回旧的逐只路径时才传 `1`。
### 文档
- 新增 [DataFrame 输出](https://openbot-coder.github.io/pytdxdata/dataframe/) 专页,
`API_REFERENCE.md`(构造参数表补 `df` 与 `ex_pool_cap`、`pool_max` 默认值修正为 24)、
`SKILL.md`、`llms.txt`、`README.md`、`mkdocs.yml` 导航同步。
- 全站同步 0.7.0 口径:首页特性表与导航卡片、安装页(extras 与构造参数表补
`df` / `std_pool_cap` / `ex_pool_cap`)、场景示例的「转成 pandas」改为推荐 `df=` 开关、
数据模型页说明 dataclass 与 DataFrame 是同一份数据、README「已知限制」补 EX 成交额口径。
## [0.6.9] - 2026-10-23
### 修复
- **`get_universe` 冷启动 12~18s / 偶发失败:证券清单请求多发了 2 字节,污染连接**。
`GetSecurityListCmd` 的请求体是「12 字节命令头 + market(H) + start(H)」= **16 字节**,
但实现里多塞了一个 `H`(写死 0),实际发出 **18 字节**。服务端只消费前 16 字节,
剩下的 `00 00` 停在它的接收缓冲里,把**下一个请求**的开头吃掉 —— 于是同一条连接
「第一次成功、第二次起永远无响应」。
分页器复用连接,等于每拉一页都要先失败重连,冷启动被拖到 12~18s,还经常直接抛
`ConnectionError`。
| 场景 | 修复前 | 修复后 |
|---|---|---|
| `get_universe("sh")` 冷启动(27,534 条 / 28 页) | 12,267ms | **1,610ms** |
| `get_universe("sz")` 冷启动(24,460 条 / 25 页) | 18,260ms | **571ms** |
| `get_universe()` 全市场冷启动(146,848 条) | 19,085ms | **4,371ms** |
| `get_universe()` 热缓存 | — | 669ms |
| 同一连接连发 2 次清单(27 台主机) | **0/27 成功** | **27/27 成功** |
- **北交所清单不再卡 15s 后报错,改为立即返回空列表**。
`0x053E` 对 `market=2` 在实测的 **27 台标准主机上全部无响应**(26 台 6s 无回包、
1 台立刻拒连),而同市场的 `0x053D` 数量接口正常(返回 389)。原实现会重试 2 次、
每次 3s 超时,最后让 `get_universe()`(不带参数)整批失败。
现在该市场直接返回空列表并 `WARNING` 一次,**北交所标的本身不受影响**:
`get_quotes("bj920992")` / `get_bars` / 逐笔全部正常(实测 11.79 与日线 close 一致)。
### 优化
- **`get_universe()` 的 EX 全量只取一次**:命中缓存也要反序列化 10 万条(~200ms),
原先十几个 EX 市场各来一次,纯属白烧。
- **EX 商品列表改并发翻页**(110 页,8 并发):全市场冷启动的一半时间花在这里。
### 文档
- `get_universe` docstring 写明北交所限制;`API_REFERENCE` / `llms.txt` / `SKILL.md` 同步。
- 新增 `tests/test_universe.py` 7 项:请求长度锁定 16 字节、无尾部 padding、
北交所返回空且**不碰连接池**、`_ex_all` 只取一次。
### 已知限制(非本次引入)
- EX 全量列表含**非证券条目**(如人员名录),`(market, code)` 在原始数据里就不唯一,
且重复项出现在**同一页内部**。属数据源特性,未做去重(去重会丢真实品种)。
## [0.6.8] - 2026-10-23
### 修复
- **CLI 价格按品种小数位显示;`tdx minute` 时间列改回真实时钟**。
两处纯显示层缺陷,数据本身没问题(分时/逐笔数值见 0.6.7 的核对结论):
| 现象 | 原因 |
|---|---|
| `tdx transactions sh113708` 打印 `128.89` | 价格写死 `%8.2f`;可转债报价步长 0.001 元,末位被截掉 |
| `tdx minute sh113708` 时间列 `00:00~03:59` | 按序号推算 `i // 60, i % 60`,与 bar 自带时间无关 |
| `tdx quotes sh113708` 打印 `128.8920` | `price_decimal_digits` 是**解码位数**(原始整数 / 10⁴),第 4 位恒为 0 |
| 位置 | 变化 |
|---|---|
| `_price_fmt(dp)`(新) | 宽度随小数位走(`%8.2f` → `%9.3f`),不破坏表格对齐 |
| `_display_dp(market, code)`(新) | 可转债(沪 `110/111/113/118`、深 `123/127/128`)由解码 4 位降到显示 3 位;其余沿用 `price_decimal_digits`(ETF 3 位、国债/回购 4 位、股票/指数 2 位) |
| `cmd_kline` / `cmd_transactions` / `cmd_minute` / `_print_quote` | 统一改用上面的格式串 |
| `cmd_minute` | 时间取 `MinuteBar.hour/minute`,不再用序号推算 |
| `cmd_transactions` / `cmd_minute` | 改调 `get_ticks` / `get_minutes`,消掉 `get_transactions` / `get_minute` 的 DeprecationWarning |
新增回归测试 8 项(`tests/test_cli_format.py`)。
文档:`docs/cli.md` 补「价格小数位按品种适配」对照表与 `tdx minute` 时间列说明。
## [0.6.7] - 2026-10-22
### 性能
- **全市场 A股报价 3.5s → 0.33s:单连接流水线 + 工作窃取**(5,227 只 / 66 片实测)。
老实现 `get_quotes` 是**纯串行 for 循环**逐片发请求:协议硬上限 80 只/请求,
全市场必须切 66 片,每片一次往返(≈60ms)→ 3.5s 全花在等网络上。
关键发现:通达信响应是**自描述长度帧**(16B 帧头 + body)且服务器**按序应答**,
因此同一 TCP 连接上可以连续下发多条请求、只付一次往返。实测单连接流水 66 个请求
只要 526ms(串行 7,372ms),响应顺序与代码完全对得上(用昨收价交叉比对 30 只,零错配)。
| 位置 | 变化 |
|---|---|
| `TdxConnection.execute_pipeline(cmds)`(新) | 一次 write 全部请求 → 按序读回全部响应。中途失败**强制断连**(响应流已错配,不可复用) |
| `PooledConnection.execute_pipeline`(新) | 池化包装转发 |
| `api._execute_std_pipeline`(新) | 借一条连接流水一整组分片;节点不支持流水线时自动降级为逐片 |
| `get_quotes(..., pipeline=True, concurrency=None)` | 新参数;小批量(≤80 只)仍走原路径,零额外开销 |
| `_quotes_std` | 改为**工作窃取**:分片放队列,连接做完一批回来再取,快的多干、慢的少干 |
| `DynamicPool.warm(n)`(新) | **并发**预建连接。`acquire()` 建连在全局锁内一次一条,22 并发首次会串行握手 22 次 —— 全市场首拉因此多花 5~6s;预热后降到 0.78s |
| `CacheManager.get_or_fetch_obj`(新) | 回源直接返回对象,省掉冷路径「pickle→立刻 unpickle」的一次白烧(5,227 条实测 ~40ms) |
| `TdxData(pool_max=)` | 默认 12 → 24,让报价并发能到「每台 2 连接」(池仍是懒扩容,不影响其他接口) |
调优实测(5,227 只 A股,11 台服务器,p50/max):
| 并发 | 每台连接 | 流水深度 | p50 | max |
|---|---|---|---|---|
| 11 | 1 | 6 | 455ms | 464ms |
| 12 | 1~2 | 3 | 457ms | 523ms |
| **22** | **2** | **3** | **325ms** | **334ms** |
| 33 | 3 | 2 | 328ms | 345ms |
⚠️ 剩余下限由公网决定:本机 → 服务器 TCP 握手 RTT 59~80ms,66 片最多只能压到
「1 次往返」;网络抖动时段实测会到 460~600ms。
端到端实测(全默认参数 `TdxData()`,11 台服务器,5,227 只):
| 场景 | 耗时 |
|---|---|
| 首次调用(含并发建 22 条连接) | 783ms |
| 稳态(第 2 次起) | **300~343ms** |
| 命中 TTL 缓存 | 67ms |
| 老版本对照(串行) | 5,996ms(首次)/ 3,460ms(稳态) |
### 修复
- **指数 / ETF / LOF 的 `trade_count` 不再伪装成成交笔数**。
通达信对**指数**和**多数场内基金**不提供笔数,但逐笔报文里那 4 字节仍塞了值:
指数是「当时均价 × 1000」,ETF/LOF 是「价格 × 1000」,货币 ETF(`sh511990`)恒为 `0`。
旧版直接把它当笔数,于是 `tdx transactions sh510310` 会打印出「3994笔」这种假数据
(实测 2026-10-22,价 3.989,原字段 3994)。
| 位置 | 变化 |
|---|---|
| `TransactionRecord.trade_count_available`(新字段) | 该品种协议上是否带笔数;默认 `True` |
| `symbols.has_order_count(market, code)`(新函数) | 按品种判定;**沪市 501x/502x/506x 实测有真实笔数**,不能按「5 开头=基金」一刀切 |
| `transaction.py` 三个解析器 | 不可用时 `trade_count=0` + `trade_count_available=False`;历史通道(0x013001,无笔数字段)同样标记 |
| `tdx transactions` CLI | 不可用时打印 `(-)`,不再打印假笔数 |
实测样本(2026-10-22,按前缀各取样):沪股票/科创/深股票/深可转债/沪逆回购 → 真实笔数;
沪 `51/52/56/58`、深 `159/15x/16x/17x/18x`、所有指数 → 不可用。
### 文档
- **可转债的量纲口径补全**(数据本身无缺陷,但对外文档一片空白,很容易被误判成 bug)。
起因:核查可转债的分时(`0x122D`)与逐笔(`0x122F`)是否有类似 ETF/LOF 的笔数问题。
结论是**价格 / 成交量 / 笔数三样全部正确**,顺带确认了 K 线标度也对;唯一的问题是
`vol` 的单位没人写清楚 —— 直接拿 `amount / vol` 算均价会**错 10 倍**。
实测(2026-10-22,16 只 A股可转债当日 + 8 只历史日 `2026-10-21`):
| 校验项 | 结果 |
|---|---|
| 分时末价 / 快照现价 | **1.000000** |
| Σ分时 vol / 日线 vol | **1.000000** |
| Σ逐笔 vol / 日线 vol | **1.000000** |
| 逐笔 VWAP vs `amount/(vol×10)` | 吻合(差 ≤0.002,是 amount 精度) |
| 快照 `pre_close` vs 上一交易日日线 `close` | **16/16 精确相等** |
| `trade_count` | 真实笔数(`sh111000` 3631 条切片 / 20443 笔) |
关键口径对照(这是文档缺失的部分):
| 品种 | 分时 / 逐笔 `vol` | 日线 `vol` | `Σ分时vol / 日线vol` | `amount / vol` |
|---|---|---|---|---|
| 股票 / ETF / LOF | 手(= 100 股) | 股 | **0.01** | 均价 ✓ |
| 可转债 | 手(= 10 张) | **手** | **1.0** | 均价 **×10** ⚠️ |
| 位置 | 变化 |
|---|---|
| `SecurityBar` / `TransactionRecord` / `MinuteBar` | 量纲注释补可转债(`vol`=手;日线 `amount/vol` 需再 `/10`) |
| `symbols.has_order_count` | 实测表补沪可转债 `110/111/113/118`、沪 EB `132`、深可转债 `123/127/128`,并说明它们走「排除法」兜底分支 |
| `docs/API_REFERENCE.md` | 新增**跨品种量纲对照表** |
| `docs/llms.txt` / `SKILL.md` | 同步同一口径 |
**代码逻辑未改**:可转债在 `has_order_count` 里本来就判为「有笔数」(不在基金/指数的
排除前缀里),本次只是把实测依据补进注释与文档。
## [0.6.6] - 2026-10-22
### 改进
- **价格小数位改用协议自带的权威值,前缀规则降为兜底**。
0.6.5 修好债券/回购标度时,采用的是「按代码前缀推断」+「用全量清单做离线校验」。
但同一份证券清单接口(`get_universe`,底层 `GetSecurityListCmd`)本来就**返回**
`SecurityInfo.decimal_point`(外加自描述浮点的 `pre_close`)——权威值一直就在手上,
只是没接进取数路径。本次把它接进来:
| 位置 | 说明 |
|---|---|
| `price_decimal_digits` | 查找顺序改为 **权威表 → 静态前缀规则**,未同步时行为与 0.6.5 完全一致 |
| `decimal_sync`(新模块) | 每日后台同步一次 + 磁盘缓存(`%LOCALAPPDATA%\pytdxdata\decimal-points.json`) |
| `TdxData.sync_decimal_points()` | 手动强制刷新(排障 / 立刻要权威表) |
| `TdxData.decimal_point_status()` | 状态:`source` / `stock` / `mixed_prefixes` / `syncing` |
**对用户仍无感**:`start()` 命中当日缓存就直接装表(实测 60 ms、零网络),
未命中则挂后台 task(实测首次 50 s,含沪 27,520 + 深 24,462 条清单),
不阻塞 `start()`(`start()` 仍 1.5 s);`close()` 会取消未完成的同步。
**表结构刻意做小**:全量 51,982 只标的只产生 **179 个**「三位前缀 → 小数位」映射
(沪 96 + 深 83),内存里就是 179 条。若将来某段代码混用两种小数位,该前缀自动
退化为**逐代码表**,只存例外代码(`mixed_prefixes` 会 > 0,可据此发现),
不会静默算错。清单拉取不完整时表会偏小 —— 缺的部分退回静态规则,不影响正确性。
为什么保留前缀规则:`get_quotes` 解析是纯同步、无网络的路径,解析那一刻可能还没
同步过清单;离线 / 首次安装也必须能出价格。实测两者在全量清单上**零分歧**
(51,982 条逐条比对,不一致 0 条),并存不会造成口径冲突。
开关:`PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1` 关闭后台同步(CI / 测试用)。
### 说明
- 新增回归测试 16 项(权威表优先级 / 混合前缀退化 / 缓存跨日失效 / 损坏容错 /
后台任务取消),测试总数 **289 → 306**。
## [0.6.5] - 2026-10-22 ## [0.6.5] - 2026-10-22
### 新增 ### 新增
@@ -467,7 +853,9 @@
- 初始版本:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页 + 双通道(标准 / MAC)+ 扩展市场(港股 / 美股 / 期货 / 期权) - 初始版本:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页 + 双通道(标准 / MAC)+ 扩展市场(港股 / 美股 / 期货 / 期权)
[Unreleased]: https://github.com/openbot-coder/pytdxdata/compare/v0.6.0...HEAD [Unreleased]: https://github.com/openbot-coder/pytdxdata/compare/v0.7.1...HEAD
[0.7.1]: https://github.com/openbot-coder/pytdxdata/compare/v0.7.0...v0.7.1
[0.7.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.6.0...v0.7.0
[0.6.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.5.0...v0.6.0 [0.6.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.5.0...v0.6.0
[0.5.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.4.0...v0.5.0 [0.5.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.4.0...v0.5.0
[0.4.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.2...v0.4.0 [0.4.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.2...v0.4.0
+13 -5
View File
@@ -47,14 +47,17 @@ async def main():
asyncio.run(main()) asyncio.run(main())
``` ```
返回的是标准库 `dataclass` 组成的 `list`(库本身不依赖 pandas)。要 DataFrame 一行转: 默认返回的是标准库 `dataclass` 组成的 `list`(核心库不依赖 pandas)。需要 DataFrame 就换个后端构造:
```python ```python
from dataclasses import asdict async with TdxData(df="polars") as td: # 或 df="pandas";需 pip install "pytdxdata[polars]"
import pandas as pd df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
df = pd.DataFrame([asdict(b) for b in bars]) # 列:market code open high low close vol amount datetime trading_date symbol settle
``` ```
时间字段会被**合并成一列 `datetime`**(不再有 year/month/day/hour/minute),五档报价展开成
`bid1_price`…`ask5_vol`,详见 [DataFrame 输出](https://openbot-coder.github.io/pytdxdata/dataframe/)。
## 特性 ## 特性
| 特性 | 说明 | | 特性 | 说明 |
@@ -63,7 +66,8 @@ df = pd.DataFrame([asdict(b) for b in bars])
| 🗄️ 双层 TTL 缓存 | 内存 LRU + 磁盘 SQLite(WAL),TTL 分级;single-flight 并发同键去重;缓存**已解析记录**(重复请求 0 网络 0 解析) | | 🗄️ 双层 TTL 缓存 | 内存 LRU + 磁盘 SQLite(WAL),TTL 分级;single-flight 并发同键去重;缓存**已解析记录**(重复请求 0 网络 0 解析) |
| ⚡ 并发分页 | 单请求拆 N 页(显式 start 偏移 → 无状态可并行)并行拉取、按序拼接、失败换连接重试 | | ⚡ 并发分页 | 单请求拆 N 页(显式 start 偏移 → 无状态可并行)并行拉取、按序拼接、失败换连接重试 |
| 🔀 双通道整合 | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1 分钟 K 线),按命令自动选路 | | 🔀 双通道整合 | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1 分钟 K 线),按命令自动选路 |
| 📦 零重型依赖 | 纯 asyncio + stdlib(socket / zlib / struct / sqlite3) | | 📦 零重型依赖 | 纯 asyncio + stdlib(socket / zlib / struct / sqlite3),`dependencies` 为空 |
| 🐼 DataFrame 直出 | `TdxData(df="polars")` / `df="pandas"` 让 42 个表格型接口直接返回 DataFrame;时间列自动合并成 `datetime`,五档报价自动展开。后端是可选 extras,核心包仍零依赖 |
| 📊 全市场覆盖 | A股、港股、美股、期货、期权(46 个扩展市场) | | 📊 全市场覆盖 | A股、港股、美股、期货、期权(46 个扩展市场) |
| 📄 服务器文件解析 | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 财报 `gpcw*` **下载即解析**成 dataclass(索引名与服务器实际文件名不一致时自动纠正) | | 📄 服务器文件解析 | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 财报 `gpcw*` **下载即解析**成 dataclass(索引名与服务器实际文件名不一致时自动纠正) |
| 🤖 AI 助手友好 | 内置 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 与 [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) | | 🤖 AI 助手友好 | 内置 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 与 [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) |
@@ -114,6 +118,10 @@ uv run mkdocs serve # 本地预览文档站
- 行情来自通达信公开服务器,**15 分钟延时**;需实时数据请使用券商行情 - 行情来自通达信公开服务器,**15 分钟延时**;需实时数据请使用券商行情
- 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避 - 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避
- 港股 / 美股期权在通达信协议内无数据 - 港股 / 美股期权在通达信协议内无数据
- **EX 通道(港股 / 美股 / 期货 / 期权)的 K 线没有统一成交额**:`0x23FF` 帧内只有一个可复用槽位,
权益类市场(港股主板/基金/创业板、新三板、美股)该槽位是成交额,已回填;**期货 / 期权该槽位是持仓量,
所以它们的 `SecurityBar.amount` 恒为 `0.0`**(协议限制,不是 bug)。期货/期权的结算价在 `SecurityBar.settle`。
⚠️ 港股主板/基金的 `vol` 单位是「手」(=100 股),`amount/vol` 是均价的 100 倍
- **K 线时间戳统一为北京时间**(v0.6.2 起)。美股原始报文把「美东交易日日期」与「北京时间时分」 - **K 线时间戳统一为北京时间**(v0.6.2 起)。美股原始报文把「美东交易日日期」与「北京时间时分」
拼在一起,库已自动归一化,`bar.datetime` 可直接排序 / 过滤;但**美股一个交易日横跨两个北京 拼在一起,库已自动归一化,`bar.datetime` 可直接排序 / 过滤;但**美股一个交易日横跨两个北京
自然日**,按交易日聚合请用 `SecurityBar.trading_date`,不要用 `datetime.date()` 自然日**,按交易日聚合请用 `SecurityBar.trading_date`,不要用 `datetime.date()`
+46 -3
View File
@@ -52,6 +52,7 @@ df = pd.DataFrame([asdict(b) for b in bars])
```bash ```bash
pip install pytdxdata # 或 uv add pytdxdata pip install pytdxdata # 或 uv add pytdxdata
pip install "pytdxdata[polars]" # 需要 DataFrame 输出时才装(可选 extras)
``` ```
## 可运行模板 ## 可运行模板
@@ -82,12 +83,20 @@ async def main():
# 分时(MAC 通道,今日或历史) # 分时(MAC 通道,今日或历史)
minutes = await td.get_minutes(["sz000001"]) minutes = await td.get_minutes(["sz000001"])
# 批量 K 线:多股票自动并发,池子会分配到不同服务器 # 批量 K 线:≥16 只自动走「多连接 × 单连接流水线」,池子把标的摊到多台服务器
batch = await td.get_bars( batch = await td.get_bars(
["sz000001", "sh600000"], ["sz000001", "sh600000"],
KlinePeriod.DAY, count=240, KlinePeriod.DAY, count=240,
) # 平铺返回,每条带 .symbol 字段 ) # 平铺返回,每条带 .symbol 字段
# 全市场盘中实时:只拉已经走完的根数(10:00 → 30 根),5,200 只 1~2 秒
from datetime import datetime
live = await td.get_bars(
[s.symbol for s in await td.get_universe("sh")],
KlinePeriod.MIN_1, start_date=datetime.now(),
)
# pipeline=1 可关闭批量路径,退回逐只并发(结果一致,只是慢)
asyncio.run(main()) asyncio.run(main())
``` ```
@@ -139,13 +148,14 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约
| 需求 | 方法 | | 需求 | 方法 |
|---|---| |---|---|
| 全市场标的清单(A股+港股+期货…) | `get_universe(market=None)` | | 全市场标的清单(A股+港股+期货…;**北交所返回空**) | `get_universe(market=None)` |
| 日/周/月/分钟 K 线(任意市场) | `get_bars(symbols, period, *, count, adjust, start_date, end_date)` | | 日/周/月/分钟 K 线(任意市场) | `get_bars(symbols, period, *, count, adjust, start_date, end_date)` |
| K 线 + MACD/KDJ/RSI/BOLL | `get_indicators(symbols, indicators, ...)` | | K 线 + MACD/KDJ/RSI/BOLL | `get_indicators(symbols, indicators, ...)` |
| 实时五档报价(A股)/ 基础报价(港股/美股/期货) | `get_quotes(symbols, *, fields=None)` | | 实时五档报价(A股)/ 基础报价(港股/美股/期货) | `get_quotes(symbols, *, fields=None, pipeline=True)` |
| 逐笔成交(任意市场) | `get_ticks(symbols, *, date)` | | 逐笔成交(任意市场) | `get_ticks(symbols, *, date)` |
| 分时图 / 缩略采样 | `get_minutes(symbols, *, date, sampling=True)` | | 分时图 / 缩略采样 | `get_minutes(symbols, *, date, sampling=True)` |
| 全市场股票列表(缓存 1 天) | `get_universe("sz")` / `get_universe("sh")` | | 全市场股票列表(缓存 1 天) | `get_universe("sz")` / `get_universe("sh")` |
| ~~北交所全量代码~~ | 拿不到:清单命令对 market=2 无响应(27 台全测)。北交所标的仍可直接查 `bj920992` |
| 除权除息 / 财务快照 | `get_xdxr(symbols)` / `get_finance(symbols)` | | 除权除息 / 财务快照 | `get_xdxr(symbols)` / `get_finance(symbols)` |
| F10 公司资料 | `get_f10(symbol, section)` | | F10 公司资料 | `get_f10(symbol, section)` |
| 板块列表 / 成分股 / 涨跌排行 | `get_boards` / `get_board_members` / `get_board_ranking` | | 板块列表 / 成分股 / 涨跌排行 | `get_boards` / `get_board_members` / `get_board_ranking` |
@@ -169,10 +179,40 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约
- **K 线时间戳统一为北京时间**(v0.6.2 起)。美股原始报文里日期是美东交易日、时分是北京时间(两个时区拼在一起),库已自动归一化,`bar.datetime` 可直接排序 / 比较 / 过滤。但**美股一个交易日横跨两个北京自然日**,按交易日聚合(分钟线合成日线、日内统计)必须用 `bar.trading_date`。 - **K 线时间戳统一为北京时间**(v0.6.2 起)。美股原始报文里日期是美东交易日、时分是北京时间(两个时区拼在一起),库已自动归一化,`bar.datetime` 可直接排序 / 比较 / 过滤。但**美股一个交易日横跨两个北京自然日**,按交易日聚合(分钟线合成日线、日内统计)必须用 `bar.trading_date`。
- **`count` 很大时会自动多连接并发分页**,无需手动翻页。但标准通道 K 线 `count < 100` 部分服务器会返回空——内部已强制 `min_page=100` 规避。 - **`count` 很大时会自动多连接并发分页**,无需手动翻页。但标准通道 K 线 `count < 100` 部分服务器会返回空——内部已强制 `min_page=100` 规避。
- **`get_quotes` 一次 >80 只自动切批**;走 MAC 字段位通道(`fields=`)时上限为 80 只/次。 - **`get_quotes` 一次 >80 只自动切批**;走 MAC 字段位通道(`fields=`)时上限为 80 只/次。
- **全市场报价用默认参数即可,别自己写循环**。`get_quotes(全部A股)` 内部会切 66 片并走**单连接流水线**(一条连接连发多个分片、只付一次往返)+ 工作窃取调度,5,227 只实测 **p50 325ms**(老版本串行 3.5s)。自己 for 循环逐只/逐片调会把流水线优势全部丢掉。
- 想更保守可 `concurrency=11`(每台 1 连接),代价 p50 457ms。
- 个别服务器不支持流水线时自动降级逐片,结果不受影响。
- **可转债(110/111/113/118/123/127/128)三样都是真的**:价格、`vol`(手=10 张)、`trade_count`(真实笔数,3631 条切片 / 20443 笔量级)全部可用,`Σvol` 与日线 `vol` **1:1 相等**。
⚠️ 唯一要小心的是 **日线 `amount / vol` 不等于均价,而是均价的 10 倍**(`vol` 单位是手=10 张)。算可转债均价用 `amount / vol / 10`,或直接用 `Σ(price×vol) / Σvol`——后者跨品种都成立,最稳。
对照:股票/ETF 的 `Σ逐笔vol / 日线vol = 0.01`(逐笔手、日线股),而 `amount/vol` 恰好就是均价。
- **指数本身没有成交笔数**。`get_ticks("sh000001")` 的 `trade_count` 是「当时均价×1000」、`vol` 单位是百元(成交额/100)。要笔数只能用 `get_index_trade_stats(index)`(成分股逐笔累加,2230 只约 36-60 s)。北交所成分无笔数字段,该方法会返回 `trade_count_available=False`。 - **指数本身没有成交笔数**。`get_ticks("sh000001")` 的 `trade_count` 是「当时均价×1000」、`vol` 单位是百元(成交额/100)。要笔数只能用 `get_index_trade_stats(index)`(成分股逐笔累加,2230 只约 36-60 s)。北交所成分无笔数字段,该方法会返回 `trade_count_available=False`。
- **ETF / LOF 也没有成交笔数**。`get_ticks("sh510310")` 的 `trade_count` 是「价格×1000」(货币 ETF 恒为 0)。判定用 `symbols.has_order_count(market, code)`,读记录时看 `TransactionRecord.trade_count_available`——为 `False` 时 `trade_count` 已被置 0,不要求和/求均值。注意**沪市 `501x/502x/506x` 实测有真实笔数**,不能按「5 开头=基金」一刀切。
- **历史逐笔有笔数**(MAC `0x122F` 支持历史日期,实测可回溯最近 5 个交易日;更早返回空)。 - **历史逐笔有笔数**(MAC `0x122F` 支持历史日期,实测可回溯最近 5 个交易日;更早返回空)。
- **小数位表不用手动管,但可以手动刷**。`start()` 会检查当日缓存并后台同步一次(`SecurityInfo.decimal_point` 权威值);要强制刷新用 `await td.sync_decimal_points()`,看同步状态用 `await td.decimal_point_status()`。`PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1` 可关闭后台同步。
- 板块文件(`block_*.dat`)/ 行业(`tdxhy.cfg`)/ 财报(`gpcw*.zip`)是**服务器上的静态文件**,解析后是普通 dataclass,**落 JSON 后完全脱网可用**——适合做离线快照。 - 板块文件(`block_*.dat`)/ 行业(`tdxhy.cfg`)/ 财报(`gpcw*.zip`)是**服务器上的静态文件**,解析后是普通 dataclass,**落 JSON 后完全脱网可用**——适合做离线快照。
## DataFrame 输出(v0.7+)
表格型方法可以直出 DataFrame,**唯一开关是构造参数 `df`**,不要在调用处传 `df=True`(没有这个参数):
```python
async with TdxData(df="polars") as td: # 或 df="pandas"
df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
```
| 事项 | 说明 |
|---|---|
| 安装 | `pip install "pytdxdata[polars]"` / `[pandas]` / `[dataframe]`;核心包仍零依赖 |
| `df=None`(默认) | 行为与 0.6.x 完全一致,返回 `list[dataclass]` |
| 报错 | `df` 取值非法 → `ValueError`;包没装 → `FrameBackendError`(启动即失败,不拖到第一次查询) |
| 时间列 | `year/month/day/hour/minute` **被 `datetime` 替换**,另带 `trading_date`;`XdxrRecord` 给 `date` |
| 嵌套 | `bid`/`ask` 展开成 `bid1_price`…`ask5_vol` 共 10 列;`fields` 字典 JSON 化成字符串列;`codes` 保持列表 |
| 特殊容器 | `get_indicators` → bars+指标合并;`get_index_trade_stats(_multi)` → `minutes` 展开 + `index`/`date` 列;`get_kline_batch` / `get_minute_batch` → 纵向拼接成一张表 |
| 不受影响 | `bytes` / `int` / `dict` / 单对象 / `tuple` / `list[float]` 类返回原样(`get_file`、`get_security_count`、`get_server_info`、`get_price_limits` 等) |
| 空结果 | 列名齐全的空表;dtype 只由后端推断 |
完整口径见 [DataFrame 输出](https://openbot-coder.github.io/pytdxdata/dataframe/)。
## 陷阱清单 ## 陷阱清单
| 坑 | 后果 | 正确做法 | | 坑 | 后果 | 正确做法 |
@@ -189,7 +229,10 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约
| 港股/美股五档 bid/ask | 没有(协议不支持) | `fields` 字段位通道有 name 但无五档 | | 港股/美股五档 bid/ask | 没有(协议不支持) | `fields` 字段位通道有 name 但无五档 |
| 美股分钟线用 `datetime.date()` 分组做日聚合 | 一个交易日被拆成两天(美股跨北京零点) | 用 `bar.trading_date`;`bar.datetime` 是归一化后的北京时间 | | 美股分钟线用 `datetime.date()` 分组做日聚合 | 一个交易日被拆成两天(美股跨北京零点) | 用 `bar.trading_date`;`bar.datetime` 是归一化后的北京时间 |
| 拿指数逐笔的 `trade_count` 当笔数 | 拿到的是「均价×1000」,数值荒谬 | 用 `get_index_trade_stats(index)` 由成分累加 | | 拿指数逐笔的 `trade_count` 当笔数 | 拿到的是「均价×1000」,数值荒谬 | 用 `get_index_trade_stats(index)` 由成分累加 |
| 拿 ETF/LOF 逐笔的 `trade_count` 当笔数 | 拿到的是「价格×1000」(`sh510310` 显示 3994 笔) | 看 `trade_count_available`,或 `symbols.has_order_count()` |
| 拿深市 `399xxx` 的 `amount` 校验成分合计 | 比值 0.43,误以为数据错 | 深市指数 amount 是**全板块**口径(`sz399001`=深市全部 5081 亿),不是样本股 | | 拿深市 `399xxx` 的 `amount` 校验成分合计 | 比值 0.43,误以为数据错 | 深市指数 amount 是**全板块**口径(`sz399001`=深市全部 5081 亿),不是样本股 |
| 在期货/期权 K 线上取 `amount` | 恒 0.0,误以为解析坏了 | EX `0x23FF` 帧内**没有成交额**(协议限制);结算价看 `bar.settle`,成交额改用 `get_quotes` |
| 用港股主板的 `amount / vol` 当均价 | 差 **100 倍** | 港股主板/基金的 `vol` 单位是**手(=100 股)**,要 `amount/vol/100`;港股创业板/美股才是股 |
| 依赖实时性做信号 | 数据是 15 分钟前的 | 换券商实时源 | | 依赖实时性做信号 | 数据是 15 分钟前的 | 换券商实时源 |
| 手动改包内 `servers.json` / 写死 IP | 容器只读、升级被覆盖、快节点捞不回来 | 日常靠内置的**当日测速缓存**自动选路;要强制指定就用 `PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS` 环境变量 | | 手动改包内 `servers.json` / 写死 IP | 容器只读、升级被覆盖、快节点捞不回来 | 日常靠内置的**当日测速缓存**自动选路;要强制指定就用 `PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS` 环境变量 |
+52 -11
View File
@@ -1,6 +1,6 @@
# pytdxdata 对外接口清单 # pytdxdata 对外接口清单
> 以 `src/pytdxdata` 源码为准整理(v0.6.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。 > 以 `src/pytdxdata` 源码为准整理(v0.7.1)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
> >
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。 > 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
@@ -28,8 +28,9 @@ from pytdxdata import (
| `cache_dir` | None | 磁盘缓存目录;None=仅内存缓存 | | `cache_dir` | None | 磁盘缓存目录;None=仅内存缓存 |
| `default_adjust` | `Adjust.NONE` | 默认复权方式 | | `default_adjust` | `Adjust.NONE` | 默认复权方式 |
| `max_inflight` | 64 | single-flight 并发上限 | | `max_inflight` | 64 | single-flight 并发上限 |
| `pool_min` / `pool_max` | 3 / 12 | 动态池上下限 | | `pool_min` / `pool_max` | 3 / 24 | 动态池上下限 |
| `mac_pool_cap` | 4 | 单台 MAC 服务器连接上限 | | `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,19 +42,25 @@ from pytdxdata import (
### 2.1 统一接口(v0.6+ 推荐){#unified} ### 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`)。 以下方法在 v0.6 新增,标的一律用字符串(`sz000001` / `hk00700` / `usAAPL` / `cffex:IFL0`)。
#### 标的清单 #### 标的清单
| 方法 | 返回 | 说明 | | 方法 | 返回 | 说明 |
|------|------|------| |------|------|------|
| `get_universe(market=None)` | `list[SecurityInfo]` | 跨市场标的清单(A 股+港股+美股+期货/期权) | | `get_universe(market=None)` | `list[SecurityInfo]` | 跨市场标的清单(A 股+港股+美股+期货/期权);每条带协议自带的 `decimal_point`(价格小数位)与 `pre_close`。**北交所清单协议不支持,返回空列表** |
| `sync_decimal_points(markets=("sh","sz"))` | `dict` | 从证券清单同步**权威价格小数位表**(`SecurityInfo.decimal_point`),灌进 `price_decimal_digits` 的运行时表;`start()` 已自动做(当日缓存命中则零网络),此方法用于强制刷新/排障 |
| `decimal_point_status()` | `dict` | 小数位表状态:`source`(`cache`/`universe`/空)、`stock`、`mixed_prefixes`、`syncing` |
#### 报价 #### 报价
| 方法 | 返回 | 说明 | | 方法 | 返回 | 说明 |
|------|------|------| |------|------|------|
| `get_quotes(symbols, *, fields=None)` | `list[SecurityQuote]` | 跨市场混合报价(A 股标准五档;给了 fields 走 MAC/EX 字段位有 name) | | `get_quotes(symbols, *, fields=None, concurrency=None, pipeline=True)` | `list[SecurityQuote]` | 跨市场混合报价(A 股标准五档;给了 fields 走 MAC/EX 字段位有 name)。超 80 只自动切批,`pipeline` 开启**单连接流水线**,全市场 5,200 只 ~0.33s |
| `get_snapshot(symbols)` | `list[SymbolSnapshot]` | 个股特征快照(A 股) | | `get_snapshot(symbols)` | `list[SymbolSnapshot]` | 个股特征快照(A 股) |
| `get_auction(symbols)` | `list[AuctionItem]` | 集合竞价(A 股) | | `get_auction(symbols)` | `list[AuctionItem]` | 集合竞价(A 股) |
| `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向(A 股) | | `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向(A 股) |
@@ -62,14 +69,14 @@ 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) | | `get_indicators(symbols, indicators, *, period=DAY, count=30, adjust=None, params=None)` | `list[IndicatorSet]` | K 线+技术指标(MACD/KDJ/RSI/BOLL/MA/EMA) |
#### 逐笔与分时 #### 逐笔与分时
| 方法 | 返回 | 说明 | | 方法 | 返回 | 说明 |
|------|------|------| |------|------|------|
| `get_ticks(symbols, *, date=None, start=0, count=None, concurrency=6)` | `list[TransactionRecord]` | 跨市场逐笔成交。返回按时间升序;`start` **从最新一笔往回数**;`vol`/`trade_count` 为约 3 秒切片的增量值(非累计)。**已剔除 `bs_flag=8` 竞价委托**(非成交,`vol` 为累计撮合量)。**指数**:`vol` 单位是百元(成交额/100)、`trade_count` 是均价×1000,均非股票语义 | | `get_ticks(symbols, *, date=None, start=0, count=None, concurrency=6)` | `list[TransactionRecord]` | 跨市场逐笔成交。返回按时间升序;`start` **从最新一笔往回数**;`vol`/`trade_count` 为约 3 秒切片的增量值(非累计)。**已剔除 `bs_flag=8` 竞价委托**(非成交,`vol` 为累计撮合量)。**指数**:`vol` 单位是百元(成交额/100)、`trade_count` 是均价×1000,均非股票语义;**可转债**:`vol` 是手(=10 张)、`trade_count` 是**真实笔数**,`Σvol` 与日线 `vol` **1:1** |
| `get_minutes(symbols, *, date=None, sampling=False, concurrency=6)` | `list[MinuteBar]` | 跨市场分时(sampling=True 取缩略采样:A股由 0x122D 派生,扩展市场 0x254D) | | `get_minutes(symbols, *, date=None, sampling=False, concurrency=6)` | `list[MinuteBar]` | 跨市场分时(sampling=True 取缩略采样:A股由 0x122D 派生,扩展市场 0x254D) |
#### 公司信息/文件/板块 #### 公司信息/文件/板块
@@ -89,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_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_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线(含涨跌家数字段) | | `get_index_kline(market, code, period, *, start=0, count=800)` | `list[SecurityBar]` | 指数K线(含涨跌家数字段) |
@@ -100,7 +107,7 @@ from pytdxdata import (
| 方法 | 返回 | 说明 | | 方法 | 返回 | 说明 |
|------|------|------| |------|------|------|
| `get_quotes(symbols, *, fields=None)` | `list[SecurityQuote]` | 五档报价;>80 只自动切批;TTL 5s | | `get_quotes(symbols, *, fields=None, concurrency=None, pipeline=True)` | `list[SecurityQuote]` | 五档报价;>80 只自动切批(流水线+工作窃取,5,200 只 ~0.33s);TTL 5s |
| `get_stock_quotes(stocks, bits=None)` | `list[MemberQuote]` | MAC 自定义字段报价(≤80只/次) | | `get_stock_quotes(stocks, bits=None)` | `list[MemberQuote]` | MAC 自定义字段报价(≤80只/次) |
| `get_stock_quotes_list(category, *, start=0, count=80, sort_type=0)` | `list[MemberQuote]` | 市场分类报价(0沪A/2深A/6全A/8科创/14创业) | | `get_stock_quotes_list(category, *, start=0, count=80, sort_type=0)` | `list[MemberQuote]` | 市场分类报价(0沪A/2深A/6全A/8科创/14创业) |
| `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数/总额/市值/涨跌停数) | | `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数/总额/市值/涨跌停数) |
@@ -197,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线) | | `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 | | `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 | | `SecurityInfo` | market/code/name/volunit/decimal_point/pre_close |
@@ -221,6 +228,31 @@ from pytdxdata import (
> 注:`__init__` 仅导出 `Market/ExMarket/KlinePeriod/Adjust` 与 6 个核心模型;`BoardInfo/MemberQuote/AuctionItem` 等需 `from pytdxdata.models import ...`。 > 注:`__init__` 仅导出 `Market/ExMarket/KlinePeriod/Adjust` 与 6 个核心模型;`BoardInfo/MemberQuote/AuctionItem` 等需 `from pytdxdata.models import ...`。
**量纲对照(跨品种,2026-10-22 实测)**
同名字段在不同品种上单位不同。最典型的坑是用 `amount / vol` 算均价——它在可转债上会**错 10 倍**:
| 品种 | 分时 / 逐笔 `vol` | 日线 `SecurityBar.vol` | `Σ分时vol / 日线vol` | 日线 `amount / vol` |
|---|---|---|---|---|
| 股票 / 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`;港股主板/基金 `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**。
## 四、辅助模块 ## 四、辅助模块
**`pytdxdata.indicator`**(技术指标,纯函数) **`pytdxdata.indicator`**(技术指标,纯函数)
@@ -303,4 +335,13 @@ CLI 开关:`--discover`(三种协议全测并据实修正 `protocols`,同
| 逐笔成交 / 分时 | MAC | | 逐笔成交 / 分时 | MAC |
| 列表 / 数量 / 除权 / 财务 | 标准 | | 列表 / 数量 / 除权 / 财务 | 标准 |
| 板块 / 竞价 / 异动 / 快照 / 资金流 / 服务器 / 分类报价 | 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
View File
@@ -26,7 +26,7 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md \
## 里面有什么 ## 里面有什么
- **三条必守约定** —— 唯一入口是 `TdxData` 且必须 `async with`;标的是字符串(如 `sh600000`) - **三条必守约定** —— 唯一入口是 `TdxData` 且必须 `async with`;标的是字符串(如 `sh600000`)
而不是 `(market, code)` 元组;返回值是 `list[dataclass]` 而不是 DataFrame 而不是 `(market, code)` 元组;默认返回 `list[dataclass]`(要 DataFrame 得用 `TdxData(df="polars")` 显式声明后端)
- **枚举取值表** —— `Market` / `KlinePeriod` / `Adjust` / `ExMarket` 的准确取值 - **枚举取值表** —— `Market` / `KlinePeriod` / `Adjust` / `ExMarket` 的准确取值
- **可运行模板** —— K 线、复权、报价、逐笔、分时、批量,全部是能直接跑的代码 - **可运行模板** —— K 线、复权、报价、逐笔、分时、批量,全部是能直接跑的代码
- **「想做什么 → 用哪个方法」决策表** —— 18 个常见需求的直接映射 - **「想做什么 → 用哪个方法」决策表** —— 18 个常见需求的直接映射
+10 -2
View File
@@ -2,8 +2,16 @@
全部数据模型位于 `pytdxdata.models`,统一为 `@dataclass(slots=True)`。 全部数据模型位于 `pytdxdata.models`,统一为 `@dataclass(slots=True)`。
选择 dataclass 而不是 pandas DataFrame 是刻意的:**零依赖 + 零转换开销**, 默认(`df=None`)所有接口返回这些 dataclass —— **零依赖 + 零转换开销**。
需要 DataFrame 时你自己转(一行的事,见 [场景示例 → 转成 pandas](../cookbook.md#to-pandas))。 不想要 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);
两者是同一份数据,只是容器不同,**量纲与语义完全一致**。
## 导入方式 ## 导入方式
+11
View File
@@ -56,6 +56,17 @@ tdx minute sz000001 # 今日分时
tdx minute sz000001 --date 20260811 # 历史分时 tdx minute sz000001 --date 20260811 # 历史分时
``` ```
价格列的小数位**按品种自动适配**,不用自己换算:
| 品种 | 显示小数位 | 示例 |
|---|---|---|
| 股票 / 指数 | 2 | `12.34` |
| ETF / LOF / 沪市 B 股 / 可转债 | 3 | `128.892`(可转债报价步长 0.001 元) |
| 债券 / 回购 | 4 | `100.0100` |
> 可转债的**解码位数**是 4 位(原始整数 / 10⁴),但第 4 位恒为 0,所以显示按 3 位。
> `tdx minute` 的时间列是该 bar 的**真实时钟**(`09:31` / `14:57`),不是序号推算。
## 板块 ## 板块
```bash ```bash
+12 -1
View File
@@ -196,7 +196,18 @@ async def ex_markets():
## 转成 pandas {#to-pandas} ## 转成 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 ```python
import pandas as pd import pandas as pd
+142
View File
@@ -0,0 +1,142 @@
# 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 是每次调用现建的
——高频轮询同一批数据时,这笔转换开销每次都会付。
+21 -1
View File
@@ -35,6 +35,23 @@
安装后即可使用 `tdx` 命令行工具(见 [CLI 手册](cli.md))。 安装后即可使用 `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 加速 ### 可选:uvloop 加速
Linux / macOS 上可选用 `uvloop` 替换默认事件循环(Windows 不支持): Linux / macOS 上可选用 `uvloop` 替换默认事件循环(Windows 不支持):
@@ -63,8 +80,11 @@ asyncio.run(main())
| `cache_dir` | `None` | 磁盘缓存目录;**`None` = 仅内存缓存**(进程退出即失效) | | `cache_dir` | `None` | 磁盘缓存目录;**`None` = 仅内存缓存**(进程退出即失效) |
| `default_adjust` | `Adjust.NONE` | 默认复权方式,可被单次调用覆盖 | | `default_adjust` | `Adjust.NONE` | 默认复权方式,可被单次调用覆盖 |
| `max_inflight` | `64` | single-flight 并发上限(同键请求合并) | | `max_inflight` | `64` | single-flight 并发上限(同键请求合并) |
| `pool_min` / `pool_max` | `3` / `12` | 动态连接池上下限 | | `pool_min` / `pool_max` | `3` / `24` | 动态连接池上下限 |
| `mac_pool_cap` | `4` | 单台 MAC 服务器连接数上限 | | `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
View File
@@ -35,8 +35,9 @@ asyncio.run(main())
| ⚡ **并发分页** | 把大请求拆成显式 `start` 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 | | ⚡ **并发分页** | 把大请求拆成显式 `start` 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 |
| 🔀 **双通道整合** | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 | | 🔀 **双通道整合** | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 |
| 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制;文件名与索引不一致时自动纠正 | | 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制;文件名与索引不一致时自动纠正 |
| 🚀 **批量下载** | `get_bars` / `get_minutes` 传标的列表即多股票并发,连接池自动分配到不同服务器 | | 🚀 **批量下载** | `get_bars` / `get_minutes` 传标的列表即多股票并发,连接池自动分配到不同服务器;K 线走「多连接 × 单连接流水线」,全市场 5,225 只 1 分钟线取当天 **5~8 秒**(盘中增量 1~2 秒) |
| 📦 **零重型依赖** | 返回 `list[dataclass]`,pandas / polars 由调用方按需转换 | | 🐼 **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) [: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) [:octicons-arrow-right-24: API 参考](api/index.md)
@@ -122,6 +131,7 @@ asyncio.run(main())
- [安装与配置](getting-started.md) - [安装与配置](getting-started.md)
- [场景示例](cookbook.md) - [场景示例](cookbook.md)
- [命令行工具](cli.md) - [命令行工具](cli.md)
- [DataFrame 输出](dataframe.md)
- **参考** - **参考**
- [接口总览](api/index.md) - [接口总览](api/index.md)
+32 -4
View File
@@ -44,11 +44,21 @@ asyncio.run(main())
标的一律用字符串;以下均为 v0.6 统一接口,跨市场自动选路。 标的一律用字符串;以下均为 v0.6 统一接口,跨市场自动选路。
- **标的清单**:`get_universe`(A股 + 港股 + 美股 + 期货/期权) - **标的清单**:`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_indicators`(K线 + MACD/KDJ/RSI/BOLL/MA/EMA)
- **报价**:`get_quotes`(五档,>80 只自动切批)、`get_snapshot`(个股特征)、`get_market_stat` - **报价**:`get_quotes`(五档,>80 只自动切批;**单连接流水线**默认开启,全市场 5,200 只 A股 ~0.33s)、`get_snapshot`(个股特征)、`get_market_stat`
- **逐笔 / 分时**:`get_ticks`(含 `trade_count`,支持历史日期,返回按时间升序;`vol`/`trade_count` 为约 3 秒切片增量而非累计;已剔除 `bs_flag=8` 竞价委托;**指数**的 `vol` 是百元、`trade_count` 是均价×1000)、`get_minutes`(`sampling=True` 取缩略采样;`hour` 恒为合法时钟值 0~23,美股一个交易日跨两个北京自然日,按交易日聚合用 `MinuteBar.trading_date`、取时刻用 `MinuteBar.datetime`) - 价格标度:协议给的是整数,真实价 = `整数 / 10**小数位`。小数位由 `price_decimal_digits` 决定,
优先用**权威表**(证券清单自带的 `SecurityInfo.decimal_point`,`start()` 每日后台同步一次,
也可 `await td.sync_decimal_points()` 强制刷新),未同步时退回静态前缀规则。
债券/回购是 **4 位**、沪市 B 股 3 位 —— 这里错过两次(整批价格差 100 倍/10 倍)。
- **逐笔 / 分时**:`get_ticks`(含 `trade_count`,支持历史日期,返回按时间升序;`vol`/`trade_count` 为约 3 秒切片增量而非累计;已剔除 `bs_flag=8` 竞价委托;**指数**的 `vol` 是百元、`trade_count` 是均价×1000;**可转债**的 `vol` 是手=10 张、`trade_count` 是真实笔数,故日线 `amount/vol` 是均价的 **10 倍**,算均价要再 /10)、`get_minutes`(`sampling=True` 取缩略采样;`hour` 恒为合法时钟值 0~23,美股一个交易日跨两个北京自然日,按交易日聚合用 `MinuteBar.trading_date`、取时刻用 `MinuteBar.datetime`)
- **财务 / 除权**:`get_finance`(最新快照)、`get_xdxr`、`get_price_limits`(本地计算涨跌停) - **财务 / 除权**:`get_finance`(最新快照)、`get_xdxr`、`get_price_limits`(本地计算涨跌停)
- **F10**:`get_f10`(公司资料目录 + 正文) - **F10**:`get_f10`(公司资料目录 + 正文)
- **板块**:`get_boards`、`get_board_members`、`get_board_of`、`get_board_summary`、 - **板块**:`get_boards`、`get_board_members`、`get_board_of`、`get_board_summary`、
@@ -59,6 +69,24 @@ asyncio.run(main())
> 旧的分通道/市场方法(`get_kline` / `get_transactions` / `get_goods_*` 等共 33 个)保留为 > 旧的分通道/市场方法(`get_kline` / `get_transactions` / `get_goods_*` 等共 33 个)保留为
> deprecated 别名,1.0 移除;完整对照见[接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/)与 CHANGELOG。 > 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 只由后端推断。
## 服务器与配置 ## 服务器与配置
服务器主机来源有一条优先级链(各协议独立):环境变量 → **当日测速缓存** → 包内清单 服务器主机来源有一条优先级链(各协议独立):环境变量 → **当日测速缓存** → 包内清单
+1
View File
@@ -47,6 +47,7 @@ nav:
- 安装与配置: getting-started.md - 安装与配置: getting-started.md
- 场景示例: cookbook.md - 场景示例: cookbook.md
- 命令行工具: cli.md - 命令行工具: cli.md
- DataFrame 输出: dataframe.md
- API 参考: - API 参考:
- 接口总览: api/index.md - 接口总览: api/index.md
- TdxData 方法: api/tdxdata.md - TdxData 方法: api/tdxdata.md
+7 -1
View File
@@ -1,6 +1,6 @@
[project] [project]
name = "pytdxdata" name = "pytdxdata"
version = "0.6.5" version = "0.7.1"
description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权" description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权"
readme = "README.md" readme = "README.md"
requires-python = ">=3.11" requires-python = ">=3.11"
@@ -31,6 +31,9 @@ Documentation = "https://openbot-coder.github.io/pytdxdata/"
[project.optional-dependencies] [project.optional-dependencies]
uvloop = ["uvloop>=0.21"] uvloop = ["uvloop>=0.21"]
pandas = ["pandas>=2.0"]
polars = ["polars>=1.0"]
dataframe = ["pandas>=2.0", "polars>=1.0"]
dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.6"] dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.6"]
[project.scripts] [project.scripts]
@@ -52,6 +55,9 @@ testpaths = ["tests"]
dev = [ dev = [
"pytest>=9.1.1", "pytest>=9.1.1",
"pytest-asyncio>=1.4.0", "pytest-asyncio>=1.4.0",
# DataFrame 后端的双实现都要在本地/CI 里被真实覆盖,不能只在 extras 里声明
"pandas>=2.0",
"polars>=1.0",
] ]
docs = [ docs = [
"mkdocs-material>=9.5", "mkdocs-material>=9.5",
+1 -1
View File
@@ -18,7 +18,7 @@ from .models import (
XdxrRecord, XdxrRecord,
) )
__version__ = "0.6.5" __version__ = "0.7.1"
__all__ = [ __all__ = [
"TdxData", "TdxData",
"Market", "Market",
+650 -51
View File
File diff suppressed because it is too large. Load diff
+32
View File
@@ -90,6 +90,38 @@ class CacheManager:
# 确保清理锁(即使 fetcher 异常也清理,避免无限增长) # 确保清理锁(即使 fetcher 异常也清理,避免无限增长)
self._locks.pop(ks, None) self._locks.pop(ks, None)
async def get_or_fetch_obj(
self,
key: CacheKey,
fetcher: Callable[[], Awaitable[Any]],
*,
pack: Callable[[Any], bytes],
unpack: Callable[[bytes], Any],
) -> Any:
"""同 :meth:`get_or_fetch`,但**回源时直接返回新取到的对象**。
用于「一次取回上千条记录」的场景(如全市场报价):常规路径对冷数据
会先 ``pack`` 再立刻 ``unpack`` 一次,纯属往返浪费 —— 5,200 条报价实测
白烧约 90ms。这里命中缓存才解序列化,回源则把对象原样返回,只在写缓存时打包。
"""
ks = key.to_str()
cached = await self.get(key)
if cached is not None:
return unpack(cached)
lock = self._locks.setdefault(ks, asyncio.Lock())
try:
async with lock:
cached = await self.get(key)
if cached is not None:
return unpack(cached)
async with self._semaphore:
obj = await fetcher()
await self.set(key, pack(obj))
return obj
finally:
self._locks.pop(ks, None)
async def invalidate(self, category: str, *, market: int | None = None, async def invalidate(self, category: str, *, market: int | None = None,
code: str | None = None) -> int: code: str | None = None) -> int:
"""按前缀批量失效,返回失效条数。""" """按前缀批量失效,返回失效条数。"""
+63 -13
View File
@@ -38,6 +38,7 @@ from .api import TdxData
from dataclasses import asdict from dataclasses import asdict
from .models import Adjust, ExMarket, KlinePeriod, Market from .models import Adjust, ExMarket, KlinePeriod, Market
from .protocol.commands.quotes import price_decimal_digits
PERIODS = { PERIODS = {
"min1": KlinePeriod.MIN_1, "min5": KlinePeriod.MIN_5, "min15": KlinePeriod.MIN_15, "min1": KlinePeriod.MIN_1, "min5": KlinePeriod.MIN_5, "min15": KlinePeriod.MIN_15,
@@ -107,6 +108,40 @@ def _pct(price: float, pre: float) -> str:
return "%+.2f%%" % ((price / pre - 1) * 100) return "%+.2f%%" % ((price / pre - 1) * 100)
def _price_fmt(dp: int) -> str:
"""按品种小数位生成右对齐格式串。
股票 2 位、**可转债/ETF 3 位**、债券/回购 4 位。固定写 ``%8.2f`` 会把
可转债的 128.891 打成 128.89(少一位有效报价)。
"""
dp = max(0, min(int(dp or 2), 4))
return "%%%d.%df" % (6 + dp, dp)
# 可转债后缀(解码 4 位,但交易所报价步长 0.001 元,第 4 位恒为 0)
_CB_PREFIX = {1: ("110", "111", "113", "118"), 0: ("123", "127", "128")}
def _display_dp(market: int, code: str) -> int:
"""报价**显示**小数位。
注意 ``price_decimal_digits`` 给的是**解码位数**(原始整数 / 10**dp),
可转债是 4 位;但真实报价是 0.001 元的步长,第 4 位恒为 0,
按 4 位打印只会多一个 ``0``(``128.8920``)。
"""
dp = price_decimal_digits(market, code)
if str(code).startswith(_CB_PREFIX.get(int(market), ())):
return 3
return dp
def _dp_of(sym) -> int:
"""Symbol -> 价格小数位(非 A 股/指数一律 2 位)。"""
if getattr(sym, "kind", "") == "cn":
return _display_dp(sym.market, sym.code)
return 2
# ------------------------------------------------------------------ # # ------------------------------------------------------------------ #
# 各子命令 # 各子命令
# ------------------------------------------------------------------ # # ------------------------------------------------------------------ #
@@ -120,24 +155,31 @@ async def cmd_quotes(td: TdxData, symbols: list[str]) -> None:
def _print_quote(q) -> None: def _print_quote(q) -> None:
pct = (q.price / q.pre_close - 1) * 100 if q.pre_close else 0 pct = (q.price / q.pre_close - 1) * 100 if q.pre_close else 0
mkt = {31: "港股", 74: "美股"}.get(q.market, "") mkt = {31: "港股", 74: "美股"}.get(q.market, "")
if q.market in (0, 1):
dp = _display_dp(q.market, q.code)
else:
dp = getattr(q, "decimal_point", 2) or 2
print("=" * 58) print("=" * 58)
label = "%s %s" % (mkt, q.code) if mkt else "%s %s" % (q.code, q.server_time or datetime.now().strftime("%H:%M:%S")) label = "%s %s" % (mkt, q.code) if mkt else "%s %s" % (q.code, q.server_time or datetime.now().strftime("%H:%M:%S"))
print(" %s" % label) print(" %s" % label)
print(" 最新 %-10.2f 涨跌 %+8.2f (%+.2f%%)" % (q.price, q.price - q.pre_close, pct)) print(" 最新 %-10.*f 涨跌 %+8.*f (%+.2f%%)" % (dp, q.price, dp, q.price - q.pre_close, pct))
print(" 今开 %-10.2f 最高 %.2f 最低 %.2f" % (q.open, q.high, q.low)) print(" 今开 %-10.*f 最高 %.*f 最低 %.*f" % (dp, q.open, dp, q.high, dp, q.low))
print(" 昨收 %-10.2f 成交量 %s 成交额 %s" % (q.pre_close, _fmt_num(q.vol), _fmt_num(q.amount))) print(" 昨收 %-10.*f 成交量 %s 成交额 %s" % (dp, q.pre_close, _fmt_num(q.vol), _fmt_num(q.amount)))
if q.bid and q.ask: if q.bid and q.ask:
print(" " + "-" * 56) print(" " + "-" * 56)
pf = _price_fmt(dp)
for i in range(max(len(q.bid), len(q.ask))): for i in range(max(len(q.bid), len(q.ask))):
b = q.bid[i] if i < len(q.bid) else (0, 0) b = q.bid[i] if i < len(q.bid) else (0, 0)
a = q.ask[i] if i < len(q.ask) else (0, 0) a = q.ask[i] if i < len(q.ask) else (0, 0)
print(" 买%-1d %8.2f %10s | 卖%-1d %8.2f %10s" % ( print((" 买%-1d " + pf + " %10s | 卖%-1d " + pf + " %10s") % (
i + 1, b[0], _fmt_num(b[1]), i + 1, a[0], _fmt_num(a[1]))) i + 1, b[0], _fmt_num(b[1]), i + 1, a[0], _fmt_num(a[1])))
print() print()
async def cmd_kline(td: TdxData, sym: str, period: KlinePeriod, count: int, async def cmd_kline(td: TdxData, sym: str, period: KlinePeriod, count: int,
start: int, adjust: Adjust) -> None: start: int, adjust: Adjust) -> None:
s = parse_symbol(sym)
pf = _price_fmt(_dp_of(s))
bars = await td.get_bars(sym, period, start=start, count=count, adjust=adjust) bars = await td.get_bars(sym, period, start=start, count=count, adjust=adjust)
print("%s K线 (%s, %d根):" % (sym, period.name, len(bars))) print("%s K线 (%s, %d根):" % (sym, period.name, len(bars)))
print(" %-12s %8s %8s %8s %8s %12s" % ("日期", "开盘", "最高", "最低", "收盘", "成交量")) print(" %-12s %8s %8s %8s %8s %12s" % ("日期", "开盘", "最高", "最低", "收盘", "成交量"))
@@ -145,30 +187,38 @@ async def cmd_kline(td: TdxData, sym: str, period: KlinePeriod, count: int,
dt = "%04d-%02d-%02d" % (b.year, b.month, b.day) dt = "%04d-%02d-%02d" % (b.year, b.month, b.day)
if b.hour: if b.hour:
dt += " %02d:%02d" % (b.hour, b.minute) dt += " %02d:%02d" % (b.hour, b.minute)
print(" %-12s %8.2f %8.2f %8.2f %8.2f %12s" % ( print((" %-12s " + " ".join([pf] * 4) + " %12s") % (
dt, b.open, b.high, b.low, b.close, _fmt_num(b.vol))) dt, b.open, b.high, b.low, b.close, _fmt_num(b.vol)))
async def cmd_transactions(td: TdxData, sym: str, count: int, date: int | None) -> None: async def cmd_transactions(td: TdxData, sym: str, count: int, date: int | None) -> None:
s = parse_symbol(sym) s = parse_symbol(sym)
tx = await td.get_transactions(Market(s.market), s.code, date=date, count=count) pf = _price_fmt(_dp_of(s))
tx = await td.get_ticks(sym, date=date, count=count)
print("%s 逐笔成交 (%d条):" % (sym, len(tx))) print("%s 逐笔成交 (%d条):" % (sym, len(tx)))
print(" 时间 价格 成交量 方向") print(" 时间 价格 成交量 方向")
for t in tx: for t in tx:
bs = "买" if getattr(t, "bs_flag", 0) == 1 else "卖" if getattr(t, "bs_flag", 0) == 2 else "-" bs = "买" if getattr(t, "bs_flag", 0) == 1 else "卖" if getattr(t, "bs_flag", 0) == 2 else "-"
tc = getattr(t, "trade_count", 0) if not getattr(t, "trade_count_available", True):
print(" %-10s %8.2f %10s %s%s" % (t.time, t.price, _fmt_num(t.vol), bs, tc = " (-)" # 指数/ETF/LOF:协议不提供笔数
" (%d笔)" % tc if tc else "")) elif getattr(t, "trade_count", 0):
tc = " (%d笔)" % t.trade_count
else:
tc = ""
print((" %-10s " + pf + " %10s %s%s") % (
t.time, t.price, _fmt_num(t.vol), bs, tc))
async def cmd_minute(td: TdxData, sym: str, date: int | None) -> None: async def cmd_minute(td: TdxData, sym: str, date: int | None) -> None:
s = parse_symbol(sym) s = parse_symbol(sym)
bars = await td.get_minute(Market(s.market), s.code, date=date) pf = _price_fmt(_dp_of(s))
bars = await td.get_minutes(sym, date=date)
print("%s 分时 (%d条):" % (sym, len(bars))) print("%s 分时 (%d条):" % (sym, len(bars)))
print(" 时间 价格 均价 成交量") print(" 时间 价格 均价 成交量")
for i, b in enumerate(bars): for b in bars:
print(" %02d:%02d %8.2f %8.2f %10s" % ( # 用 bar 自带时间:早期按序号推算会打成 00:00~03:59
i // 60, i % 60, b.price, b.avg_price, _fmt_num(b.vol))) print((" %02d:%02d " + pf + " " + pf + " %10s") % (
b.hour, b.minute, b.price, b.avg_price, _fmt_num(b.vol)))
async def cmd_board(td: TdxData, args) -> None: async def cmd_board(td: TdxData, args) -> None:
+13
View File
@@ -33,6 +33,7 @@ _SERVERS_FILE = Path(__file__).resolve().parent / "servers.json" # 包内清单
# 当日测速缓存(结构变更时递增,旧版本缓存自动失效) # 当日测速缓存(结构变更时递增,旧版本缓存自动失效)
PROBE_CACHE_VERSION = 1 PROBE_CACHE_VERSION = 1
_PROBE_CACHE_NAME = "hosts-today.json" _PROBE_CACHE_NAME = "hosts-today.json"
_DECIMAL_CACHE_NAME = "decimal-points.json"
# ---------- 包内清单(只读基线) ---------- # ---------- 包内清单(只读基线) ----------
@@ -97,6 +98,18 @@ def probe_cache_file() -> Path:
return probe_cache_dir() / _PROBE_CACHE_NAME return probe_cache_dir() / _PROBE_CACHE_NAME
def decimal_cache_file() -> Path:
"""权威价格小数位表缓存路径(每次调用重新解析,便于测试改环境变量后生效)。"""
return probe_cache_dir() / _DECIMAL_CACHE_NAME
def decimal_sync_disabled() -> bool:
"""是否已通过 ``PYPYTDX_DATA_DISABLE_DECIMAL_SYNC`` 关闭小数位后台同步。"""
return os.environ.get("PYPYTDX_DATA_DISABLE_DECIMAL_SYNC", "").strip().lower() in {
"1", "true", "yes", "on",
}
def probe_disabled() -> bool: def probe_disabled() -> bool:
"""是否已通过 ``PYPYTDX_DATA_DISABLE_PROBE`` 关闭当日测速缓存。""" """是否已通过 ``PYPYTDX_DATA_DISABLE_PROBE`` 关闭当日测速缓存。"""
return os.environ.get("PYPYTDX_DATA_DISABLE_PROBE", "").strip().lower() in { return os.environ.get("PYPYTDX_DATA_DISABLE_PROBE", "").strip().lower() in {
+223
View File
@@ -0,0 +1,223 @@
"""权威价格小数位表的同步与缓存(对用户无感)。
为什么需要它
------------
``get_quotes`` 解析报价时,协议给的是**整数**,真实价格 = ``整数 / 10**小数位``。
小数位在协议里**不是**随报价一起下发的,只能靠推断(见
:func:`pytdxdata.protocol.commands.quotes.price_decimal_digits`)。
但证券清单接口(``get_universe``,底层 ``GetSecurityListCmd``)**自带**这个字段:
``SecurityInfo.decimal_point``,同时还带 ``pre_close``。这就是权威来源。本模块把它
灌进 ``price_decimal_digits`` 使用的运行时表,使价格标度不再依赖硬编码前缀规则。
行为
----
- **当日首次启动**检查缓存文件(``decimal-points.json``):命中就直接装表(纯内存,
无网络、约 10 ms);未命中则挂一个**后台 task** 拉证券清单并写缓存,
当天不再重复。
- 后台 task 不阻塞 ``start()``,不打印、不抛异常(取消除外),失败只落 debug 日志。
- 未同步成功时 ``price_decimal_digits`` 静默退回静态前缀规则,行为与 0.6.5 一致。
- 证券清单本身已被 ``cache/`` 层缓存,因此同步的实际网络开销只在**首次**
(约 26 + 25 个分页请求)。
开关
----
- ``PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1`` 关闭后台同步(CI / 测试用,保证确定性)。
- ``PYPYTDX_DATA_CACHE_DIR`` 覆盖缓存目录(测试指向临时目录)。
"""
from __future__ import annotations
import asyncio
import json
import logging
import os
from datetime import date
from pathlib import Path
from typing import TYPE_CHECKING, Any
from .config import decimal_cache_file, decimal_sync_disabled
from .protocol.commands.quotes import (
clear_decimal_map,
decimal_map_source,
decimal_map_stats,
install_decimal_map,
)
if TYPE_CHECKING: # pragma: no cover
from .api import TdxData
log = logging.getLogger(__name__)
#: 同步哪些市场(只对 A 股有意义:扩展市场报价本身不含标度歧义)
DEFAULT_MARKETS: tuple[str, ...] = ("sh", "sz")
_CN_NAME = {"sh": 1, "sz": 0}
_state: dict[str, Any] = {"loaded": "", "task": None}
# ---------------------------------------------------------------------- #
# 磁盘缓存
# ---------------------------------------------------------------------- #
def cache_file() -> Path:
"""缓存文件路径(每次重新解析,便于测试改环境变量)。"""
return decimal_cache_file()
def _read_cache(path: Path | None = None) -> dict[str, dict[str, int]] | None:
"""读缓存 → ``{"1": {code: dp}}``;缺失 / 损坏 → ``None``。"""
target = Path(path) if path is not None else cache_file()
try:
raw = json.loads(target.read_text(encoding="utf-8"))
except (OSError, ValueError):
return None
if not isinstance(raw, dict):
return None
if raw.get("date") != date.today().isoformat():
return None
markets = raw.get("markets")
if not isinstance(markets, dict) or not markets:
return None
out: dict[str, dict[str, int]] = {}
for k, v in markets.items():
if not isinstance(v, dict):
continue
try:
out[str(int(k))] = {str(c): int(d) for c, d in v.items() if int(d) > 0}
except (TypeError, ValueError):
continue
return out or None
def load_cached(path: Path | None = None) -> int:
"""把当日缓存装进权威表;成功返回覆盖条目数,否则 0。"""
if decimal_sync_disabled():
return 0
markets = _read_cache(path)
if not markets:
return 0
items = [(int(m), c, d) for m, codes in markets.items() for c, d in codes.items()]
stats = install_decimal_map(items, source="cache")
_state["loaded"] = date.today().isoformat()
log.debug("小数位表已从缓存加载: %s", stats)
return int(stats["stock"])
def _write_cache(markets: dict[str, dict[str, int]], path: Path | None = None) -> None:
"""原子写缓存(tmp + ``os.replace``),失败只落 debug 日志。"""
target = Path(path) if path is not None else cache_file()
payload = {"date": date.today().isoformat(), "markets": markets}
tmp = target.with_suffix(".tmp")
try:
target.parent.mkdir(parents=True, exist_ok=True)
tmp.write_text(
json.dumps(payload, ensure_ascii=False, separators=(",", ":")),
encoding="utf-8",
)
os.replace(tmp, target)
except OSError as e: # pragma: no cover - 磁盘不可写等
log.debug("小数位表缓存写入失败: %s", e)
try:
tmp.unlink(missing_ok=True)
except OSError:
pass
# ---------------------------------------------------------------------- #
# 同步
# ---------------------------------------------------------------------- #
async def refresh(td: "TdxData", markets: tuple[str, ...] = DEFAULT_MARKETS,
*, path: Path | None = None) -> dict[str, int]:
"""拉证券清单 → 装表 + 写缓存。返回统计。
证券清单走 ``get_universe``(含 ``cache/`` 层缓存),只有首次真正发请求。
"""
tables: dict[str, dict[str, int]] = {}
items: list[tuple[int, str, int]] = []
for name in markets:
m = _CN_NAME.get(name)
if m is None:
continue
rows = await td.get_universe(name)
table: dict[str, int] = {}
for it in rows:
dp = int(getattr(it, "decimal_point", 0) or 0)
code = str(getattr(it, "code", "") or "").strip().rstrip("\x00")
if dp <= 0 or not code:
continue
table[code] = dp
items.append((m, code, dp))
if table:
tables[str(m)] = table
stats = install_decimal_map(items, source="universe")
_state["loaded"] = date.today().isoformat()
if tables:
_write_cache(tables, path)
log.debug("小数位表同步完成: %s", stats)
return stats
async def _run(td: "TdxData") -> dict[str, int]:
try:
return await refresh(td)
except asyncio.CancelledError:
raise
except Exception as e: # pragma: no cover - 网络/解析异常都不该影响用户
log.debug("小数位表后台同步失败: %s", e)
return {}
def schedule(td: "TdxData") -> asyncio.Task | None:
"""[内部] 需要时把同步挂到后台并返回 Task(调用方持有 / 取消)。
- 已关闭(``PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1``)→ ``None``
- 当日缓存命中 → 立即装表(同步、无网络),返回 ``None``
- 否则创建后台 task;进程内单例,重复调用复用同一个 task
"""
if decimal_sync_disabled():
return None
if decimal_map_stats()["stock"] and _state["loaded"] == date.today().isoformat():
return None
if load_cached():
return None
task = _state.get("task")
if task is not None and not task.done():
return task
task = asyncio.get_running_loop().create_task(_run(td), name="pytdxdata-decimal-sync")
_state["task"] = task
return task
async def cancel(task: asyncio.Task | None) -> None:
"""取消并等待后台同步 task(供 ``TdxData.close()`` 调用)。"""
if task is None or task.done():
return
task.cancel()
try:
await task
except (asyncio.CancelledError, Exception): # noqa: BLE001 - 关闭路径不抛
pass
def status() -> dict[str, Any]:
"""当前状态快照(排障 / 测试用)。"""
task = _state.get("task")
return {
"loaded": _state["loaded"],
"source": decimal_map_source(),
"syncing": bool(task is not None and not task.done()),
**decimal_map_stats(),
}
def reset() -> None:
"""清空内存状态(测试用;不动磁盘缓存)。"""
task = _state.get("task")
if task is not None and not task.done():
task.cancel()
_state["task"] = None
_state["loaded"] = ""
clear_decimal_map()
+522
View File
@@ -0,0 +1,522 @@
"""DataFrame 转换层(0.7.0):把模型列表转成 pandas / polars 的 DataFrame。
为什么单独一层而不是改各方法的返回:
- **零运行时依赖**是项目的硬约束(``dependencies = []``)。pandas / polars 只在
真正用到 ``TdxData(df=...)`` 时才导入,没装就走不到这里。
- 转换口径(哪些列留、时间怎么摆、嵌套字段怎么展开)只写一份,40 个返回表格型
数据的方法共用,不会各自漂移。
三条口径约定(0.7.0 定稿):
1. **时间列替换原始列**:K线/分时的 ``year/month/day/hour/minute`` 不再单列输出,
统一给一列 ``datetime``(pandas 为 ``datetime64[ns]``,polars 为 ``Datetime('us')``),
另带 ``trading_date``(``YYYY-MM-DD`` 字符串,美股跨日口径见模型注释)。
2. **嵌套字段定型**:``SecurityQuote.bid/ask`` 展开成 ``bid1_price``…``ask5_vol`` 共
10 列(缺失为 ``None``);``fields`` 这类不定长字典序列化成 JSON 字符串列,
空字典给 ``None`` 而不是 ``"{}"``;``TdxBlock.codes`` 保持列表。
3. **嵌套调用不二次转换**:``get_kline_batch`` 这类方法内部还会调 ``get_bars``,
用 :data:`_FRAME_DEPTH`(``ContextVar``,按 task 隔离)标记层次,内层一律返回
原始 ``list``,只有最外层那次才转 DataFrame。
"""
from __future__ import annotations
import functools
import json
import re
from collections.abc import Callable, Sequence
from contextvars import ContextVar
from datetime import datetime as _dt
from enum import IntEnum
from operator import attrgetter
from typing import Any, NamedTuple
from . import models as _models
from .models import (
IndexTradeStats,
IndicatorSet,
MinuteBar,
MinuteTradeStat,
SecurityBar,
SecurityQuote,
TransactionRecord,
XdxrRecord,
)
__all__ = ["BACKENDS", "FrameBackendError", "framed", "to_frame"]
BACKENDS: tuple[str, ...] = ("polars", "pandas")
"""支持的后端名,也是 ``TdxData(df=...)`` 的合法取值。"""
class FrameBackendError(ImportError):
"""指定的 DataFrame 后端未安装。
继承 :class:`ImportError` 是刻意的:捕获姿势和缺包一致,
且 ``e.name`` 就是缺的那个包名。
"""
def __init__(self, backend: str) -> None:
self.backend = backend
super().__init__(
f"未安装 {backend},无法输出 DataFrame。请执行:pip install pytdxdata[{backend}]",
name=backend,
)
# 转换层次计数:>0 表示当前正处于某次公开方法的执行过程中(内层),此时不转换。
_FRAME_DEPTH: ContextVar[int] = ContextVar("pytdxdata_frame_depth", default=0)
# ---------------------------------------------------------------- 后端
class _Backend:
"""后端适配:只封装「造表」和「拼表」两个动作。"""
name: str = ""
def frame(self, cols: dict[str, list]) -> Any: # pragma: no cover - 抽象
raise NotImplementedError
def concat(self, frames: Sequence[Any]) -> Any: # pragma: no cover - 抽象
raise NotImplementedError
def empty(self, cols: Sequence[str]) -> Any:
return self.frame({name: [] for name in cols})
class _PolarsBackend(_Backend):
name = "polars"
def __init__(self) -> None:
try:
import polars as _pl
except ImportError as exc: # pragma: no cover - 依赖环境
raise FrameBackendError("polars") from exc
self._pl = _pl
def frame(self, cols: dict[str, list]) -> Any:
# 全空时必须显式给列名,否则 polars 会造出 0 列的表
return self._pl.DataFrame(cols)
def concat(self, frames: Sequence[Any]) -> Any:
frames = [f for f in frames if f is not None and f.height > 0]
if not frames:
return None
if len(frames) == 1:
return frames[0]
# vertical_relaxed:批量接口各标的分块建表,dtype 可能略有差异(如 Null 列)
return self._pl.concat(frames, how="vertical_relaxed")
class _PandasBackend(_Backend):
name = "pandas"
def __init__(self) -> None:
try:
import pandas as _pd
except ImportError as exc: # pragma: no cover - 依赖环境
raise FrameBackendError("pandas") from exc
self._pd = _pd
def frame(self, cols: dict[str, list]) -> Any:
return self._pd.DataFrame(cols)
def concat(self, frames: Sequence[Any]) -> Any:
frames = [f for f in frames if f is not None and len(f) > 0]
if not frames:
return None
if len(frames) == 1:
return frames[0]
return self._pd.concat(frames, ignore_index=True)
_BACKEND_CACHE: dict[str, _Backend] = {}
def get_backend(name: str) -> _Backend:
"""取后端实例(进程内缓存,重复取不会重复 import)。
:raises ValueError: 名字不在 :data:`BACKENDS` 里。
:raises FrameBackendError: 对应的包没装。
"""
if name not in BACKENDS:
raise ValueError(f"未知的 DataFrame 后端 {name!r},可选:{', '.join(BACKENDS)}")
be = _BACKEND_CACHE.get(name)
if be is None:
be = _PolarsBackend() if name == "polars" else _PandasBackend()
_BACKEND_CACHE[name] = be
return be
# ---------------------------------------------------------------- 列计划
def _as_int(value: Any) -> Any:
"""``IntEnum`` 转纯 ``int``:polars 对 IntEnum 的类型推断不可靠,转掉最稳。"""
if isinstance(value, IntEnum):
return int(value)
return value
def _json_or_none(value: Any) -> str | None:
"""不定长字典序列化成 JSON 列;空字典给 ``None``(别让用户看到一列 ``"{}"``)。"""
if not value:
return None
return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
def _json_getter(name: str) -> Callable[[Any], Any]:
def _get(row: Any) -> Any:
return _json_or_none(getattr(row, name))
return _get
def _level_getter(side: str, index: int, pos: int) -> Callable[[Any], Any]:
"""``bid``/``ask`` 第 ``index`` 档的价格(pos=0)或数量(pos=1)。"""
def _get(row: Any) -> Any:
levels = getattr(row, side)
if len(levels) <= index:
return None
return levels[index][pos]
return _get
def _moment(row: SecurityBar | MinuteBar) -> _dt:
return row.datetime
def _trading_date(row: SecurityBar | MinuteBar) -> str:
return row.trading_date
def _xdxr_day(row: XdxrRecord) -> _dt:
# 除权日是「日」不是「时刻」,但 datetime64 / Datetime 才是可排序、可比较的列类型。
# 全项目时间口径都是「不带 tzinfo 的北京时间」,这里保持一致。
return _dt(row.year, row.month, row.day) # noqa: DTZ001
#: 模型 -> 需要丢弃的原始字段(时间拆解字段,由增强列替代)
_DROPS: dict[type, tuple[str, ...]] = {
SecurityBar: ("year", "month", "day", "hour", "minute"),
MinuteBar: ("hour", "minute", "date", "day_offset"),
XdxrRecord: ("year", "month", "day"),
SecurityQuote: ("bid", "ask"),
}
#: 模型 -> 在「第一个被丢弃字段的位置」插入的增强列
_EXTRAS: dict[type, tuple[tuple[str, Callable[[Any], Any]], ...]] = {
SecurityBar: (("datetime", _moment), ("trading_date", _trading_date)),
MinuteBar: (("datetime", _moment), ("trading_date", _trading_date)),
XdxrRecord: (("date", _xdxr_day),),
SecurityQuote: tuple(
(f"{side}{level + 1}_{part}", _level_getter(side, level, pos))
for side in ("bid", "ask")
for level in range(5)
for pos, part in ((0, "price"), (1, "vol"))
),
}
#: 模型 -> 需要 JSON 化的字典字段(按类区分,避免误伤 ``FinancialRecord.fields: list[float]``)
_JSON_FIELDS: dict[type, frozenset[str]] = {
SecurityQuote: frozenset({"fields"}),
TransactionRecord: frozenset({"fields"}),
MinuteBar: frozenset({"fields"}),
}
#: 交易日列的缓存键(时间字段里参与 ``trading_date`` 计算的那些)。
#:
#: ``trading_date`` 是纯函数:A股/港股/期货就是自然日,美股凌晨段回退一天。
#: 但它每算一次都要格式化三个整数(美股还要减一天),240k 行里往往只有
#: **1~2 个不同的键** —— 按「除 minute 外的时间字段」缓存后,整列从 218ms 降到 33ms。
#: 键里保留 ``hour`` 是为了一箭双雕:既覆盖美股 ``hour < 12`` 的跨日判断,
#: 又不必把 ``_US_DAY_SPLIT_HOUR`` 的取值抄过来(切换点改了本文件也不用跟着改)。
_TD_KEYS: dict[type, tuple[str, ...]] = {
SecurityBar: ("year", "month", "day", "hour"),
MinuteBar: ("date", "day_offset", "hour"),
}
#: 交易日列名(走缓存路径,不按行取属性)
_TD_COL = "trading_date"
#: 增强列里可以直接用 ``attrgetter`` 取的(属性本身即得值,不需要额外加工)
_PLAIN_EXTRAS = frozenset({"datetime"})
class _ColPlan(NamedTuple):
"""某模型的输出列计划(构造一次,按类缓存)。
分成三类是性能决定的:逐行调 Python 闭包比 C 层 ``attrgetter`` 慢一倍以上,
而 ``trading_date`` 这种「同一批里值大量重复」的列更是值得单独缓存。
"""
order: tuple[str, ...] # 输出列顺序
plain: tuple[str, ...] # 直接取属性即可的列名
wrapped: tuple[tuple[str, Callable[[Any], Any]], ...] # 需要加工的列(JSON / 五档 / 除权日)
td_name: str | None # 交易日列名
td_key: Callable[[Any], Any] | None # 交易日缓存键
_PLAN_CACHE: dict[type, _ColPlan] = {}
def _plan_for(cls: type) -> _ColPlan:
"""构造(并缓存)某模型的输出列计划。
查找顺序按 MRO 走:``IndexBar`` 没有自己的计划,但它是 ``SecurityBar`` 的子类,
直接复用父类计划即可(字段完全相同)。
"""
cached = _PLAN_CACHE.get(cls)
if cached is not None:
return cached
drops: tuple[str, ...] = ()
extras: tuple[tuple[str, Callable[[Any], Any]], ...] = ()
json_fields: frozenset[str] = frozenset()
td_fields: tuple[str, ...] = ()
for klass in cls.__mro__:
if not drops and klass in _DROPS:
drops = _DROPS[klass]
if not extras and klass in _EXTRAS:
extras = _EXTRAS[klass]
if not json_fields and klass in _JSON_FIELDS:
json_fields = _JSON_FIELDS[klass]
if not td_fields and klass in _TD_KEYS:
td_fields = _TD_KEYS[klass]
import dataclasses
order: list[str] = []
plain: list[str] = []
wrapped: list[tuple[str, Callable[[Any], Any]]] = []
td_name: str | None = None
def add(name: str, getter: Callable[[Any], Any] | None = None) -> None:
nonlocal td_name
order.append(name)
if name == _TD_COL:
td_name = name # 交易日列走缓存,不看 getter
elif getter is None or name in _PLAIN_EXTRAS:
plain.append(name)
else:
wrapped.append((name, getter))
inserted = False
for f in dataclasses.fields(cls): # type: ignore[arg-type]
if f.name in drops:
if not inserted:
for name, getter in extras:
add(name, getter)
inserted = True
continue
add(f.name, _json_getter(f.name) if f.name in json_fields else None)
if not inserted:
# 没有丢弃字段的模型(如 SecurityInfo):增强列直接追加到末尾
for name, getter in extras:
add(name, getter)
plan = _ColPlan(
order=tuple(order),
plain=tuple(plain),
wrapped=tuple(wrapped),
td_name=td_name,
td_key=attrgetter(*td_fields) if td_fields else None,
)
_PLAN_CACHE[cls] = plan
return plan
def _trading_dates(key_of: Callable[[Any], Any], rows: Sequence[Any]) -> list[str]:
"""按缓存键批量算交易日串(同一批里绝大多数行是重复键)。"""
cache: dict[Any, str] = {}
out: list[str] = []
ap = out.append
for row in rows:
key = key_of(row)
value = cache.get(key)
if value is None: # trading_date 永远是字符串,不会与 None 混淆
value = cache[key] = row.trading_date
ap(value)
return out
def _columns(cls: type, rows: Sequence[Any]) -> dict[str, list]:
"""列式采集:逐列一次遍历,比逐行 ``asdict()`` 快得多。
- 普通列用 ``list(map(attrgetter(name), rows))``:取值发生在 C 层,没有 Python 帧;
- ``trading_date`` 按时间字段缓存(240k 行常只有 1~2 个键);
- 其余列(JSON / 五档 / 除权日)才走逐行回调;
- ``IntEnum`` 归一化放在最后**按列**做一次,而不是每个单元格都判一次。
"""
plan = _plan_for(cls)
if not rows:
return {name: [] for name in plan.order}
cols: dict[str, list] = {}
for name in plan.plain:
cols[name] = list(map(attrgetter(name), rows))
if plan.td_name is not None and plan.td_key is not None:
cols[plan.td_name] = _trading_dates(plan.td_key, rows)
for name, get in plan.wrapped:
cols[name] = [get(row) for row in rows]
# polars 对 IntEnum 的类型推断不可靠(会退化成 Object 列),统一转纯 int。
# 只在首元素就是 IntEnum 时才整列转,普通 int 列一次都不多花。
for name, col in cols.items():
if col and isinstance(col[0], IntEnum):
cols[name] = [_as_int(value) for value in col]
return {name: cols[name] for name in plan.order}
def _columns_of_dicts(rows: Sequence[dict]) -> dict[str, list]:
"""``list[dict]``(板块排行这类字段不固定的返回)按首次出现顺序并集列名。"""
keys: list[str] = []
seen: set[str] = set()
for row in rows:
for key in row:
if key not in seen:
seen.add(key)
keys.append(key)
return {key: [row.get(key) for row in rows] for key in keys}
# ---------------------------------------------------------------- 容器分发
def _model_by_name(name: str | None) -> type | None:
if not name:
return None
obj = getattr(_models, name, None)
return obj if isinstance(obj, type) else None
def _resolve_model(data: Any, model: str | None) -> type | None:
"""推断元素类型:非空列表看首元素;空列表只能靠调用方给的类型提示。"""
if isinstance(data, list) and data:
return type(data[0])
return _model_by_name(model)
def _frames_of_rows(be: _Backend, cls: type | None, rows: Sequence[Any]) -> Any:
if cls is not None and rows and hasattr(cls, "__dataclass_fields__"):
return be.frame(_columns(cls, rows))
if rows and isinstance(rows[0], dict):
return be.frame(_columns_of_dicts(rows))
return be.empty(())
def _from_indicator_sets(be: _Backend, items: Sequence[IndicatorSet]) -> Any:
frames = []
for item in items:
cols = _columns(SecurityBar, item.bars)
size = len(item.bars)
if item.symbol:
cols["symbol"] = [item.symbol] * size
for name, series in item.indicators.items():
values = list(series[:size])
if len(values) < size:
values.extend([None] * (size - len(values)))
cols[name] = values
frames.append(be.frame(cols))
merged = be.concat(frames)
return merged if merged is not None else be.frame(_columns(SecurityBar, []))
def _from_index_trade_stats(be: _Backend, items: Sequence[IndexTradeStats]) -> Any:
frames = []
for stat in items:
cols = _columns(MinuteTradeStat, stat.minutes)
size = len(stat.minutes)
# 元信息补成常量列:一张表就能看出是哪个指数、哪一天
cols = {"index": [stat.index] * size, "date": [stat.date] * size, **cols}
frames.append(be.frame(cols))
merged = be.concat(frames)
return merged if merged is not None else be.frame(_columns(MinuteTradeStat, []))
def to_frame(data: Any, *, backend: str = "polars", model: str | None = None) -> Any:
"""把模型返回值转成 DataFrame。
:param data: ``list[dataclass]`` / ``list[dict]`` / ``dict[str, list[dataclass]]``
/ ``list[IndicatorSet]`` / ``IndexTradeStats`` / ``list[IndexTradeStats]``。
:param backend: ``"polars"`` 或 ``"pandas"``。
:param model: 元素类型的名字(如 ``"SecurityBar"``);只在 ``data`` 为空、
无法从元素推断类型时使用,由 :func:`framed` 从返回注解里自动填。
"""
be = get_backend(backend)
if isinstance(data, IndexTradeStats):
return _from_index_trade_stats(be, [data])
if isinstance(data, IndicatorSet):
return _from_indicator_sets(be, [data])
if isinstance(data, dict):
# 批量接口:{标的: [行]} → 拼成一张表(symbol/code 列本来就在行里)
frames = []
for rows in data.values():
if isinstance(rows, list) and rows:
frames.append(_frames_of_rows(be, type(rows[0]), rows))
merged = be.concat(frames)
if merged is not None:
return merged
cls = _model_by_name(model)
return be.empty(_plan_for(cls).order if cls else ())
if isinstance(data, list):
if data and isinstance(data[0], IndexTradeStats):
return _from_index_trade_stats(be, data)
if data and isinstance(data[0], IndicatorSet):
return _from_indicator_sets(be, data)
cls = _resolve_model(data, model)
if data and isinstance(data[0], dict):
return _frames_of_rows(be, None, data)
if cls is not None and data and hasattr(cls, "__dataclass_fields__"):
return _frames_of_rows(be, cls, data)
if data:
# 元素既不是 dataclass 也不是 dict(如 list[float])——不该走到这里
raise TypeError(f"无法转换为 DataFrame 的列表元素:{type(data[0])!r}")
return (be.frame({name: [] for name in _plan_for(cls).order})
if cls else be.empty(()))
raise TypeError(f"无法转换为 DataFrame 的返回值类型:{type(data)!r}")
# ---------------------------------------------------------------- 接线
_RETURN_MODEL = re.compile(r"list\[(\w+)\]")
def framed(method: Callable[..., Any]) -> Callable[..., Any]:
"""给 ``TdxData`` 的表格型方法套一层「按需转 DataFrame」。
- ``self._df_backend is None``(默认)时零开销,原样返回 ``list[dataclass]``。
- 处于某次公开方法执行过程中(:data:`_FRAME_DEPTH` > 0)时不转换,
保证批量/别名方法内部拿到的仍是原始 ``list``。
"""
model: str | None = None
annotation = getattr(method, "__annotations__", {}).get("return")
if isinstance(annotation, str):
matched = _RETURN_MODEL.search(annotation)
if matched:
model = matched.group(1)
@functools.wraps(method)
async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
backend = getattr(self, "_df_backend", None)
if backend is None or _FRAME_DEPTH.get() > 0:
return await method(self, *args, **kwargs)
token = _FRAME_DEPTH.set(1)
try:
result = await method(self, *args, **kwargs)
finally:
_FRAME_DEPTH.reset(token)
return to_frame(result, backend=backend, model=model)
return wrapper
+60 -5
View File
@@ -103,6 +103,10 @@ _US_EX_MARKETS: frozenset[int] = frozenset({int(ExMarket.US_STOCK)})
_US_DAY_SPLIT_HOUR = 12 _US_DAY_SPLIT_HOUR = 12
# SecurityBar 上「后加的」可选字段:旧磁盘缓存反序列化时要补默认值(见 __setstate__)
_BAR_LATE_FIELDS: tuple[str, ...] = ("settle",)
@dataclass(slots=True) @dataclass(slots=True)
class SecurityBar: class SecurityBar:
"""K线记录(价格单位:元)。跨市场统一模型(A股/港股/美股/期货共用)。 """K线记录(价格单位:元)。跨市场统一模型(A股/港股/美股/期货共用)。
@@ -110,6 +114,10 @@ class SecurityBar:
时间戳口径**统一为北京时间**:A股/港股/期货原始即为北京时间;美股原始是 时间戳口径**统一为北京时间**:A股/港股/期货原始即为北京时间;美股原始是
「日期=美东交易日 + 时分=北京时间」的混合值,构造时已还原为真实北京时间 「日期=美东交易日 + 时分=北京时间」的混合值,构造时已还原为真实北京时间
(见 ``__post_init__``)。该 bar 归属的交易日见 :attr:`trading_date`。 (见 ``__post_init__``)。该 bar 归属的交易日见 :attr:`trading_date`。
``amount`` / ``settle`` 的可取性**按通道**:A股标准/MAC 通道两者都有;
EX 通道(0x23FF)一个 32B 记录里只有**一个** 4B 槽位可复用,权益类市场用它
装成交额、期货期权类用它装结算价,两者不可能同时拿到 —— 详见 :attr:`amount`。
""" """
market: int market: int
code: str code: str
@@ -117,14 +125,36 @@ class SecurityBar:
high: float high: float
low: float low: float
close: float close: float
vol: float # 股票=股 / 转债=手(与vipdoc一致) # vol 单位按品种:A股/ETF/美股=股;转债=手(1手=10张);⚠️港股主板/基金=手(1手=100股)
amount: float # 元 vol: float
# 元。⚠️ amount/vol 只在 A股上等于均价;转债还要再 /10(手=10张)、港股再 /100(手=100股)。
# ⚠️ EX 通道的期货/期权(中金所、上期所、郑商所、大商所及各期权)协议帧内**没有成交额**,
# 恒为 0.0 —— 要成交额请改用 EX 报价(``get_quotes``)或其它数据源。
amount: float
year: int year: int
month: int month: int
day: int day: int
hour: int = 0 hour: int = 0
minute: int = 0 minute: int = 0
symbol: str = "" # 规范化标的串(sz000001 / hk00700),由 API 层填充 symbol: str = "" # 规范化标的串(sz000001 / hk00700),由 API 层填充
# 结算价。仅 EX 通道的**期货/期权**有(日线才有值,分钟线为 None);其余通道恒 None。
settle: float | None = None
def __setstate__(self, state: Any) -> None:
"""反序列化兜底:早期版本写下的磁盘缓存里没有后加的可选字段(如 ``settle``)。
``@dataclass(slots=True)`` 的默认反序列化只把 pickle 里存在的槽位塞回去,
缺键的槽位**不会**被赋默认值 —— 直接读 ``bar.settle`` 会抛 ``AttributeError``。
缓存键里没有 schema 版本号,所以这里必须容错,否则升级后读旧缓存即崩。
"""
if isinstance(state, tuple) and len(state) == 2: # slots 形式的 (dict, slots)
data = dict(state[1] or {})
else:
data = dict(state or {})
for name in _BAR_LATE_FIELDS:
data.setdefault(name, None)
for key, value in data.items():
object.__setattr__(self, key, value)
def __post_init__(self) -> None: def __post_init__(self) -> None:
"""美股(EX 通道)时间戳归一化:还原成真实北京时间。 """美股(EX 通道)时间戳归一化:还原成真实北京时间。
@@ -247,17 +277,42 @@ class TransactionRecord:
- ``trade_count`` **不是笔数**,而是**当时均价 × 1000**(实测 tc/1000 与分时 - ``trade_count`` **不是笔数**,而是**当时均价 × 1000**(实测 tc/1000 与分时
``avg_price`` 的差 < 1.1)。指数没有「成交笔数」概念。 ``avg_price`` 的差 < 1.1)。指数没有「成交笔数」概念。
- ``bs_flag`` 语义不成立(实测返回 2,而模型只定义 0=卖 / 1=买)。 - ``bs_flag`` 语义不成立(实测返回 2,而模型只定义 0=卖 / 1=买)。
**场内基金同样没有笔数**(ETF / 多数 LOF,见
:func:`~pytdxdata.symbols.has_order_count`):
- ``trade_count`` 是 ``价格 × 1000``(实测 ``sh510310`` 收盘 tc=3994,
当时价 3.989 → 3989,偏差 σ≈2;货币 ETF ``sh511990`` 恒为 0)。
- ``vol`` 仍是**手**,``bs_flag`` 正常。
- 这类标的的 :attr:`trade_count_available` 为 ``False``,``trade_count`` 已被
置 ``0``,不要拿去求和/求均值。
``trade_count_available=False`` 表示该品种**协议上就不带笔数**,
与「本切片恰好 0 笔」不是一回事。
**可转债(110/111/113/118/123/127/128/132)三样都是真的**(实测 2026-10-22,
16 只 A股可转债当日 + 8 只历史日全部自洽):
- ``vol`` 单位是**手**(1 手 = 10 张),与股票逐笔一致;``trade_count`` 是**真实成交笔数**
(``sh111000`` 3631 条切片 / 20443 笔,可转债在
:func:`~pytdxdata.symbols.has_order_count` 里判为**可用**)。
- ``Σvol`` 与**日线** ``SecurityBar.vol`` **1:1 相等**(比值 1.000000)——
这点和股票相反:股票逐笔是「手」、日线是「股」,Σ比值是 **0.01**。
- ⚠️ 但**日线** ``amount / vol`` **不等于**均价,而是均价的 **10 倍**(``vol`` 的「手」= 10 张)。
要算可转债均价须用 ``amount / vol / 10``;股票则是 ``amount / vol`` 直接就对。
实测:``sz127025`` 逐笔 VWAP 105.9063 vs ``amount/vol`` 1059.0957,比值 10.0003。
""" """
market: int market: int
code: str code: str
time: str # HH:MM:SS(扩展市场为 HH:MM) time: str # HH:MM:SS(扩展市场为 HH:MM)
price: float price: float
vol: float # 股票=手;指数=百元(成交额/100),见类注释 vol: float # 股票/转债=手;指数=百元(成交额/100),见类注释
trade_count: int # 股票=笔数增量;指数=均价×1000,见类注释 trade_count: int # 股票=笔数增量;指数/基金=占位值,见类注释
bs_flag: int # 1=主动买 0=主动卖 2=中性 5=盘后固定价(指数语义不成立) bs_flag: int # 1=主动买 0=主动卖 2=中性 5=盘后固定价(指数语义不成立)
symbol: str = "" symbol: str = ""
fields: dict[str, float] = field(default_factory=dict) # 扩展市场额外字段(增仓等) fields: dict[str, float] = field(default_factory=dict) # 扩展市场额外字段(增仓等)
trade_count_available: bool = True # 指数/ETF/LOF 为 False(协议无笔数字段)
@dataclass(slots=True) @dataclass(slots=True)
@@ -268,7 +323,7 @@ class MinuteBar:
:attr:`datetime` / :attr:`trading_date`,不要自己拿 ``hour`` 拼日期。 :attr:`datetime` / :attr:`trading_date`,不要自己拿 ``hour`` 拼日期。
""" """
price: float price: float
vol: float vol: float # 手(股票/转债同);Σ分时vol 与当日日线 vol 同口径
avg_price: float = 0.0 # 均价(协议第2字段) avg_price: float = 0.0 # 均价(协议第2字段)
hour: int = 0 hour: int = 0
minute: int = 0 minute: int = 0
+54
View File
@@ -3,6 +3,7 @@ from __future__ import annotations
import asyncio import asyncio
import time import time
from collections.abc import Sequence
from typing import Generic, TypeVar from typing import Generic, TypeVar
from ..protocol.commands.base import BaseCommand from ..protocol.commands.base import BaseCommand
@@ -22,6 +23,7 @@ class TdxConnection(Generic[T]):
self._reader: asyncio.StreamReader | None = None self._reader: asyncio.StreamReader | None = None
self._writer: asyncio.StreamWriter | None = None self._writer: asyncio.StreamWriter | None = None
self._last_result: T | None = None self._last_result: T | None = None
self._pipeline_result: list[T] = []
@property @property
def alive(self) -> bool: def alive(self) -> bool:
@@ -107,6 +109,58 @@ class TdxConnection(Generic[T]):
body = decompress_body(header, raw_body) body = decompress_body(header, raw_body)
self._last_result: T = cmd.parse_response(body) self._last_result: T = cmd.parse_response(body)
async def execute_pipeline(
self, cmds: Sequence[BaseCommand[T]], *, timeout: float | None = None
) -> list[T]:
"""单连接**流水线**:一次性发出全部请求,再按序读取全部响应。
通达信协议是自描述长度帧(16 字节帧头 + body),且服务器**按序**应答,
因此可以在同一 TCP 连接上连续下发多条请求、省掉 ``(N-1)`` 次往返。
实测 66 个「80 只报价」请求:逐条 7,372ms → 流水线 526ms(14 倍)。
与 :meth:`execute` 的关键差异:``execute`` 逐条严格配对,失败可小范围重试;
流水线一旦中途失败,**响应流已错配**,剩余响应无法再与请求对齐,
故此处强制断开连接(上层应换连接重试)。
参数:
cmds: 同一连接的请求序列(通常为同一类命令的不同分片)。
timeout: 整体超时(默认 ``self.timeout * 2``,流水线耗时随条数增长)。
返回:
与 ``cmds`` **等长且同序**的结果列表。
"""
if not cmds:
return []
if not self.alive:
raise ConnectionError(f"连接未建立或已关闭: {self.host}")
assert self._reader is not None and self._writer is not None
budget = timeout if timeout is not None else self.timeout * 2
try:
try:
await asyncio.wait_for(self._io_pipeline(cmds), budget)
except asyncio.TimeoutError:
self._force_close()
raise ConnectionError(
f"流水线超时 {self.host} ({budget:.1f}s, {len(cmds)} 条)") from None
except (ConnectionError, OSError) as e:
self._force_close()
raise ConnectionError(f"流水线错误 {self.host}: {e}") from e
except (ConnectionError, OSError):
raise
return self._pipeline_result
async def _io_pipeline(self, cmds: Sequence[BaseCommand[T]]) -> None:
assert self._reader is not None and self._writer is not None
self._writer.write(b"".join(c.build_request() for c in cmds))
await self._writer.drain()
results: list[T] = []
for cmd in cmds:
header_buf = await self._recv_exact(HEADER_SIZE)
header = parse_header(header_buf)
raw_body = await self._recv_exact(header.zipsize)
results.append(cmd.parse_response(decompress_body(header, raw_body)))
self._pipeline_result: list[T] = results
async def _send_setup(self) -> None: async def _send_setup(self) -> None:
"""按序发送3条握手命令并丢弃响应。""" """按序发送3条握手命令并丢弃响应。"""
assert self._reader is not None and self._writer is not None assert self._reader is not None and self._writer is not None
+45
View File
@@ -59,6 +59,11 @@ class PooledConnection:
self.last_used = time.monotonic() self.last_used = time.monotonic()
return await self.conn.execute(cmd) return await self.conn.execute(cmd)
async def execute_pipeline(self, cmds, *, timeout: float | None = None):
"""在同一条连接上流水线执行多条命令(见 TdxConnection.execute_pipeline)。"""
self.last_used = time.monotonic()
return await self.conn.execute_pipeline(cmds, timeout=timeout)
async def close(self) -> None: async def close(self) -> None:
self.alive = False self.alive = False
try: try:
@@ -273,6 +278,46 @@ class DynamicPool:
] ]
return random.choice(alive) if alive else None return random.choice(alive) if alive else None
async def warm(self, n: int) -> None:
"""并发预建连接至 ``n`` 条(最多到 ``max_size``)。
:meth:`acquire` 建连时持有池锁,**一次只能建一条**——22 路并发首次
调用会排队 22×握手时间(实测全市场首拉多花 5~6s)。大批量请求前先调
本方法把连接并发建好,首拉只多付一次握手。
失败静默忽略:缺的连接后续由 ``acquire`` 按需补齐。
"""
if self._closed:
return
need = min(n, self.max_size) - self._total
if need <= 0:
return
# 用局部计数挑 host,避免并发建连时反复选中同一台
counts = dict(self._server_count)
ranked = self.health.rank(self.servers)
hosts: list[str] = []
for _ in range(need):
host = next((h for h in ranked
if not self.health.in_cooldown(h)
and counts.get(h, 0) < self.per_server_cap), None)
if host is None:
break
hosts.append(host)
counts[host] = counts.get(host, 0) + 1
if not hosts:
return
results = await asyncio.gather(
*(self._new_conn(h) for h in hosts), return_exceptions=True)
async with self._lock:
for pc in results:
if isinstance(pc, PooledConnection):
self._total += 1
self.stats.total = self._total
if not self._closed and pc.alive:
self._idle.append(pc)
async def release(self, pc: PooledConnection, *, broken: bool = False) -> None: async def release(self, pc: PooledConnection, *, broken: bool = False) -> None:
if self.stats.borrowed > 0: if self.stats.borrowed > 0:
self.stats.borrowed -= 1 self.stats.borrowed -= 1
+48 -6
View File
@@ -4,9 +4,24 @@ from __future__ import annotations
import struct import struct
from ..._binary import unpack_from from ..._binary import unpack_from
from ...models import ExMarket
from ..datetime_ import get_datetime from ..datetime_ import get_datetime
from .base import BaseCommand from .base import BaseCommand
# 0x23FF 的「槽位 5 是成交额」的市场集合(其余市场该槽位是持仓量、槽位 7 是结算价)。
# 实测依据(2026-10-28,日线,逐条校验 成交额/(close×vol)):
# 31 港股主板 = 100.0(vol 单位手,1手=100股)、49 港股基金 = 100.3、
# 48 港股创业板 ≈1.0、44 新三板 ≈0.99、74 美股 ≈1.0(vol 单位股)。
# ⚠️ 27 港股指数 / 62 中证指数 该槽位既非成交额也非结算价(量级对不上),故**不在**表内,
# 保持 amount=0.0 的原始行为,避免给出可疑数值。
_EX_AMOUNT_MARKETS: frozenset[int] = frozenset({
int(ExMarket.HK_MAIN_BOARD),
int(ExMarket.HK_GEM),
int(ExMarket.HK_FUND),
int(ExMarket.NEEQ),
int(ExMarket.US_STOCK),
})
# pytdx EX setup 握手命令(完整84B: 12B帧头+72B body, 0x2454)—— 与MAC EX login同ID不同body # pytdx EX setup 握手命令(完整84B: 12B帧头+72B body, 0x2454)—— 与MAC EX login同ID不同body
EX_SETUP_CMD = bytes.fromhex("0101486500015200520054241f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb41cce16dffd5ba3fb8cbc57a054f7748ea") EX_SETUP_CMD = bytes.fromhex("0101486500015200520054241f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb411f32c6e5d53dfb41cce16dffd5ba3fb8cbc57a054f7748ea")
@@ -57,7 +72,24 @@ class GetMarketsCmd(BaseCommand[list[dict]]):
class GetExInstrumentBarsCmd(BaseCommand[list[dict]]): class GetExInstrumentBarsCmd(BaseCommand[list[dict]]):
"""EX商品K线(0x23FF, 32B/条: 4B时间戳+28B行情)。""" """EX商品K线(0x23FF, 32B/条: 4B时间戳+28B行情)。
后 28B 的字段语义**按市场分两类**(2026-10-28 全市场实测,见 ``_EX_AMOUNT_MARKETS``):
* 权益类(港股主板/创业板/基金、新三板、美股)::
open(4) high(4) low(4) close(4) 成交额(4f) 成交量(4I) 保留(4f)
成交额可用;校验 ``成交额 / (close × 成交量)`` = 100.0(港股主板/基金,
``vol`` 单位是「手」=100 股)或 ≈1.0(港股创业板/新三板/美股,``vol`` 单位是股)。
* 期货期权类(中金所/上期所/郑商所/大商所及各期权)::
open(4) high(4) low(4) close(4) 持仓量(4I) 成交量(4I) 结算价(4f)
**协议帧内没有成交额**(``amount`` 恒 0.0,不是解析漏读);末位 float 是结算价,
日线有值、分钟线为 0(``settle`` 归一化成 ``None``)。
"""
def __init__(self, market: int, code: str, category: int = 0, def __init__(self, market: int, code: str, category: int = 0,
start: int = 0, count: int = 700) -> None: start: int = 0, count: int = 700) -> None:
@@ -76,6 +108,7 @@ class GetExInstrumentBarsCmd(BaseCommand[list[dict]]):
if len(body) < 20: if len(body) < 20:
return [] return []
(ret_count,) = unpack_from("<H", body, 18, "ex bars count") (ret_count,) = unpack_from("<H", body, 18, "ex bars count")
amount_market = self.market in _EX_AMOUNT_MARKETS
items: list[dict] = [] items: list[dict] = []
off = 20 off = 20
for _ in range(ret_count): for _ in range(ret_count):
@@ -83,14 +116,23 @@ class GetExInstrumentBarsCmd(BaseCommand[list[dict]]):
break break
# 时间4字节按category分格式:分钟级=2B zipday+2B tminutes;日线及以上=YYYYMMDD # 时间4字节按category分格式:分钟级=2B zipday+2B tminutes;日线及以上=YYYYMMDD
year, month, day, hour, minute, _ = get_datetime(self.category, body, off) year, month, day, hour, minute, _ = get_datetime(self.category, body, off)
open_, high, low, close, position, trade, _ = struct.unpack( raw = body[off + 4: off + 32]
"<ffffIIf", body[off + 4: off + 32]) open_, high, low, close = struct.unpack("<ffff", raw[:16])
items.append({ item = {
"year": year, "month": month, "day": day, "year": year, "month": month, "day": day,
"hour": hour, "minute": minute, "hour": hour, "minute": minute,
"open": open_, "high": high, "low": low, "close": close, "open": open_, "high": high, "low": low, "close": close,
"position": position, "trade": trade, }
}) if amount_market:
# 权益类:槽位 5 = 成交额(float),槽位 7 语义未知(保留不用)
amount, trade, _reserved = struct.unpack("<fIf", raw[16:28])
item.update(amount=amount, trade=trade, position=0, settle=None)
else:
# 期货/期权:槽位 5 = 持仓量,槽位 7 = 结算价(分钟线为 0 → None)
position, trade, settle = struct.unpack("<IIf", raw[16:28])
item.update(amount=0.0, trade=trade, position=position,
settle=settle or None)
items.append(item)
off += 32 off += 32
return items return items
+124 -19
View File
@@ -12,30 +12,93 @@ from .base import BaseCommand
MAX_QUOTES = 80 MAX_QUOTES = 80
def price_decimal_digits(market: int, code: str) -> int: # ====================================================================== #
"""推断报价的小数位:**协议原始整数除以 ``10**该值``** 才是真实价格。 # 权威小数位表(由证券清单 SecurityInfo.decimal_point 灌入)
# ====================================================================== #
# 查找顺序:**权威表 → 静态前缀规则**。权威表来自 ``get_universe`` 返回的
# ``SecurityInfo.decimal_point``(协议自带,见 protocol/commands/security_list.py),
# 由 ``pytdxdata.decimal_sync`` 在后台每日同步一次;未同步时静默退回静态规则,
# 行为与 0.6.5 完全一致。
_DECIMAL_PREFIX: dict[tuple[int, str], int] = {}
_DECIMAL_CODE: dict[tuple[int, str], int] = {}
_DECIMAL_MIXED: set[tuple[int, str]] = set()
_DECIMAL_SOURCE: str = ""
四档:股票/指数/板块 ``2``、基金/ETF/B股 ``3``、债券/回购 ``4``。
该函数只是**离线推断**(``get_quotes`` 解析时拿不到证券清单)。真正的权威来源 def install_decimal_map(
是证券列表里协议自带的 ``SecurityInfo.decimal_point`` 字段——2026-10-22 拉取 items: "list[tuple[int, str, int]] | tuple[tuple[int, str, int], ...]",
全量 51,982 只(沪 27,520 + 深 24,462)逐条比对,本函数与之一一吻合、**零例外**。 *,
能对上是因为「三位前缀 → 小数位」在全量清单里没有任何一个前缀出现混合小数位。 source: str = "",
) -> dict[str, int]:
"""用证券清单灌入权威小数位表。
历史修正(两次都是同一类错误:把某段前缀想当然地归错档): ``items`` 为 ``(market, code, decimal_point)`` 序列(直接来自
``SecurityInfo``)。按**三位代码前缀**归并成一个极小的表(全量 5 万只标的
只产生数百个前缀);若某个前缀出现**不同**小数位,则该前缀退化为逐代码查表,
只把这些例外代码存进 ``_DECIMAL_CODE``——这样即使将来交易所新增代码段,
也不会因为前缀规则过时而算错价格。
- **2026-10-21**:沪市 ``000``/``8`` 被判成 3 位 → 上证指数/上证50/科创50/ 返回统计:``{"prefixes", "codes", "mixed_prefixes", "stock"}``。
板块指数**价格少 10 倍**(3713 读成 371)。它们实际是 2 位。
- **2026-10-22**:债券与回购全线偏差 —— 沪市 ``010/018/019/020/1xx/2xx``
与深市 ``10x/11x/12x/13x/14x/19x/50x/52x/56x`` 实际是 **4 位**,原先
沪市落到 2 位(**少 100 倍**)、深市落到 3 位(**少 10 倍**)。实测例:
``sh019742`` 110.228 读成 11022.8、``sh204001`` 1.385 读成 138.5、
``sz131810`` 1.38 读成 13.8。同时沪市 B 股 ``900xxx`` 是 3 位(原先 2 位)。
实证方法:拿 ``pre_close``(快照口径)除以上一交易日**日线收盘**(K线口径,
走 ``/1000`` 独立路径),比值即标度误差 —— 1.0 正确、10 少 10 倍、100 少 100 倍。
""" """
code = (code or "").strip().rstrip("\x00") global _DECIMAL_SOURCE
votes: dict[tuple[int, str], dict[int, int]] = {}
per_code: dict[tuple[int, str], int] = {}
for market, code, dp in items:
c = str(code or "").strip().rstrip("\x00")
if len(c) < 3:
continue
m = int(market)
if m not in (0, 1):
continue
d = int(dp)
if d <= 0:
continue
per_code[(m, c)] = d
key = (m, c[:3])
bucket = votes.setdefault(key, {})
bucket[d] = bucket.get(d, 0) + 1
_DECIMAL_PREFIX.clear()
_DECIMAL_CODE.clear()
_DECIMAL_MIXED.clear()
for key, bucket in votes.items():
if len(bucket) == 1:
_DECIMAL_PREFIX[key] = next(iter(bucket))
else:
_DECIMAL_MIXED.add(key)
for (m, c), d in per_code.items():
if (m, c[:3]) in _DECIMAL_MIXED:
_DECIMAL_CODE[(m, c)] = d
_DECIMAL_SOURCE = source or "universe"
return decimal_map_stats()
def clear_decimal_map() -> None:
"""清空权威表(回到纯静态前缀规则;测试与排障用)。"""
global _DECIMAL_SOURCE
_DECIMAL_PREFIX.clear()
_DECIMAL_CODE.clear()
_DECIMAL_MIXED.clear()
_DECIMAL_SOURCE = ""
def decimal_map_stats() -> dict[str, int]:
"""权威表状态:已覆盖前缀数 / 例外代码数 / 混合前缀数 / 总条目数。"""
return {
"prefixes": len(_DECIMAL_PREFIX),
"codes": len(_DECIMAL_CODE),
"mixed_prefixes": len(_DECIMAL_MIXED),
"stock": len(_DECIMAL_PREFIX) + len(_DECIMAL_CODE),
}
def decimal_map_source() -> str:
"""权威表来源标记(``universe`` / ``cache`` / ``""``=未加载)。"""
return _DECIMAL_SOURCE
def _decimal_digits_static(market: int, code: str) -> int:
"""静态前缀规则(**兜底**,权威表缺失时使用)。"""
if market == 1: # 沪市 if market == 1: # 沪市
if code.startswith("5"): if code.startswith("5"):
return 3 # 基金/ETF/LOF(50/51/52/56/58 系) return 3 # 基金/ETF/LOF(50/51/52/56/58 系)
@@ -56,6 +119,48 @@ def price_decimal_digits(market: int, code: str) -> int:
return 2 return 2
def price_decimal_digits(market: int, code: str) -> int:
"""报价小数位:**协议原始整数除以 ``10**该值``** 才是真实价格。
查找顺序:
1. **权威表**(:func:`install_decimal_map` 灌入)—— 来自证券清单里协议自带的
``SecurityInfo.decimal_point``,由 ``pytdxdata.decimal_sync`` 每日后台同步一次。
2. **静态前缀规则**(:func:`_decimal_digits_static`)—— 权威表未就绪时兜底。
四档:股票/指数/板块 ``2``、基金/ETF/B股 ``3``、债券/回购 ``4``。
为什么还要静态规则:``get_quotes`` 解析是**纯同步、无网络**的路径,解析那一刻
可能还没同步过证券清单;而现网首次安装/离线环境也必须能算出价格。
权威表与静态规则的一致性:2026-10-22 拉取全量 51,982 只(沪 27,520 + 深 24,462)
逐条比对,静态规则与 ``decimal_point`` **一一吻合、零例外**——因为全量清单里
没有任何一个三位前缀出现混合小数位。因此两者并存不会产生口径冲突。
历史修正(两次都是同一类错误:把某段前缀想当然地归错档):
- **2026-10-21**:沪市 ``000``/``8`` 被判成 3 位 → 上证指数/上证50/科创50/
板块指数**价格少 10 倍**(3713 读成 371)。它们实际是 2 位。
- **2026-10-22**:债券与回购全线偏差 —— 沪市 ``010/018/019/020/1xx/2xx``
与深市 ``10x/11x/12x/13x/14x/19x/50x/52x/56x`` 实际是 **4 位**,原先
沪市落到 2 位(**少 100 倍**)、深市落到 3 位(**少 10 倍**)。实测例:
``sh019742`` 110.228 读成 11022.8、``sh204001`` 1.385 读成 138.5、
``sz131810`` 1.38 读成 13.8。同时沪市 B 股 ``900xxx`` 是 3 位(原先 2 位)。
实证方法:拿 ``pre_close``(快照口径)除以上一交易日**日线收盘**(K线口径,
走 ``/1000`` 独立路径),比值即标度误差 —— 1.0 正确、10 少 10 倍、100 少 100 倍。
"""
code = (code or "").strip().rstrip("\x00")
m = int(market)
if m in (0, 1):
hit = _DECIMAL_PREFIX.get((m, code[:3]))
if hit is not None:
return hit
hit = _DECIMAL_CODE.get((m, code))
if hit is not None:
return hit
return _decimal_digits_static(m, code)
def format_server_time(raw: int) -> str: def format_server_time(raw: int) -> str:
"""服务器时间编码:小时 + 百万分之一小时。14999212 -> 14:59:57.163""" """服务器时间编码:小时 + 百万分之一小时。14999212 -> 14:59:57.163"""
hours, fractional_hour = divmod(raw, 1_000_000) hours, fractional_hour = divmod(raw, 1_000_000)
@@ -36,8 +36,12 @@ class GetSecurityListCmd(BaseCommand[list[SecurityInfo]]):
self.start = start self.start = start
def build_request(self) -> bytes: def build_request(self) -> bytes:
# 12 字节头 + market(H) + start(H) = **16 字节**。
# ⚠️ 曾经多塞一个 H(18 字节):服务端只消费前 16 字节,剩下的 00 00
# 留在它的接收缓冲里,会把**下一个请求**的开头吃掉 → 该连接的后续请求
# 永远得不到响应(表现为「第一次成功、第二次起全部通信超时」)。
header = bytes.fromhex("0c0118640101060006005004".replace(" ", "")) header = bytes.fromhex("0c0118640101060006005004".replace(" ", ""))
return header + struct.pack("<HHH", self.market, self.start, 0) return header + struct.pack("<HH", self.market, self.start)
def parse_response(self, body: bytes) -> list[SecurityInfo]: def parse_response(self, body: bytes) -> list[SecurityInfo]:
(num,) = unpack_from("<H", body, 0, "security list header") (num,) = unpack_from("<H", body, 0, "security list header")
+15 -5
View File
@@ -5,6 +5,7 @@ import struct
from ..._binary import unpack_from from ..._binary import unpack_from
from ...models import TransactionRecord from ...models import TransactionRecord
from ...symbols import has_order_count
from ..datetime_ import get_time from ..datetime_ import get_time
from ..mac_frame import build_mac_request from ..mac_frame import build_mac_request
from ..price import get_price from ..price import get_price
@@ -32,6 +33,8 @@ class GetTransactionDataCmd(BaseCommand[list[TransactionRecord]]):
pos = 2 pos = 2
last_price = 0 last_price = 0
records: list[TransactionRecord] = [] records: list[TransactionRecord] = []
code = self.code.decode("utf-8")
has_tc = has_order_count(self.market, code)
for _ in range(num): for _ in range(num):
hour, minute, pos = get_time(body, pos) hour, minute, pos = get_time(body, pos)
price_diff, pos = get_price(body, pos) price_diff, pos = get_price(body, pos)
@@ -41,10 +44,12 @@ class GetTransactionDataCmd(BaseCommand[list[TransactionRecord]]):
_unknown, pos = get_price(body, pos) _unknown, pos = get_price(body, pos)
last_price += price_diff last_price += price_diff
records.append(TransactionRecord( records.append(TransactionRecord(
market=self.market, code=self.code.decode("utf-8"), market=self.market, code=code,
time=f"{hour:02d}:{minute:02d}:00", time=f"{hour:02d}:{minute:02d}:00",
price=last_price / 100.0, vol=float(vol), price=last_price / 100.0, vol=float(vol),
trade_count=int(num_orders), bs_flag=bs_flag, # 指数/ETF/LOF 该字段是「价格×1000」占位,不是笔数
trade_count=int(num_orders) if has_tc else 0,
bs_flag=bs_flag, trade_count_available=has_tc,
)) ))
return records return records
@@ -68,6 +73,7 @@ class GetHistoryTransactionDataCmd(BaseCommand[list[TransactionRecord]]):
pos = 6 # 2(num) + 4(skip) pos = 6 # 2(num) + 4(skip)
last_price = 0 last_price = 0
records: list[TransactionRecord] = [] records: list[TransactionRecord] = []
code = self.code.decode("utf-8")
for _ in range(num): for _ in range(num):
hour, minute, pos = get_time(body, pos) hour, minute, pos = get_time(body, pos)
price_diff, pos = get_price(body, pos) price_diff, pos = get_price(body, pos)
@@ -76,10 +82,11 @@ class GetHistoryTransactionDataCmd(BaseCommand[list[TransactionRecord]]):
_unknown, pos = get_price(body, pos) _unknown, pos = get_price(body, pos)
last_price += price_diff last_price += price_diff
records.append(TransactionRecord( records.append(TransactionRecord(
market=self.market, code=self.code.decode("utf-8"), market=self.market, code=code,
time=f"{hour:02d}:{minute:02d}:00", time=f"{hour:02d}:{minute:02d}:00",
price=last_price / 100.0, vol=float(vol), price=last_price / 100.0, vol=float(vol),
trade_count=0, bs_flag=bs_flag, # 历史无笔数 trade_count=0, bs_flag=bs_flag,
trade_count_available=False, # 历史通道整条链路都没有笔数字段
)) ))
return records return records
@@ -108,6 +115,7 @@ class MacTransactionCmd(BaseCommand[list[TransactionRecord]]):
def parse_response(self, body: bytes) -> list[TransactionRecord]: def parse_response(self, body: bytes) -> list[TransactionRecord]:
(count,) = unpack_from("<H", body, 29, "mac transaction count") (count,) = unpack_from("<H", body, 29, "mac transaction count")
records: list[TransactionRecord] = [] records: list[TransactionRecord] = []
has_tc = has_order_count(self.market, self.code)
for i in range(count): for i in range(count):
offset = 39 + i * 18 offset = 39 + i * 18
try: try:
@@ -124,6 +132,8 @@ class MacTransactionCmd(BaseCommand[list[TransactionRecord]]):
market=self.market, code=self.code, market=self.market, code=self.code,
time=f"{h:02d}:{m:02d}:{s:02d}", time=f"{h:02d}:{m:02d}:{s:02d}",
price=price, vol=float(volume), price=price, vol=float(volume),
trade_count=int(trade_count), bs_flag=bs_flag, # 指数/ETF/LOF 该字段是「价格×1000」占位,不是笔数
trade_count=int(trade_count) if has_tc else 0,
bs_flag=bs_flag, trade_count_available=has_tc,
)) ))
return records return records
+50
View File
@@ -238,3 +238,53 @@ def is_cn_index(market: int, code: str) -> bool:
or (code.startswith("000") and int(market) == int(Market.SH)) or (code.startswith("000") and int(market) == int(Market.SH))
or (code.startswith("399") and int(market) == int(Market.SZ)) or (code.startswith("399") and int(market) == int(Market.SZ))
) )
def has_order_count(market: int, code: str) -> bool:
"""该标的的逐笔 ``trade_count`` 是否是**真实成交笔数**。
通达信对**指数**和**多数场内基金**不提供笔数,但那 4 字节里仍塞了值:
- 指数:``当时均价 × 1000``(见 :class:`~pytdxdata.models.TransactionRecord`)
- ETF / LOF:``价格 × 1000``;货币 ETF(如 ``sh511990``)恒为 ``0``
直接当笔数用会得到 3994 这种荒谬值(实测 ``sh510310``)。
实测覆盖(2026-10-22,按代码前缀各取样 1~7 只):
================== ========================== ==========
品种 前缀 笔数可用
================== ========================== ==========
沪股票/科创 600/601/603/605/688/689 是
沪 LOF 501/502/506 是
沪 ETF/LOF 51/52/56/58 **否**
沪指数 000/88 否
沪可转债 110/111/113/118 是
沪 EB(可交换债) 132 是
沪逆回购 204 是
深股票 000/001/002/003/300/301 是
深 ETF 159 **否**
深 LOF/基金 15/16/17/18 **否**
深指数 399 否
深可转债 123/127/128 是
================== ========================== ==========
``501x/502x/506x``(沪市 LOF)实测**有**真实笔数,所以不能用「沪市 5 开头
一律当基金」的粗规则;必须按上面这组前缀精确判定。
可转债(沪 110/111/113/118/132、深 123/127/128)**走的是兜底分支**——
它们既不在沪市 ``51/52/56/58`` 里,也不在深市 ``159/15/16/17/18`` 里,
所以两个分支都落到「是」。这不是巧合而是设计:兜底按「**排除法**」认定
基金/指数,其余一律当普通品种。实测验证(2026-10-22,16 只当日 + 8 只历史日):
笔数合计与日线量级吻合(``sh111000`` 3631 条切片 / 20443 笔,
``sz128136`` 1939 条 / 14593 笔),且 ``Σvol`` 与日线 ``vol`` 比值 **1.000000**。
"""
code = str(code)
if is_cn_index(market, code):
return False
m = int(market)
if m == int(Market.SH):
return code[:2] not in ("51", "52", "56", "58")
if m == int(Market.SZ):
return not (code[:3] == "159" or code[:2] in ("15", "16", "17", "18"))
return True
+31
View File
@@ -0,0 +1,31 @@
"""测试全局隔离。
默认关掉两个**后台网络行为**:
- 权威小数位表同步:否则任何调用 ``TdxData.start()`` 的用例都会顺手发起证券
清单请求(26 + 25 个分页),测试变慢且依赖网络。
- 当日服务器测速:后台 task 会真的去连主机取K线,会污染「往返次数」这类
断言(实测同一个用例的 ``calls`` 在 3/4 之间随机跳),也会拖慢整体。
需要验证这两个行为本身的用例(``test_decimal_sync.py`` / ``test_probe_cache.py``)
自己 ``delenv`` 后再测。
"""
from __future__ import annotations
import os
import pytest
_ENV_KEYS = ("PYPYTDX_DATA_DISABLE_DECIMAL_SYNC", "PYPYTDX_DATA_DISABLE_PROBE")
@pytest.fixture(autouse=True, scope="session")
def _disable_background_network():
old = {k: os.environ.get(k) for k in _ENV_KEYS}
for k in _ENV_KEYS:
os.environ[k] = "1"
yield
for k, v in old.items():
if v is None:
os.environ.pop(k, None)
else:
os.environ[k] = v
+21
View File
@@ -324,6 +324,27 @@ async def test_universe_and_quotes(td):
assert len(qex) == 1 assert len(qex) == 1
async def test_decimal_point_sync(td, tmp_path, monkeypatch):
"""权威小数位表同步:把证券清单的 decimal_point 灌进价格标度表。"""
for name in ("sync_decimal_points", "decimal_point_status"):
_use(name)
from pytdxdata.protocol.commands.quotes import clear_decimal_map, price_decimal_digits
# 缓存目录指向临时目录,避免把 mock 数据写进用户真实缓存
monkeypatch.setenv("PYPYTDX_DATA_CACHE_DIR", str(tmp_path))
before = price_decimal_digits(1, "600000")
try:
st = await td.sync_decimal_points()
assert set(st) >= {"prefixes", "codes", "mixed_prefixes", "stock"}
assert st["stock"] >= 0
status = await td.decimal_point_status()
assert isinstance(status, dict) and "source" in status
finally:
clear_decimal_map()
# 清空后回到静态规则,不受本用例污染
assert price_decimal_digits(1, "600000") == before
async def test_snapshot_auction_flow(td): async def test_snapshot_auction_flow(td):
for name in ("get_snapshot", "get_auction", "get_capital_flow"): for name in ("get_snapshot", "get_auction", "get_capital_flow"):
_use(name) _use(name)
+234
View File
@@ -0,0 +1,234 @@
"""K线批量流水线路径(多连接 × 单连接流水线)。
背景:单只K线一请求一标的,全市场 5,000 只就是 5,000 次往返。串行时每只固定付
一个 RTT(实测 33ms),实测 24 台 × 8 流水能把全市场 1 分钟K线取当天从 43.6s
压到 5s 级。这里用替身验证「路径选择」与「结果口径」,不依赖网络。
"""
from __future__ import annotations
import datetime
import pytest
from pytdxdata import TdxData
from pytdxdata.api import _auto_pipeline, _bars_for_range, _elapsed_trading_minutes
from pytdxdata.models import KlinePeriod, SecurityBar
# 替身的时间锚点必须跟着**真实 now** 走:API 内部用 ``datetime.now()`` 判断「是不是今天」,
# 用固定日期会在 CI(UTC 时区,与本地差 8 小时)上漂到别的时段分支,断言时绿时红。
NEWEST = datetime.datetime.now().replace(microsecond=0) # noqa: DTZ001
def _bar(when: datetime.datetime, close: float = 10.0) -> SecurityBar:
return SecurityBar(
market=1, code="600000", open=10.0, high=10.1, low=9.9, close=close,
vol=1000, amount=10000, year=when.year, month=when.month, day=when.day,
hour=when.hour, minute=when.minute)
class _MacFakeConn:
"""MAC 通道语义替身:**offset 0 = 最新一根**,偏移越大越老。"""
seen: list[tuple[str, int, int, bool]] = [] # (命令名, start, count, 是否流水线)
fail_pipeline = False
def __init__(self, host="m1", port=7709, timeout=10.0):
self.host = host
self._alive = True
@property
def alive(self) -> bool:
return self._alive
async def connect(self) -> None:
pass
async def close(self) -> None:
self._alive = False
def _rows(self, cmd, *, record: bool = True):
if record:
type(self).seen.append(
(type(cmd).__name__, getattr(cmd, "start", 0),
getattr(cmd, "count", 0), False))
if "MacKlineCmd" not in type(cmd).__name__:
return []
out = []
for off in range(cmd.start, cmd.start + cmd.count):
if off > 20_000:
continue
when = NEWEST - datetime.timedelta(minutes=off)
out.append(_bar(when, 10.0 + (20_000 - off) * 0.001))
return out
async def execute(self, cmd):
return self._rows(cmd)
async def execute_pipeline(self, cmds, **kwargs):
if type(self).fail_pipeline:
raise ConnectionError("流水线炸了")
for c in cmds:
type(self).seen.append(
(type(c).__name__, getattr(c, "start", 0), getattr(c, "count", 0), True))
return [self._rows(c, record=False) for c in cmds]
def _syms(n: int) -> list[str]:
"""n 只沪市股票代码(互不相同,避免按 symbol 归并时互相覆盖)。"""
return [f"sh60{i:04d}" for i in range(n)]
async def _run(n: int, period=KlinePeriod.MIN_1, **kw):
_MacFakeConn.seen = []
_MacFakeConn.fail_pipeline = False
with pytest.MonkeyPatch.context() as mp:
mp.setattr("pytdxdata.api.get_mac_hosts", lambda: ["m1", "m2"])
mp.setattr("pytdxdata.pool.pool.TdxConnection",
lambda h, p=7709, t=10.0: _MacFakeConn(h))
td = TdxData(cache_dir=None, pool_min=1, pool_max=4)
await td.start()
try:
bars = await td.get_bars(_syms(n), period, **kw)
finally:
await td.close()
return bars
def _data_calls() -> list[tuple[str, int, int, bool]]:
"""只看真正的数据请求(排除建连探针:count=100 那条)。"""
return [c for c in _MacFakeConn.seen if c[2] != 100]
@pytest.mark.asyncio
async def test_bulk_path_uses_pipeline_for_many_symbols():
bars = await _run(20, count=240)
data = _data_calls()
assert data, "应该有数据请求"
assert all(via_pipe for *_, via_pipe in data), "20 只必须走流水线"
assert len(data) == 20
assert len(bars) == 20 * 240
@pytest.mark.asyncio
async def test_small_batch_falls_back_to_single():
"""低于阈值走逐只:不经过流水线,结果不变。"""
bars = await _run(5, count=240)
data = _data_calls()
assert data and not any(via_pipe for *_, via_pipe in data)
assert len(bars) == 5 * 240
@pytest.mark.asyncio
async def test_pipeline_1_disables_bulk():
bars = await _run(20, count=240, pipeline=1)
data = _data_calls()
assert data and not any(via_pipe for *_, via_pipe in data)
assert len(bars) == 20 * 240
@pytest.mark.asyncio
async def test_result_order_follows_input_order():
"""返回按入参标的顺序拼接(组内升序)。"""
bars = await _run(20, count=30)
seen: list[str] = []
for b in bars:
if not seen or seen[-1] != b.symbol:
seen.append(b.symbol)
assert seen == _syms(20)
# 组内按时间正序
head = [b.datetime for b in bars if b.symbol == _syms(20)[0]]
assert head == sorted(head)
@pytest.mark.asyncio
async def test_long_count_is_paged_inside_pipeline():
"""count 超过单请求上限时按页切分,且页也走流水线(不是逐只串行翻页)。"""
bars = await _run(20, count=1600, pipeline=8)
data = _data_calls()
assert all(via_pipe for *_, via_pipe in data)
assert len(data) == 20 * 3 # 700 + 700 + 200
assert {c[2] for c in data} == {700, 200}
assert len(bars) == 20 * 1600
@pytest.mark.asyncio
async def test_pipeline_failure_falls_back_to_single_per_symbol():
"""流水线失败 → 该批交回逐只重试,结果不丢。"""
_MacFakeConn.seen = []
_MacFakeConn.fail_pipeline = True
with pytest.MonkeyPatch.context() as mp:
mp.setattr("pytdxdata.api.get_mac_hosts", lambda: ["m1", "m2"])
mp.setattr("pytdxdata.pool.pool.TdxConnection",
lambda h, p=7709, t=10.0: _MacFakeConn(h))
td = TdxData(cache_dir=None, pool_min=1, pool_max=4)
await td.start()
try:
bars = await td.get_bars(_syms(20), KlinePeriod.MIN_1, count=240)
finally:
await td.close()
assert len(bars) == 20 * 240
@pytest.mark.asyncio
async def test_dated_range_bulk_trims_to_start_date():
"""日期区间走批量时,区间左端仍然精确裁剪。"""
start = NEWEST - datetime.timedelta(minutes=30)
bars = await _run(20, start_date=start)
assert bars
assert all(b.datetime >= start for b in bars)
assert all(b.symbol in set(_syms(20)) for b in bars)
@pytest.mark.asyncio
async def test_dated_future_range_returns_empty_without_requests():
future = NEWEST + datetime.timedelta(days=5)
bars = await _run(20, start_date=future)
assert bars == []
# ---------------- 纯函数 ----------------
def test_elapsed_trading_minutes():
def at(h, m):
return datetime.datetime(2026, 10, 28, h, m) # noqa: DTZ001
assert _elapsed_trading_minutes(at(9, 0)) == 0
assert _elapsed_trading_minutes(at(9, 30)) == 0
assert _elapsed_trading_minutes(at(10, 0)) == 30
assert _elapsed_trading_minutes(at(11, 45)) == 120 # 午休
assert _elapsed_trading_minutes(at(13, 30)) == 150
assert _elapsed_trading_minutes(at(15, 0)) == 240
assert _elapsed_trading_minutes(at(20, 0)) == 240 # 收盘后
def test_bars_for_range_shrinks_intraday():
"""盘中只需已走完的根数,不是一整天 240 根。"""
morning = datetime.datetime(2026, 10, 28, 10, 0) # noqa: DTZ001
midnight = datetime.datetime(2026, 10, 28, 0, 0) # noqa: DTZ001
# 10:00 走了 30 分钟 → 30 + 余量,远小于 240
assert 30 <= _bars_for_range(KlinePeriod.MIN_1, midnight, morning) <= 40
# 收盘后回到一整天的量级
close = datetime.datetime(2026, 10, 28, 16, 0) # noqa: DTZ001
assert _bars_for_range(KlinePeriod.MIN_1, midnight, close) >= 245
def test_bars_for_range_past_days():
now = datetime.datetime(2026, 10, 28, 16, 0) # noqa: DTZ001
start = now - datetime.timedelta(days=5)
n = _bars_for_range(KlinePeriod.DAY, start, now)
assert 5 <= n <= 12 # 5 个自然日 × 1.6 余量
def test_auto_pipeline():
# 每根 32B:小 count 用深流水,大 count 用浅流水(在途字节数恒定)
assert _auto_pipeline(2, None) == 32
assert _auto_pipeline(240, None) == 8
assert _auto_pipeline(240, 4) == 4 # 显式指定优先
assert _auto_pipeline(2, 1) == 2 # 夹到最小值 2
+125
View File
@@ -0,0 +1,125 @@
"""CLI 价格小数位 / 分时时间列的显示回归。
覆盖两个曾经出错的地方:
1. ``tdx minute`` 的时间列按序号推算(``i // 60, i % 60``),240 根分时被打印成
``00:00~03:59``,与真实交易时间无关。
2. 价格固定写死 ``%8.2f``,可转债(报价步长 0.001 元)会被截成 2 位
——``128.892`` 打成 ``128.89``。
注意 ``price_decimal_digits`` 返回的是**解码位数**(原始整数 / 10**dp),可转债
是 4 位,但第 4 位恒为 0,显示层只该给 3 位(见 ``_display_dp``)。
"""
from __future__ import annotations
from pytdxdata.cli import (
_display_dp,
_dp_of,
_price_fmt,
cmd_minute,
cmd_transactions,
parse_symbol,
)
from pytdxdata.models import MinuteBar, TransactionRecord
class FakeTD:
"""只实现 minute / transactions 需要的两个接口。"""
def __init__(self, minutes=None, ticks=None):
self._minutes = minutes or []
self._ticks = ticks or []
async def get_minutes(self, sym, date=None):
return self._minutes
async def get_ticks(self, sym, date=None, count=None):
return self._ticks
def _bar(price, hour, minute, vol=100.0, avg=0.0):
return MinuteBar(price=price, vol=vol, avg_price=avg or price,
hour=hour, minute=minute, fields={})
def _tick(price, vol, trade_count=1, available=True, time="14:59:54"):
return TransactionRecord(market=1, code="113708", time=time, price=price, vol=vol,
trade_count=trade_count, bs_flag=0, fields={},
trade_count_available=available)
# --------------------------------------------------------------------------- #
# 小数位判定
# --------------------------------------------------------------------------- #
def test_price_fmt_width_tracks_decimals():
assert _price_fmt(2) == "%8.2f" # 股票:保持原宽度,不破坏对齐
assert _price_fmt(3) == "%9.3f"
assert _price_fmt(4) == "%10.4f"
assert _price_fmt(None) == "%8.2f" # 缺省当 2 位
def test_display_dp_by_instrument():
assert _display_dp(1, "600000") == 2 # 沪股票
assert _display_dp(0, "000001") == 2 # 深股票
assert _display_dp(1, "000001") == 2 # 指数
assert _display_dp(1, "113708") == 3 # 沪可转债(解码 4 位,显示 3 位)
assert _display_dp(1, "110102") == 3
assert _display_dp(0, "123235") == 3 # 深可转债
assert _display_dp(0, "128136") == 3
assert _display_dp(1, "510310") == 3 # ETF
assert _display_dp(1, "019547") == 4 # 国债:4 位是真实报价精度
def test_dp_of_uses_cn_only():
assert _dp_of(parse_symbol("sh113708")) == 3
assert _dp_of(parse_symbol("sh600000")) == 2
assert _dp_of(parse_symbol("hk00700")) == 2 # 非 A 股固定 2 位
# --------------------------------------------------------------------------- #
# tdx minute
# --------------------------------------------------------------------------- #
async def test_cmd_minute_prints_real_clock(capsys):
bars = [_bar(129.271, 9, 30), _bar(129.270, 9, 31), _bar(128.892, 14, 59)]
await cmd_minute(FakeTD(minutes=bars), "sh113708", None)
out = capsys.readouterr().out
assert "09:30" in out and "09:31" in out and "14:59" in out
assert "00:00" not in out and "03:59" not in out
async def test_cmd_minute_cb_keeps_three_decimals(capsys):
await cmd_minute(FakeTD(minutes=[_bar(128.892, 14, 59)]), "sh113708", None)
out = capsys.readouterr().out
assert "128.892" in out
assert "128.89 " not in out
async def test_cmd_minute_stock_two_decimals(capsys):
await cmd_minute(FakeTD(minutes=[_bar(9.62, 15, 0)]), "sh600000", None)
out = capsys.readouterr().out
assert "9.62" in out and "9.620" not in out
# --------------------------------------------------------------------------- #
# tdx transactions
# --------------------------------------------------------------------------- #
async def test_cmd_transactions_cb_price_and_count(capsys):
await cmd_transactions(FakeTD(ticks=[_tick(128.892, 3, trade_count=4)]),
"sh113708", 50, None)
out = capsys.readouterr().out
assert "128.892" in out
assert "(4笔)" in out
async def test_cmd_transactions_etf_marks_missing_count(capsys):
tick = TransactionRecord(market=1, code="510310", time="15:27:35", price=3.989,
vol=15, trade_count=0, bs_flag=0, fields={},
trade_count_available=False)
await cmd_transactions(FakeTD(ticks=[tick]), "sh510310", 50, None)
out = capsys.readouterr().out
assert "3.989" in out # ETF 也是 3 位
assert "(-)" in out # 不打印假笔数
assert "笔)" not in out
+233
View File
@@ -0,0 +1,233 @@
"""权威价格小数位表(decimal_sync)单元测试。
覆盖点:
- 权威表(来自 ``SecurityInfo.decimal_point``)**优先于**静态前缀规则
- 某前缀出现混合小数位 → 自动退化为逐代码查表,不误伤同前缀其它代码
- 清空权威表 → 回到静态规则(与 0.6.5 行为一致)
- 磁盘缓存:写入 / 读取 / 跨日失效 / 损坏容错,均不回退到网络
- ``PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1`` → 完全不动作
- 证券清单里 ``decimal_point == 0`` 的脏条目被忽略
- 后台 task 可取消,且 ``close()`` 后不再改写表
(全部注入假 ``TdxData``,不连真实网络)
"""
from __future__ import annotations
import asyncio
import json
from types import SimpleNamespace
import pytest
from pytdxdata import decimal_sync
from pytdxdata.protocol.commands.quotes import (
clear_decimal_map,
decimal_map_stats,
install_decimal_map,
price_decimal_digits,
)
# ---------------------------------------------------------------------- #
# 夹具
# ---------------------------------------------------------------------- #
@pytest.fixture(autouse=True)
def _isolate(tmp_path, monkeypatch):
"""每个用例独立缓存目录 + 干净的内存状态。"""
monkeypatch.setenv("PYPYTDX_DATA_CACHE_DIR", str(tmp_path))
monkeypatch.delenv("PYPYTDX_DATA_DISABLE_DECIMAL_SYNC", raising=False)
decimal_sync.reset()
yield
decimal_sync.reset()
def _info(code: str, dp: int) -> SimpleNamespace:
return SimpleNamespace(code=code, decimal_point=dp, market=1)
class FakeTd:
"""只有 ``get_universe`` 的假客户端(记录调用次数,便于断言"没走网络")。"""
def __init__(self, tables: dict[str, list[tuple[str, int]]] | None = None) -> None:
self.tables = tables or {}
self.calls: list[str] = []
async def get_universe(self, market: str | None = None):
self.calls.append(market or "all")
return [_info(c, d) for c, d in self.tables.get(market, [])]
# ---------------------------------------------------------------------- #
# 权威表优先级
# ---------------------------------------------------------------------- #
def test_authoritative_map_overrides_static_rule():
# 静态规则说 sh019742 是 4 位;权威表说 3 位 → 必须听权威表的
assert price_decimal_digits(1, "019742") == 4
install_decimal_map([(1, "019742", 3)], source="test")
assert price_decimal_digits(1, "019742") == 3
def test_codes_outside_map_still_use_static_rule():
install_decimal_map([(1, "019742", 3)], source="test")
assert price_decimal_digits(1, "600000") == 2 # 股票
assert price_decimal_digits(1, "510300") == 3 # ETF
assert price_decimal_digits(0, "131810") == 4 # 深回购(表里没有)
def test_mixed_prefix_falls_back_to_per_code_lookup():
"""同一前缀出现两种小数位 → 该前缀不进前缀表,只把例外代码存进逐代码表。"""
stats = install_decimal_map(
[(1, "110001", 4), (1, "110002", 4), (1, "110003", 3)], source="test")
assert stats["mixed_prefixes"] == 1
assert stats["codes"] == 3 # 混合前缀下所有代码都进逐代码表
assert price_decimal_digits(1, "110001") == 4
assert price_decimal_digits(1, "110003") == 3
def test_clear_map_restores_static_rules():
install_decimal_map([(1, "019742", 3)], source="test")
assert price_decimal_digits(1, "019742") == 3
clear_decimal_map()
assert decimal_map_stats()["stock"] == 0
assert price_decimal_digits(1, "019742") == 4
def test_reinstall_replaces_previous_map():
install_decimal_map([(1, "019742", 3)], source="a")
install_decimal_map([(1, "019742", 4)], source="b")
assert price_decimal_digits(1, "019742") == 4
assert decimal_map_stats()["prefixes"] == 1
# ---------------------------------------------------------------------- #
# 同步
# ---------------------------------------------------------------------- #
def test_refresh_installs_and_writes_cache(tmp_path):
td = FakeTd({"sh": [("019742", 4), ("600000", 2)],
"sz": [("000001", 2), ("131810", 4)]})
stats = asyncio.run(decimal_sync.refresh(td))
assert td.calls == ["sh", "sz"]
assert stats["stock"] == 4
assert price_decimal_digits(1, "600000") == 2
assert price_decimal_digits(0, "131810") == 4
raw = json.loads((tmp_path / "decimal-points.json").read_text(encoding="utf-8"))
assert raw["markets"]["1"]["019742"] == 4
assert raw["markets"]["0"]["131810"] == 4
def test_refresh_skips_zero_decimal_point():
td = FakeTd({"sh": [("019742", 0), ("600000", 2)]})
stats = asyncio.run(decimal_sync.refresh(td, ("sh",)))
assert stats["stock"] == 1
def test_refresh_ignores_unknown_market():
td = FakeTd({"hk": [("00700", 3)]})
stats = asyncio.run(decimal_sync.refresh(td, ("hk",)))
assert stats["stock"] == 0
assert not (decimal_sync.cache_file()).exists()
def test_load_cached_roundtrip(tmp_path):
td = FakeTd({"sh": [("019742", 4)]})
asyncio.run(decimal_sync.refresh(td))
decimal_sync.reset()
assert decimal_map_stats()["stock"] == 0
assert decimal_sync.load_cached() == 1
assert price_decimal_digits(1, "019742") == 4
def test_cache_expires_across_days(tmp_path):
td = FakeTd({"sh": [("019742", 4)]})
asyncio.run(decimal_sync.refresh(td))
decimal_sync.reset()
path = tmp_path / "decimal-points.json"
payload = json.loads(path.read_text(encoding="utf-8"))
payload["date"] = "2000-01-01"
path.write_text(json.dumps(payload), encoding="utf-8")
assert decimal_sync.load_cached() == 0
def test_corrupt_cache_is_ignored(tmp_path):
path = tmp_path / "decimal-points.json"
path.write_text("{not json", encoding="utf-8")
assert decimal_sync.load_cached() == 0
# ---------------------------------------------------------------------- #
# 调度
# ---------------------------------------------------------------------- #
def test_schedule_disabled_by_env(monkeypatch):
monkeypatch.setenv("PYPYTDX_DATA_DISABLE_DECIMAL_SYNC", "1")
td = FakeTd({"sh": [("019742", 4)]})
async def run():
task = decimal_sync.schedule(td)
return task
assert asyncio.run(run()) is None
assert td.calls == []
def test_schedule_loads_cache_without_network(tmp_path):
td = FakeTd({"sh": [("019742", 4)]})
asyncio.run(decimal_sync.refresh(td))
decimal_sync.reset()
quiet = FakeTd({"sh": [("019742", 4)]})
async def run():
return decimal_sync.schedule(quiet)
assert asyncio.run(run()) is None # 缓存命中 → 不起 task
assert quiet.calls == [] # 也没走网络
assert price_decimal_digits(1, "019742") == 4
def test_schedule_runs_background_sync_without_cache():
td = FakeTd({"sh": [("019742", 4)]})
async def run():
task = decimal_sync.schedule(td)
assert task is not None
await task
return decimal_sync.status()
st = asyncio.run(run())
assert st["source"] == "universe"
assert st["syncing"] is False
assert td.calls == ["sh", "sz"] # 默认两市
def test_cancel_stops_background_task():
class SlowTd:
def __init__(self) -> None:
self.calls = 0
async def get_universe(self, market=None):
self.calls += 1
await asyncio.sleep(5)
return []
td = SlowTd()
async def run():
task = decimal_sync.schedule(td)
await asyncio.sleep(0.01)
await decimal_sync.cancel(task)
return task.done() or task.cancelled()
assert asyncio.run(run()) is True
def test_status_shape():
st = decimal_sync.status()
assert set(st) >= {"loaded", "source", "syncing", "prefixes", "codes",
"mixed_prefixes", "stock"}
+175
View File
@@ -0,0 +1,175 @@
"""EX 0x23FF K线的字段语义:``amount`` / ``settle`` 按市场分别回填。
背景(2026-10-28 实测):0x23FF 每条 32B = 4B 时间戳 + **28B 行情**,这 28B 只有
**一个** 4B 槽位可复用,语义随市场变化 ——
* 权益类(港股主板/创业板/基金、新三板、美股):该槽位是**成交额**,
校验 ``成交额 / (close × vol)`` ≈ 100(港股主板/基金,vol 单位是手)或 ≈ 1(其余,vol 是股);
* 期货期权类:该槽位是**结算价**,成交额在帧内根本不存在(恒 0.0)。
改之前 ``amount`` 被硬编码成 0.0、末位 float 直接丢弃,于是港股/美股拿不到成交额、
期货期权拿不到结算价。
"""
from __future__ import annotations
import pickle
import struct
import pytest
from pytdxdata.api import TdxData
from pytdxdata.models import SecurityBar
from pytdxdata.protocol.commands.ex_proto import (
_EX_AMOUNT_MARKETS,
GetExInstrumentBarsCmd,
)
from pytdxdata.symbols import parse_symbols
DAY = 20261028
def _f2u(value: float) -> int:
"""float32 -> 其位模式的 uint32(用来拼「同一槽位两种解释」的报文)。"""
return struct.unpack("<I", struct.pack("<f", value))[0]
def _ex_body(rows: list[tuple[int, ...]], category: int = 4) -> bytes:
"""拼 0x23FF 响应体:20B 头(count@18)+ N × 32B(时间4B + 7×4B)。"""
body = bytearray(20 + 32 * len(rows))
struct.pack_into("<H", body, 18, len(rows))
for i, words in enumerate(rows):
off = 20 + i * 32
struct.pack_into("<I", body, off, DAY)
struct.pack_into("<7I", body, off + 4, *words)
return bytes(body)
def _equity_words(close: float, amount: float, vol: int) -> tuple[int, ...]:
"""权益类布局:OHLC + 成交额(float) + 成交量(uint) + 保留(float)。"""
return (_f2u(close), _f2u(close), _f2u(close), _f2u(close),
_f2u(amount), vol, _f2u(0.0))
def _derivative_words(close: float, position: int, vol: int,
settle: float) -> tuple[int, ...]:
"""期货/期权布局:OHLC + 持仓量(uint) + 成交量(uint) + 结算价(float)。"""
return (_f2u(close), _f2u(close), _f2u(close), _f2u(close),
position, vol, _f2u(settle))
# ---------- 解析层 ----------
@pytest.mark.parametrize("market", [31, 48, 49, 44, 74])
def test_equity_markets_read_amount_from_fifth_slot(market: int) -> None:
cmd = GetExInstrumentBarsCmd(market, "00700", 4, 0, 1)
rows = cmd.parse_response(_ex_body([_equity_words(10.2, 2_040_000.0, 2000)]))
assert len(rows) == 1
assert rows[0]["amount"] == pytest.approx(2_040_000.0)
assert rows[0]["trade"] == 2000 # 成交量不受影响
assert rows[0]["position"] == 0 # 权益类无持仓量概念
assert rows[0]["settle"] is None
@pytest.mark.parametrize("market", [7, 8, 9, 47])
def test_derivative_markets_read_settle_from_seventh_slot(market: int) -> None:
cmd = GetExInstrumentBarsCmd(market, "IFL0", 4, 0, 1)
rows = cmd.parse_response(_ex_body([_derivative_words(4021.0, 49_772, 25_392, 4047.8)]))
assert rows[0]["amount"] == 0.0 # 帧内没有成交额,不是解析漏读
assert rows[0]["position"] == 49_772
assert rows[0]["trade"] == 25_392
assert rows[0]["settle"] == pytest.approx(4047.8)
def test_intraday_settle_zero_normalized_to_none() -> None:
"""结算价是日终量:分钟线该槽位恒 0,归一化成 None 而不是 0.0。"""
cmd = GetExInstrumentBarsCmd(47, "IFL0", 7, 0, 1)
rows = cmd.parse_response(_ex_body([_derivative_words(4054.6, 49_490, 260, 0.0)], 7))
assert rows[0]["settle"] is None
def test_index_markets_kept_out_of_amount_table() -> None:
"""港股指数(27)/中证指数(62) 该槽位既非成交额也非结算价 —— 不能猜,保持 0.0。"""
assert 27 not in _EX_AMOUNT_MARKETS
assert 62 not in _EX_AMOUNT_MARKETS
cmd = GetExInstrumentBarsCmd(27, "HSI", 4, 0, 1)
rows = cmd.parse_response(_ex_body([_equity_words(23041.32, 178_348.0, 17_835)]))
assert rows[0]["amount"] == 0.0
# ---------- API 层透传 ----------
def _fake_api(rows_for: dict[int, list[dict]]) -> TdxData:
td = TdxData(cache_dir=None, pool_min=1, pool_max=2)
seen: list[tuple[int, str]] = []
async def fake(make_cmd, spec): # noqa: ANN001 — 与真实签名同形
cmd = make_cmd(0, spec.page_size)
seen.append((cmd.market, cmd.code))
return rows_for[cmd.market]
td._fetch_paginated_ex = fake # type: ignore[method-assign]
td._seen_ex = seen # type: ignore[attr-defined]
return td
def _row(market: int, code: str, **kw) -> dict:
base = {"year": 2026, "month": 10, "day": 28, "hour": 15, "minute": 0,
"open": 10.0, "high": 10.5, "low": 9.5, "close": 10.2,
"amount": 0.0, "position": 0, "trade": 2000, "settle": None}
base.update(kw)
return base
@pytest.mark.asyncio
async def test_bars_ex_backfills_amount_for_hk() -> None:
td = _fake_api({31: [_row(31, "00700", amount=2_040_000.0)]})
bars = await td.get_bars("hk00700", count=1)
assert len(bars) == 1
assert bars[0].amount == pytest.approx(2_040_000.0)
assert bars[0].vol == 2000
assert bars[0].settle is None
@pytest.mark.asyncio
async def test_bars_ex_backfills_settle_for_futures() -> None:
td = _fake_api({47: [_row(47, "IFL0", position=49_772, trade=25_392, settle=4047.8)]})
bars = await td.get_bars("cffex_futures:IFL0", count=1)
assert bars[0].settle == pytest.approx(4047.8)
assert bars[0].amount == 0.0
# ---------- 旧磁盘缓存兼容 ----------
def test_legacy_pickle_without_settle_still_loads() -> None:
"""升级前写下的缓存没有 settle 槽位;默认反序列化不会补默认值,读它必崩。"""
bar = SecurityBar(market=1, code="600000", open=1.0, high=2.0, low=0.5,
close=1.5, vol=100.0, amount=150.0,
year=2026, month=10, day=28, settle=12.3)
_, slots = bar.__getstate__()
legacy = dict(slots)
legacy.pop("settle")
revived = SecurityBar.__new__(SecurityBar)
revived.__setstate__((None, legacy))
assert revived.settle is None
assert revived.close == 1.5
def test_new_pickle_roundtrip_keeps_settle() -> None:
bar = SecurityBar(market=47, code="IFL0", open=4021.0, high=4060.0, low=4010.0,
close=4054.6, vol=25_618.0, amount=0.0,
year=2026, month=10, day=28, settle=4052.6)
assert pickle.loads(pickle.dumps(bar)).settle == pytest.approx(4052.6)
def test_ex_symbols_route_to_ex_path() -> None:
"""守住前提:上面对 31/47 的断言确实走的是 EX 通道。"""
assert parse_symbols(["hk00700"])[0].is_ex
assert parse_symbols(["cffex_futures:IFL0"])[0].is_ex
+383
View File
@@ -0,0 +1,383 @@
"""DataFrame 转换层测试(0.7.0)。
覆盖两条独立路径:
1. **转换口径**:直接调 :func:`to_frame`,喂合成模型对象,断言列名/列序/取值/dtype。
不碰网络,双后端各跑一遍。
2. **接线**:``TdxData(df=...)`` 的取值校验、装饰器的「内层不二次转换」语义。
"""
from __future__ import annotations
import math
import sys
import pytest
from pytdxdata import TdxData
from pytdxdata import frames as _frames
from pytdxdata.frames import FrameBackendError, framed, get_backend, to_frame
from pytdxdata.models import (
ExMarket,
IndexBar,
IndexTradeStats,
IndicatorSet,
Market,
MinuteBar,
MinuteTradeStat,
SecurityBar,
SecurityQuote,
TdxBlock,
XdxrRecord,
)
BACKENDS = ("polars", "pandas")
# ---------------------------------------------------------------- 工具
def bar(**kw) -> SecurityBar:
base = {
"market": int(Market.SH), "code": "600000", "open": 10.0, "high": 11.0,
"low": 9.5, "close": 10.5, "vol": 1000.0, "amount": 10500.0,
"year": 2026, "month": 10, "day": 27, "hour": 0, "minute": 0,
"symbol": "sh600000",
}
base.update(kw)
return SecurityBar(**base)
def rows(df, backend: str) -> int:
return len(df) if backend == "pandas" else df.height
def cols(df, backend: str) -> list[str]:
return list(df.columns)
def cell(df, backend: str, name: str, index: int = 0):
if backend == "pandas":
return df[name].iloc[index]
# polars 2.x:Series[0] 会返回 Series 而不是标量,统一走 to_list()
return df.get_column(name).to_list()[index]
def missing(value) -> bool:
"""pandas 的数值列会把 None 变成 NaN,两者都算「缺」。"""
return value is None or (isinstance(value, float) and math.isnan(value))
# ---------------------------------------------------------------- 后端
def test_backend_instances_are_cached():
assert get_backend("polars") is get_backend("polars")
assert get_backend("pandas") is get_backend("pandas")
def test_unknown_backend_raises_value_error():
with pytest.raises(ValueError, match="未知的 DataFrame 后端"):
get_backend("numpy")
def test_missing_backend_raises_with_install_hint(monkeypatch):
monkeypatch.setitem(sys.modules, "polars", None) # 让 import polars 抛 ImportError
monkeypatch.delitem(_frames._BACKEND_CACHE, "polars", raising=False)
with pytest.raises(FrameBackendError) as excinfo:
get_backend("polars")
assert isinstance(excinfo.value, ImportError)
assert excinfo.value.name == "polars"
assert "pip install pytdxdata[polars]" in str(excinfo.value)
monkeypatch.delitem(_frames._BACKEND_CACHE, "polars", raising=False)
# ---------------------------------------------------------------- 转换口径
@pytest.mark.parametrize("backend", BACKENDS)
def test_bar_replaces_split_time_with_datetime(backend):
df = to_frame([bar(), bar(minute=30)], backend=backend)
assert cols(df, backend) == [
"market", "code", "open", "high", "low", "close", "vol", "amount",
"datetime", "trading_date", "symbol", "settle",
]
assert rows(df, backend) == 2
assert cell(df, backend, "market") == 1
assert cell(df, backend, "trading_date") == "2026-10-27"
stamp = cell(df, backend, "datetime", 1)
assert stamp.year == 2026 and stamp.hour == 0 and stamp.minute == 30
@pytest.mark.parametrize("backend", BACKENDS)
def test_int_enum_column_is_plain_int(backend):
df = to_frame([bar(market=Market.SZ)], backend=backend)
value = cell(df, backend, "market")
assert value == 0
assert not isinstance(value, Market)
@pytest.mark.parametrize("backend", BACKENDS)
def test_empty_list_falls_back_to_annotation_hint(backend):
df = to_frame([], backend=backend, model="SecurityBar")
assert rows(df, backend) == 0
assert cols(df, backend) == [
"market", "code", "open", "high", "low", "close", "vol", "amount",
"datetime", "trading_date", "symbol", "settle",
]
@pytest.mark.parametrize("backend", BACKENDS)
def test_quote_expands_bid_ask_levels(backend):
quote = SecurityQuote(
market=1, code="600000", price=10.5, pre_close=10.0, open=10.1, high=10.6,
low=9.9, vol=100.0, amount=1000.0, s_vol=40.0, b_vol=60.0,
bid=[(10.49, 100.0), (10.48, 200.0)], ask=[(10.51, 300.0)],
symbol="sh600000", fields={"0x7": 1.5},
)
df = to_frame([quote], backend=backend)
out = cols(df, backend)
assert "bid1_price" in out and "ask5_vol" in out
assert "bid" not in out and "ask" not in out
assert cell(df, backend, "bid2_vol") == 200.0
assert missing(cell(df, backend, "bid3_price")) # 只有两档,缺档给 None
assert cell(df, backend, "fields") == '{"0x7":1.5}'
@pytest.mark.parametrize("backend", BACKENDS)
def test_empty_dict_field_becomes_none(backend):
df = to_frame([SecurityQuote(
market=1, code="600000", price=1.0, pre_close=1.0, open=1.0, high=1.0,
low=1.0, vol=1.0, amount=1.0, s_vol=0.0, b_vol=0.0,
)], backend=backend)
assert missing(cell(df, backend, "fields"))
@pytest.mark.parametrize("backend", BACKENDS)
def test_minute_uses_real_clock(backend):
late = MinuteBar(price=1.0, vol=10.0, avg_price=1.0, hour=27, minute=59,
symbol="usAAPL", market=74, code="AAPL", date=20261026)
df = to_frame([late], backend=backend)
assert cols(df, backend) == [
"price", "vol", "avg_price", "datetime", "trading_date",
"symbol", "market", "code", "fields",
]
stamp = cell(df, backend, "datetime")
assert (stamp.year, stamp.month, stamp.day, stamp.hour, stamp.minute) == (
2026, 10, 27, 3, 59,
)
assert cell(df, backend, "trading_date") == "2026-10-26"
@pytest.mark.parametrize("backend", BACKENDS)
def test_xdxr_date_column(backend):
row = XdxrRecord(market=1, code="600000", year=2026, month=6, day=12,
category=1, name="分红", fenhong=0.5, symbol="sh600000")
df = to_frame([row], backend=backend)
assert cols(df, backend)[:3] == ["market", "code", "date"]
stamp = cell(df, backend, "date")
assert (stamp.year, stamp.month, stamp.day) == (2026, 6, 12)
@pytest.mark.parametrize("backend", BACKENDS)
def test_tdx_block_keeps_codes_list(backend):
df = to_frame([TdxBlock(name="银行", category=0, count=2, codes=["600000", "600036"])],
backend=backend)
assert cols(df, backend) == ["name", "category", "count", "codes"]
assert cell(df, backend, "codes") == ["600000", "600036"]
@pytest.mark.parametrize("backend", BACKENDS)
def test_indicator_set_merges_bars_and_indicators(backend):
item = IndicatorSet(
symbol="sh600000",
bars=[bar(), bar(minute=1), bar(minute=2)],
indicators={"ma5": [1.0, 2.0, 3.0], "boll": [None, None, 9.0]},
)
df = to_frame([item], backend=backend)
assert rows(df, backend) == 3
assert cell(df, backend, "symbol") == "sh600000"
assert cell(df, backend, "ma5", 2) == 3.0
assert missing(cell(df, backend, "boll"))
@pytest.mark.parametrize("backend", BACKENDS)
def test_indicator_series_shorter_than_bars_is_padded(backend):
item = IndicatorSet(symbol="sh600000", bars=[bar(), bar(minute=1)],
indicators={"ma5": [7.0]})
df = to_frame([item], backend=backend)
assert rows(df, backend) == 2
assert cell(df, backend, "ma5") == 7.0
assert missing(cell(df, backend, "ma5", 1))
@pytest.mark.parametrize("backend", BACKENDS)
def test_index_trade_stats_single_and_multi(backend):
stat = IndexTradeStats(
index="sh000300", date=20261027, member_count=300, active_members=299,
trade_count_members=299,
minutes=[MinuteTradeStat(time="09:31", volume=10.0, trade_count=5, amount=1000.0)],
)
single = to_frame(stat, backend=backend)
assert cols(single, backend) == ["index", "date", "time", "volume", "trade_count", "amount"]
assert cell(single, backend, "index") == "sh000300"
multi = to_frame([stat, stat], backend=backend)
assert rows(multi, backend) == 2
@pytest.mark.parametrize("backend", BACKENDS)
def test_batch_dict_is_concatenated(backend):
data = {
"600000": [bar(code="600000"), bar(code="600000", minute=1)],
"600036": [bar(code="600036", symbol="sh600036")],
}
df = to_frame(data, backend=backend)
assert rows(df, backend) == 3
assert cols(df, backend)[:2] == ["market", "code"]
@pytest.mark.parametrize("backend", BACKENDS)
def test_batch_dict_all_empty_returns_typed_empty(backend):
df = to_frame({"600000": [], "600036": []}, backend=backend, model="SecurityBar")
assert rows(df, backend) == 0
assert "datetime" in cols(df, backend)
@pytest.mark.parametrize("backend", BACKENDS)
def test_list_of_dicts_uses_key_union(backend):
df = to_frame([{"name": "银行", "rise": 1.2}, {"name": "券商", "amount": 5.0}],
backend=backend)
assert cols(df, backend) == ["name", "rise", "amount"]
assert missing(cell(df, backend, "amount", 0))
def test_unsupported_payload_raises_type_error():
with pytest.raises(TypeError, match="无法转换为 DataFrame 的返回值类型"):
to_frame(42, backend="polars")
with pytest.raises(TypeError, match="无法转换为 DataFrame 的列表元素"):
to_frame([1.0, 2.0], backend="polars")
def test_subclass_reuses_parent_plan():
df = to_frame([IndexBar(market=1, code="000001", open=1.0, high=1.0, low=1.0,
close=1.0, vol=1.0, amount=1.0, year=2026, month=1, day=5)],
backend="polars")
assert "datetime" in df.columns
assert "year" not in df.columns
# ---------------------------------------------------------------- 接线
def test_tdxdata_default_keeps_legacy_behaviour():
td = TdxData()
assert td._df_backend is None
def test_tdxdata_rejects_unknown_backend():
with pytest.raises(ValueError, match="未知的 DataFrame 后端"):
TdxData(df="numpy")
def test_tdxdata_accepts_supported_backend():
td = TdxData(df="polars")
assert td._df_backend == "polars"
class _Source:
"""最小替身:只验装饰器语义,不碰网络。"""
def __init__(self, backend: str | None) -> None:
self._df_backend = backend
@framed
async def single(self) -> list[SecurityBar]:
return [bar()]
@framed
async def nested(self) -> dict[str, list[SecurityBar]]:
got = await self.single() # 内层必须是原始 list
assert isinstance(got, list), f"内层被提前转换成了 {type(got)!r}"
return {"600000": got}
async def test_decorator_passthrough_when_no_backend():
src = _Source(None)
assert isinstance(await src.single(), list)
async def test_decorator_converts_outermost_only():
src = _Source("polars")
out = await src.nested()
assert cols(out, "polars")[0] == "market"
assert rows(out, "polars") == 1
def test_model_name_resolution():
# 注解是 dict[str, list[SecurityBar]] 时正则也能取到 SecurityBar;
# 但 "dict" 这类内建名在 models 里找不到,必须返回 None 而不是内建类型
assert _frames._model_by_name("dict") is None
assert _frames._model_by_name("SecurityBar") is SecurityBar
def test_datetime_dtype_is_datetime_like():
pl = pytest.importorskip("polars")
df = to_frame([bar()], backend="polars")
assert isinstance(df.schema["datetime"], pl.Datetime)
# ---------------------------------------------------------------- 交易日列缓存
@pytest.mark.parametrize("backend", BACKENDS)
def test_trading_date_multi_key_batch_matches_model(backend):
"""一批里混着 A股与美股、跨 0~23 点,逐行都要等于模型自己的 ``trading_date``。
``trading_date`` 是按「时间字段」缓存算出来的(240k 行常只有 1~2 个键),
这里专门造出「多键同批」的极端情形,防止缓存键漏掉参与计算的因素。
注意:美股的跨日处理在 ``SecurityBar.__post_init__`` 里就做完了(凌晨段
的年月日会被推进一天),所以 ``trading_date`` 对每个 bar 只是自然日,
真正会分叉的是 ``datetime`` —— 两者都要逐行核对。
"""
batch = []
for market in (int(Market.SH), int(ExMarket.US_STOCK)):
for hour in range(24):
batch.append(bar(market=market, hour=hour, minute=15))
df = to_frame(batch, backend=backend)
got_td = [cell(df, backend, "trading_date", i) for i in range(rows(df, backend))]
got_dt = [cell(df, backend, "datetime", i) for i in range(rows(df, backend))]
assert got_td == [b.trading_date for b in batch]
assert got_dt == [b.datetime for b in batch]
# 美股凌晨段的 datetime 确实落在下一天(否则这条测试等于没测)
us = [b for b in batch if b.market == int(ExMarket.US_STOCK)]
assert {b.datetime.date().isoformat() for b in us} == {"2026-10-27", "2026-10-28"}
@pytest.mark.parametrize("backend", BACKENDS)
def test_minute_trading_date_cache_matches_model(backend):
"""分时的 ``day_offset`` 也参与交易日计算,缓存键不能漏。"""
batch = [
MinuteBar(price=10.0, vol=1.0, hour=9, minute=30, date=20261027),
MinuteBar(price=10.0, vol=1.0, hour=21, minute=30, date=20261027,
market=int(ExMarket.US_STOCK)),
MinuteBar(price=10.0, vol=1.0, hour=3, minute=0, date=20261027,
market=int(ExMarket.US_STOCK), day_offset=1),
]
df = to_frame(batch, backend=backend)
got = [cell(df, backend, "trading_date", i) for i in range(rows(df, backend))]
assert got == [b.trading_date for b in batch]
@pytest.mark.parametrize("backend", BACKENDS)
def test_every_bar_field_equals_model(backend):
"""逐字段等价:DataFrame 的每个值都必须等于 dataclass 的同名字段。
这条是取列路径(``attrgetter`` 批量取 + 按列转 Enum)改动的兜底,
避免「快是快了,但某列悄悄串了值」。
"""
src = bar(minute=15, settle=3.5)
df = to_frame([src], backend=backend)
for name in cols(df, backend):
want = getattr(src, name)
assert cell(df, backend, name) == want, name
+166
View File
@@ -0,0 +1,166 @@
"""K线「按日期区间」取数的路径选择:倒推快路径 vs 二分慢路径。
背景:二分要先探总根数(翻倍 6 次)再跳 log2(N) 次,1 分钟 K 线约 36 次串行
往返 = 4 秒级;而「取今天」「增量到最新」这类贴着右端的请求,倒推只要 1~3 次。
"""
import datetime
from unittest import mock
import pytest
from pytdxdata import TdxData
from pytdxdata.models import KlinePeriod, SecurityBar
NEWEST = datetime.datetime(2026, 10, 28, 15, 0) # noqa: DTZ001 — 全项目用裸北京时间
TOTAL_BARS = 5_000
def _bar(when: datetime.datetime, close: float) -> SecurityBar:
return SecurityBar(
market=1, code="600000", open=10.0, high=10.1, low=9.9, close=close,
vol=1000, amount=10000, year=when.year, month=when.month, day=when.day,
hour=when.hour, minute=when.minute)
class _FakeConn:
"""标准通道语义替身:**offset 0 = 最新一根**,偏移越大越老。"""
calls = 0
def __init__(self, host="s1", port=7709, timeout=10.0):
self.host = host
self.alive_flag = True
@property
def alive(self):
return self.alive_flag
async def connect(self):
pass
async def close(self):
self.alive_flag = False
async def execute_pipeline(self, cmds, **kwargs):
return [await self.execute(c) for c in cmds]
async def execute(self, cmd):
type(self).calls += 1
if "GetSecurityBarsCmd" not in type(cmd).__name__:
return []
rows = []
for off in range(cmd.start, min(cmd.start + cmd.count, TOTAL_BARS)):
rows.append(_bar(NEWEST - datetime.timedelta(days=off),
10.0 + (TOTAL_BARS - off) * 0.01))
return rows
class _AscendingConn(_FakeConn):
"""方向相反的替身(MAC/EX 语义):offset 0 = **最老**一根。"""
async def execute(self, cmd):
type(self).calls += 1
if "GetSecurityBarsCmd" not in type(cmd).__name__:
return []
rows = []
base = datetime.datetime(2020, 1, 1) # noqa: DTZ001
for off in range(cmd.start, min(cmd.start + cmd.count, TOTAL_BARS)):
rows.append(_bar(base + datetime.timedelta(days=off), 10.0 + off * 0.01))
return rows
def _patched(conn_cls):
return (
mock.patch("pytdxdata.api.get_standard_hosts", return_value=["s1"]),
mock.patch("pytdxdata.api.get_mac_hosts", return_value=["m1"]),
mock.patch("pytdxdata.pool.pool.TdxConnection",
side_effect=lambda h, p=7709, t=10.0: conn_cls(h)),
)
async def _fetch(conn_cls, **kwargs):
conn_cls.calls = 0
p1, p2, p3 = _patched(conn_cls)
with p1, p2, p3:
td = TdxData(cache_dir=None, pool_min=1, pool_max=2)
await td.start()
try:
bars = await td.get_bars("sh600000", KlinePeriod.DAY, **kwargs)
finally:
await td.close()
return bars, conn_cls.calls
@pytest.mark.asyncio
async def test_recent_range_uses_backtrack():
"""右端贴最新 → 倒推,往返次数是个位数(不是二分那几十次)。"""
bars, calls = await _fetch(
_FakeConn, start_date=NEWEST - datetime.timedelta(days=5), end_date=NEWEST)
# 返回按时间升序 → 偏移由老到新(5,4,...,0)
assert [b.datetime.date() for b in bars] == [
(NEWEST - datetime.timedelta(days=i)).date() for i in range(5, -1, -1)]
assert calls <= 4, f"倒推路径应 1~3 次往返,实际 {calls}"
@pytest.mark.asyncio
async def test_end_before_newest_within_one_bar_still_backtracks():
"""end 比最新一根略早(K线时间戳是周期结束时刻)仍算贴最新。"""
end = NEWEST - datetime.timedelta(minutes=30)
bars, calls = await _fetch(
_FakeConn, start_date=NEWEST - datetime.timedelta(days=3), end_date=end)
# offset 0 那根(15:00)晚于 end,被裁掉
assert bars[-1].datetime.date() == (NEWEST - datetime.timedelta(days=1)).date()
assert calls <= 4
@pytest.mark.asyncio
async def test_middle_range_falls_back_to_bisect():
"""历史中段倒推够不着左边 → 回落二分,结果仍要正确。"""
bars, calls = await _fetch(
_FakeConn,
start_date=NEWEST - datetime.timedelta(days=100),
end_date=NEWEST - datetime.timedelta(days=90))
assert [b.datetime.date() for b in bars] == [
(NEWEST - datetime.timedelta(days=i)).date() for i in range(100, 89, -1)]
assert calls > 10, f"中段应走二分(几十次往返),实际只有 {calls}"
@pytest.mark.asyncio
async def test_future_range_returns_empty_quickly():
# 用相对 now 的未来,别用固定日期:固定日期会随运行日漂进 _BACKTRACK_GRACE
# (默认 1 天容差覆盖长假),倒推就成立、会多取一轮,断言随日期时绿时红。
future = datetime.datetime.now() + datetime.timedelta(days=5) # noqa: DTZ001
bars, calls = await _fetch(_FakeConn, start_date=future)
assert bars == []
assert calls <= 3
@pytest.mark.asyncio
async def test_ascending_channel_skips_backtrack():
"""offset 0 是最老(MAC/EX 语义)时倒推不成立,必须走二分且结果正确。"""
base = datetime.datetime(2020, 1, 1) # noqa: DTZ001
bars, calls = await _fetch(
_AscendingConn,
start_date=base + datetime.timedelta(days=99),
end_date=base + datetime.timedelta(days=109))
assert [b.datetime.date() for b in bars] == [
(base + datetime.timedelta(days=i)).date() for i in range(99, 110)]
assert calls > 10
@pytest.mark.asyncio
async def test_backtrack_matches_plain_count_result():
"""倒推裁剪结果 == 直接取一大段再裁剪(两条路径口径必须一致)。"""
start = NEWEST - datetime.timedelta(days=7)
by_date, _ = await _fetch(_FakeConn, start_date=start, end_date=NEWEST)
whole, _ = await _fetch(_FakeConn, count=60)
expect = [b for b in whole if b.datetime >= start]
assert [(b.datetime, b.close) for b in by_date] == \
[(b.datetime, b.close) for b in expect]
+236
View File
@@ -0,0 +1,236 @@
"""单连接流水线(execute_pipeline)单元测试:不连真实网络。
关键防线:流水线把多条请求塞进同一条 TCP 流,一旦响应与请求错配就是
「价格张冠李戴」级别的灾难,所以这里逐项锁死顺序、长度与失败语义。
"""
from __future__ import annotations
import struct
import unittest.mock as mock
import pytest
from pytdxdata.pool.connection import TdxConnection
from pytdxdata.pool.pool import PooledConnection
from pytdxdata.protocol.commands.base import BaseCommand
class EchoCmd(BaseCommand[bytes]):
"""请求体即 tag,响应体原样带回,便于断言顺序。"""
def __init__(self, tag: bytes) -> None:
self.tag = tag
def build_request(self) -> bytes:
return b"REQ:" + self.tag
def parse_response(self, body: bytes) -> bytes:
return body
class FakeQuote:
"""最小报价替身:stamp() 会写 symbol,需要 market/code 是可 int/str 的真值。"""
def __init__(self) -> None:
self.market = 0
self.code = "000001"
self.symbol = ""
def frame(body: bytes) -> bytes:
"""构造一帧未压缩响应(zipsize == unzipsize)。"""
return struct.pack("<IIIHH", 7654321, 0, 0x053E, len(body), len(body)) + body
class FakeReader:
def __init__(self, data: bytes) -> None:
self.data = data
self.pos = 0
async def read(self, n: int) -> bytes:
chunk = self.data[self.pos:self.pos + n]
self.pos += len(chunk)
return chunk
class FakeWriter:
def __init__(self) -> None:
self.written = b""
self.closed = False
self.transport = FakeQuote()
def write(self, data: bytes) -> None:
self.written += data
async def drain(self) -> None:
pass
def is_closing(self) -> bool:
return self.closed
def close(self) -> None:
self.closed = True
async def wait_closed(self) -> None:
pass
def make_conn(payload: bytes, host: str = "1.2.3.4") -> TdxConnection:
conn = TdxConnection(host, 7709, 5.0)
conn._reader = FakeReader(payload) # type: ignore[assignment]
conn._writer = FakeWriter() # type: ignore[assignment]
return conn
# ---------- 基本语义 ----------
@pytest.mark.asyncio
async def test_empty_cmds_returns_empty():
conn = make_conn(b"")
assert await conn.execute_pipeline([]) == []
@pytest.mark.asyncio
async def test_responses_paired_in_order():
bodies = [b"AAA", b"BBB", b"CCC"]
conn = make_conn(b"".join(frame(b) for b in bodies))
cmds = [EchoCmd(t) for t in (b"1", b"2", b"3")]
got = await conn.execute_pipeline(cmds)
assert got == bodies # 顺序必须与 cmds 严格一致
@pytest.mark.asyncio
async def test_all_requests_sent_at_once():
conn = make_conn(b"".join(frame(b"X") for _ in range(3)))
cmds = [EchoCmd(t) for t in (b"a", b"b", b"c")]
await conn.execute_pipeline(cmds)
assert conn._writer.written == b"REQ:aREQ:bREQ:c"
@pytest.mark.asyncio
async def test_closed_connection_raises():
conn = make_conn(b"")
conn._writer = None
with pytest.raises(ConnectionError):
await conn.execute_pipeline([EchoCmd(b"1")])
# ---------- 失败语义:响应流错配后必须废连接 ----------
@pytest.mark.asyncio
async def test_truncated_stream_force_closes():
# 只给第一帧完整的、第二帧只有半个头 → 读不满,抛错且连接作废
conn = make_conn(frame(b"AAA") + b"\x00" * 5)
with pytest.raises(ConnectionError):
await conn.execute_pipeline([EchoCmd(b"1"), EchoCmd(b"2")])
assert conn._writer is None # _force_close 已清空 writer
@pytest.mark.asyncio
async def test_body_length_mismatch_propagates():
bad = struct.pack("<IIIHH", 7654321, 0, 0x053E, 99, 99) + b"short"
conn = make_conn(bad)
# 帧头自称 99 字节但流里没有 → _recv_exact 读空,连接作废
with pytest.raises(ConnectionError):
await conn.execute_pipeline([EchoCmd(b"1")])
assert conn._writer is None
# ---------- 池包装转发 ----------
@pytest.mark.asyncio
async def test_pooled_connection_forwards_pipeline():
inner = mock.AsyncMock()
inner.execute_pipeline = mock.AsyncMock(return_value=["r1", "r2"])
pc = PooledConnection(inner, "host1")
got = await pc.execute_pipeline([EchoCmd(b"1"), EchoCmd(b"2")])
assert got == ["r1", "r2"]
inner.execute_pipeline.assert_awaited_once()
# ---------- api 层:切批是否走流水线 ----------
def _api_with_fake_pool():
from pytdxdata.api import TdxData
from pytdxdata.symbols import CN, Symbol
td = TdxData.__new__(TdxData) # 跳过 __init__(不建网络池)
td._std_pool = FakeQuote()
td._std_pool.max_size = 24
td._std_pool.servers = [f"s{i}" for i in range(11)]
td._std_pool.acquire = mock.AsyncMock()
td._std_pool.release = mock.AsyncMock()
td._std_pool.warm = mock.AsyncMock() # 预建连接是网络动作,测试里空转
return td, Symbol, CN
@pytest.mark.asyncio
async def test_quotes_std_uses_pipeline_for_multi_page():
td, Symbol, CN = _api_with_fake_pool()
syms = [Symbol(0, f"{i:06d}", CN) for i in range(1, 401)] # 5 片
chunks = []
async def fake_pipeline(batch_group):
chunks.append(len(batch_group))
return [[FakeQuote()] * 80 for _ in batch_group]
td._execute_std_pipeline = fake_pipeline
out = await td._quotes_std(syms, pipeline=True)
assert len(out) == 5 * 80
assert sum(chunks) == 5 # 每片恰好被处理一次,不多不少
@pytest.mark.asyncio
async def test_quotes_std_single_page_skips_pipeline():
td, Symbol, CN = _api_with_fake_pool()
called = []
td._execute_std_pipeline = mock.AsyncMock(return_value=[])
async def fake_std(cmd):
called.append(1)
return []
td._execute_standard = fake_std
syms = [Symbol(0, f"{i:06d}", CN) for i in range(1, 51)] # 1 片
await td._quotes_std(syms, pipeline=True)
assert called == [1]
td._execute_std_pipeline.assert_not_awaited()
@pytest.mark.asyncio
async def test_quotes_std_no_pipeline_flag_uses_plain_path():
td, Symbol, CN = _api_with_fake_pool()
async def fake_std(cmd):
return [FakeQuote()] * 80
td._execute_standard = fake_std
td._execute_std_pipeline = mock.AsyncMock(return_value=[])
syms = [Symbol(0, f"{i:06d}", CN) for i in range(1, 401)]
out = await td._quotes_std(syms, pipeline=False)
assert len(out) == 5 * 80
td._execute_std_pipeline.assert_not_awaited()
@pytest.mark.asyncio
async def test_pipeline_failure_falls_back_to_per_page():
"""节点不支持流水线时,降级逐片,结果条数不变。"""
td, Symbol, CN = _api_with_fake_pool()
pool = td._std_pool
pool.acquire = mock.AsyncMock(return_value=mock.Mock(
execute_pipeline=mock.AsyncMock(side_effect=ConnectionError("boom"))))
pool.release = mock.AsyncMock()
calls = []
async def fake_std(cmd):
calls.append(1)
return [FakeQuote()] * 80
td._execute_standard = fake_std
syms = [Symbol(0, f"{i:06d}", CN) for i in range(1, 241)] # 3 片
out = await td._execute_std_pipeline(
[syms[i:i + 80] for i in range(0, len(syms), 80)])
assert len(out) == 3 and len(calls) == 3
assert pool.release.await_args.kwargs.get("broken") is True
+44
View File
@@ -206,6 +206,50 @@ def test_mac_transaction_parse_negative_trade_count_auction():
assert max(r.trade_count for r in recs) == 3 assert max(r.trade_count for r in recs) == 3
def test_mac_transaction_etf_trade_count_unavailable():
"""ETF/LOF 的 trade_count 是「价格×1000」占位,必须标记为不可用。
实测(2026-10-22 sh510310 15:27:35):价 3.989、原字段 3994;
旧行为把它当笔数打印成「3994笔」,是假的。
"""
body = bytearray(39 + 2 * 18)
struct.pack_into("<H", body, 29, 2)
struct.pack_into("<IfIiH", body, 39, 56000, 3.989, 15, 3994, 5)
struct.pack_into("<IfIiH", body, 39 + 18, 56003, 3.989, 4, 3994, 5)
for code, market, expect in (("510310", 1, False), ("159915", 0, False),
("600000", 1, True), ("501050", 1, True)):
cmd = MacTransactionCmd(market, code, 20261022, 0, 100)
recs = cmd.parse_response(bytes(body))
assert recs[0].trade_count_available is expect, code
if expect:
assert recs[0].trade_count == 3994
else:
assert recs[0].trade_count == 0
@pytest.mark.parametrize("market,code,expect", [
# 股票 / 可转债 / 回购:有笔数
(1, "600000", True), (1, "688111", True), (1, "689009", True),
(0, "000001", True), (0, "300750", True), (0, "128136", True),
(1, "204001", True),
# 沪市 LOF 50x:实测有真实笔数,不能一刀切
(1, "501050", True), (1, "501018", True), (1, "502000", True), (1, "506000", True),
# 沪市 ETF/LOF 51/52/56/58:无笔数
(1, "510310", False), (1, "511990", False), (1, "512880", False),
(1, "513050", False), (1, "515000", False), (1, "518880", False),
(1, "560010", False), (1, "562500", False), (1, "588000", False),
# 深市基金:无笔数
(0, "159915", False), (0, "159001", False),
(0, "161725", False), (0, "160119", False), (0, "165520", False),
# 指数:无笔数
(1, "000001", False), (0, "399001", False), (1, "880305", False),
])
def test_has_order_count(market, code, expect):
from pytdxdata.symbols import has_order_count
assert has_order_count(market, code) is expect
# ---------- 跨时区时间戳归一化(美股 EX 通道) ---------- # ---------- 跨时区时间戳归一化(美股 EX 通道) ----------
# #
# 通达信 EX 通道对美股返回的时间戳把两个时区拼在一起:日期字段是**美东交易日**、 # 通达信 EX 通道对美股返回的时间戳把两个时区拼在一起:日期字段是**美东交易日**、
+91
View File
@@ -0,0 +1,91 @@
"""证券清单(0x053E)回归测试:请求长度 + 北交所降级。全部离线。
背景(2026-10-23 实测):`build_request` 曾经多塞一个 ``H``(18 字节),
服务端只消费前 16 字节,剩下的 ``00 00`` 留在它的接收缓冲里,把**下一个请求**
的开头吃掉 → 同一连接「第一次成功、第二次起全部通信超时」。
`get_universe` 的分页器复用连接,于是 66/28 页全靠失败重连,冷启动 12~18s。
"""
from __future__ import annotations
import struct
import unittest.mock as mock
import pytest
from pytdxdata.models import Market
from pytdxdata.protocol.commands import GetSecurityListCmd
_HEADER = bytes.fromhex("0c0118640101060006005004")
def test_request_is_exactly_16_bytes():
"""12 字节命令头 + market(H) + start(H),一个字节都不能多。"""
req = GetSecurityListCmd(1, 0).build_request()
assert len(req) == 16
assert req == _HEADER + struct.pack("<HH", 1, 0)
def test_request_encodes_market_and_start_little_endian():
req = GetSecurityListCmd(0, 2000).build_request()
assert req[:12] == _HEADER
market, start = struct.unpack("<HH", req[12:])
assert (market, start) == (0, 2000)
def test_request_has_no_trailing_padding():
"""尾部不能有 padding:多余的 0 会让服务端解析错位。"""
for market in (0, 1, 2):
for start in (0, 1000, 27000):
req = GetSecurityListCmd(market, start).build_request()
assert len(req) == 16, f"market={market} start={start} -> {len(req)} 字节"
def test_parse_response_reads_all_records():
"""29 字节/条,头部 2 字节条数。"""
code, name = b"600000", "浦发银行".encode("gbk").ljust(8, b"\x00")
rec = struct.pack("<6sH8s4sBI4s", code, 100, name, b"\x00" * 4, 2, 0, b"\x00" * 4)
assert len(rec) == 29
body = struct.pack("<H", 2) + rec + rec
rows = GetSecurityListCmd(1, 0).parse_response(body)
assert len(rows) == 2
assert rows[0].code == "600000"
assert rows[0].decimal_point == 2
@pytest.mark.asyncio
async def test_bj_universe_returns_empty_without_network():
"""北交所清单协议不支持:必须立刻返回空,且**不碰连接池**。"""
from pytdxdata.api import TdxData
td = TdxData()
td._std_pool.acquire = mock.AsyncMock(side_effect=AssertionError("不该联网"))
td._std_pool.acquire_many = mock.AsyncMock(
side_effect=AssertionError("不该联网"))
rows = await td.get_universe("bj")
assert rows == []
td._std_pool.acquire.assert_not_called()
td._std_pool.acquire_many.assert_not_called()
@pytest.mark.asyncio
async def test_bj_market_is_in_unsupported_set():
from pytdxdata import api as api_mod
assert int(Market.BJ) in api_mod._LIST_UNSUPPORTED_MARKETS
@pytest.mark.asyncio
async def test_ex_all_fetched_once_in_get_universe():
"""`get_universe()` 跨多个 EX 市场时,EX 全量只能取一次。"""
from pytdxdata.api import TdxData
td = TdxData()
calls = {"n": 0}
async def fake_ex_all():
calls["n"] += 1
return []
td._ex_all = fake_ex_all
await td.get_universe("all")
assert calls["n"] == 1, f"_ex_all 被调用 {calls['n']} 次(应为 1)"
Generated
+742 -440
View File
File diff suppressed because it is too large. Load diff