From feec86bf132fb28a5809908d1236a25a862f6efc Mon Sep 17 00:00:00 2001 From: OpenBot Date: Fri, 23 Oct 2026 08:40:44 +0800 Subject: [PATCH] chore: re-sync source to PyPI 0.6.7 (index trade stats, decimal sync, trade_count semantics fix); docs+CHANGELOG backfilled --- CHANGELOG.md | 16 +- docs/API_REFERENCE.md | 15 + pyproject.toml | 29 +- src/pytdxdata/__init__.py | 6 +- src/pytdxdata/api.py | 573 ++++++++++++++++-- src/pytdxdata/cache/manager.py | 32 + src/pytdxdata/cli.py | 125 +++- src/pytdxdata/config.py | 13 + src/pytdxdata/decimal_sync.py | 223 +++++++ src/pytdxdata/models/__init__.py | 188 +++++- src/pytdxdata/pool/connection.py | 54 ++ src/pytdxdata/pool/pool.py | 45 ++ src/pytdxdata/protocol/commands/quotes.py | 157 ++++- .../protocol/commands/transaction.py | 25 +- src/pytdxdata/scheduler/paginator.py | 10 +- src/pytdxdata/symbols.py | 50 ++ 16 files changed, 1463 insertions(+), 98 deletions(-) create mode 100644 src/pytdxdata/decimal_sync.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 2496d04..a7487ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,21 @@ 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 -## [0.6.3] - 2026-10-18 +## [0.6.7] - 2026-10-22 + +### 新增 +- `get_index_members` / `get_index_trade_stats` / `get_index_trade_stats_multi`:指数成分股与逐笔聚合统计(分钟级增量;北交所成分无笔数自动剔除) +- `sync_decimal_points` / `decimal_point_status`:权威价格小数位表运行时同步(报价标度不再依赖硬编码前缀规则),`start()` 自动装载 +- `decimal_sync` 模块 + +### 修复 +- **指数/ETF/LOF 逐笔的 `trade_count` 语义修正**:协议字段在指数上是「均价×1000」、ETF/LOF 上是「价格×1000」,**不是笔数**;新增 `TransactionRecord.trade_count_available`(判定见 `symbols.has_order_count`),CLI 对无笔数口径标的显示 `(-)` 而非假笔数 +- 集合竞价委托(bs_flag=8)不再混入逐笔结果(会被覆盖、Σvol 虚高 20%~160%、不同主机条数不一致) +- 缓存管理器 / 连接池 / 分页调度若干健壮性修复 + +### 说明 +- 0.6.4~0.6.6 为中间迭代,未单独发版记录;本次合并 PyPI sdist 与仓库,源码恢复双仓一致 + - fix(pool): ExPool acquire 背压等待(Condition 排队,默认 30s 超时)替代 3x0.05s 快速失败;超时异常带池状态 - feat(api): 新增 ex_pool_cap 参数(默认 2),单 EX 服务器场景不再静默退化为 1 并发(fixes #1) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index b51000d..b7b6db1 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -82,6 +82,21 @@ from pytdxdata import ( | `get_board_members(board, *, fields=None, count=100000)` | `list[SecurityQuote]` | 板块成分股报价(归一模型) | | `get_board_of(symbols)` | `list[BelongBoard]` | 个股所属板块 | +#### 指数成分与统计(v0.6.7) + +| 方法 | 返回 | 说明 | +|------|------|------| +| `get_index_members(index, *, count=100000, fields=None)` | `list[SecurityQuote]` | 指数成分股含实时报价(MAC 0x122C,指数码→板块码映射) | +| `get_index_trade_stats(index, *, date=None, members=None, batch_size=50, concurrency=24, skip_errors=True)` | `IndexTradeStats` | 指数逐笔聚合统计(分钟级增量 vol/trade_count/amount;北交所成分无笔数自动剔除) | +| `get_index_trade_stats_multi(index, dates, *, concurrency=24, batch_size=50, skip_errors=True, on_progress=None)` | `dict[int, IndexTradeStats]` | 多日批量版(按日期键) | + +#### 价格小数位(v0.6.7) + +| 方法 | 返回 | 说明 | +|------|------|------| +| `sync_decimal_points(markets=("sh","sz"))` | `dict[str, int]` | 从证券清单同步权威价格小数位表(`start()` 已自动处理,此为手动刷新口) | +| `decimal_point_status()` | `dict` | 小数位表当前状态(source/stock/syncing,排障用) | + ### 2.2 K线(旧接口,共 6 个) {#legacy-kline} | 方法 | 返回 | 说明 | diff --git a/pyproject.toml b/pyproject.toml index 7750de2..9be90d4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,14 +1,24 @@ [project] name = "pytdxdata" -version = "0.6.3" +version = "0.6.7" description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权" readme = "README.md" requires-python = ">=3.11" license = "MIT" license-files = ["LICENSE"] -keywords = ["tdx", "trading", "stock", "kline", "quote", "通达信", "A股", "港股", "美股", "期货", "asyncio", "quant"] -authors = [ - { name = "openbot-coder", email = "openbot-coder@users.noreply.github.com" } +keywords = [ + "tdx", + "trading", + "stock", + "kline", + "quote", + "通达信", + "A股", + "港股", + "美股", + "期货", + "asyncio", + "quant", ] classifiers = [ "Development Status :: 4 - Beta", @@ -24,6 +34,10 @@ classifiers = [ ] dependencies = [] +[[project.authors]] +name = "openbot-coder" +email = "openbot-coder@users.noreply.github.com" + [project.urls] Homepage = "https://github.com/openbot-coder/pytdxdata" Repository = "https://github.com/openbot-coder/pytdxdata" @@ -31,7 +45,11 @@ Documentation = "https://openbot-coder.github.io/pytdxdata/" [project.optional-dependencies] uvloop = ["uvloop>=0.21"] -dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.6"] +dev = [ + "pytest>=8.0", + "pytest-asyncio>=0.24", + "ruff>=0.6", +] [project.scripts] tdx = "pytdxdata.cli:main" @@ -59,4 +77,3 @@ docs = [ "ruff>=0.6", "jieba>=0.42", ] - diff --git a/src/pytdxdata/__init__.py b/src/pytdxdata/__init__.py index b2eb91f..382d374 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.2" +__version__ = "0.6.7" __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 3d9a084..6f32450 100644 --- a/src/pytdxdata/api.py +++ b/src/pytdxdata/api.py @@ -23,11 +23,15 @@ from __future__ import annotations import asyncio 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 from typing import Sequence +from . import decimal_sync from .cache.disk import DiskCache from .cache.key import CacheKey from .cache.manager import CacheManager @@ -45,11 +49,13 @@ from .models import ( FinancialFileInfo, FinancialRecord, IndicatorSet, + IndexTradeStats, IndustryInfo, KlinePeriod, Market, MemberQuote, MinuteBar, + MinuteTradeStat, SecurityBar, SecurityInfo, SecurityQuote, @@ -142,10 +148,13 @@ _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 # 港股逐笔单页 _ALL_PAGES_CAP = 50 # count=None(全量)时的翻页上限 +# 集合竞价**委托**记录标记(0x122F 第 5 字段)。不是成交,见 _ticks_one 注释。 +_BS_AUCTION_ORDER = 8 # 港股系市场:逐笔走 EX 专用 16B 协议(0x23FC/0x2406),其余扩展市场走 MAC 0x122F _HK_MARKETS = frozenset({27, 31, 48, 49, 71, 98}) @@ -230,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, @@ -279,6 +288,7 @@ class TdxData: self._paginator_std = Paginator(self._std_pool) self._paginator_mac = Paginator(self._mac_pool) self._started = False + self._decimal_task: asyncio.Task | None = None async def start(self) -> None: await self._std_pool.start() @@ -286,8 +296,13 @@ class TdxData: await self._ex_pool.start() await self._cache.start() self._started = True + # 权威价格小数位表:当日缓存命中则同步装表(无网络),否则挂后台同步。 + # 不阻塞 start(),失败静默退回静态前缀规则。 + self._decimal_task = decimal_sync.schedule(self) async def close(self) -> None: + await decimal_sync.cancel(self._decimal_task) + self._decimal_task = None await self._std_pool.close() await self._mac_pool.close() await self._ex_pool.close() @@ -325,6 +340,39 @@ class TdxData: out.extend(await self._universe_cn(mkt)) return out + async def sync_decimal_points(self, markets: Sequence[str] = ("sh", "sz") + ) -> dict[str, int]: + """从证券清单同步**权威价格小数位表**,返回统计。 + + 报价接口返回的是整数,真实价格 = ``整数 / 10**小数位``。小数位不随报价下发, + 但证券清单接口自带权威值 ``SecurityInfo.decimal_point`` —— 本方法把它灌进 + :func:`~pytdxdata.protocol.commands.quotes.price_decimal_digits` 使用的运行时表, + 从此价格标度不再依赖硬编码前缀规则(新增代码段也不会算错)。 + + ``start()`` 已自动处理:当日缓存命中就直接装表,否则挂后台同步,**不用手动调**。 + 这个方法用于「立刻要权威表」「排障时强制刷新」。 + + 参数: + markets: 拉哪些市场,默认 ``("sh", "sz")``。证券清单走 ``get_universe``, + 其本身已有缓存层,重复调用只花一次网络。 + + 返回: + ``{"prefixes", "codes", "mixed_prefixes", "stock"}`` —— 已覆盖的三位前缀数、 + 例外代码数、出现混合小数位的前缀数、总条目数。 + ``mixed_prefixes`` > 0 说明某段代码混用了不同小数位(已自动退化为逐代码查表)。 + + 用法:: + + async with TdxData() as td: + print(await td.sync_decimal_points()) # {'prefixes': 300+, 'codes': 0, ...} + q = await td.get_quotes("sh019742") # 110.228(4 位小数) + """ + return await decimal_sync.refresh(self, tuple(markets)) + + async def decimal_point_status(self) -> dict: + """权威小数位表当前状态(``source`` / ``stock`` / ``syncing`` 等,排障用)。""" + return decimal_sync.status() + async def _universe_cn(self, market: int) -> list[SecurityInfo]: key = CacheKey("list", market) @@ -396,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]: """报价,一次可跨市场、跨通道混合查询。 @@ -406,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``)。 @@ -416,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) @@ -795,12 +955,30 @@ class TdxData: 参数: date: ``None``=当日,``YYYYMMDD``=历史某日。 - start: 起始偏移。 + start: 起始偏移,**从最新一笔往回数**(``0``=当天最后一条)。 + ``start=1000`` 表示跳过最近 1000 条、从更早的位置开始。 count: ``None``=尽量取全量(自动翻页,上限 50 页);给了就取这么多条。 返回: - ``list[TransactionRecord]``,按入参标的顺序拼接(A股含 ``trade_count``, - 港股为 HH:MM 时间 + ``fields["zengcang"]`` 增仓)。 + ``list[TransactionRecord]``,按入参标的顺序拼接,**每条标的内部按时间升序**。 + 注意服务端是按约 3 秒聚合的切片,``vol``/``trade_count`` 是切片增量 + 而非当日累计。 + A股含 ``trade_count``,港股为 HH:MM 时间 + ``fields["zengcang"]`` 增仓。 + + **集合竞价委托(``bs_flag=8``)不会出现在结果里**:它们不是成交,``vol`` + 是累计撮合量(会被后续记录覆盖),计入会让 Σvol 比真值虚高 20%~160%, + 且不同主机收录的条数不同 → 同一查询两次调用结果不一致。 + + **指数(``sh000016`` 等)的两个字段语义与个股不同**: + + - ``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) sem = asyncio.Semaphore(max(1, concurrency)) @@ -821,18 +999,19 @@ class TdxData: if sym.is_ex: rows = await self._ticks_ex(sym, date=date, start=start, count=count) else: - def make_cmd(s: int, c: int): - return MacTransactionCmd(sym.market, sym.code, date or 0, s, c) - - spec = PageSpec( - page_size=_TICK_PAGE, - total=None if count is None else start + count, - min_page=100, - stop_when_short=True, - max_pages=_ALL_PAGES_CAP if count is None else None, - start_offset=start, - ) - rows = await self._fetch_paginated_list("mac", make_cmd, spec) + rows = await self._ticks_cn_serial(sym, date=date, start=start, + count=count) + # ★ 过滤集合竞价**委托**记录(bs_flag=8)。必须在逐页拉取**全部结束之后**做: + # 分页靠 `len(rows) < page_size` 判终止,若在 parse_response 里过滤, + # 满页会被剥短成"短页" → 提前终止 → 丢数据。 + # 实测(2026-10-21 sh600000):b8 是 09:15~09:25 / 14:57~15:00 竞价段的 + # 撮合快照,vol 是**累计值**(可被后续记录覆盖),不是成交增量; + # 计入后 Σvol 比真值虚高 20%~160%,且**不同主机的 b8 集合不同** + # (干净主机 0 条、脏主机 135 条)→ 同一查询两次调用结果不一致。 + # 剔除后:Σvol 与快照 vol 精确相等(比值 1.0000),且跨主机逐条一致。 + rows = [r for r in rows if r.bs_flag != _BS_AUCTION_ORDER] + # 排序放在 pack 之前,让缓存直接存入正确顺序,避免每次命中都重排。 + rows.sort(key=lambda r: r.time) return pack_payload(rows) records = unpack_payload(await self._cache.get_or_fetch(key, fetch)) @@ -840,6 +1019,54 @@ class TdxData: r.symbol = sym.text return records + async def _ticks_cn_serial(self, sym: Symbol, *, date: int | None, start: int, + count: int | None) -> list[TransactionRecord]: + """A股逐笔(0x122F)**单连接串行游标**翻页。 + + 为什么不用并发分页器:``0x122F`` 的 ``start`` 是「从**最新一笔**往回数的偏移」, + 是个**相对锚点**,不是稳定的绝对序号。而池里各主机对集合竞价委托(``bs_flag=8``) + 的收录**不一致**(实测干净主机 0 条、脏主机 135 条),同一 ``start`` 在不同主机上 + 落到**不同的真实成交**上。并发分页 = 各页来自不同主机 → 页边界既**重叠** + (sh600000 冗余 116 条)又**漏条**(13:03 附近丢 59 条),Σvol 偏移 −1.2%。 + + 逐笔单日仅 5~6 页(1000 条/页),串行开销可忽略、换来精确一致, + 故这里固定**单连接**、按 ``start`` 递增(= 向更早方向)推进。 + + 返回:按页序累加后再**整体翻转**,得到时间升序的完整列表。 + """ + chunks: list[list[TransactionRecord]] = [] + pos = start + remaining = count + pc = await self._mac_pool.acquire() + try: + for _ in range(_ALL_PAGES_CAP): + n = _TICK_PAGE if remaining is None else min(_TICK_PAGE, remaining) + if n <= 0: + break + rows = await pc.execute( + MacTransactionCmd(sym.market, sym.code, date or 0, pos, n)) + if not rows: + break + chunks.append(list(rows)) + pos += len(rows) + if remaining is not None: + remaining -= len(rows) + if remaining <= 0: + break + # 短页 = 已到最早一笔 + if len(rows) < n: + break + except Exception: + await self._mac_pool.release(pc, broken=True) + raise + await self._mac_pool.release(pc) + out: list[TransactionRecord] = [] + for chunk in reversed(chunks): + out.extend(chunk) + for r in out: + r.symbol = sym.text + return out + async def _ticks_ex(self, sym: Symbol, *, date: int | None, start: int, count: int | None) -> list[TransactionRecord]: from .protocol.commands.ex_ext import ( @@ -848,7 +1075,7 @@ class TdxData: ) hk = sym.market in _HK_MARKETS page = _EX_TICK_PAGE if hk else _TICK_PAGE - out: list[TransactionRecord] = [] + chunks: list[list[TransactionRecord]] = [] pos = start remaining = count for _ in range(_ALL_PAGES_CAP): @@ -860,22 +1087,27 @@ class TdxData: if date else GetExTransactionDataCmd(sym.market, sym.code, pos, n)) rows = await self._execute_ex(cmd) - out.extend(self._ex_tick(sym, r) for r in rows) + chunk = [self._ex_tick(sym, r) for r in rows] else: cmd = MacTransactionCmd(sym.market, sym.code, date or 0, pos, n) rows = await self._execute_ex(cmd) for r in rows: r.symbol = sym.text - out.extend(rows) - if not rows: + chunk = list(rows) + if not chunk: break - pos += len(rows) + # EX 通道的 pos 同样是"从最新往回数",逐页倒序累加 → 最后整体翻转。 + chunks.append(chunk) + pos += len(chunk) if remaining is not None: - remaining -= len(rows) + remaining -= len(chunk) if remaining <= 0: break - if len(rows) < n: + if len(chunk) < n: break + out: list[TransactionRecord] = [] + for chunk in reversed(chunks): + out.extend(chunk) return out @staticmethod @@ -892,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( @@ -1221,6 +1454,248 @@ 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`)。 + + 注意:返回的是**当前**成分,指数调仓后历史日期不适用。 + + ⚠️ **综合指数的成员名单不完整**(实测 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") + 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 + # 成分里若混入 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 getattr(t, "trade_count_available", True) and 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/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 367425a..d393dd7 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] # 板块涨跌幅排行 @@ -37,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, @@ -106,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 + + # ------------------------------------------------------------------ # # 各子命令 # ------------------------------------------------------------------ # @@ -119,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" % ("日期", "开盘", "最高", "最低", "收盘", "成交量")) @@ -144,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: @@ -204,6 +255,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 +478,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/config.py b/src/pytdxdata/config.py index 8b34ae8..74ca443 100644 --- a/src/pytdxdata/config.py +++ b/src/pytdxdata/config.py @@ -33,6 +33,7 @@ _SERVERS_FILE = Path(__file__).resolve().parent / "servers.json" # 包内清单 # 当日测速缓存(结构变更时递增,旧版本缓存自动失效) PROBE_CACHE_VERSION = 1 _PROBE_CACHE_NAME = "hosts-today.json" +_DECIMAL_CACHE_NAME = "decimal-points.json" # ---------- 包内清单(只读基线) ---------- @@ -97,6 +98,18 @@ def probe_cache_file() -> Path: return probe_cache_dir() / _PROBE_CACHE_NAME +def decimal_cache_file() -> Path: + """权威价格小数位表缓存路径(每次调用重新解析,便于测试改环境变量后生效)。""" + return probe_cache_dir() / _DECIMAL_CACHE_NAME + + +def decimal_sync_disabled() -> bool: + """是否已通过 ``PYPYTDX_DATA_DISABLE_DECIMAL_SYNC`` 关闭小数位后台同步。""" + return os.environ.get("PYPYTDX_DATA_DISABLE_DECIMAL_SYNC", "").strip().lower() in { + "1", "true", "yes", "on", + } + + def probe_disabled() -> bool: """是否已通过 ``PYPYTDX_DATA_DISABLE_PROBE`` 关闭当日测速缓存。""" return os.environ.get("PYPYTDX_DATA_DISABLE_PROBE", "").strip().lower() in { diff --git a/src/pytdxdata/decimal_sync.py b/src/pytdxdata/decimal_sync.py new file mode 100644 index 0000000..ad1b7e6 --- /dev/null +++ b/src/pytdxdata/decimal_sync.py @@ -0,0 +1,223 @@ +"""权威价格小数位表的同步与缓存(对用户无感)。 + +为什么需要它 +------------ +``get_quotes`` 解析报价时,协议给的是**整数**,真实价格 = ``整数 / 10**小数位``。 +小数位在协议里**不是**随报价一起下发的,只能靠推断(见 +:func:`pytdxdata.protocol.commands.quotes.price_decimal_digits`)。 + +但证券清单接口(``get_universe``,底层 ``GetSecurityListCmd``)**自带**这个字段: +``SecurityInfo.decimal_point``,同时还带 ``pre_close``。这就是权威来源。本模块把它 +灌进 ``price_decimal_digits`` 使用的运行时表,使价格标度不再依赖硬编码前缀规则。 + +行为 +---- +- **当日首次启动**检查缓存文件(``decimal-points.json``):命中就直接装表(纯内存, + 无网络、约 10 ms);未命中则挂一个**后台 task** 拉证券清单并写缓存, + 当天不再重复。 +- 后台 task 不阻塞 ``start()``,不打印、不抛异常(取消除外),失败只落 debug 日志。 +- 未同步成功时 ``price_decimal_digits`` 静默退回静态前缀规则,行为与 0.6.5 一致。 +- 证券清单本身已被 ``cache/`` 层缓存,因此同步的实际网络开销只在**首次** + (约 26 + 25 个分页请求)。 + +开关 +---- +- ``PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1`` 关闭后台同步(CI / 测试用,保证确定性)。 +- ``PYPYTDX_DATA_CACHE_DIR`` 覆盖缓存目录(测试指向临时目录)。 +""" +from __future__ import annotations + +import asyncio +import json +import logging +import os +from datetime import date +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from .config import decimal_cache_file, decimal_sync_disabled +from .protocol.commands.quotes import ( + clear_decimal_map, + decimal_map_source, + decimal_map_stats, + install_decimal_map, +) + +if TYPE_CHECKING: # pragma: no cover + from .api import TdxData + +log = logging.getLogger(__name__) + +#: 同步哪些市场(只对 A 股有意义:扩展市场报价本身不含标度歧义) +DEFAULT_MARKETS: tuple[str, ...] = ("sh", "sz") + +_CN_NAME = {"sh": 1, "sz": 0} + +_state: dict[str, Any] = {"loaded": "", "task": None} + + +# ---------------------------------------------------------------------- # +# 磁盘缓存 +# ---------------------------------------------------------------------- # + +def cache_file() -> Path: + """缓存文件路径(每次重新解析,便于测试改环境变量)。""" + return decimal_cache_file() + + +def _read_cache(path: Path | None = None) -> dict[str, dict[str, int]] | None: + """读缓存 → ``{"1": {code: dp}}``;缺失 / 损坏 → ``None``。""" + target = Path(path) if path is not None else cache_file() + try: + raw = json.loads(target.read_text(encoding="utf-8")) + except (OSError, ValueError): + return None + if not isinstance(raw, dict): + return None + if raw.get("date") != date.today().isoformat(): + return None + markets = raw.get("markets") + if not isinstance(markets, dict) or not markets: + return None + out: dict[str, dict[str, int]] = {} + for k, v in markets.items(): + if not isinstance(v, dict): + continue + try: + out[str(int(k))] = {str(c): int(d) for c, d in v.items() if int(d) > 0} + except (TypeError, ValueError): + continue + return out or None + + +def load_cached(path: Path | None = None) -> int: + """把当日缓存装进权威表;成功返回覆盖条目数,否则 0。""" + if decimal_sync_disabled(): + return 0 + markets = _read_cache(path) + if not markets: + return 0 + items = [(int(m), c, d) for m, codes in markets.items() for c, d in codes.items()] + stats = install_decimal_map(items, source="cache") + _state["loaded"] = date.today().isoformat() + log.debug("小数位表已从缓存加载: %s", stats) + return int(stats["stock"]) + + +def _write_cache(markets: dict[str, dict[str, int]], path: Path | None = None) -> None: + """原子写缓存(tmp + ``os.replace``),失败只落 debug 日志。""" + target = Path(path) if path is not None else cache_file() + payload = {"date": date.today().isoformat(), "markets": markets} + tmp = target.with_suffix(".tmp") + try: + target.parent.mkdir(parents=True, exist_ok=True) + tmp.write_text( + json.dumps(payload, ensure_ascii=False, separators=(",", ":")), + encoding="utf-8", + ) + os.replace(tmp, target) + except OSError as e: # pragma: no cover - 磁盘不可写等 + log.debug("小数位表缓存写入失败: %s", e) + try: + tmp.unlink(missing_ok=True) + except OSError: + pass + + +# ---------------------------------------------------------------------- # +# 同步 +# ---------------------------------------------------------------------- # + +async def refresh(td: "TdxData", markets: tuple[str, ...] = DEFAULT_MARKETS, + *, path: Path | None = None) -> dict[str, int]: + """拉证券清单 → 装表 + 写缓存。返回统计。 + + 证券清单走 ``get_universe``(含 ``cache/`` 层缓存),只有首次真正发请求。 + """ + tables: dict[str, dict[str, int]] = {} + items: list[tuple[int, str, int]] = [] + for name in markets: + m = _CN_NAME.get(name) + if m is None: + continue + rows = await td.get_universe(name) + table: dict[str, int] = {} + for it in rows: + dp = int(getattr(it, "decimal_point", 0) or 0) + code = str(getattr(it, "code", "") or "").strip().rstrip("\x00") + if dp <= 0 or not code: + continue + table[code] = dp + items.append((m, code, dp)) + if table: + tables[str(m)] = table + + stats = install_decimal_map(items, source="universe") + _state["loaded"] = date.today().isoformat() + if tables: + _write_cache(tables, path) + log.debug("小数位表同步完成: %s", stats) + return stats + + +async def _run(td: "TdxData") -> dict[str, int]: + try: + return await refresh(td) + except asyncio.CancelledError: + raise + except Exception as e: # pragma: no cover - 网络/解析异常都不该影响用户 + log.debug("小数位表后台同步失败: %s", e) + return {} + + +def schedule(td: "TdxData") -> asyncio.Task | None: + """[内部] 需要时把同步挂到后台并返回 Task(调用方持有 / 取消)。 + + - 已关闭(``PYPYTDX_DATA_DISABLE_DECIMAL_SYNC=1``)→ ``None`` + - 当日缓存命中 → 立即装表(同步、无网络),返回 ``None`` + - 否则创建后台 task;进程内单例,重复调用复用同一个 task + """ + if decimal_sync_disabled(): + return None + if decimal_map_stats()["stock"] and _state["loaded"] == date.today().isoformat(): + return None + if load_cached(): + return None + task = _state.get("task") + if task is not None and not task.done(): + return task + task = asyncio.get_running_loop().create_task(_run(td), name="pytdxdata-decimal-sync") + _state["task"] = task + return task + + +async def cancel(task: asyncio.Task | None) -> None: + """取消并等待后台同步 task(供 ``TdxData.close()`` 调用)。""" + if task is None or task.done(): + return + task.cancel() + try: + await task + except (asyncio.CancelledError, Exception): # noqa: BLE001 - 关闭路径不抛 + pass + + +def status() -> dict[str, Any]: + """当前状态快照(排障 / 测试用)。""" + task = _state.get("task") + return { + "loaded": _state["loaded"], + "source": decimal_map_source(), + "syncing": bool(task is not None and not task.done()), + **decimal_map_stats(), + } + + +def reset() -> None: + """清空内存状态(测试用;不动磁盘缓存)。""" + task = _state.get("task") + if task is not None and not task.done(): + task.cancel() + _state["task"] = None + _state["loaded"] = "" + clear_decimal_map() diff --git a/src/pytdxdata/models/__init__.py b/src/pytdxdata/models/__init__.py index 9f4459a..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 @@ -228,23 +228,72 @@ class SecurityInfo: @dataclass(slots=True) class TransactionRecord: - """逐笔成交(跨市场统一模型;A股 MAC 通道含 trade_count=成交笔数)""" + """逐笔成交(跨市场统一模型;A股 MAC 通道含 trade_count=成交笔数)。 + + 注意(实测 2026-10-21): + + - 服务端是按**约 3 秒聚合**返回的切片,不是交易所原始逐笔成交。 + - ``vol`` / ``trade_count`` 都是**该切片自身的增量**,不是当日累计值。 + - ``trade_count`` 为**有符号**值:集合竞价段(``bs_flag=8``)会是负数 + (实测 sh600000 09:15 段为 -874),不要对全表直接求 max/mean。 + - 返回列表已按时间升序,但同秒多条时顺序不保证。 + - ``bs_flag=8`` 的**竞价委托记录已被 ``get_ticks()`` 过滤掉**,不会出现在结果里。 + + **指数语义完全不同**(``is_cn_index`` 为真时,如 ``sh000016``): + + - ``vol`` 单位是**百元**(= 成交额 / 100),不是「手」。实测 + ``快照amount / Σtick.vol = 100.0002``,且 ``Σtick.vol`` 与分时 Σvol **逐位相等**。 + 想和成分股成交量对比必须先换算,直接比会得到 ~26 倍的假比例。 + - ``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 # 手(MAC逐笔) - trade_count: int # 成交笔数(MAC=逐笔记录字段;标准当日逐笔协议也有但需单独解析) - bs_flag: int # 1=主动买 0=主动卖 + 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) 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 + vol: float # 手(股票/转债同);Σ分时vol 与当日日线 vol 同口径 avg_price: float = 0.0 # 均价(协议第2字段) hour: int = 0 minute: int = 0 @@ -253,6 +302,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) @@ -494,3 +587,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/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/quotes.py b/src/pytdxdata/protocol/commands/quotes.py index 1e84d68..c9ff683 100644 --- a/src/pytdxdata/protocol/commands/quotes.py +++ b/src/pytdxdata/protocol/commands/quotes.py @@ -12,20 +12,155 @@ from .base import BaseCommand MAX_QUOTES = 80 -def price_decimal_digits(market: int, code: str) -> int: - """推断报价有效小数位:股票2位(/100)、指数/ETF/基金/转债/国债3位(/1000)。""" - code = (code or "").strip().rstrip("\x00") - if market == 1: # SH - if code.startswith(("5", "000", "8")): - return 3 - return 2 - if market == 0: # SZ - if code.startswith("1"): - return 3 - return 2 +# ====================================================================== # +# 权威小数位表(由证券清单 SecurityInfo.decimal_point 灌入) +# ====================================================================== # +# 查找顺序:**权威表 → 静态前缀规则**。权威表来自 ``get_universe`` 返回的 +# ``SecurityInfo.decimal_point``(协议自带,见 protocol/commands/security_list.py), +# 由 ``pytdxdata.decimal_sync`` 在后台每日同步一次;未同步时静默退回静态规则, +# 行为与 0.6.5 完全一致。 +_DECIMAL_PREFIX: dict[tuple[int, str], int] = {} +_DECIMAL_CODE: dict[tuple[int, str], int] = {} +_DECIMAL_MIXED: set[tuple[int, str]] = set() +_DECIMAL_SOURCE: str = "" + + +def install_decimal_map( + items: "list[tuple[int, str, int]] | tuple[tuple[int, str, int], ...]", + *, + source: str = "", +) -> dict[str, int]: + """用证券清单灌入权威小数位表。 + + ``items`` 为 ``(market, code, decimal_point)`` 序列(直接来自 + ``SecurityInfo``)。按**三位代码前缀**归并成一个极小的表(全量 5 万只标的 + 只产生数百个前缀);若某个前缀出现**不同**小数位,则该前缀退化为逐代码查表, + 只把这些例外代码存进 ``_DECIMAL_CODE``——这样即使将来交易所新增代码段, + 也不会因为前缀规则过时而算错价格。 + + 返回统计:``{"prefixes", "codes", "mixed_prefixes", "stock"}``。 + """ + global _DECIMAL_SOURCE + votes: dict[tuple[int, str], dict[int, int]] = {} + per_code: dict[tuple[int, str], int] = {} + for market, code, dp in items: + c = str(code or "").strip().rstrip("\x00") + if len(c) < 3: + continue + m = int(market) + if m not in (0, 1): + continue + d = int(dp) + if d <= 0: + continue + per_code[(m, c)] = d + key = (m, c[:3]) + bucket = votes.setdefault(key, {}) + bucket[d] = bucket.get(d, 0) + 1 + + _DECIMAL_PREFIX.clear() + _DECIMAL_CODE.clear() + _DECIMAL_MIXED.clear() + for key, bucket in votes.items(): + if len(bucket) == 1: + _DECIMAL_PREFIX[key] = next(iter(bucket)) + else: + _DECIMAL_MIXED.add(key) + for (m, c), d in per_code.items(): + if (m, c[:3]) in _DECIMAL_MIXED: + _DECIMAL_CODE[(m, c)] = d + _DECIMAL_SOURCE = source or "universe" + return decimal_map_stats() + + +def clear_decimal_map() -> None: + """清空权威表(回到纯静态前缀规则;测试与排障用)。""" + global _DECIMAL_SOURCE + _DECIMAL_PREFIX.clear() + _DECIMAL_CODE.clear() + _DECIMAL_MIXED.clear() + _DECIMAL_SOURCE = "" + + +def decimal_map_stats() -> dict[str, int]: + """权威表状态:已覆盖前缀数 / 例外代码数 / 混合前缀数 / 总条目数。""" + return { + "prefixes": len(_DECIMAL_PREFIX), + "codes": len(_DECIMAL_CODE), + "mixed_prefixes": len(_DECIMAL_MIXED), + "stock": len(_DECIMAL_PREFIX) + len(_DECIMAL_CODE), + } + + +def decimal_map_source() -> str: + """权威表来源标记(``universe`` / ``cache`` / ``""``=未加载)。""" + return _DECIMAL_SOURCE + + +def _decimal_digits_static(market: int, code: str) -> int: + """静态前缀规则(**兜底**,权威表缺失时使用)。""" + if market == 1: # 沪市 + if code.startswith("5"): + 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 +def price_decimal_digits(market: int, code: str) -> int: + """报价小数位:**协议原始整数除以 ``10**该值``** 才是真实价格。 + + 查找顺序: + + 1. **权威表**(:func:`install_decimal_map` 灌入)—— 来自证券清单里协议自带的 + ``SecurityInfo.decimal_point``,由 ``pytdxdata.decimal_sync`` 每日后台同步一次。 + 2. **静态前缀规则**(:func:`_decimal_digits_static`)—— 权威表未就绪时兜底。 + 四档:股票/指数/板块 ``2``、基金/ETF/B股 ``3``、债券/回购 ``4``。 + + 为什么还要静态规则:``get_quotes`` 解析是**纯同步、无网络**的路径,解析那一刻 + 可能还没同步过证券清单;而现网首次安装/离线环境也必须能算出价格。 + + 权威表与静态规则的一致性:2026-10-22 拉取全量 51,982 只(沪 27,520 + 深 24,462) + 逐条比对,静态规则与 ``decimal_point`` **一一吻合、零例外**——因为全量清单里 + 没有任何一个三位前缀出现混合小数位。因此两者并存不会产生口径冲突。 + + 历史修正(两次都是同一类错误:把某段前缀想当然地归错档): + + - **2026-10-21**:沪市 ``000``/``8`` 被判成 3 位 → 上证指数/上证50/科创50/ + 板块指数**价格少 10 倍**(3713 读成 371)。它们实际是 2 位。 + - **2026-10-22**:债券与回购全线偏差 —— 沪市 ``010/018/019/020/1xx/2xx`` + 与深市 ``10x/11x/12x/13x/14x/19x/50x/52x/56x`` 实际是 **4 位**,原先 + 沪市落到 2 位(**少 100 倍**)、深市落到 3 位(**少 10 倍**)。实测例: + ``sh019742`` 110.228 读成 11022.8、``sh204001`` 1.385 读成 138.5、 + ``sz131810`` 1.38 读成 13.8。同时沪市 B 股 ``900xxx`` 是 3 位(原先 2 位)。 + + 实证方法:拿 ``pre_close``(快照口径)除以上一交易日**日线收盘**(K线口径, + 走 ``/1000`` 独立路径),比值即标度误差 —— 1.0 正确、10 少 10 倍、100 少 100 倍。 + """ + code = (code or "").strip().rstrip("\x00") + m = int(market) + if m in (0, 1): + hit = _DECIMAL_PREFIX.get((m, code[:3])) + if hit is not None: + return hit + hit = _DECIMAL_CODE.get((m, code)) + if hit is not None: + return hit + return _decimal_digits_static(m, code) + + def format_server_time(raw: int) -> str: """服务器时间编码:小时 + 百万分之一小时。14999212 -> 14:59:57.163""" hours, fractional_hour = divmod(raw, 1_000_000) diff --git a/src/pytdxdata/protocol/commands/transaction.py b/src/pytdxdata/protocol/commands/transaction.py index 155be90..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,11 +115,15 @@ class MacTransactionCmd(BaseCommand[list[TransactionRecord]]): def parse_response(self, body: bytes) -> list[TransactionRecord]: (count,) = unpack_from(" list[tuple[int, int]]: """切页:返回 [(start, count), ...]。""" @@ -158,9 +159,12 @@ class Paginator: return None, False return None, False - def _assemble(self, results: list[PageResult], ordered: bool) -> list[Any]: + def _assemble(self, results: list[PageResult], ordered: bool, + newest_first: bool = False) -> list[Any]: + # newest_first=True:start=0 是最新一页,start 越大越旧 → 反向拼才对得上时间序。 + # 单页内部服务端已按时间升序,所以只翻页序,不翻页内元素。 if ordered: - results.sort(key=lambda r: r.start) + results.sort(key=lambda r: r.start, reverse=newest_first) out: list[Any] = [] for r in results: out.extend(r.items) diff --git a/src/pytdxdata/symbols.py b/src/pytdxdata/symbols.py index d02286f..8ee4a7f 100644 --- a/src/pytdxdata/symbols.py +++ b/src/pytdxdata/symbols.py @@ -238,3 +238,53 @@ def is_cn_index(market: int, code: str) -> bool: or (code.startswith("000") and int(market) == int(Market.SH)) or (code.startswith("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