上一提交只补了 getting-started / routing / llms.txt / SKILL.md 四处,本轮把其余 教程类页面与接口清单补齐,并顺手修正 v0.6.0 统一接口改造后遗留的过时说明。 补齐(当日测速缓存): - README「已知限制」:说明当日首次启动会自动后台测速并缓存 - FAQ 新增「启动时会变慢吗?会不会在后台偷偷联网?」:无感保证 + 三个环境变量开关 - FAQ「连不上服务器怎么办」:加入"删当日测速缓存 / 环境变量指定主机"两条前置排查 - API_REFERENCE 四、辅助模块:config 补全当日测速相关函数与优先级链说明, 新增 pytdxdata.pool.probe_cache 一节(ProbeCache / schedule_probe / get_probe_cache) - internals/architecture.md 目录树:config.py、probe_cache.py 的职责注释更新 - internals/cache-pool.md「下一步」:补「服务器是怎么选出来的」交叉链接 修正(v0.6.0 遗留过时描述): - FAQ / api/enums.md:删掉「所有接口的第一个参数都是 market」——统一接口已改为字符串标的 - FAQ / cookbook:`*_batch` 已并入 `get_bars`(多标的),不再作为批量入口 - FAQ / getting-started「自建服务器清单」:`standard_servers` 实际是 Sequence[str] 而非 (host, port) 元组(端口由统一的 port= 指定);原示例照抄会取到错的主机名 (已实测:字符串写法正确,元组写法不会被解析) 校验:check_docs.py exit 0;mkdocs build --strict 无告警;新增交叉链接 #当日自动测速无感 / #daily-probe 均正确渲染且目标锚点存在;全量 164 项通过; src/pytdxdata/servers.json 跑测前后逐字节不变。
5.7 KiB
5.7 KiB
pytdxdata
通达信(TongDaXin)行情数据客户端:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页。
纯 asyncio 实现,零运行时依赖(只用 stdlib);A股(沪/深/北) + 港股 + 美股 + 期货 + 期权,一套接口全市场。
pip install pytdxdata
import asyncio
from pytdxdata import TdxData
from pytdxdata.models import KlinePeriod
async def main():
async with TdxData() as td: # 自动探测服务器 + 建池 + 建缓存
bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=2400)
print(bars[-1].datetime, bars[-1].close)
asyncio.run(main())
特性
| 特性 | 说明 |
|---|---|
| 🧩 动态连接池 | 启动时对服务器真实 K 线探测选优(剔除握手正常但返回空数据的坏节点);健康分(失败 ×0.5 / 成功 +0.2 / 冷却 120s)+ EWMA 延迟选路;按等待队列与空闲时长动态扩缩容;跨服务器故障转移 |
| 🗄️ 双层 TTL 缓存 | 内存 LRU + 磁盘 SQLite(WAL);TTL 分级:报价 5s / 分钟K线 60s / 日线当天 / 复权K线 1天 / 历史逐笔永久;single-flight 同键并发去重;缓存「已解析记录」,重复请求 0 网络 0 解析 |
| ⚡ 并发分页 | 把大请求拆成显式 start 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 |
| 🔀 双通道整合 | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 |
| 📄 服务器文件解析 | 板块 block_*.dat / 行业 tdxhy.cfg / 历史财报 gpcw*.zip 下载即解析成 dataclass(纯 stdlib),无需自己拆二进制 |
| 🚀 批量下载 | get_bars / get_minutes 传标的列表即多股票并发,连接池自动分配到不同服务器 |
| 📦 零重型依赖 | 返回 list[dataclass],pandas / polars 由调用方按需转换 |
从这里开始
-
装好并跑通
安装、构造参数、缓存目录、第一个脚本。
-
命令行直接拿数据
19 个子命令,不写代码也能拉行情、板块、财报。
-
场景示例
全市场批量落库、分钟线增量、报价轮询、板块轮动、逐笔复盘。
-
查接口签名
28 个统一方法(+ 33 个 deprecated 别名),从 docstring 实时生成,不会过期。
-
让 AI 助手写对代码
枚举取值反直觉,AI 凭常识几乎必错。装载
SKILL.md就能一次写对。
设计取舍
参照 easy-tdx 重新实现,解决其三大短板(无连接池、串行分页、单连接单锁)。 协议层独立实现——不依赖 easy-tdx 包,仅参照其字节级格式。
| 维度 | easy-tdx | pytdxdata |
|---|---|---|
| 并发分页 | ❌ 串行 while 循环 | ✅ 3 连接并行 |
| 连接池 | ❌ 单连接单锁 | ✅ 动态池 + 故障转移 |
| 缓存 | 仅证券列表(1天) | ✅ 双层 TTL + single-flight |
| 数据正确性 | 基准 | ✅ K线 6 字段 / 报价 7 字段逐字段一致(实测) |
| 2400 根日K耗时 | 0.31s | 0.16s(1.97x) |
| 缓存命中重取 | — | 0.016s(0 网络) |
| 依赖 | pandas 等 | 零运行时依赖 |
实测环境:Windows 11 / Python 3.13 / 同一批通达信服务器(2026-08)。
数据来源与限制
- 行情来自通达信公开行情服务器(无需账号),15 分钟延时;需实时数据请使用券商行情
- 服务器清单由
python -m pytdxdata.server_probe探测生成;运行时当日首次启动会自动在后台测速并缓存 (对调用方无感,当天不再重测),可用性随时间变化 - 港股 / 美股 / 期货 / 期权走通达信 EX 通道(端口 7727),部分市场(美股期权、港股期权)协议内无数据
完整清单见 常见问题。
!!! warning "免责声明" 本包仅用于技术研究与教育目的。行情数据来自通达信公开接口,不保证实时性与准确性; 作者不对任何投资决策负责。使用前请遵守通达信服务条款及相关法律法规。