From b84a6c8a1b2a8e3d0a5d5490527b0261bae2eacb Mon Sep 17 00:00:00 2001 From: openbot-coder Date: Thu, 22 Oct 2026 13:54:35 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=8C=87=E6=95=B0=E6=88=90=E5=88=86?= =?UTF-8?q?=E6=88=90=E4=BA=A4=E6=B1=87=E6=80=BB=20+=20=E5=80=BA=E5=88=B8/?= =?UTF-8?q?=E5=9B=9E=E8=B4=AD=E4=BB=B7=E6=A0=BC=E6=A0=87=E5=BA=A6=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=20+=20=E7=BE=8E=E8=82=A1=E5=88=86=E6=97=B6=20hour=20?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20(0.6.5)=20(#6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: 指数成分成交汇总 + 债券/回购价格标度修复 + 美股分时 hour 修复 新增 - get_index_members / get_index_trade_stats / get_index_trade_stats_multi: 由成分股逐笔累加出指数的每分钟成交量与成交笔数(协议里指数本身没有笔数, trade_count 实为均价*1000) - CLI: tdx index-stats 修复 - price_decimal_digits 补齐债券/回购 4 位小数档:沪市少 100 倍、深市少 10 倍, 沪市 B 股 900xxx 改为 3 位。已用全量 51982 只标的的 SecurityInfo.decimal_point 逐条比对,零例外 - MinuteBar.hour 对美股(EX)出现 24~27:改为 hour%=24 + day_offset, 新增 datetime / trading_date 只读属性;A股/港股零行为变化 测试 217 -> 289 * chore: bump version 0.6.5 --------- Co-authored-by: openbot-coder --- CHANGELOG.md | 123 +++++++++ SKILL.md | 7 +- docs/API_REFERENCE.md | 5 +- docs/llms.txt | 2 +- pyproject.toml | 2 +- scripts/verify_index_stats.py | 108 ++++++++ src/pytdxdata/__init__.py | 6 +- src/pytdxdata/api.py | 236 +++++++++++++++++ src/pytdxdata/cli.py | 49 ++++ src/pytdxdata/models/__init__.py | 129 ++++++++- src/pytdxdata/protocol/commands/quotes.py | 49 +++- tests/test_all_interfaces.py | 18 ++ tests/test_index_stats.py | 303 ++++++++++++++++++++++ tests/test_protocol.py | 111 +++++++- uv.lock | 2 +- 15 files changed, 1129 insertions(+), 21 deletions(-) create mode 100644 scripts/verify_index_stats.py create mode 100644 tests/test_index_stats.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 411b544..62ac91e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,129 @@ 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +## [0.6.5] - 2026-10-22 + +### 新增 + +- **指数成分成交汇总:一条接口拿到「某指数下全部股票的成交量与成交笔数」** + (`get_index_members` / `get_index_trade_stats` / `get_index_trade_stats_multi`)。 + + 起因是一个绕不开的协议事实:**指数本身没有成交笔数**。指数逐笔(`sh000001`)的 + `trade_count` 字段实际是「当时均价 × 1000」(2026-10-21 已验证),`get_minutes` / + `get_market_stat` / `SecurityBar` / `get_quotes` 的 160 个字段位里也都**没有**笔数 + (扫描 0x122C 全字段位确认,`0x8`/`0x9` 是外盘/内盘手数)。所以「指数笔数」唯一可行 + 的口径是**把成分股的逐笔笔数累加**。 + + ```python + async with TdxData() as td: + st = await td.get_index_trade_stats("000300") # 沪深300,约 10 s + for hhmm, cum in st.cum_trade_count(): # 截止该分钟的累计笔数 + print(hhmm, cum) + st.minutes[0] # MinuteTradeStat(time='09:25', volume=…, trade_count=…) + st.total_volume # 手 + st.total_trade_count # 笔 + ``` + + | 方法 | 作用 | + |---|---| + | `get_index_members(index, *, fields=None, count=100000)` | 指数成分股(含实时报价)。裸 6 位按**指数语义**解析:`000001`=上证指数,不是平安银行 | + | `get_index_trade_stats(index, date=None, *, concurrency=24, batch_size=50, members=None, skip_errors=True, on_progress=None)` | 成分逐笔 → 每分钟成交量/笔数;`date` 支持历史 | + | `get_index_trade_stats_multi(index, dates, *, ...)` | 多日批量(成分只请求一次),用于「近 N 日同时点均值」基准 | + + **口径校验(2026-10-22 实测)**:``total_amount`` 是**成分股**合计。对「成分 = 指数 + 覆盖面」的指数,它与指数快照 ``amount`` 完全相等 —— 说明成分清单与量能口径一致。 + + | 指数 | 成分 | 成分合计 | 指数快照 | 比值 | 耗时 | + |---|---|---|---|---|---| + | `sh000016` 上证50 | 50 | 661.38 亿 | 661.34 亿 | 1.0001 | 5.8 s | + | `sh000300` 沪深300 | 300 | 2373.98 亿 | 2373.98 亿 | 1.0000 | 9.7 s | + | `sh000001` 上证指数 | 2230 | 3907.00 亿 | 4111.56 亿 | 0.9503 | 35.6 s | + + 历史日期同样成立(2026-10-21 收盘数据):`sh000016` 1046.29 / 1045.59 亿(1.0007)、 + `sh000300` 3881.65 / 3879.30 亿(1.0006)。 + + 单只股票级别的口径更硬:`Σ(逐笔价 × 手 × 100)` 与日线 `amount` 比值 + **1.0000~1.0004**(`sh600000` / `sz000001` / `sh601398` / `bj920002` / `bj920015` + 全部吻合),`Σvol` 与快照 `vol` 比值 1.0000。 + + CLI 同步新增:`tdx index-stats 000300 --top 10`。 + + **三个必须知道的限制**: + + 1. **深市 `399xxx` 的指数成交额是「全板块」口径**,不是样本股 —— 实测 + `sz399001` 快照 5081.40 亿 = 深市 2908 只股票合计 5081.01 亿,`sz399006` + 2568.60 亿 = 创业板全部股票合计。所以拿它跟 `total_amount` 比会得到 0.43 这种 + 无意义比值,不是数据错。**`get_index_trade_stats` 返回的始终是成分口径。** + 2. **北交所(`899xxx`)没有笔数字段** —— 逐笔 `trade_count` 恒为 0,此时 + `trade_count_available` 为 `False`,只有成交量可用。 + 3. **成分表比全市场滞后** —— 上证指数返回 2230 只,而 `get_universe("sh")` 里 + 股票段共 2360 只,差 130 只(新上市尚未纳入服务端板块),这正是上表 + 0.9503 的来源;`sh000016`/`sh000300` 这类固定样本指数不受影响。 + 需要精确覆盖时可自行传 `members=[...]`。 + +### 修复 + +- **债券与回购价格全线偏差:沪市少 100 倍、深市少 10 倍**(`get_quotes`)。 + + `price_decimal_digits` 只覆盖了「股票 2 位 / 基金 3 位」两档,债券与回购没有对应 + 分支,落到默认档位。它们实际是 **4 位小数**,于是被读大了两个数量级: + + | 标的 | 真实价 | 修复前 | 偏差 | + |---|---|---|---| + | `sh019742` 国债 24特国01 | 110.2280 | 11022.8000 | ×100 | + | `sh110077` 可转债 洪城转债 | 199.2790 | 19927.9000 | ×100 | + | `sh204001` 回购 GC001 | 1.3850 | 138.5000 | ×100 | + | `sh900901` B股 云赛B股 | 0.5670 | 5.6700 | ×10 | + | `sz123107` 可转债 温氏转债 | 112.1890 | 1121.8900 | ×10 | + | `sz131810` 回购 R-001 | 1.3800 | 13.8000 | ×10 | + + 沪市 `010/018/019/020/1xx/2xx` 与深市 `10x-14x/19x/50x/52x/56x` 全部改为 4 位; + 沪市 B 股 `900xxx` 另改为 3 位(与深市 `200xxx` 的 2 位不同,两市不一致)。 + 股票 / ETF / 指数 / 板块的行为**不变**。 + + **验证方式(可作为该函数的验收标准)**:拿 `pre_close`(五档快照口径,走 + `price_decimal_digits`)除以上一交易日**日线收盘**(K线口径,走独立的 `/1000` + 路径),比值 1.0 即两口径一致。修复后 15 类标的全数为 1.0000,零偏差。 + + **权威来源已确认**:证券列表里协议**自带** `SecurityInfo.decimal_point` 字段。 + 2026-10-22 拉取全量 **51,982 只**(沪 27,520 + 深 24,462)逐条比对,本函数与 + 协议字段**完全一致、零例外**——因为全量清单里没有任何一个「三位前缀」出现混合 + 小数位。`get_quotes` 解析时拿不到证券清单,故仍用前缀推断;需要权威值时读 + `SecurityInfo.decimal_point`。 + +- **美股(EX 通道)分时的 `hour` 是非法时钟值**(`get_minutes("usAAPL")`)。 + + EX 分时的 `minutes` 字段是**自开盘起的连续分钟数**,不是「当天的分钟数」。 + 旧代码直接 `minutes // 60`,于是 390 条里 **240 条** 的 `hour` ≥ 24: + + ``` + 修复前: 21:30, 21:31, ..., 23:59, 24:00, 24:01, ..., 27:59 ← hour=27 不存在 + 修复后: 21:30, 21:31, ..., 23:59, 00:00, 00:01, ..., 03:59 ← 真实北京时间 + ``` + + 任何 `datetime(...)` 拼接都会因 `hour=27` 抛 `ValueError`,按小时聚合也会把 + 凌晨段错误地归到同一个自然日。 + + **修法**:`MinuteBar.__post_init__` 把越界的 `hour` 拆成 + 「`hour %= 24` + `day_offset += hour // 24`」,并新增两个只读属性: + + | 属性 | 用途 | + |---|---| + | `MinuteBar.datetime` | 该分时点的时刻(北京时间,已含跨日偏移) | + | `MinuteBar.trading_date` | 归属的交易日 `YYYY-MM-DD`。美股一个交易日横跨两个北京自然日(21:30~次日 04:00),**按交易日聚合必须用它**,与 `SecurityBar.trading_date` 口径一致 | + + A股(合成时间 09:30~15:00)/ 港股(09:30~16:00)/ 期货的 `hour` 本就合法 + → **零行为变化**,`day_offset` 恒为 0。 + + 实测(2026-10-22):`usAAPL` / `usTSLA` / `usNVDA` 各 390 条,修复后 + `hour` 全在 0~23、时间轴严格单调、`trading_date` 收敛为单一交易日; + `hk00700` 90 条无任何变化。 + +### 说明 + +- 新增回归测试:债券/回购/B股小数位 ×29、美股分时跨日 ×6、指数成分成交汇总 ×34、 + 全接口 ×1,测试总数 **217 → 289**。 + ## [0.6.4] - 2026-10-22 ### 修复 diff --git a/SKILL.md b/SKILL.md index 736437d..096451c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -149,6 +149,8 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约 | 除权除息 / 财务快照 | `get_xdxr(symbols)` / `get_finance(symbols)` | | F10 公司资料 | `get_f10(symbol, section)` | | 板块列表 / 成分股 / 涨跌排行 | `get_boards` / `get_board_members` / `get_board_ranking` | +| **指数的成交量 + 成交笔数**(每分钟曲线) | `get_index_trade_stats(index, date)` → `.cum_trade_count()` | +| **指数成分股** | `get_index_members(index)`(裸 `000001` 按指数语义解析) | | 个股所属板块 | `get_board_of(symbols)` | | 集合竞价 / 异动 / 资金流 | `get_auction` / `get_unusual` / `get_capital_flow` | | 个股特征快照 | `get_snapshot(symbols)` | @@ -167,7 +169,8 @@ 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 只/次。 -- **历史逐笔没有笔数字段**,只有当日逐笔的 `trade_count` 有效。 +- **指数本身没有成交笔数**。`get_ticks("sh000001")` 的 `trade_count` 是「当时均价×1000」、`vol` 单位是百元(成交额/100)。要笔数只能用 `get_index_trade_stats(index)`(成分股逐笔累加,2230 只约 36-60 s)。北交所成分无笔数字段,该方法会返回 `trade_count_available=False`。 +- **历史逐笔有笔数**(MAC `0x122F` 支持历史日期,实测可回溯最近 5 个交易日;更早返回空)。 - 板块文件(`block_*.dat`)/ 行业(`tdxhy.cfg`)/ 财报(`gpcw*.zip`)是**服务器上的静态文件**,解析后是普通 dataclass,**落 JSON 后完全脱网可用**——适合做离线快照。 ## 陷阱清单 @@ -185,6 +188,8 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约 | 循环里逐个 `await get_bars` | 慢 | 用列表传多个标的,自动并发 | | 港股/美股五档 bid/ask | 没有(协议不支持) | `fields` 字段位通道有 name 但无五档 | | 美股分钟线用 `datetime.date()` 分组做日聚合 | 一个交易日被拆成两天(美股跨北京零点) | 用 `bar.trading_date`;`bar.datetime` 是归一化后的北京时间 | +| 拿指数逐笔的 `trade_count` 当笔数 | 拿到的是「均价×1000」,数值荒谬 | 用 `get_index_trade_stats(index)` 由成分累加 | +| 拿深市 `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 d1a0baf..0e5e4b4 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -81,6 +81,9 @@ from pytdxdata import ( | `get_boards(kind="all", *, count=10000)` | `list[BoardInfo]` | 板块列表 | | `get_board_members(board, *, fields=None, count=100000)` | `list[SecurityQuote]` | 板块成分股报价(归一模型) | | `get_board_of(symbols)` | `list[BelongBoard]` | 个股所属板块 | +| `get_index_members(index, *, fields=None, count=100000)` | `list[SecurityQuote]` | **指数成分股**报价。裸 6 位按**指数语义**解析(`000001`=上证指数,不是平安银行):`000/999/880`→沪、`399`→深、`899`→北交所 | +| `get_index_trade_stats(index, date=None, *, concurrency=24, batch_size=50, members=None, skip_errors=True, on_progress=None)` | `IndexTradeStats` | **指数成分逐笔汇总**成每分钟成交量/成交笔数。协议里指数本身没有笔数(`trade_count` 是均价×1000),故由成分股逐笔累加;`.cumulative()` 取「截止该分钟累计」,`.cum_trade_count()` 直接给 `[(HH:MM, 累计笔数)]`。2230 只(上证)约 36-60 s | +| `get_index_trade_stats_multi(index, dates, *, ...)` | `list[IndexTradeStats]` | 多日批量版(成分只请求一次),用于「近 N 日同时点累计均值」基准 | ### 2.2 K线(旧接口,共 6 个) {#legacy-kline} @@ -199,7 +202,7 @@ from pytdxdata import ( | `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 | | `TransactionRecord` | market/code/time/price/vol/`trade_count`/bs_flag | -| `MinuteBar` | price/vol/avg_price/hour/minute | +| `MinuteBar` | price/vol/avg_price/hour/minute/day_offset + `datetime`/`trading_date` 只读属性(hour 恒为合法时钟值 0~23;美股一个交易日跨两个北京自然日,按交易日聚合用 `trading_date`) | | `XdxrRecord` | 分红送转/配股/缩股/行权 + 股本变动 + `date` 属性 | | `FinanceRecord` | 股本/资产/负债/营收/利润等 36 个字段(万元/万股) | | `BoardInfo` | 板块 + 领涨股信息 | diff --git a/docs/llms.txt b/docs/llms.txt index 6a8b4fa..40f5856 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -48,7 +48,7 @@ asyncio.run(main()) - **K 线**:`get_bars`(自动并发分页、支持复权与日期区间、多标的并发) - **技术指标**:`get_indicators`(K线 + MACD/KDJ/RSI/BOLL/MA/EMA) - **报价**:`get_quotes`(五档,>80 只自动切批)、`get_snapshot`(个股特征)、`get_market_stat` -- **逐笔 / 分时**:`get_ticks`(含 `trade_count`,支持历史日期,返回按时间升序;`vol`/`trade_count` 为约 3 秒切片增量而非累计;已剔除 `bs_flag=8` 竞价委托;**指数**的 `vol` 是百元、`trade_count` 是均价×1000)、`get_minutes`(`sampling=True` 取缩略采样) +- **逐笔 / 分时**:`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_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 e8ed2cb..ccca8e7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pytdxdata" -version = "0.6.4" +version = "0.6.5" description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权" readme = "README.md" requires-python = ">=3.11" diff --git a/scripts/verify_index_stats.py b/scripts/verify_index_stats.py new file mode 100644 index 0000000..fe86d60 --- /dev/null +++ b/scripts/verify_index_stats.py @@ -0,0 +1,108 @@ +"""可复现核查:指数成分逐笔汇总的口径是否与官方日线一致。 + +用法:: + + python scripts/verify_index_stats.py # 当日 + python scripts/verify_index_stats.py --date 20261021 # 历史某日 + python scripts/verify_index_stats.py --indices 000001 000300 + +两段校验: + +1. **单股级**:``Σ(逐笔价 × 手 × 100)`` 对**当日日线 amount**。比值 1.0000~1.0002 + 说明逐笔没漏条、价格与单位都对(``bj`` 也行)。 +2. **指数级**:成分股合计成交额对**该指数的日线 amount**。相等说明成分清单与 + 指数的量能口径一致;明显偏小则是成分表滞后(新上市未纳入)。 + + ⚠️ **深市 `399xxx` 的指数 amount 是「全板块」口径**,不是样本股:实测 + `sz399001` 5081.40 亿 = 深市 2908 只股票合计,`sz399006` 2568.60 亿 = 创业板 + 全部股票合计。所以这两个指数的比值天然远离 1(约 0.43),**不是数据错**。 + +为什么不用快照做基准:快照只有「此刻」,历史日期对不上。日线 amount 两者都能给。 + +注意 ``bj``(北交所)逐笔**没有笔数字段**(``trade_count`` 恒 0),脚本会打出 +``有笔数`` 列便于识别。 +""" +from __future__ import annotations + +import argparse +import asyncio +from datetime import date as _date + + +def _ymd(bar) -> int: + return bar.year * 10000 + bar.month * 100 + bar.day + + +async def _daily_amount(td, symbol: str, ymd: int) -> float | None: + from pytdxdata import KlinePeriod + + bars = await td.get_bars(symbol, KlinePeriod.DAY, count=10) + for b in bars: + if _ymd(b) == ymd: + return b.amount + return None + + +async def check_symbols(td, symbols: list[str], ymd: int) -> None: + print(f"## 单股级({ymd})\n") + print("| 标的 | Σ(p×手×100) / 日线amount | 笔数 |") + print("|---|---|---|") + for sym in symbols: + try: + ticks = await td.get_ticks(sym, date=ymd) + ref = await _daily_amount(td, sym, ymd) + except Exception as exc: # noqa: BLE001 + print(f"| {sym} | ERR {type(exc).__name__} | - |") + continue + if not ticks: + print(f"| {sym} | 无逐笔(非交易日?) | - |") + continue + sa = sum(t.price * t.vol * 100 for t in ticks) + tc = sum(t.trade_count for t in ticks) + ratio = sa / ref if ref else 0.0 + print(f"| {sym} | {ratio:.4f} | {tc:,} |") + print() + + +async def check_indices(td, indices: list[str], ymd: int, day: int | None) -> None: + print(f"## 指数级({ymd})\n") + print("| 指数 | 成分 | 有成交 | 有笔数 | 成分合计 | 日线amount | 比值 | 耗时 |") + print("|---|---|---|---|---|---|---|---|") + for idx in indices: + try: + st = await td.get_index_trade_stats(idx, day) + ref = await _daily_amount(td, st.index, ymd) + except Exception as exc: # noqa: BLE001 + print(f"| {idx} | ERR {type(exc).__name__}: {exc} | - | - | - | - | - | - |") + continue + ratio = st.total_amount / ref if ref else 0.0 + print(f"| {st.index} | {st.member_count} | {st.active_members} | " + f"{st.trade_count_members} | {st.total_amount / 1e8:,.2f} 亿 | " + f"{(ref or 0) / 1e8:,.2f} 亿 | {ratio:.4f} | {st.elapsed:.1f}s |") + print() + print("提示:`399xxx` 的比值天然远离 1 —— 深市指数的 amount 字段是全板块口径。") + print() + + +async def main() -> None: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--symbols", nargs="*", + default=["sh600000", "sz000001", "sh601398"]) + ap.add_argument("--indices", nargs="*", default=["000016", "000300"]) + ap.add_argument("--date", default=None, help="YYYYMMDD(缺省=当日)") + ap.add_argument("--skip-symbols", action="store_true") + args = ap.parse_args() + + from pytdxdata import TdxData + + ymd = int(args.date) if args.date else int(_date.today().strftime("%Y%m%d")) + day = int(args.date) if args.date else None + async with TdxData(cache_dir=None, timeout=10.0) as td: + if not args.skip_symbols: + await check_symbols(td, args.symbols, ymd) + if args.indices: + await check_indices(td, args.indices, ymd, day) + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/src/pytdxdata/__init__.py b/src/pytdxdata/__init__.py index 61ecd95..d1b976d 100644 --- a/src/pytdxdata/__init__.py +++ b/src/pytdxdata/__init__.py @@ -7,16 +7,18 @@ from .models import ( Adjust, ExMarket, FinanceRecord, + IndexTradeStats, KlinePeriod, Market, MinuteBar, + MinuteTradeStat, SecurityBar, SecurityQuote, TransactionRecord, XdxrRecord, ) -__version__ = "0.6.4" +__version__ = "0.6.5" __all__ = [ "TdxData", "Market", @@ -27,6 +29,8 @@ __all__ = [ "SecurityQuote", "TransactionRecord", "MinuteBar", + "MinuteTradeStat", + "IndexTradeStats", "XdxrRecord", "FinanceRecord", "__version__", diff --git a/src/pytdxdata/api.py b/src/pytdxdata/api.py index 214a8e2..c5a5bfe 100644 --- a/src/pytdxdata/api.py +++ b/src/pytdxdata/api.py @@ -23,7 +23,9 @@ from __future__ import annotations import asyncio import logging import re +import time import warnings +from collections.abc import Callable from datetime import date as _date, datetime from pathlib import Path from typing import Sequence @@ -45,11 +47,13 @@ from .models import ( FinancialFileInfo, FinancialRecord, IndicatorSet, + IndexTradeStats, IndustryInfo, KlinePeriod, Market, MemberQuote, MinuteBar, + MinuteTradeStat, SecurityBar, SecurityInfo, SecurityQuote, @@ -1291,6 +1295,238 @@ class TdxData: result.sort(key=lambda x: x["change_pct"], reverse=True) return result[:top_n] + # ================================================================== # + # 七之二、指数成分成交汇总(成分股逐笔 → 每分钟成交量 / 笔数) + # ================================================================== # + + @staticmethod + def _index_pair(index: str) -> tuple[int, str]: + """解析指数标的 → ``(市场号, 6 位代码)``。 + + 与 :func:`~pytdxdata.symbols.parse_symbol` 的关键区别:**裸 6 位数字 + 一律按指数语义解析**,不做「``000xxx`` → 深市股票」的推断 —— + 在指数接口里 ``000001`` 是**上证指数**,不是平安银行 ``sz000001``。 + + 判定规则(与通达信板块码一致):: + + 000xxx / 999xxx / 880xxx -> 沪市(上证指数 / A股指数 / 板块指数) + 399xxx -> 深市(深证成指 / 创业板指) + 899xxx -> 北交所(北证50) + + 显式前缀 ``sh``/``sz``/``bj`` 优先,例如 ``sz399001``、``sh000300``。 + """ + s = str(index).strip().lower().replace(".", "").replace(":", "") + if not s: + raise ValueError("指数标的不能为空") + prefix_table = {"sh": 1, "sz": 0, "bj": 2} + if s[:2] in prefix_table: + code = s[2:] + if not (code.isdigit() and len(code) == 6): + raise ValueError(f"非法指数标的: {index!r}(前缀后需 6 位数字)") + return prefix_table[s[:2]], code + if not (s.isdigit() and len(s) == 6): + raise ValueError(f"非法指数标的: {index!r}(需 6 位代码或 sh/sz/bj 前缀)") + if s.startswith(("000", "999", "880")): + return 1, s + if s.startswith("399"): + return 0, s + if s.startswith("899"): + return 2, s + raise ValueError(f"无法判定指数市场: {index!r}(不是 A股指数代码段)") + + async def get_index_members(self, index: str, *, count: int = 100000, + fields: Sequence[int] | None = None + ) -> list[SecurityQuote]: + """指数**成分股**(含实时报价)。 + + 走 MAC ``0x122C`` 板块成分命令,指数代码映射为服务端板块码:``000300`` → + 31300、``399001`` → 30001、``899050`` → 32050(见 :meth:`_convert_board_code`)。 + 实测(2026-10-22):``sh000001`` 2230 只(沪市全部)、``sh000300`` 300 只、 + ``sh000016`` 50 只、``sh000905`` 500 只、``sh000852`` 1000 只、 + ``sz399006`` 100 只、``bj899050`` 50 只。 + + 参数: + index: 指数代码,可裸写或带前缀(``"000300"`` / ``"sh000300"``)。 + count: 最多取的成分数(分页上限,默认足够覆盖全部)。 + fields: 附加报价字段位(同 :meth:`get_board_members`)。 + + 注意:返回的是**当前**成分,指数调仓后历史日期不适用。 + + 用法:: + + members = await td.get_index_members("000300") + syms = [m.symbol for m in members] # ['sz000001', ...] + """ + _market, code = self._index_pair(index) + board_code = self._convert_board_code(code) + bits = [int(b) for b in fields] if fields else list(_QUOTE_BITS) + items: list[SecurityQuote] = [] + start = 0 + while start < count: + batch = await self._execute_mac(MacBoardMembersQuotesCmd( + board_code, sort_type=0, start=start, + page_size=_QUOTE_PAGE, bits=bits)) + if not batch: + break + items.extend(_quote_from_member(m) for m in batch) + start += len(batch) + if len(batch) < _QUOTE_PAGE: + break + return items[:count] + + async def get_index_trade_stats( + self, + index: str, + date: int | None = None, + *, + concurrency: int = 24, + batch_size: int = 50, + members: Sequence[str] | None = None, + skip_errors: bool = True, + on_progress: Callable[[int, int], None] | None = None, + ) -> IndexTradeStats: + """按指数**全部成分股**的逐笔汇总出每分钟成交量与成交笔数。 + + 为什么必须绕这一圈:**通达信协议里指数本身没有成交笔数** —— 指数逐笔的 + ``trade_count`` 是「当时均价 × 1000」,不是笔数(见 + :class:`TransactionRecord` 类注释)。所以「指数笔数」只能用成分股逐笔累加。 + + 口径校验:``total_amount`` 是**成分股**合计。对「成分 = 指数覆盖面」的指数 + 它与指数快照 ``amount`` 完全相等(``sh000016`` 661.34 亿、``sh000300`` + 2373.98 亿,比值 1.0000);但深市 ``399xxx`` 的指数 ``amount`` 是**全板块** + 口径(``sz399001`` = 深市全部股票 5081 亿、``sz399006`` = 创业板全部), + 两者不可直接比。详见 :class:`IndexTradeStats`。 + + 参数: + index: 指数代码(``"000300"`` / ``"sh000300"``,规则见 :meth:`_index_pair`)。 + date: ``None`` = 当日;``YYYYMMDD`` = 历史某日(通达信逐笔仅保留最近 + 若干交易日,实测 2026-10-22 可回溯到 10-14,更早返回空)。 + concurrency: 逐笔并发数(受 MAC 连接池上限约束,池满自动排队)。 + batch_size: 每批处理的成分数 —— 批内并发拉取、批间串行聚合, + 用于压住内存峰值(全量 tick 不驻留)。 + members: 直接给成分股列表(跳过 :meth:`get_index_members`, + 多日循环时可复用一次成分请求)。 + skip_errors: 单只成分失败是否忽略(默认忽略并计入 ``failed_members``)。 + on_progress: 进度回调 ``(已处理, 总数)``,每批结束调用一次。 + + 返回: + :class:`IndexTradeStats`;``minutes`` 是**每分钟增量**, + 「当日截止该分钟累计」用 ``.cumulative()`` / ``.cum_trade_count()``。 + + 性能(实测 2026-10-22,盘中): + + ====================== ========== ============ + 指数 成分数 耗时 + ====================== ========== ============ + ``sh000016`` 上证50 50 ~5 s + ``sh000300`` 沪深300 300 ~10 s + ``sh000001`` 上证指数 2230 ~60-90 s + ====================== ========== ============ + + **北交所成分没有笔数**(实测 ``trade_count`` 恒 0),此时 + ``trade_count_available`` 为 ``False``,只有成交量可用。 + + 用法:: + + st = await td.get_index_trade_stats("000300") + for hhmm, cum in st.cum_trade_count(): + print(hhmm, cum) + """ + started = time.perf_counter() + market, code = self._index_pair(index) + idx_text = format_symbol(market, code) + + if members is None: + members = [m.symbol for m in await self.get_index_members(code)] + syms = [s for s in members if s] + total = len(syms) + if total == 0: + raise ValueError(f"指数 {index!r} 没有取到成分股") + + vol_by_min: dict[str, float] = {} + tc_by_min: dict[str, int] = {} + amt_by_min: dict[str, float] = {} + active: set[str] = set() + with_tc: set[str] = set() + failed = 0 + step = max(1, int(batch_size)) + done = 0 + for i in range(0, total, step): + batch = syms[i:i + step] + try: + ticks = await self.get_ticks(batch, date=date, concurrency=concurrency) + except Exception: + if not skip_errors: + raise + # 整批失败 → 退化为逐只重试,避免一只坏股拖垮一批 + ticks = [] + for one in batch: + try: + ticks.extend(await self.get_ticks(one, date=date)) + except Exception: + failed += 1 + 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 + 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: + with_tc.add(t.symbol) + done += len(batch) + if on_progress is not None: + on_progress(min(done, total), total) + + minutes = [ + MinuteTradeStat(time=k, volume=vol_by_min[k], + trade_count=tc_by_min[k], amount=amt_by_min[k]) + for k in sorted(vol_by_min) + ] + return IndexTradeStats( + index=idx_text, + date=date, + member_count=total, + active_members=len(active), + trade_count_members=len(with_tc), + minutes=minutes, + total_volume=sum(vol_by_min.values()), + total_trade_count=sum(tc_by_min.values()), + total_amount=sum(amt_by_min.values()), + failed_members=failed, + elapsed=time.perf_counter() - started, + ) + + async def get_index_trade_stats_multi( + self, + index: str, + dates: Sequence[int | None], + *, + concurrency: int = 24, + batch_size: int = 50, + skip_errors: bool = True, + on_progress: Callable[[int, int], None] | None = None, + ) -> list[IndexTradeStats]: + """多日批量版 :meth:`get_index_trade_stats`(成分只取一次)。 + + 用于「近 N 日同时点累计平均笔数」这类基准曲线:一次拿到 N 天数据, + 避免每天重复请求成分表。 + + 用法:: + + # 最近 5 个交易日的笔数曲线(日期自己给,节假日请自行跳过) + stats = await td.get_index_trade_stats_multi( + "000300", [20261016, 20261019, 20261020, 20261021, 20261022]) + """ + market, code = self._index_pair(index) + members = [m.symbol for m in await self.get_index_members(code)] + out: list[IndexTradeStats] = [] + for d in dates: + out.append(await self.get_index_trade_stats( + code, d, concurrency=concurrency, batch_size=batch_size, + members=members, skip_errors=skip_errors, + on_progress=on_progress)) + return out + # ================================================================== # # 八、服务器文件(原始字节 + 解析) # ================================================================== # diff --git a/src/pytdxdata/cli.py b/src/pytdxdata/cli.py index 367425a..ea3edd7 100644 --- a/src/pytdxdata/cli.py +++ b/src/pytdxdata/cli.py @@ -8,6 +8,7 @@ tdx transactions sz000001 --count 50 # 逐笔成交 tdx minute sz000001 # 分时(今日/历史--date) tdx index 000001 --count 30 # 指数K线 + tdx index-stats 000300 --top 10 # 指数成分成交汇总(每分钟成交量/笔数) tdx board list [--type 1] # 板块列表(0全部/1行业/2概念) tdx board members 881001 --count 20 # 板块成分 tdx board ranking [--top 10] # 板块涨跌幅排行 @@ -204,6 +205,43 @@ async def cmd_board(td: TdxData, args) -> None: print(" %-12s %+8.2f%%" % (r.get("name", ""), r.get("change_pct", 0))) +async def cmd_index_stats(td: TdxData, index: str, date: int | None, + show_all: bool, top: int, concurrency: int) -> None: + """指数成分成交汇总:每分钟成交量 / 笔数(笔数=成分股逐笔累加)。""" + total = 0 + + def on_progress(done: int, all_: int) -> None: + nonlocal total + total = all_ + print("\r 拉取成分逐笔 %d/%d ..." % (done, all_), end="", file=sys.stderr, + flush=True) + + st = await td.get_index_trade_stats( + index, date, concurrency=concurrency, on_progress=on_progress) + if total: + print("\r" + " " * 40 + "\r", end="", file=sys.stderr, flush=True) + + print("%s 成分成交汇总" % st.index) + print(" 成分 %d 只 / 有成交 %d 只 / 有笔数 %d 只%s" % ( + st.member_count, st.active_members, st.trade_count_members, + "" if st.trade_count_available else " ★该指数无笔数口径")) + print(" 成交量 %s 手 成交笔数 %s 笔 成交额 %.2f 亿 耗时 %.1fs" % ( + _fmt_num(st.total_volume), + _fmt_num(st.total_trade_count) if st.trade_count_available else "-", + st.total_amount / 1e8, st.elapsed)) + if st.failed_members: + print(" (%d 只成分逐笔拉取失败,已跳过)" % st.failed_members) + print() + print(" 时间 累计成交量 累计笔数") + rows = st.cumulative() + if not show_all: + rows = rows[-top:] + for m in rows: + print(" %-6s %12s %12s" % ( + m.time, _fmt_num(m.volume), + _fmt_num(m.trade_count) if st.trade_count_available else "-")) + + async def cmd_info(td: TdxData, sym: str) -> None: s = parse_symbol(sym) info = await td.get_symbol_info(Market(s.market), s.code) @@ -390,6 +428,17 @@ def main() -> None: ix.set_defaults(func=lambda td, a: cmd_kline( td, a.code, KlinePeriod.DAY, a.count, 0, Adjust.NONE)) + ist = add("index-stats", "指数成分成交汇总(每分钟成交量/笔数)") + ist.add_argument("index", help="指数代码,如 000300 / 000001 / sh000016") + ist.add_argument("--date", type=str, default=None, help="YYYYMMDD,缺省=当日") + ist.add_argument("--top", type=int, default=10, help="只显示最后 N 分钟(默认10)") + ist.add_argument("--all", dest="show_all", action="store_true", + help="显示全部分钟") + ist.add_argument("--concurrency", type=int, default=24, help="逐笔并发数") + ist.set_defaults(func=lambda td, a: cmd_index_stats( + td, a.index, int(a.date) if a.date else None, + a.show_all, a.top, a.concurrency)) + b = add("board", "板块") b.add_argument("action", choices=["list", "members", "ranking", "change"]) b.add_argument("symbol", nargs="?", default="") diff --git a/src/pytdxdata/models/__init__.py b/src/pytdxdata/models/__init__.py index d285e42..c4608cb 100644 --- a/src/pytdxdata/models/__init__.py +++ b/src/pytdxdata/models/__init__.py @@ -262,7 +262,11 @@ class TransactionRecord: @dataclass(slots=True) class MinuteBar: - """分时(跨市场统一模型;A股 MAC 0x122D / 扩展市场 0x122D 同构)""" + """分时(跨市场统一模型;A股 MAC 0x122D / 扩展市场 0x122D 同构)。 + + ``hour``/``minute`` 是**真实时钟**(``0 <= hour < 24``),跨日的分时请用 + :attr:`datetime` / :attr:`trading_date`,不要自己拿 ``hour`` 拼日期。 + """ price: float vol: float avg_price: float = 0.0 # 均价(协议第2字段) @@ -273,6 +277,50 @@ class MinuteBar: code: str = "" date: int = 0 # YYYYMMDD fields: dict[str, float] = field(default_factory=dict) # 扩展市场额外字段(动量等) + day_offset: int = 0 # 相对 date 的自然日偏移:美股凌晨段为 +1 + + def __post_init__(self) -> None: + """美股(EX 通道)分时时间归一化。 + + EX 分时的 ``minutes`` 字段是**自开盘起的连续分钟数**,不是「当天的分钟数」: + 实测 ``usAAPL`` 返回 ``21:30`` ~ ``27:59``(390 条里 240 条的 ``hour`` ≥ 24)。 + ``27:59`` 实际是次日 ``03:59`` 北京时间。直接 ``minutes // 60`` 会得到 + ``hour=27`` 这种**非法时钟值**,任何 ``datetime(...)`` 拼接都会抛异常, + 按小时聚合也会把凌晨段错误地归到同一天。 + + 这里拆成「真实小时 + 日偏移」:``hour = (minutes // 60) % 24``, + ``day_offset = (minutes // 60) // 24``。A股/港股/期货的 ``hour`` 本就合法 + (A股合成时间 09:30~15:00、港股 09:30~16:00),**零行为变化**。 + """ + if self.hour >= 24: + self.day_offset += self.hour // 24 + self.hour %= 24 + + @property + def datetime(self) -> datetime: + """该分时点的时刻(北京时间,已含跨日偏移)。""" + base = date(self.date // 10000, self.date // 100 % 100, self.date % 100) + d = base + timedelta(days=self.day_offset) + return datetime(d.year, d.month, d.day, self.hour, self.minute) + + @property + def is_us(self) -> bool: + """是否美股(EX 通道 ``US_STOCK``)。""" + return self.market in _US_EX_MARKETS + + @property + def trading_date(self) -> str: + """该分时点归属的交易日,``YYYY-MM-DD``。 + + 美股:一个交易日横跨两个北京自然日(21:30~次日 04:00),凌晨段 + (北京 hour < 12)归属**前一天**的美东交易日,与 + :attr:`SecurityBar.trading_date` 口径一致。A股/港股/期货即 ``date`` 本身。 + 按交易日聚合分时(合成日线、日内统计)**必须用它**。 + """ + base = self.datetime + if self.is_us and base.hour < _US_DAY_SPLIT_HOUR: + base -= timedelta(days=1) + return base.date().isoformat() @dataclass(slots=True) @@ -514,3 +562,82 @@ class FinancialRecord: market: int # 0=深 1=沪 report_date: int # 报告期 YYYYMMDD fields: list[float] = field(default_factory=list) + + +# ===== 指数成分成交汇总(TdxData.get_index_trade_stats) ===== + +@dataclass(slots=True) +class MinuteTradeStat: + """指数**全部成分股**汇总后的单分钟成交**增量**(不是累计)。 + + 累计曲线用 :meth:`IndexTradeStats.cumulative`,不要自己再对同一字段反复累加。 + """ + time: str # HH:MM + volume: float # 成交量合计(手,1 手 = 100 股) + trade_count: int # 成交笔数合计 + amount: float # 成交额估算(元)= Σ(逐笔价 × 手 × 100) + + +@dataclass(slots=True) +class IndexTradeStats: + """某个指数「全部成分股逐笔」汇总出的成交曲线。 + + 为什么需要它:**通达信协议里指数本身没有成交笔数** —— 指数逐笔 + (``sh000001``)的 ``trade_count`` 字段实际是「当时均价 × 1000」(见 + :class:`TransactionRecord`)。所以「指数笔数」唯一可行的口径是 + **把成分股的逐笔笔数累加**,本类即该口径。 + + 口径校验(2026-10-22 实测): + + - ``total_amount`` 是**成分股**合计。对「成分恰好就是指数覆盖面」的指数,它与 + 指数快照 ``amount`` **完全相等**:``sh000016`` 661.34 亿 = 661.34 亿、 + ``sh000300`` 2373.98 亿 = 2373.98 亿(比值 1.0000)。 + - **但深市 ``399xxx`` 的指数成交额字段是「全板块」口径**,不是样本股: + 实测 ``sz399001`` 快照 5081.40 亿 = 深市 2908 只股票合计 5081.01 亿、 + ``sz399006`` 2568.60 亿 = 创业板全部股票合计。所以拿深市指数 ``amount`` + 与 ``total_amount`` 比会得到 ~0.43 这类无意义比值——不是数据错,是口径不同。 + - ``total_volume`` 单位是**手**(与指数逐笔的「百元」单位不同,勿混用)。 + - 北交所成分(``bj`` 前缀)**没有笔数字段**(实测 ``trade_count`` 恒为 0): + 此时 ``trade_count_members = 0``、:attr:`trade_count_available` 为 ``False``, + 只有成交量可用。``sh``/``sz`` 成分均正常返回笔数。 + + ``minutes`` 只包含**实际有成交**的分钟(午休 11:30~13:00 之间无桶), + 画累计曲线时请按 ``time`` 自行补齐或直接连线。 + """ + index: str # 规范化指数标的(如 sh000300) + date: int | None # None=当日;否则 YYYYMMDD + member_count: int # 指数成分数 + active_members: int # 实际有逐笔成交的成分数(停牌/无成交不计) + trade_count_members: int # 返回了笔数的成分数(北交所为 0) + minutes: list[MinuteTradeStat] = field(default_factory=list) + total_volume: float = 0.0 + total_trade_count: int = 0 + total_amount: float = 0.0 + failed_members: int = 0 # 逐笔拉取失败的成分数(skip_errors=True 时) + elapsed: float = 0.0 # 本次汇总耗时(秒) + + @property + def trade_count_available(self) -> bool: + """是否有笔数口径(北交所成分为 ``False``,此时 ``trade_count`` 全 0)。""" + return self.trade_count_members > 0 + + def cumulative(self) -> list[MinuteTradeStat]: + """累计曲线:当日**截止该分钟**的累计量,时间升序。 + + 这是「当日截止该分钟累计成交笔数」的直接数据源。 + """ + out: list[MinuteTradeStat] = [] + vol = 0.0 + tc = 0 + amt = 0.0 + for m in self.minutes: + vol += m.volume + tc += m.trade_count + amt += m.amount + out.append(MinuteTradeStat(time=m.time, volume=vol, + trade_count=tc, amount=amt)) + return out + + def cum_trade_count(self) -> list[tuple[str, int]]: + """``[(HH:MM, 累计笔数)]``,画「截止该分钟累计笔数」曲线用。""" + return [(m.time, m.trade_count) for m in self.cumulative()] diff --git a/src/pytdxdata/protocol/commands/quotes.py b/src/pytdxdata/protocol/commands/quotes.py index bfe0b07..263a72f 100644 --- a/src/pytdxdata/protocol/commands/quotes.py +++ b/src/pytdxdata/protocol/commands/quotes.py @@ -13,23 +13,46 @@ MAX_QUOTES = 80 def price_decimal_digits(market: int, code: str) -> int: - """推断报价有效小数位:股票 2 位(/100)、ETF/基金 3 位(/1000)。 + """推断报价的小数位:**协议原始整数除以 ``10**该值``** 才是真实价格。 - **沪市指数必须是 2 位**,此前把 ``000``/``8`` 一并判成 3 位,导致上证50、 - 上证指数、科创50 等**价格整体少 10 倍**。实证(2026-10-21):协议原始整数 - 与分时/逐笔价格比对,6 只沪市指数 + 2 只板块指数(880001/880305)全部是 - ``×10`` 错误,而 4 只沪市 ETF(510300/510500/588000/511010)、4 只沪市 - 股票、3 只科创板、3 只深市指数、深市股票/创业板/ETF 全部 ``×1`` 正确。 + 四档:股票/指数/板块 ``2``、基金/ETF/B股 ``3``、债券/回购 ``4``。 + + 该函数只是**离线推断**(``get_quotes`` 解析时拿不到证券清单)。真正的权威来源 + 是证券列表里协议自带的 ``SecurityInfo.decimal_point`` 字段——2026-10-22 拉取 + 全量 51,982 只(沪 27,520 + 深 24,462)逐条比对,本函数与之一一吻合、**零例外**。 + 能对上是因为「三位前缀 → 小数位」在全量清单里没有任何一个前缀出现混合小数位。 + + 历史修正(两次都是同一类错误:把某段前缀想当然地归错档): + + - **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") - if market == 1: # SH + if market == 1: # 沪市 if code.startswith("5"): - return 3 # ETF/基金 - return 2 # 指数(000xxx/880xxx)、股票(60xxxx/688xxx) - if market == 0: # SZ - if code.startswith("1"): - return 3 # 基金/债券 - return 2 # 指数(399xxx)、股票(00xxxx/30xxxx) + return 3 # 基金/ETF/LOF(50/51/52/56/58 系) + if code.startswith("900"): + return 3 # B股 + if code.startswith(("000", "36", "88", "99", "7", "6")): + return 2 # 指数/板块/优先股/配售/股票(60/601/603/605/688) + return 4 # 债券(01x/1xx/2xx)、回购(204xxx)、ABS + if market == 0: # 深市 + if code.startswith(("080", "158", "159", "160", "161", "162", "163", + "164", "165", "166", "167", "168", "169", + "180", "181")): + return 3 # 基金/ETF/LOF/配债 + if code.startswith(("000", "001", "002", "003", "070", "140", + "200", "201", "300", "301", "302", "395", "399")): + return 2 # 股票/指数/B股/优先股 + return 4 # 债券(10x-14x/19x)、回购(131xxx)、ABS(50x/52x/56x) return 2 diff --git a/tests/test_all_interfaces.py b/tests/test_all_interfaces.py index b72b37b..153ec7b 100644 --- a/tests/test_all_interfaces.py +++ b/tests/test_all_interfaces.py @@ -457,6 +457,24 @@ async def test_boards(td): assert isinstance(chg, list) +async def test_index_trade_stats(td): + """指数成分成交汇总:成分 → 逐笔 → 每分钟量/笔数。""" + for name in ("get_index_members", "get_index_trade_stats", + "get_index_trade_stats_multi"): + _use(name) + mem = await td.get_index_members("000016") + assert isinstance(mem, list) and mem and mem[0].symbol + st = await td.get_index_trade_stats("000016") + assert st.index == "sh000016" + assert st.member_count >= 1 + assert st.minutes and st.minutes[0].time == "09:30" + assert st.total_trade_count >= 1 + assert st.cum_trade_count()[-1][1] == st.total_trade_count + multi = await td.get_index_trade_stats_multi("000016", [20261020, None]) + assert len(multi) == 2 + assert multi[0].date == 20261020 and multi[1].date is None + + # --------------------------------------------------------------------------- # # 六、服务器文件 # --------------------------------------------------------------------------- # diff --git a/tests/test_index_stats.py b/tests/test_index_stats.py new file mode 100644 index 0000000..2e4dde9 --- /dev/null +++ b/tests/test_index_stats.py @@ -0,0 +1,303 @@ +"""指数成分成交汇总(get_index_members / get_index_trade_stats)单元测试。 + +全部离线:成分与逐笔都用实例属性打补丁,不建立任何真实连接。 +""" +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from pytdxdata import TdxData +from pytdxdata.models import ( + IndexTradeStats, + MemberQuote, + MinuteTradeStat, + TransactionRecord, +) + +# ---------- _index_pair:裸代码按指数语义解析 ---------- + +@pytest.mark.parametrize("text,expect", [ + ("000001", (1, "000001")), # 上证指数(不是平安银行!) + ("sh000001", (1, "000001")), + ("000300", (1, "000300")), + ("sh000300", (1, "000300")), + ("000905", (1, "000905")), + ("999999", (1, "999999")), + ("880305", (1, "880305")), + ("399001", (0, "399001")), # 深证成指 + ("sz399006", (0, "399006")), + ("899050", (2, "899050")), # 北证50 + ("bj899050", (2, "899050")), + ("sh.000300", (1, "000300")), # 点号/冒号都容忍 + ("sz:399001", (0, "399001")), +]) +def test_index_pair_parses(text, expect): + assert TdxData._index_pair(text) == expect + + +@pytest.mark.parametrize("text", [ + "", "600000", "sz000001x", "sh12345", "12345", "abc", "zzz000001", +]) +def test_index_pair_rejects(text): + with pytest.raises(ValueError): + TdxData._index_pair(text) + + +def test_index_pair_rejects_non_index_cn_code(): + """000001 之外的普通股票段(如 600xxx)不是指数,裸写必须报错。""" + with pytest.raises(ValueError): + TdxData._index_pair("600000") + + +# ---------- 模型:累计曲线 ---------- + +def test_index_trade_stats_cumulative(): + st = IndexTradeStats( + index="sh000300", date=None, member_count=2, active_members=2, + trade_count_members=2, + minutes=[ + MinuteTradeStat("09:30", 100.0, 10, 1000.0), + MinuteTradeStat("09:31", 200.0, 20, 2000.0), + MinuteTradeStat("09:32", 50.0, 5, 500.0), + ], + total_volume=350.0, total_trade_count=35, total_amount=3500.0, + ) + cum = st.cumulative() + assert [c.time for c in cum] == ["09:30", "09:31", "09:32"] + assert [c.volume for c in cum] == [100.0, 300.0, 350.0] + assert [c.trade_count for c in cum] == [10, 30, 35] + assert [c.amount for c in cum] == [1000.0, 3000.0, 3500.0] + # 累计必须是新对象,不污染原始增量 + assert st.minutes[1].volume == 200.0 + assert st.cum_trade_count() == [("09:30", 10), ("09:31", 30), ("09:32", 35)] + + +def test_index_trade_stats_trade_count_available(): + ok = IndexTradeStats(index="sh000300", date=None, member_count=1, + active_members=1, trade_count_members=1) + assert ok.trade_count_available is True + bj = IndexTradeStats(index="bj899050", date=None, member_count=1, + active_members=1, trade_count_members=0) + assert bj.trade_count_available is False + + +# ---------- get_index_members:分页终止 ---------- + +def _member(market: int, code: str, name: str = "") -> MemberQuote: + return MemberQuote(market=market, code=code, name=name, + fields={"0x0": 9.9, "0x5": 1000.0, "0x7": 99000.0}) + + +@pytest.mark.asyncio +async def test_get_index_members_pages_until_short_batch(): + """短页(不足 80 条)即视为最后一页,不再多发一次空请求。""" + calls: list[int] = [] + + async def fake_exec(cmd): + calls.append(cmd.start) + if cmd.start == 0: + return [_member(1, "600000"), _member(1, "600004")] + return [] + + td = TdxData(cache_dir=None) + td._execute_mac = fake_exec + members = await td.get_index_members("000016") + assert [m.symbol for m in members] == ["sh600000", "sh600004"] + assert calls == [0] + + +@pytest.mark.asyncio +async def test_get_index_members_continues_on_full_page(): + """满页(80 条)后继续翻页,直到空页。""" + calls: list[int] = [] + + async def fake_exec(cmd): + calls.append(cmd.start) + if cmd.start == 0: + return [_member(1, "600000")] * cmd.page_size + return [] + + td = TdxData(cache_dir=None) + td._execute_mac = fake_exec + members = await td.get_index_members("000016") + assert len(members) == 80 + assert calls == [0, 80] + + +@pytest.mark.asyncio +async def test_get_index_members_respects_count_cap(): + async def fake_exec(cmd): + # 永远返回满页,验证 count 能截断结果 + return [_member(1, "600000")] * cmd.page_size + + td = TdxData(cache_dir=None) + td._execute_mac = fake_exec + members = await td.get_index_members("000016", count=5) + assert len(members) == 5 + + +# ---------- get_index_trade_stats:按分钟聚合 ---------- + +def _tick(sym: str, hhmm: str, price: float, vol: float, tc: int) -> TransactionRecord: + market, code = (1, sym[2:]) if sym.startswith("sh") else (0, sym[2:]) + return TransactionRecord(market=market, code=code, time=f"{hhmm}:00", + price=price, vol=vol, trade_count=tc, bs_flag=1, + symbol=sym) + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_aggregates_minutes(): + async def fake_ticks(symbols, date=None, concurrency=6, **kw): + out = [] + for s in symbols: + if s == "sh600000": + out += [_tick(s, "09:30", 10.0, 100.0, 10), + _tick(s, "09:30", 10.0, 50.0, 5), + _tick(s, "09:31", 11.0, 200.0, 20)] + else: + out += [_tick(s, "09:30", 5.0, 1000.0, 7)] + return out + + td = TdxData(cache_dir=None) + td.get_ticks = fake_ticks + st = await td.get_index_trade_stats( + "000016", members=["sh600000", "sz000001"]) + + assert st.index == "sh000016" + assert st.member_count == 2 + assert st.active_members == 2 + assert st.trade_count_members == 2 + assert st.trade_count_available is True + assert st.failed_members == 0 + + m = {x.time: x for x in st.minutes} + assert sorted(m) == ["09:30", "09:31"] + assert m["09:30"].volume == 1150.0 # 100 + 50 + 1000 + assert m["09:30"].trade_count == 22 # 10 + 5 + 7 + assert m["09:31"].volume == 200.0 + # amount = Σ(price × 手 × 100) + assert m["09:30"].amount == pytest.approx( + 10.0 * 100 * 100 + 10.0 * 50 * 100 + 5.0 * 1000 * 100) + assert st.total_volume == 1350.0 + assert st.total_trade_count == 42 + assert st.total_amount == pytest.approx( + 10.0 * 100 * 100 + 10.0 * 50 * 100 + 5.0 * 1000 * 100 + 11.0 * 200 * 100) + assert st.cum_trade_count() == [("09:30", 22), ("09:31", 42)] + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_bj_has_no_trade_count(): + """北交所成分返回 trade_count=0 → trade_count_available False。""" + async def fake_ticks(symbols, date=None, concurrency=6, **kw): + return [_tick("sh600000", "09:30", 10.0, 100.0, 0)] + + td = TdxData(cache_dir=None) + td.get_ticks = fake_ticks + st = await td.get_index_trade_stats("899050", members=["sh600000"]) + assert st.trade_count_members == 0 + assert st.trade_count_available is False + assert st.total_volume == 100.0 + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_retries_per_symbol_on_batch_failure(): + """整批失败 → 退化为逐只重试,只有真正失败的计入 failed_members。""" + async def fake_ticks(symbols, date=None, concurrency=6, **kw): + single = isinstance(symbols, str) + if not single: + raise ConnectionError("批量炸了") + if symbols == "sh600004": + raise ConnectionError("这只也炸了") + return [_tick(symbols, "09:30", 10.0, 100.0, 3)] + + td = TdxData(cache_dir=None) + td.get_ticks = fake_ticks + st = await td.get_index_trade_stats( + "000016", members=["sh600000", "sh600004", "sh600006"]) + assert st.failed_members == 1 + assert st.active_members == 2 + assert st.total_trade_count == 6 + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_raises_when_not_skip_errors(): + async def fake_ticks(symbols, date=None, concurrency=6, **kw): + raise ConnectionError("boom") + + td = TdxData(cache_dir=None) + td.get_ticks = fake_ticks + with pytest.raises(ConnectionError): + await td.get_index_trade_stats( + "000016", members=["sh600000"], skip_errors=False) + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_progress_callback(): + seen: list[tuple[int, int]] = [] + + async def fake_ticks(symbols, date=None, concurrency=6, **kw): + return [_tick(s, "09:30", 10.0, 1.0, 1) for s in symbols] + + td = TdxData(cache_dir=None) + td.get_ticks = fake_ticks + st = await td.get_index_trade_stats( + "000016", members=[f"sh60000{i}" for i in range(5)], + batch_size=2, on_progress=lambda d, t: seen.append((d, t))) + assert seen == [(2, 5), (4, 5), (5, 5)] + assert st.member_count == 5 + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_fetches_members_when_absent(): + asked: list[str] = [] + + async def fake_members(code): + asked.append(code) + return [SimpleNamespace(symbol="sh600000")] + + async def fake_ticks(symbols, date=None, concurrency=6, **kw): + return [_tick(s, "09:30", 10.0, 1.0, 1) for s in symbols] + + td = TdxData(cache_dir=None) + td.get_index_members = fake_members + td.get_ticks = fake_ticks + await td.get_index_trade_stats("sh000300") + assert asked == ["000300"] + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_rejects_empty_members(): + td = TdxData(cache_dir=None) + + async def fake_members(code): + return [] + + td.get_index_members = fake_members + with pytest.raises(ValueError, match="没有取到成分股"): + await td.get_index_trade_stats("000300") + + +@pytest.mark.asyncio +async def test_get_index_trade_stats_multi_reuses_members(): + member_calls: list[str] = [] + tick_dates: list[int | None] = [] + + async def fake_members(code): + member_calls.append(code) + return [SimpleNamespace(symbol="sh600000")] + + async def fake_ticks(symbols, date=None, concurrency=6, **kw): + tick_dates.append(date) + return [_tick(s, "09:30", 10.0, 1.0, 2) for s in symbols] + + td = TdxData(cache_dir=None) + td.get_index_members = fake_members + td.get_ticks = fake_ticks + out = await td.get_index_trade_stats_multi( + "000300", [20261020, 20261021, None]) + assert len(out) == 3 + assert member_calls == ["000300"] # 成分只取一次 + assert tick_dates == [20261020, 20261021, None] + assert all(s.total_trade_count == 2 for s in out) diff --git a/tests/test_protocol.py b/tests/test_protocol.py index c737139..2a76412 100644 --- a/tests/test_protocol.py +++ b/tests/test_protocol.py @@ -337,7 +337,37 @@ def test_finish_bars_sorts_us_session_chronologically(): (0, "000001", 2), # 平安银行(不是指数!) (0, "300750", 2), (0, "159915", 3), # 深市 ETF - (0, "128035", 3), # 深市转债 + # 债券/回购:2026-10-22 修正(沪市曾少 100 倍、深市曾少 10 倍) + (1, "019742", 4), # 沪市国债 24特国01(110.228,曾读成 11022.8) + (1, "019547", 4), # 沪市国债 + (1, "010706", 4), # 沪市老国债 07国债06 + (1, "018014", 4), # 沪市 018 段 + (1, "020812", 4), # 沪市贴债 + (1, "110077", 4), # 沪市可转债 洪城转债(199.279,曾读成 19927.9) + (1, "113616", 4), # 沪市可转债 韦尔转债 + (1, "118031", 4), # 沪市可转债 + (1, "111000", 4), # 沪市 111 段 + (1, "132024", 4), # 沪市可交换债 + (1, "184832", 4), # 沪市 184 段 + (1, "204001", 4), # 沪市国债逆回购 GC001(1.385,曾读成 138.5) + (1, "204028", 4), + (0, "123107", 4), # 深市可转债 温氏转债(112.189,曾读成 1121.89) + (0, "128136", 4), # 深市可转债 立讯转债 + (0, "127025", 4), # 深市可转债 + (0, "131810", 4), # 深市国债逆回购 R-001(1.38,曾读成 13.8) + (0, "148004", 4), # 深市 148 段 + (0, "112001", 4), # 深市公司债 + (0, "101917", 4), # 深市国债 + (0, "520261", 4), # 深市 520 段 + # 沪市 B 股:3 位(2026-10-22 修正,曾按 2 位少 10 倍) + (1, "900901", 3), # 云赛B股 + (1, "900948", 3), + # 深市 B 股:2 位(与沪市不同!) + (0, "200011", 2), # 深物业B + (0, "200488", 2), + # 边界:999xxx 是「指数」,不能被 9 开头当成 B 股 + (1, "999999", 2), # 上证指数 + (1, "999998", 2), # A股指数 ]) def test_price_decimal_digits(market, code, expect): assert price_decimal_digits(market, code) == expect @@ -345,3 +375,82 @@ def test_price_decimal_digits(market, code, expect): def test_price_decimal_digits_strips_nul(): assert price_decimal_digits(1, "000016\x00\x00") == 2 + + +# ---------- 美股分时跨日:hour 必须是合法时钟值(回归:曾出现 hour=27) ---------- + +def _us_minutes(n: int = 390) -> list: + """构造 usAAPL 的 390 条分时:从北京 21:30 起连续 n 分钟。""" + from pytdxdata.models import MinuteBar + + start = 21 * 60 + 30 + return [ + MinuteBar(price=100.0 + i * 0.01, vol=1.0, + hour=(start + i) // 60, minute=(start + i) % 60, + market=74, code="AAPL", date=20261022) + for i in range(n) + ] + + +def test_minute_bar_us_hour_is_valid_clock_value(): + """EX 分时的 minutes 是「自开盘起的连续分钟数」,直接 //60 会得到 hour=27。""" + bars = _us_minutes() + assert all(0 <= b.hour < 24 for b in bars) + # 归一化前的原始值确实越界(21:30 + 390min = 28:00) + assert max(b.hour + b.day_offset * 24 for b in bars) > 23 + + +def test_minute_bar_us_day_offset_marks_next_day(): + bars = _us_minutes() + assert bars[0].day_offset == 0 # 21:30 当晚 + assert bars[-1].day_offset == 1 # 03:59 次日 + assert (bars[-1].hour, bars[-1].minute) == (3, 59) + + +def test_minute_bar_us_datetime_is_monotonic_across_midnight(): + bars = _us_minutes() + dts = [b.datetime for b in bars] + assert dts == sorted(dts) + assert dts[0] == datetime(2026, 10, 22, 21, 30) + assert dts[-1] == datetime(2026, 10, 23, 3, 59) + + +def test_minute_bar_us_trading_date_spans_two_calendar_days(): + """一个美股交易日的分时横跨两个北京自然日,trading_date 必须都是同一天。""" + bars = _us_minutes() + tds = {b.trading_date for b in bars} + assert tds == {"2026-10-22"} + # 而 datetime.date() 会给出两天 —— 这正是不能用它的原因 + assert len({b.datetime.date() for b in bars}) == 2 + + +def test_minute_bar_cn_unchanged(): + """A股/港股分时 hour 本就合法,归一化必须零行为变化。""" + from pytdxdata.models import MinuteBar + + for hour, minute in ((9, 30), (11, 29), (13, 0), (14, 59)): + b = MinuteBar(price=10.0, vol=1.0, hour=hour, minute=minute, + market=1, code="600000", date=20261022) + assert (b.hour, b.minute) == (hour, minute) + assert b.day_offset == 0 + assert b.datetime == datetime(2026, 10, 22, hour, minute) + assert b.trading_date == "2026-10-22" + + +def test_minute_bar_cn_datetime_monotonic_full_session(): + """A股全天 240 条(09:30~11:29 + 13:00~14:59)时间轴严格递增。""" + from pytdxdata.models import MinuteBar + + bars = [] + for idx in range(240): + if idx < 120: + hour, minute = 9 + (30 + idx) // 60, (30 + idx) % 60 + else: + hour, minute = 13 + (idx - 120) // 60, (idx - 120) % 60 + bars.append(MinuteBar(price=10.0, vol=1.0, hour=hour, minute=minute, + market=1, code="600000", date=20261022)) + dts = [b.datetime for b in bars] + assert dts == sorted(dts) + assert dts[0] == datetime(2026, 10, 22, 9, 30) + assert dts[-1] == datetime(2026, 10, 22, 14, 59) + assert {b.trading_date for b in bars} == {"2026-10-22"} diff --git a/uv.lock b/uv.lock index b273c11..f8e76f6 100644 --- a/uv.lock +++ b/uv.lock @@ -535,7 +535,7 @@ wheels = [ [[package]] name = "pytdxdata" -version = "0.6.4" +version = "0.6.5" source = { editable = "." } [package.optional-dependencies]