From 7c4541a3158afc4197d8a129496432d3f2a7e2cc Mon Sep 17 00:00:00 2001 From: openbot-coder Date: Sat, 14 Nov 2026 14:16:10 +0800 Subject: [PATCH] =?UTF-8?q?fix(ex):=20=E6=9C=9F=E8=B4=A7/=E6=9C=9F?= =?UTF-8?q?=E6=9D=83K=E7=BA=BF=20amount=20=E6=81=92=200=20+=20=E8=A1=A5?= =?UTF-8?q?=E9=BD=90=E6=8C=81=E4=BB=93=E9=87=8F=20position=20=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=20(#17)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 0x23FF 帧内无成交额槽位(协议语义,非解析遗漏),期货/期权 amount 按 close×vol×合约乘数 估算(新增 ex_multiplier 乘数表,覆盖 cffex/shf/dl/zz/gz 主流品种 + 股票期权 10000;未知品种保持 0.0 不编造) - position(持仓量)协议层早已解析但 api 层丢弃,v3 起透传至 SecurityBar.position(权益类市场无此概念 → None) - 缓存 schema v2→v3:旧缓存 amount 恒 0/无 position,自然失效重建 - 真机验证:rb2611/IFL0/au2611/上交所期权 10011425 日线 amount/settle/position 全部有值 --- pyproject.toml | 2 +- src/pytdxdata/api.py | 43 +++++++++---- src/pytdxdata/ex_multiplier.py | 106 +++++++++++++++++++++++++++++++ src/pytdxdata/models/__init__.py | 3 + tests/test_ex_bars_fields.py | 47 +++++++++++++- tests/test_frames.py | 4 +- 6 files changed, 187 insertions(+), 18 deletions(-) create mode 100644 src/pytdxdata/ex_multiplier.py diff --git a/pyproject.toml b/pyproject.toml index bd89af9..e7fca76 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pytdxdata" -version = "0.7.2" +version = "0.7.3" description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权" readme = "README.md" requires-python = ">=3.11" diff --git a/src/pytdxdata/api.py b/src/pytdxdata/api.py index 8080b52..0fe8125 100644 --- a/src/pytdxdata/api.py +++ b/src/pytdxdata/api.py @@ -1077,28 +1077,43 @@ class TdxData: async def _bars_ex(self, sym: Symbol, period: KlinePeriod, adj: Adjust, start: int, count: int) -> list[SecurityBar]: """扩展市场K线(EX 0x23FF;category=周期编码,与 TDXParams 一致)。""" - from .protocol.commands.ex_proto import GetExInstrumentBarsCmd + from .protocol.commands.ex_proto import GetExInstrumentBarsCmd, _EX_AMOUNT_MARKETS cat = int(period) fetch_count = max(700, start + count) - # extra 带的 @v2 是缓存 schema 标记:v2 起 EX K线开始回填 amount/settle, - # 旧版本写下的缓存里 amount 恒 0.0,必须让它们自然失效。 + # extra 带的 @v3 是缓存 schema 标记:v3 起期货/期权回填估算 amount + position; + # 旧版本写下的缓存里 amount 恒 0.0、position 丢失,必须让它们自然失效。 key = CacheKey("kline", sym.market, sym.code, period.name, start, - fetch_count, f"{adj.name}@{cat}@v2") + fetch_count, f"{adj.name}@{cat}@v3") + # 期货/期权乘数(估算成交额用);未知品种乘数为 None → amount 保持 0.0 + from .ex_multiplier import find_multiplier + from .symbols import _EX_PREFIX + mult = None + if sym.market not in _EX_AMOUNT_MARKETS: + mult = find_multiplier(_EX_PREFIX.get(sym.market, ""), sym.code, sym.market) async def fetch() -> bytes: rows = await self._fetch_paginated_ex( lambda s2, c2: GetExInstrumentBarsCmd(sym.market, sym.code, cat, s2, c2), PageSpec(page_size=700, total=fetch_count, min_page=100)) - bars = [SecurityBar( - market=sym.market, code=sym.code, - year=d["year"], month=d["month"], day=d["day"], - hour=d.get("hour", 0), minute=d.get("minute", 0), - open=d["open"], high=d["high"], low=d["low"], close=d["close"], - vol=float(d.get("trade", 0) or 0), - # 权益类(港股/美股/新三板)真有成交额;期货期权的帧里没有,恒 0.0 - amount=float(d.get("amount", 0.0) or 0.0), - settle=d.get("settle"), - ) for d in rows] + bars = [] + for d in rows: + vol = float(d.get("trade", 0) or 0) + amount = float(d.get("amount", 0.0) or 0.0) + if amount == 0.0 and mult and vol: + # 期货/期权:帧内无成交额,按收盘价估算(见 ex_multiplier 模块 docstring) + amount = vol * float(d["close"]) * mult + pos = d.get("position", 0) or 0 + bars.append(SecurityBar( + market=sym.market, code=sym.code, + year=d["year"], month=d["month"], day=d["day"], + hour=d.get("hour", 0), minute=d.get("minute", 0), + open=d["open"], high=d["high"], low=d["low"], close=d["close"], + vol=vol, + amount=amount, + settle=d.get("settle"), + # 权益类市场 position 恒 0 → None;期货/期权给真实持仓量 + position=float(pos) if pos else None, + )) return pack_payload(bars) bars = self._finish_bars(unpack_payload(await self._cache.get_or_fetch(key, fetch)), sym) diff --git a/src/pytdxdata/ex_multiplier.py b/src/pytdxdata/ex_multiplier.py new file mode 100644 index 0000000..287b476 --- /dev/null +++ b/src/pytdxdata/ex_multiplier.py @@ -0,0 +1,106 @@ +"""EX 期货/期权合约乘数表(估算成交额用)。 + +0x23FF 帧内没有成交额槽位(见 ex_proto.py 注释)。要给期货/期权 K 线一个 +可用的 ``amount``,只能客户端自算。本表覆盖主流境内品种,键为**品种代码 +小写字母前缀**(从合约代码提取:``RB2611`` → ``rb``,``IFL0`` → ``if``)。 + +⚠️ 口径:``amount = vol × close × multiplier`` —— 按**收盘价**估算, +不是 Σ(逐笔成交价×手数×乘数) 的精确值,日线级别误差通常 <2%(收盘价 +成交集中假设)。对多数策略足够;要精确成交额请用逐笔聚合。 +""" +from __future__ import annotations + +# 中金所(乘数:点×元) +_CFFEX = { + "if": 200, "ih": 300, "ic": 200, "im": 200, + "ifl0": 200, "ihl0": 300, "icl0": 200, "iml0": 200, + "tf": 10_000, "t": 10_000, "ts": 10_000, "tl": 10_000, "tp": 10_000, + "mo": 50, "ho": 50, "io": 100, +} +# 上期所 +_SHF = { + "rb": 10, "hc": 10, "wr": 10, "cu": 5, "al": 5, "zn": 5, "pb": 5, + "ni": 1, "sn": 1, "ss": 5, "ao": 20, "au": 100, "ag": 15, + "fu": 10, "bu": 10, "ru": 10, "br": 5, "sp": 10, "lu": 10, "nr": 10, + "sc": 1000, "bc": 5, "ec": 50, "sh": 1_000_000, "dii": 100, +} +# 大商所 +_DL = { + "a": 10, "b": 10, "m": 10, "y": 10, "p": 10, "c": 10, "cs": 20, + "i": 100, "j": 100, "jm": 60, "jd": 5, "fb": 10, "bb": 500, + "l": 5, "v": 5, "pp": 5, "eg": 10, "eb": 5, "pg": 20, "rr": 10, + "lh": 16, "px": 10, "lg": 50, +} +# 郑商所 +_ZZ = { + "sr": 10, "cf": 5, "cy": 5, "ap": 10, "cj": 5, "pj": 10, + "ta": 5, "ma": 10, "fg": 20, "sa": 20, "ur": 20, "sf": 5, "sm": 5, + "oi": 10, "rm": 10, "zc": 100, "wh": 20, "pm": 50, "ri": 20, "jr": 20, + "lr": 20, "pf": 5, "sh": 30, "pk": 5, "cft": 5, +} +# 广期所 +_GZ = {"si": 5, "lc": 20, "ps": 5} + +_MARKET_TABLES = { + "cffex": _CFFEX, + "shf": _SHF, + "dl": _DL, + "zz": _ZZ, + "gz": _GZ, +} + +# 期权乘数:金融期权按标的;商品期权 = 标的期货乘数(同一品种字母前缀命中即可)。 +# 沪深股票期权(50ETF/300ETF/500ETF/科创50ETF/创业板ETF)乘数 10000。 +_STOCK_OPTION_MULTIPLIER = 10_000 + + +def product_code(code: str) -> str: + """合约代码 -> 品种小写前缀(``RB2611``→``rb``、``IFL0``→``ifl0``、``m2501``→``m``)。 + + 规则:取前缀直到首个数字;连续/主力后缀(L0、M0 等)保留在品种键里, + 表中给主力键与普通键都录入(见 _CFFEX 的 IFL0/IF 双键)。 + """ + s = code.strip().lower() + out = [] + for ch in s: + if ch.isdigit(): + break + out.append(ch) + return "".join(out) + + +def find_multiplier(ex_prefix: str, code: str, market: int | None = None) -> float | None: + """(EX 市场短前缀, 合约代码[, 市场号]) -> 合约乘数;未知返回 None。 + + 期权市场按**市场号**判断(IntEnum 名含 OPTION):股票期权乘数 10000, + 商品期权(ZZ/DL/CFFEX 期权市场号 4/5/7)回落到对应商品品种表。 + """ + if market is not None: + name = _OPTION_MARKET_NAMES.get(int(market)) + if name == "stock": + return _STOCK_OPTION_MULTIPLIER + if name == "commodity": + ex_prefix = {"ZZ_FUTURES_OPTION": "zz", "DL_FUTURES_OPTION": "dl", + "CFFEX_OPTION": "cffex", "GZ_OPTIONS": "gz"}.get(name, ex_prefix) + s = ex_prefix.lower() + if s.endswith("_option") or s in ("opt", "option"): + return _STOCK_OPTION_MULTIPLIER + table = _MARKET_TABLES.get(s) + if table is None: + return None + prod = product_code(code) + if prod in table: + return float(table[prod]) + # 主力/连续后缀剥离后再试(IFL0 → IF) + stripped = prod.rstrip("lmo0") + return table.get(stripped) + + +_OPTION_MARKET_NAMES = { + 4: "commodity", # ZZ_FUTURES_OPTION + 5: "commodity", # DL_FUTURES_OPTION + 7: "commodity", # CFFEX_OPTION + 67: "commodity", # GZ_OPTIONS + 8: "stock", # SH_STOCK_OPTION + 9: "stock", # SZ_STOCK_OPTION +} diff --git a/src/pytdxdata/models/__init__.py b/src/pytdxdata/models/__init__.py index cf13329..7f3decf 100644 --- a/src/pytdxdata/models/__init__.py +++ b/src/pytdxdata/models/__init__.py @@ -139,6 +139,9 @@ class SecurityBar: symbol: str = "" # 规范化标的串(sz000001 / hk00700),由 API 层填充 # 结算价。仅 EX 通道的**期货/期权**有(日线才有值,分钟线为 None);其余通道恒 None。 settle: float | None = None + # 持仓量(手)。仅 EX 通道的**期货/期权**有(0x23FF 帧槽位 5);其余通道恒 None。 + # 权益类市场(港股/美股等)无此概念,归一化为 None。 + position: float | None = None def __setstate__(self, state: Any) -> None: """反序列化兜底:早期版本写下的磁盘缓存里没有后加的可选字段(如 ``settle``)。 diff --git a/tests/test_ex_bars_fields.py b/tests/test_ex_bars_fields.py index 1ea0dcf..9b2ce31 100644 --- a/tests/test_ex_bars_fields.py +++ b/tests/test_ex_bars_fields.py @@ -132,6 +132,7 @@ async def test_bars_ex_backfills_amount_for_hk() -> None: assert bars[0].amount == pytest.approx(2_040_000.0) assert bars[0].vol == 2000 assert bars[0].settle is None + assert bars[0].position is None # 权益类无持仓量 @pytest.mark.asyncio @@ -140,7 +141,9 @@ async def test_bars_ex_backfills_settle_for_futures() -> None: bars = await td.get_bars("cffex_futures:IFL0", count=1) assert bars[0].settle == pytest.approx(4047.8) - assert bars[0].amount == 0.0 + # v3 起期货按收盘价估算成交额:close 10.2 × vol 25392 × IF 乘数 200 + assert bars[0].amount == pytest.approx(10.2 * 25392 * 200) + assert bars[0].position == 49_772.0 # ---------- 旧磁盘缓存兼容 ---------- @@ -173,3 +176,45 @@ def test_ex_symbols_route_to_ex_path() -> None: """守住前提:上面对 31/47 的断言确实走的是 EX 通道。""" assert parse_symbols(["hk00700"])[0].is_ex assert parse_symbols(["cffex_futures:IFL0"])[0].is_ex + + +# ---------- v3:期权持仓量 + 乘数表 ---------- + +def test_multiplier_known_products() -> None: + from pytdxdata.ex_multiplier import find_multiplier + assert find_multiplier("cffex", "IFL0") == 200 + assert find_multiplier("shf", "rb2611") == 10 + assert find_multiplier("shf", "au2611") == 100 + assert find_multiplier("dl", "i2501") == 100 + assert find_multiplier("zz", "AP0") == 10 + + +def test_multiplier_unknown_returns_none() -> None: + from pytdxdata.ex_multiplier import find_multiplier + assert find_multiplier("shf", "xyz999") is None + assert find_multiplier("nosuch", "rb2611") is None + + +def test_stock_option_multiplier() -> None: + from pytdxdata.ex_multiplier import find_multiplier + assert find_multiplier("sh_stock_option", "10011425") == 10_000 + + +@pytest.mark.asyncio +async def test_bars_ex_option_position_backfilled() -> None: + """期权 K 线持仓量透传(用户主诉):协议槽位 5 已解析,v3 起到 SecurityBar。""" + td = _fake_api({8: [_row(8, "10011425", position=123_456, trade=6373, settle=0.0887)]}) + bars = await td.get_bars("sh_stock_option:10011425", count=1) + + assert bars[0].position == 123_456.0 + # 股票期权乘数 10000:close 10.2 × vol 6373 × 10000 + assert bars[0].amount == pytest.approx(10.2 * 6373 * 10_000) + + +@pytest.mark.asyncio +async def test_bars_ex_unknown_multiplier_keeps_amount_zero() -> None: + """乘数表没有的品种:宁可不给 amount 也不编造。""" + td = _fake_api({30: [_row(30, "ZZZ2601", position=10, trade=5, settle=1.0)]}) + bars = await td.get_bars("shf:ZZZ2601", count=1) + assert bars[0].amount == 0.0 + assert bars[0].position == 10.0 diff --git a/tests/test_frames.py b/tests/test_frames.py index 3c43551..d7a097b 100644 --- a/tests/test_frames.py +++ b/tests/test_frames.py @@ -99,7 +99,7 @@ def test_bar_replaces_split_time_with_datetime(backend): df = to_frame([bar(), bar(minute=30)], backend=backend) assert cols(df, backend) == [ "market", "code", "open", "high", "low", "close", "vol", "amount", - "datetime", "trading_date", "symbol", "settle", + "datetime", "trading_date", "symbol", "settle", "position", ] assert rows(df, backend) == 2 assert cell(df, backend, "market") == 1 @@ -122,7 +122,7 @@ def test_empty_list_falls_back_to_annotation_hint(backend): assert rows(df, backend) == 0 assert cols(df, backend) == [ "market", "code", "open", "high", "low", "close", "vol", "amount", - "datetime", "trading_date", "symbol", "settle", + "datetime", "trading_date", "symbol", "settle", "position", ]