From 8a781561453f84d0ad23d13f38c66f10c3762ae1 Mon Sep 17 00:00:00 2001 From: openbot-coder Date: Thu, 22 Oct 2026 19:41:55 +0800 Subject: [PATCH] =?UTF-8?q?perf:=20=E5=85=A8=E5=B8=82=E5=9C=BA=E6=8A=A5?= =?UTF-8?q?=E4=BB=B7=E6=94=B9=E5=8D=95=E8=BF=9E=E6=8E=A5=E6=B5=81=E6=B0=B4?= =?UTF-8?q?=E7=BA=BF=EF=BC=883.5s=20=E2=86=92=200.33s=EF=BC=89+=20?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=9F=BA=E9=87=91=E7=AC=94=E6=95=B0=E5=8F=A3?= =?UTF-8?q?=E5=BE=84=20(#9)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 性能: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 --- CHANGELOG.md | 100 ++++++++ SKILL.md | 11 +- docs/API_REFERENCE.md | 21 +- docs/llms.txt | 4 +- pyproject.toml | 2 +- src/pytdxdata/__init__.py | 2 +- src/pytdxdata/api.py | 187 +++++++++++--- src/pytdxdata/cache/manager.py | 32 +++ src/pytdxdata/cli.py | 76 +++++- src/pytdxdata/models/__init__.py | 35 ++- src/pytdxdata/pool/connection.py | 54 ++++ src/pytdxdata/pool/pool.py | 45 ++++ .../protocol/commands/transaction.py | 20 +- src/pytdxdata/symbols.py | 50 ++++ tests/test_pipeline.py | 236 ++++++++++++++++++ tests/test_protocol.py | 44 ++++ uv.lock | 2 +- 17 files changed, 860 insertions(+), 61 deletions(-) create mode 100644 tests/test_pipeline.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 63871c5..d167b15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,106 @@ 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +## [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 ### 改进 diff --git a/SKILL.md b/SKILL.md index 096451c..df521cb 100644 --- a/SKILL.md +++ b/SKILL.md @@ -142,7 +142,7 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约 | 全市场标的清单(A股+港股+期货…) | `get_universe(market=None)` | | 日/周/月/分钟 K 线(任意市场) | `get_bars(symbols, period, *, count, adjust, start_date, end_date)` | | 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_minutes(symbols, *, date, sampling=True)` | | 全市场股票列表(缓存 1 天) | `get_universe("sz")` / `get_universe("sh")` | @@ -169,8 +169,16 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约 - **K 线时间戳统一为北京时间**(v0.6.2 起)。美股原始报文里日期是美东交易日、时分是北京时间(两个时区拼在一起),库已自动归一化,`bar.datetime` 可直接排序 / 比较 / 过滤。但**美股一个交易日横跨两个北京自然日**,按交易日聚合(分钟线合成日线、日内统计)必须用 `bar.trading_date`。 - **`count` 很大时会自动多连接并发分页**,无需手动翻页。但标准通道 K 线 `count < 100` 部分服务器会返回空——内部已强制 `min_page=100` 规避。 - **`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`。 +- **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 个交易日;更早返回空)。 +- **小数位表不用手动管,但可以手动刷**。`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 后完全脱网可用**——适合做离线快照。 ## 陷阱清单 @@ -189,6 +197,7 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约 | 港股/美股五档 bid/ask | 没有(协议不支持) | `fields` 字段位通道有 name 但无五档 | | 美股分钟线用 `datetime.date()` 分组做日聚合 | 一个交易日被拆成两天(美股跨北京零点) | 用 `bar.trading_date`;`bar.datetime` 是归一化后的北京时间 | | 拿指数逐笔的 `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 亿),不是样本股 | | 依赖实时性做信号 | 数据是 15 分钟前的 | 换券商实时源 | | 手动改包内 `servers.json` / 写死 IP | 容器只读、升级被覆盖、快节点捞不回来 | 日常靠内置的**当日测速缓存**自动选路;要强制指定就用 `PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS` 环境变量 | diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 0aeddba..74ee389 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -55,7 +55,7 @@ from pytdxdata import ( | 方法 | 返回 | 说明 | |------|------|------| -| `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_auction(symbols)` | `list[AuctionItem]` | 集合竞价(A 股) | | `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向(A 股) | @@ -71,7 +71,7 @@ from pytdxdata import ( | 方法 | 返回 | 说明 | |------|------|------| -| `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) | #### 公司信息/文件/板块 @@ -102,7 +102,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_list(category, *, start=0, count=80, sort_type=0)` | `list[MemberQuote]` | 市场分类报价(0沪A/2深A/6全A/8科创/14创业) | | `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数/总额/市值/涨跌停数) | @@ -223,6 +223,21 @@ from pytdxdata 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` 是全板块口径) | + +算均价:股票 `amount / vol`;可转债 `amount / vol / 10`;跨品种统一用 `Σ(price×vol) / Σvol`。 + +> 可转债的价格标度、分时、逐笔已全量校验(16 只当日 + 8 只历史日):分时末价 / 快照现价、`Σvol / 日线vol`、逐笔 VWAP vs `amount/(vol×10)` 比值均为 **1.000000**。 + + ## 四、辅助模块 **`pytdxdata.indicator`**(技术指标,纯函数) diff --git a/docs/llms.txt b/docs/llms.txt index 99df73e..a982f94 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -47,12 +47,12 @@ asyncio.run(main()) - **标的清单**:`get_universe`(A股 + 港股 + 美股 + 期货/期权) - **K 线**:`get_bars`(自动并发分页、支持复权与日期区间、多标的并发) - **技术指标**:`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` - 价格标度:协议给的是整数,真实价 = `整数 / 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)、`get_minutes`(`sampling=True` 取缩略采样;`hour` 恒为合法时钟值 0~23,美股一个交易日跨两个北京自然日,按交易日聚合用 `MinuteBar.trading_date`、取时刻用 `MinuteBar.datetime`) +- **逐笔 / 分时**:`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`(本地计算涨跌停) - **F10**:`get_f10`(公司资料目录 + 正文) - **板块**:`get_boards`、`get_board_members`、`get_board_of`、`get_board_summary`、 diff --git a/pyproject.toml b/pyproject.toml index f71341a..49b302e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pytdxdata" -version = "0.6.6" +version = "0.6.7" description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权" readme = "README.md" requires-python = ">=3.11" diff --git a/src/pytdxdata/__init__.py b/src/pytdxdata/__init__.py index 1ebc8b5..382d374 100644 --- a/src/pytdxdata/__init__.py +++ b/src/pytdxdata/__init__.py @@ -18,7 +18,7 @@ from .models import ( XdxrRecord, ) -__version__ = "0.6.6" +__version__ = "0.6.7" __all__ = [ "TdxData", "Market", diff --git a/src/pytdxdata/api.py b/src/pytdxdata/api.py index 76c7a25..6f32450 100644 --- a/src/pytdxdata/api.py +++ b/src/pytdxdata/api.py @@ -25,6 +25,7 @@ import logging import re import time import warnings +from collections import deque from collections.abc import Callable from datetime import date as _date, datetime from pathlib import Path @@ -147,6 +148,7 @@ _KLINE_MAX_BARS: dict[KlinePeriod, int] = { # 自定义字段报价(0x122B/0x122C)基础字段位:昨收/开/高/低/现价/量/量比/额 _QUOTE_BITS = [0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07] _QUOTE_PAGE = 80 # 0x122B/0x122C 单次上限 80 只 +_QUOTE_PIPE_CHUNK = 3 # 单连接流水线一次取几片(实测 3 片 + 每台 2 连接最稳) _EX_PAGE = 1000 # EX 商品列表单页 _TICK_PAGE = 1000 # MAC 逐笔单页 _EX_TICK_PAGE = 1800 # 港股逐笔单页 @@ -237,7 +239,7 @@ class TdxData: default_adjust: Adjust = Adjust.NONE, max_inflight: int = 64, pool_min: int = 3, - pool_max: int = 12, + pool_max: int = 24, mac_pool_cap: int = 4, std_pool_cap: int = 4, ex_pool_cap: int = 2, @@ -442,7 +444,9 @@ class TdxData: # ================================================================== # async def get_quotes(self, symbols: str | Sequence[str], *, - fields: Sequence[int] | None = None + fields: Sequence[int] | None = None, + concurrency: int | None = None, + pipeline: bool = True ) -> list[SecurityQuote]: """报价,一次可跨市场、跨通道混合查询。 @@ -452,6 +456,11 @@ class TdxData: fields: 可选自定义字段位(如 ``[0x00, 0x04, 0x38]``)。给了就走 MAC/EX 的 0x122B 字段位通道(有 ``name``,无五档);不给时 A股走标准通道 (**有五档 bid/ask、买卖量、涨跌停价,无 name**),扩展市场走 0x122B。 + concurrency: 连接并发数(默认取连接池上限)。协议硬上限 80 只/请求, + 全市场约 5,200 只 A股需切 66 片;调小可降低对服务器的压力。 + pipeline: 是否启用**单连接流水线**(默认开启)。开启后一条连接可一次发出 + 多个分片、只付一次往返,全市场 5,200 只 A股由 ~4s 降到 **~0.3s**; + 个股或小批量不受影响。个别服务器不支持流水线时会自动降级为逐片。 返回: ``list[SecurityQuote]``,按入参顺序排列(各记录带 ``symbol``)。 @@ -462,50 +471,155 @@ class TdxData: bits = [int(b) for b in fields] if fields else None tag = "mac:" + _fields_tag(bits) if bits else "std" key = CacheKey.quote_key([s.as_pair() for s in syms], tag=tag) - payload = await self._cache.get_or_fetch( - key, lambda: self._fetch_quotes(syms, bits)) - quotes = unpack_payload(payload) + quotes = await self._cache.get_or_fetch_obj( + key, + lambda: self._fetch_quotes(syms, bits, concurrency, pipeline), + pack=pack_payload, unpack=unpack_payload) order = {s.as_pair(): i for i, s in enumerate(syms)} quotes.sort(key=lambda q: order.get((int(q.market), q.code), len(order))) return quotes - async def _fetch_quotes(self, syms: list[Symbol], bits: list[int] | None) -> bytes: + async def _fetch_quotes(self, syms: list[Symbol], bits: list[int] | None, + concurrency: int | None = None, + pipeline: bool = True) -> list[SecurityQuote]: out: list[SecurityQuote] = [] cn = [s for s in syms if not s.is_ex] ex = [s for s in syms if s.is_ex] if bits is None: if cn: - out.extend(await self._quotes_std(cn)) + out.extend(await self._quotes_std( + cn, concurrency=concurrency, pipeline=pipeline)) if ex: rows = await self._execute_ex( MacSymbolQuotesCmd([s.as_pair() for s in ex], None)) out.extend(_quote_from_member(m) for m in rows) else: - for i in range(0, len(syms), _QUOTE_PAGE): - batch = syms[i:i + _QUOTE_PAGE] - pairs = [s.as_pair() for s in batch] - cn_pairs = [p for p, s in zip(pairs, batch) if not s.is_ex] - ex_pairs = [p for p, s in zip(pairs, batch) if s.is_ex] - if cn_pairs: - rows = await self._execute_mac(MacSymbolQuotesCmd(cn_pairs, bits)) - out.extend(_quote_from_member(m) for m in rows) - if ex_pairs: - rows = await self._execute_ex(MacSymbolQuotesCmd(ex_pairs, bits)) - out.extend(_quote_from_member(m) for m in rows) - return pack_payload(out) + batches = [syms[i:i + _QUOTE_PAGE] + for i in range(0, len(syms), _QUOTE_PAGE)] + sem = asyncio.Semaphore(self._quote_concurrency(concurrency)) - async def _quotes_std(self, syms: list[Symbol]) -> list[SecurityQuote]: - """A股标准通道五档报价(>80 只自动切批)。""" - out: list[SecurityQuote] = [] - for i in range(0, len(syms), MAX_QUOTES): - batch = syms[i:i + MAX_QUOTES] - cmd = GetSecurityQuotesCmd([s.as_pair() for s in batch]) - rows = await self._execute_standard(cmd) + async def one(batch: list[Symbol]) -> list[SecurityQuote]: + async with sem: + pairs = [s.as_pair() for s in batch] + cn_pairs = [p for p, s in zip(pairs, batch) if not s.is_ex] + ex_pairs = [p for p, s in zip(pairs, batch) if s.is_ex] + got: list[SecurityQuote] = [] + if cn_pairs: + rows = await self._execute_mac( + MacSymbolQuotesCmd(cn_pairs, bits)) + got.extend(_quote_from_member(m) for m in rows) + if ex_pairs: + rows = await self._execute_ex( + MacSymbolQuotesCmd(ex_pairs, bits)) + got.extend(_quote_from_member(m) for m in rows) + return got + + if batches: + for got in await asyncio.gather(*(one(b) for b in batches)): + out.extend(got) + return out + + def _quote_concurrency(self, requested: int | None) -> int: + """连接并发数:显式指定优先,否则按「每台服务器 2 连接」估算。 + + 实测(5,227 只 A股 / 66 片,11 台服务器): + + ========== ===== ====== ====== ====== + 并发 每台连接 流水深度 p50 max + ========== ===== ====== ====== ====== + 11 1 6 455ms 464ms + 12 1~2 3 457ms 523ms + **22** **2** **3** **325ms** **334ms** + 33 3 2 328ms 345ms + ========== ===== ====== ====== ====== + + 结论:每台 2 连接 × 流水 3 片最稳;再多连接只是把同一台的队列搬个位置, + 对整体无益反增抖动。池 ``per_server_cap`` 默认 4,2 连接仍留有余量。 + """ + if requested is not None and requested > 0: + return max(1, int(requested)) + n = len(self._std_pool.servers) + return max(1, min(self._std_pool.max_size, (n or 1) * 2)) + + async def _quotes_std(self, syms: list[Symbol], *, + concurrency: int | None = None, + pipeline: bool = True) -> list[SecurityQuote]: + """A股标准通道五档报价(协议上限 80 只/请求,超出自动切批)。 + + 切片多于 1 片时把各片**按轮转分给若干条连接**,每条连接内部用流水线 + 一次发出(1 次往返拿多片),不再逐片往返。 + """ + if not syms: + return [] + + def stamp(rows: list[SecurityQuote]) -> list[SecurityQuote]: for q in rows: q.symbol = format_symbol(q.market, q.code) - out.extend(rows) + return rows + + batches = [syms[i:i + MAX_QUOTES] + for i in range(0, len(syms), MAX_QUOTES)] + if len(batches) == 1: + cmd = GetSecurityQuotesCmd([s.as_pair() for s in batches[0]]) + return stamp(await self._execute_standard(cmd)) + + conc = min(self._quote_concurrency(concurrency), len(batches)) + + # 首次大批量:先把连接并发建好,否则 acquire 会在池锁里串行握手 + # (22 路并发首次调用实测多花 5~6s) + await self._std_pool.warm(conc) + + if not pipeline: + sem = asyncio.Semaphore(conc) + + async def one(batch: list[Symbol]) -> list[SecurityQuote]: + async with sem: + cmd = GetSecurityQuotesCmd([s.as_pair() for s in batch]) + return stamp(await self._execute_standard(cmd)) + + groups = await asyncio.gather(*(one(b) for b in batches)) + return [q for g in groups for q in g] + + # 工作窃取:连接做完一批就回来再取,快的多干、慢的少干。 + # 平均分配(每台固定几片)会被最慢的一台拖住 —— 实测 11 台平均分 + # 时 p50 在 400~580ms 之间抖,改窃取后波动收窄。 + queue = deque(batches) + gate = asyncio.Lock() + + async def worker() -> list[SecurityQuote]: + got: list[SecurityQuote] = [] + while True: + async with gate: + if not queue: + return got + take = min(_QUOTE_PIPE_CHUNK, len(queue)) + chunk = [queue.popleft() for _ in range(take)] + for rows in await self._execute_std_pipeline(chunk): + got.extend(stamp(rows)) + + out: list[SecurityQuote] = [] + for part in await asyncio.gather(*(worker() for _ in range(conc))): + out.extend(part) return out + async def _execute_std_pipeline( + self, batches: list[list[Symbol]] + ) -> list[list[SecurityQuote]]: + """一条连接流水线执行多片报价;节点不支持流水线时降级为逐片。""" + cmds = [GetSecurityQuotesCmd([s.as_pair() for s in b]) for b in batches] + pc = await self._std_pool.acquire() + try: + rows = await pc.execute_pipeline(cmds) + except Exception: + # 流水线中断后响应流已错配,连接必须废弃;改用逐片(每条独立借还) + await self._std_pool.release(pc, broken=True) + fallback: list[list[SecurityQuote]] = [] + for cmd in cmds: + fallback.append(await self._execute_standard(cmd)) + return fallback + await self._std_pool.release(pc) + return rows + async def get_snapshot(self, symbols: str | Sequence[str]) -> list[SymbolSnapshot]: """个股特征快照(当日/换手/活跃度等,仅 A股)。""" syms = parse_symbols(symbols) @@ -860,6 +974,10 @@ class TdxData: - ``vol`` 单位是**百元**(成交额/100),不是手。 - ``trade_count`` 是**当时均价 × 1000**,不是笔数。 + **ETF / LOF 同样没有笔数**:``trade_count`` 是「价格 × 1000」(货币 ETF 恒为 0), + 这类记录的 ``trade_count_available`` 为 ``False`` 且 ``trade_count`` 已置 0。 + 判定规则见 :func:`~pytdxdata.symbols.has_order_count`。 + 详见 :class:`~pytdxdata.models.TransactionRecord` 的类注释。 """ syms = parse_symbols(symbols) @@ -1006,6 +1124,7 @@ class TdxData: trade_count=0, bs_flag=int(row.get("direction", 0) or 0), fields=fields, + trade_count_available=False, # 扩展市场逐笔不带笔数字段 ) async def get_minutes( @@ -1392,6 +1511,14 @@ class TdxData: 注意:返回的是**当前**成分,指数调仓后历史日期不适用。 + ⚠️ **综合指数的成员名单不完整**(实测 2026-10-22):``sh000001`` 只返回 + 2230 只(2190 A + 40 B),而当日沪市 A 股实有 2318 只;缺的 128 只 + (多为近期科创板/主板新股)当日成交 282 亿,正好对上「指数日线 amount − + 成员日线 amount」的 297 亿(残差 4.9%)。因此 + :meth:`get_index_trade_stats` 对**综合指数**会系统性低估约 4.6%; + 样本指数 ``sh000016``(50 只)/ ``sh000300``(300 只)实测比值 + **1.000000**,不受影响。要精确汇总综指成交,请自行用全市场股票列表。 + 用法:: members = await td.get_index_members("000300") @@ -1508,10 +1635,12 @@ class TdxData: for t in ticks: hhmm = t.time[:5] vol_by_min[hhmm] = vol_by_min.get(hhmm, 0.0) + t.vol - tc_by_min[hhmm] = tc_by_min.get(hhmm, 0) + t.trade_count + # 成分里若混入 ETF/LOF(协议无笔数),不能把占位值累加进笔数 + if getattr(t, "trade_count_available", True): + tc_by_min[hhmm] = tc_by_min.get(hhmm, 0) + t.trade_count amt_by_min[hhmm] = amt_by_min.get(hhmm, 0.0) + t.price * t.vol * 100.0 active.add(t.symbol) - if t.trade_count: + if getattr(t, "trade_count_available", True) and t.trade_count: with_tc.add(t.symbol) done += len(batch) if on_progress is not None: diff --git a/src/pytdxdata/cache/manager.py b/src/pytdxdata/cache/manager.py index 61228f2..37e91db 100644 --- a/src/pytdxdata/cache/manager.py +++ b/src/pytdxdata/cache/manager.py @@ -90,6 +90,38 @@ class CacheManager: # 确保清理锁(即使 fetcher 异常也清理,避免无限增长) 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, code: str | None = None) -> int: """按前缀批量失效,返回失效条数。""" diff --git a/src/pytdxdata/cli.py b/src/pytdxdata/cli.py index ea3edd7..d393dd7 100644 --- a/src/pytdxdata/cli.py +++ b/src/pytdxdata/cli.py @@ -38,6 +38,7 @@ from .api import TdxData from dataclasses import asdict from .models import Adjust, ExMarket, KlinePeriod, Market +from .protocol.commands.quotes import price_decimal_digits PERIODS = { "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) +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: pct = (q.price / q.pre_close - 1) * 100 if q.pre_close else 0 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) 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(" 最新 %-10.2f 涨跌 %+8.2f (%+.2f%%)" % (q.price, q.price - q.pre_close, pct)) - print(" 今开 %-10.2f 最高 %.2f 最低 %.2f" % (q.open, q.high, q.low)) - print(" 昨收 %-10.2f 成交量 %s 成交额 %s" % (q.pre_close, _fmt_num(q.vol), _fmt_num(q.amount))) + print((" 最新 %-10.*f 涨跌 %+8.*f (%+.2f%%)" % (dp, q.price, dp, q.price - q.pre_close, pct))) + print((" 今开 %-10.*f 最高 %.*f 最低 %.*f" % (dp, q.open, dp, q.high, dp, q.low))) + print((" 昨收 %-10.*f 成交量 %s 成交额 %s" % (dp, q.pre_close, _fmt_num(q.vol), _fmt_num(q.amount)))) if q.bid and q.ask: print(" " + "-" * 56) + pf = _price_fmt(dp) for i in range(max(len(q.bid), len(q.ask))): b = q.bid[i] if i < len(q.bid) 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]))) print() async def cmd_kline(td: TdxData, sym: str, period: KlinePeriod, count: int, 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) print("%s K线 (%s, %d根):" % (sym, period.name, len(bars))) 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) if b.hour: 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))) async def cmd_transactions(td: TdxData, sym: str, count: int, date: int | None) -> None: 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(" 时间 价格 成交量 方向") for t in tx: bs = "买" if getattr(t, "bs_flag", 0) == 1 else "卖" if getattr(t, "bs_flag", 0) == 2 else "-" - tc = getattr(t, "trade_count", 0) - print(" %-10s %8.2f %10s %s%s" % (t.time, t.price, _fmt_num(t.vol), bs, - " (%d笔)" % tc if tc else "")) + if not getattr(t, "trade_count_available", True): + tc = " (-)" # 指数/ETF/LOF:协议不提供笔数 + 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: 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(" 时间 价格 均价 成交量") - for i, b in enumerate(bars): - print(" %02d:%02d %8.2f %8.2f %10s" % ( - i // 60, i % 60, b.price, b.avg_price, _fmt_num(b.vol))) + for b in bars: + # 用 bar 自带时间:早期按序号推算会打成 00:00~03:59 + 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: diff --git a/src/pytdxdata/models/__init__.py b/src/pytdxdata/models/__init__.py index c4608cb..ef4fd52 100644 --- a/src/pytdxdata/models/__init__.py +++ b/src/pytdxdata/models/__init__.py @@ -117,8 +117,8 @@ class SecurityBar: high: float low: float close: float - vol: float # 股票=股 / 转债=手(与vipdoc一致) - amount: float # 元 + vol: float # 股票=股 / 转债=手(1 手=10 张,与 vipdoc 一致) + amount: float # 元。⚠️ amount/vol 只在股票上等于均价;转债还要再 /10(手=10张) year: int month: int day: int @@ -247,17 +247,42 @@ class TransactionRecord: - ``trade_count`` **不是笔数**,而是**当时均价 × 1000**(实测 tc/1000 与分时 ``avg_price`` 的差 < 1.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 code: str time: str # HH:MM:SS(扩展市场为 HH:MM) price: float - vol: float # 股票=手;指数=百元(成交额/100),见类注释 - trade_count: int # 股票=笔数增量;指数=均价×1000,见类注释 + vol: float # 股票/转债=手;指数=百元(成交额/100),见类注释 + trade_count: int # 股票=笔数增量;指数/基金=占位值,见类注释 bs_flag: int # 1=主动买 0=主动卖 2=中性 5=盘后固定价(指数语义不成立) symbol: str = "" fields: dict[str, float] = field(default_factory=dict) # 扩展市场额外字段(增仓等) + trade_count_available: bool = True # 指数/ETF/LOF 为 False(协议无笔数字段) @dataclass(slots=True) @@ -268,7 +293,7 @@ class MinuteBar: :attr:`datetime` / :attr:`trading_date`,不要自己拿 ``hour`` 拼日期。 """ price: float - vol: float + vol: float # 手(股票/转债同);Σ分时vol 与当日日线 vol 同口径 avg_price: float = 0.0 # 均价(协议第2字段) hour: int = 0 minute: int = 0 diff --git a/src/pytdxdata/pool/connection.py b/src/pytdxdata/pool/connection.py index 7fa9dd4..cc1dad9 100644 --- a/src/pytdxdata/pool/connection.py +++ b/src/pytdxdata/pool/connection.py @@ -3,6 +3,7 @@ from __future__ import annotations import asyncio import time +from collections.abc import Sequence from typing import Generic, TypeVar from ..protocol.commands.base import BaseCommand @@ -22,6 +23,7 @@ class TdxConnection(Generic[T]): self._reader: asyncio.StreamReader | None = None self._writer: asyncio.StreamWriter | None = None self._last_result: T | None = None + self._pipeline_result: list[T] = [] @property def alive(self) -> bool: @@ -107,6 +109,58 @@ class TdxConnection(Generic[T]): body = decompress_body(header, raw_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: """按序发送3条握手命令并丢弃响应。""" assert self._reader is not None and self._writer is not None diff --git a/src/pytdxdata/pool/pool.py b/src/pytdxdata/pool/pool.py index f9aedd9..3f36ecf 100644 --- a/src/pytdxdata/pool/pool.py +++ b/src/pytdxdata/pool/pool.py @@ -59,6 +59,11 @@ class PooledConnection: self.last_used = time.monotonic() 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: self.alive = False try: @@ -273,6 +278,46 @@ class DynamicPool: ] 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: if self.stats.borrowed > 0: self.stats.borrowed -= 1 diff --git a/src/pytdxdata/protocol/commands/transaction.py b/src/pytdxdata/protocol/commands/transaction.py index 015b6de..8770005 100644 --- a/src/pytdxdata/protocol/commands/transaction.py +++ b/src/pytdxdata/protocol/commands/transaction.py @@ -5,6 +5,7 @@ import struct from ..._binary import unpack_from from ...models import TransactionRecord +from ...symbols import has_order_count from ..datetime_ import get_time from ..mac_frame import build_mac_request from ..price import get_price @@ -32,6 +33,8 @@ class GetTransactionDataCmd(BaseCommand[list[TransactionRecord]]): pos = 2 last_price = 0 records: list[TransactionRecord] = [] + code = self.code.decode("utf-8") + has_tc = has_order_count(self.market, code) for _ in range(num): hour, minute, pos = get_time(body, pos) price_diff, pos = get_price(body, pos) @@ -41,10 +44,12 @@ class GetTransactionDataCmd(BaseCommand[list[TransactionRecord]]): _unknown, pos = get_price(body, pos) last_price += price_diff records.append(TransactionRecord( - market=self.market, code=self.code.decode("utf-8"), + market=self.market, code=code, time=f"{hour:02d}:{minute:02d}:00", 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 @@ -68,6 +73,7 @@ class GetHistoryTransactionDataCmd(BaseCommand[list[TransactionRecord]]): pos = 6 # 2(num) + 4(skip) last_price = 0 records: list[TransactionRecord] = [] + code = self.code.decode("utf-8") for _ in range(num): hour, minute, pos = get_time(body, pos) price_diff, pos = get_price(body, pos) @@ -76,10 +82,11 @@ class GetHistoryTransactionDataCmd(BaseCommand[list[TransactionRecord]]): _unknown, pos = get_price(body, pos) last_price += price_diff records.append(TransactionRecord( - market=self.market, code=self.code.decode("utf-8"), + market=self.market, code=code, time=f"{hour:02d}:{minute:02d}:00", 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 @@ -108,6 +115,7 @@ class MacTransactionCmd(BaseCommand[list[TransactionRecord]]): def parse_response(self, body: bytes) -> list[TransactionRecord]: (count,) = unpack_from(" bool: or (code.startswith("000") and int(market) == int(Market.SH)) 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 diff --git a/tests/test_pipeline.py b/tests/test_pipeline.py new file mode 100644 index 0000000..f3ce462 --- /dev/null +++ b/tests/test_pipeline.py @@ -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(" 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("