openbotandopenbot-coder 8344ed6e6b fix: 修复沪市指数价格少10倍 + 逐笔竞价委托污染(Σvol 虚高/跨主机不稳定) (#3)
核对 sh000016 上证50 与 50 只成分股的 tick 汇总时,发现三个口径
(快照/分时/逐笔)互不一致,追查到 5 个缺陷。

1. 沪市指数价格整体少 10 倍
   price_decimal_digits 把沪市 000xxx(上证/上证50/沪深300/科创50)与
   8xxxxx(板块指数)判为 3 位小数,实际协议是 2 位。
   上证指数 3713 -> 371、上证50 2747 -> 274。
   实证 6 只指数 + 2 只板块指数全部 ×10,而 ETF/股票/科创板/深市全类 ×1 正确。
   改法:沪市仅 ETF(5开头) 保留 3 位,其余 2 位。

2. get_ticks 把 bs_flag=8 竞价委托当成成交
   该记录是 09:15~09:25 / 14:57~15:00 竞价段的撮合委托快照,
   vol 是累计值(可被后续覆盖),不是成交增量。
   - Σvol 虚高:sh600000 含 b8 = 668,693 vs 快照 462,562(1.4456);
     剔 b8 = 462,634(1.000156,精确一致)
   - 跨主机不稳定:干净主机 0 条、脏主机 135 条 -> 同一 start 落到不同真实成交
   改法:分页后统一剔除 b8。

3. A股逐笔改单连接串行游标(_ticks_cn_serial)
   并发分页各页来自不同主机,而 0x122F 的 start 是「从最新往回数」的相对锚点,
   主机间 b8 收录差异导致页边界既重叠(冗余 116 条)又漏条(13:03 附近丢 59 条)。
   逐笔单日仅 5~6 页,串行开销可忽略。

4. trade_count 有符号解析(前序)、返回列表时间序(前序)保留。

- sh000016 三口径闭合:快照 vol/amount 比值 1.00000061/0.99999997;
  指数逐笔 Σvol = 分时 Σvol = 1,045,584,467(完全相等)
- 6 只标的 Σvol/快照 vol 全部回到 1.0001~1.0007
- 跨主机公共时间窗逐条一致(5/5 标的,条数差 0)
- 测试 194 -> 217 passed(+20 小数位、+3 逐笔回归)

- TransactionRecord 类注释 + get_ticks docstring 明示指数语义:
  vol 单位「百元」(成交额/100)、trade_count 为「均价×1000」而非笔数
- API_REFERENCE / llms.txt 同步

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-22 09:06:40 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-10-18 16:12:51 +08:00

pytdxdata

CI PyPI version Python License PyPI downloads

通达信(TongDaXin)行情数据客户端:动态连接池 + 双层 TTL 缓存 + 多连接并发分页,纯 asyncio、零运行时依赖。

A股(沪/深/北) + 港股 + 美股 + 期货 + 期权,一套接口全市场。

📖 完整文档:https://openbot-coder.github.io/pytdxdata/

安装

pip install pytdxdata          # 或 uv add pytdxdata

可选异步加速:

pip install "pytdxdata[uvloop]"

30 秒上手

import asyncio
from pytdxdata import TdxData
from pytdxdata.models import KlinePeriod, Adjust

async def main():
    async with TdxData() as td:                     # 自动建连接池 + 缓存
        # 日K线(count 超过单页大小会自动多连接并发分页)
        bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
        # 前复权(自动走 MAC 通道)
        qfq = await td.get_bars(["sz300308"], KlinePeriod.DAY,
                                 count=500, adjust=Adjust.QFQ)
        # 跨市场报价:A股+港股+美股一次拿全
        quotes = await td.get_quotes(["sh600000", "hk00700", "usAAPL"])
        # 逐笔成交(MAC 通道,支持历史日期)
        ticks = await td.get_ticks(["sz000001"], date=20260811)
        print(bars[-1].close, quotes[0].price, len(ticks))

asyncio.run(main())

返回的是标准库 dataclass 组成的 list(库本身不依赖 pandas)。要 DataFrame 一行转:

from dataclasses import asdict
import pandas as pd
df = pd.DataFrame([asdict(b) for b in bars])

特性

特性 说明
🧩 动态连接池 启动时对服务器真实 K 线探测选优(剔除握手正常但数据为空的坏节点),健康分 + EWMA 延迟选路,跨服务器故障转移
🗄️ 双层 TTL 缓存 内存 LRU + 磁盘 SQLite(WAL),TTL 分级;single-flight 并发同键去重;缓存已解析记录(重复请求 0 网络 0 解析)
⚡ 并发分页 单请求拆 N 页(显式 start 偏移 → 无状态可并行)并行拉取、按序拼接、失败换连接重试
🔀 双通道整合 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1 分钟 K 线),按命令自动选路
📦 零重型依赖 纯 asyncio + stdlib(socket / zlib / struct / sqlite3)
📊 全市场覆盖 A股、港股、美股、期货、期权(46 个扩展市场)
📄 服务器文件解析 板块 block_*.dat / 行业 tdxhy.cfg / 财报 gpcw* 下载即解析成 dataclass(索引名与服务器实际文件名不一致时自动纠正)
🤖 AI 助手友好 内置 SKILL.md 与 llms.txt

文档导航

我想… 去哪
装好跑起来 快速开始
抄场景代码(转 DataFrame / 批量下载 / 离线板块快照) 场景示例
查方法签名与参数 TdxData 方法 — 由 docstring 自动生成
搞清枚举该填几 枚举速查
看协议二进制格式、三池路由、缓存策略 深入原理
用命令行 命令行工具
完整接口清单(28 个统一方法 + 33 个废弃别名) docs/API_REFERENCE.md
重构审查(数据一致性 / 遗漏对账) 接口重构审查
版本变更 CHANGELOG.md

本 README 只做入口层。深度内容一律在文档站,避免两处维护造成漂移。

给 AI 助手用

仓库根的 SKILL.md 是一份可直接加载的技能:三条必守约定、KlinePeriod 等枚举取值表、 「想做什么 → 用哪个方法」决策表、以及 11 条真实陷阱。AI 编程助手读完就能一次写对,不必翻源码。

# 丢进你所用 AI 助手的 skills 目录即可
curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \
  https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md

示例

开发

uv sync                        # 建虚拟环境 + 注册 tdx 命令
uv run pytest tests/           # 191 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移 / 当日测速缓存)
uv sync --group docs           # 文档站依赖(mkdocs-material + mkdocstrings)
uv run mkdocs serve            # 本地预览文档站

已知限制

  • 行情来自通达信公开服务器,15 分钟延时;需实时数据请使用券商行情
  • 标准通道 K 线 count < 100 部分服务器返回空 → 分页器已强制 min_page=100 规避
  • 港股 / 美股期权在通达信协议内无数据
  • K 线时间戳统一为北京时间(v0.6.2 起)。美股原始报文把「美东交易日日期」与「北京时间时分」 拼在一起,库已自动归一化,bar.datetime 可直接排序 / 过滤;但美股一个交易日横跨两个北京 自然日,按交易日聚合请用 SecurityBar.trading_date,不要用 datetime.date()
  • 服务器可用性随时间变化。当日首次启动会自动在后台测速并缓存(对调用方无感,当天不再重测); 也可用 python -m pytdxdata.server_probe 离线重生成随包清单。 缓存路径与三个开关见 安装与配置 → 当日自动测速

免责声明

本包仅用于技术研究与教育目的。行情数据来自通达信公开接口,不保证实时性与准确性; 作者不对任何投资决策负责。使用前请遵守通达信服务条款及相关法律法规。

License

MIT

S
Description
通达信(TDX)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯 asyncio、零运行时依赖;支持 A股/港股/美股/期货/期权
Readme MIT
1.2 MiB
0 Stars 3 Watchers 0 Forks
Languages
Python 100%