fix(ex): 期货/期权K线 amount 恒 0 + 补齐持仓量 position 字段 (#17)

- 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 全部有值
This commit is contained in:
openbot-coder committed 2026-11-14 14:16:10 +08:00
1 parent 1cd8f692a1
commit 7c4541a315
6 files changed
+182 -13

No files matched your search

+1 -1
View File
@@ -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"
+24 -9
View File
@@ -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(
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=float(d.get("trade", 0) or 0),
# 权益类(港股/美股/新三板)真有成交额;期货期权的帧里没有,恒 0.0
amount=float(d.get("amount", 0.0) or 0.0),
vol=vol,
amount=amount,
settle=d.get("settle"),
) for d in rows]
# 权益类市场 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)
+106
View File
@@ -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
}
+3
View File
@@ -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``)。
+46 -1
View File
@@ -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
+2 -2
View File
@@ -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",
]