v0.6.7
## 性能:get_quotes 全市场 5,227 只 A股 3.5s → 0.33s 协议硬上限 80 只/请求 → 必须切 66 片;老实现是纯串行 for 循环, 每片一次往返(≈60ms),3.5s 全花在等网络上。 发现通达信响应是自描述长度帧且服务器按序应答,因此同一连接可连发 多条请求只付一次往返:实测单连接流水 66 请求 526ms(串行 7,372ms)。 - TdxConnection.execute_pipeline(cmds):一次下发全部 → 按序读回;中途失败强制断连 - _quotes_std 改工作窃取调度(快台多干,避免被最慢节点拖累) - DynamicPool.warm(n):并发预建连接(acquire 在全局锁内一次一条,22 并发首拉会多花 5~6s) - CacheManager.get_or_fetch_obj:回源直接返回对象,省掉冷路径 pickle→unpickle 白烧 - pool_max 默认 12 → 24 调优实测 p50/max:每台 1 连接×深度 6 = 455ms;每台 2 连接×深度 3 = 325ms。 端到端(全默认):首次 783ms、稳态 300~343ms、热缓存 67ms。 正确性:用昨收价交叉比对 30 只零错配,流水线与逐片结果集合完全一致。 ## 修复:指数 / ETF / LOF 的 trade_count 不再伪装成笔数 通达信对指数和多数场内基金不提供笔数,那 4 字节里塞的是「价格 × 1000」 (指数是「均价 × 1000」)。旧版直接当笔数用,tdx transactions sh510310 会打印出「3994 笔」这种假数据。 - 新增 TransactionRecord.trade_count_available - 新增 symbols.has_order_count(market, code) 按品种判定 (沪市 501x/502x/506x 实测有真实笔数,不能按「5 开头=基金」一刀切) - 历史通道 0x013001 无笔数字段,同样标记不可用 ## 文档:可转债量纲口径 核查可转债分时/逐笔后确认数据本身无缺陷(16 只当日 + 8 只历史日, 分时末价/现价、Σvol/日线vol、逐笔 VWAP 比值均 1.000000), 但 vol 单位是「手」(=10 张)导致 amount/vol 是均价的 10 倍,对外文档缺失。 - SecurityBar / TransactionRecord / MinuteBar 量纲注释补全 - has_order_count 实测表补沪可转债 110/111/113/118、沪 EB 132、深可转债 123/127/128 - API_REFERENCE 新增跨品种量纲对照表;llms.txt / SKILL.md 同步 ## 版本 0.6.7 ## 测试 306 → 346 全通过(新增 tests/test_pipeline.py 11 项 + 基金笔数相关回归) Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
pytdxdata
通达信(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
示例
examples/quickstart.py— 报价 / K线 / 分时 / 板块examples/server_files.py— 板块 / 行业 / 财报 下载 + 解析
开发
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
Description
通达信(TDX)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯 asyncio、零运行时依赖;支持 A股/港股/美股/期货/期权
1.2 MiB
0 Stars
3 Watchers
0 Forks
Languages
Python
100%