pytdxdata

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

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

参照 easy-tdx 重新实现，解决其三大短板（无连接池、串行分页、单连接单锁），协议层独立实现（不依赖 easy-tdx 包，仅参照其字节级格式）。

特性

安装

pip install pytdxdata          # 或 uv add pytdxdata

从源码开发：

git clone <repo-url>
cd pytdxdata
uv sync                          # 创建虚拟环境 + 安装CLI
uv run python -c "import pytdxdata"

可选加速（uvloop）：

uv add --optional uvloop uvloop

注：数据来自通达信公开行情服务器（无需账号），服务器清单由 server_probe.py 导入时自动探测可用性与延时，存于 servers.json。

CLI 命令行工具

pip install -e .   # 或 uv sync，注册 tdx 命令

tdx quotes sz000001                    # 行情报价(五档) / hk00700 / usAAPL
tdx kline sz000001 --period day --count 30 --adjust qfq
tdx kline cffex:IFL0 --count 30        # 期货K线(hk/us/zz/dl/shf/cffex/gz)
tdx transactions sz000001 --count 50   # 逐笔(含成交笔数)
tdx minute sz000001                    # 分时
tdx index 000001 --count 30            # 指数K线
tdx board list / members 881001 / ranking / change --days 5
tdx info sz000001                      # 个股快照
tdx list --market sz --count 100       # 证券列表
tdx auction sz000001 / unusual / xdxr / finance / flow
tdx block block_gn.dat --limit 10      # 板块文件下载+解析(成分股)
tdx industry 600000 --search 银行       # 行业分类下载+解析(tdxhy.cfg)
tdx financial-list                      # 历史专业财报文件索引(gpcw.txt)
tdx financial gpcw20260331.zip          # 历史专业财报记录下载+解析
tdx server-info / market-stat

快速开始

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

async def main():
    async with TdxData() as td:   # 自动建标准池(52台)+MAC池(3台)+缓存
        # 日K线（count>800 自动3连接并发分页）
        bars = await td.get_kline(1, "600000", KlinePeriod.DAY, count=2400)
        # 分钟K线（复权走MAC通道）
        m1 = await td.get_kline(0, "300308", KlinePeriod.MIN_1, count=240)
        # 五档报价（TTL 5s 缓存，重复请求0网络）
        q = await td.get_quotes([(1, "600000"), (0, "000001")])
        # 逐笔成交（MAC通道，含 trade_count=成交笔数，支持历史回溯）
        t = await td.get_transactions(0, "000001", date=20260811)
        total_trades = sum(r.trade_count for r in t)   # 当天总成交笔数
        # 证券列表/数量
        n = await td.get_security_count(0)
        lst = await td.get_security_list(1, start=0, count=1000)
        # 分时/除权除息/财务
        minute = await td.get_minute(1, "600000")
        xdxr = await td.get_xdxr(1, "600000")
        fin = await td.get_finance(1, "600000")

asyncio.run(main())

API 参考

统一入口 TdxData（async with TdxData() as td: 自动 start/close）。

完整接口清单（每个方法的参数 / 返回值 / 通道）见 docs/API_REFERENCE.md。

连接管理

行情接口

板块/竞价/异动（MAC）

快照/服务器/扩展（MAC）

文件/信息（标准+MAC）

数据模型（dataclass）

枚举

• Market：SZ=0 / SH=1 / BJ=2（北交所）
• KlinePeriod：MIN_5=0 / MIN_15=1 / MIN_30=2 / MIN_60=3 / DAY=4 / WEEK=5 / MONTH=6 / MIN_1=7 / MIN_3=8 / YEAR=9 / SEASON=10（与通达信协议字节一致）
• Adjust：NONE / QFQ（前复权）/ HFQ（后复权）

通道路由

架构

src/pytdxdata/
├── api.py              # 统一接口 TdxData（对外唯一入口）
├── router.py           # 标准/MAC 通道选路
├── config.py           # 服务器清单加载（servers.json + 环境变量覆盖）
├── protocol/           # 独立协议层（帧/变长整数/差分还原/自定义浮点/命令）
│   └── commands/       # kline/quotes/list/transaction/minute/xdxr/finance/mac
├── pool/               # 动态连接池（connection/health/pool）
├── cache/              # 双层TTL缓存（key/ttl/memory/disk/manager）
├── scheduler/          # 并发分页调度器（Paginator，3连接并行）
├── models/             # dataclass 模型 + 枚举
└── codec/              # 缓存载荷序列化（pickle+zlib）+ 服务器文件解析（板块/行业/财报）

扩展市场（EX通道：港股/美股/期货/期权）

get_kline 的 market 参数接受 ExMarket 枚举（港股/美股/期货/期权等52个市场）：

from pytdxdata.models import ExMarket, KlinePeriod

# 港股（HK_MAIN_BOARD=31，代码5位）
bars = await td.get_kline(ExMarket.HK_MAIN_BOARD, '00700', KlinePeriod.DAY, count=700)
# 美股（US_STOCK=74）
bars = await td.get_kline(ExMarket.US_STOCK, 'AAPL', KlinePeriod.DAY, count=700)
# 期货（CFFEX=47 / 郑28 / 大29 / 上30，合约如 IFL0/rb2610）
bars = await td.get_kline(ExMarket.CFFEX_FUTURES, 'IFL0', KlinePeriod.DAY, count=700)
# 股票期权（沪8/深9，合约代码8位）
bars = await td.get_kline(ExMarket.SH_STOCK_OPTION, '10010971', KlinePeriod.DAY, count=700)

• 端口 7727，统一走 pytdx EX 协议（0x23FF K线 / 0x23FA 报价 / 0x23F4 市场列表）
• 4台EX服务器：MAC EX 2台（116.205.135.205 / 121.37.232.167，0x2454 login）+ pytdx EX 2台（通达信扩展市场 116.205.143.214 / 国泰君安 103.221.142.82，0x2454 setup）
• EX 辅助接口：get_goods_list / get_goods_count / get_goods_quotes / get_goods_tick_chart / get_goods_transaction 等
• 实测：腾讯00700=466.6 / AAPL=332.8 / IFL0=4683.2 / 沪期权10010971=0.192
• 美股/港股期权：通达信协议无数据（美股期权可用 CBOE 公开接口，见 quantdata/scripts/import/cboe_options.py）

服务器文件：板块 / 行业 / 财报

通达信服务器上除了行情，还有一批静态文件（板块成分、行业分类、历史专业财报）。 pytdxdata 提供「下载 + 解析」一步到位：既保留原始 bytes 通道，也提供解析成 dataclass 的方法。

async with TdxData() as td:
    # ① 板块文件（block_zs.dat 行业 / block_gn.dat 概念 / block_fg.dat 风格）
    blocks = await td.get_block_parsed("block_gn.dat")
    for b in blocks:
        print(b.name, b.category, b.count, b.codes[:5])

    # ② 行业分类（tdxhy.cfg → 通达信行业 + 申万行业）
    hy = await td.get_industry_map()              # {6位代码: IndustryInfo}
    print(hy["600000"].tdx_industry, hy["600000"].sw_industry)

    # ③ 历史专业财报（gpcw.txt 索引 + gpcw*.zip 解压解析）
    infos = await td.get_financial_file_infos()   # 文件名 / MD5 / 大小
    records = await td.get_financial_records_parsed(infos[-1].filename)
    print(records[0].code, records[0].report_date, records[0].fields[:4])

不解析的原始字节通道仍保留（向后兼容）：get_block_info() / get_report_file() / get_financial_file_list() / get_financial_records()。

解析器集中在 codec/（block.py / industry.py / financial.py），纯标准库（struct / zipfile）， 可脱网单测；也可直接 from pytdxdata.codec import parse_block_dat 单独复用。

与 easy-tdx 对比

实测环境：Windows 11 / Python 3.13 / 同一批通达信服务器（2026-08 实测）。

已知限制

• 标准通道K线 count<100 部分服务器返回空 → 分页器已强制 min_page=100 规避
• 标准当日逐笔的笔数字段协议中有但 easy-tdx 模型丢弃（pytdxdata 已显式解析）；历史逐笔无笔数字段
• 报价价格小数位按品种推断（股票2位/指数ETF转债3位），同代码不同市场含义不同（SH 000001=指数 vs SZ 000001=股票）
• 行情数据来自通达信公开服务器，15分钟延时；需实时数据请使用券商行情
• 港股/美股/期货/期权数据走通达信 EX 通道（7727），部分市场（美股/港股期权）协议内无数据
• 服务器可用性随时间变化，可用 python -m pytdxdata.server_probe 重新探测

免责声明

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

测试

uv run pytest tests/        # 85个测试：协议/池/缓存/分页/API/文件解析/CLI

目录

• docs/API_REFERENCE.md — 完整对外接口清单（Python API / 数据模型 / 枚举 / CLI）
• examples/quickstart.py — 快速上手（报价 / K线 / 分时 / 板块）
• examples/server_files.py — 服务器文件下载 + 解析（板块 / 行业 / 财报）

Changelog

v0.4.0 (2026-09-15)

• 新增「服务器文件下载 + 解析」能力（对齐并超越 easy-tdx 的文件解析）：
  • get_block_parsed(filename) — 板块 block_zs/gn/fg.dat → TdxBlock 列表（板块名 / 类别 / 成分股代码）
  • get_industry_map() — tdxhy.cfg → {代码: IndustryInfo}（通达信行业 + 申万行业）
  • get_financial_file_infos() — tdxfin/gpcw.txt → FinancialFileInfo 列表（文件名 / MD5 / 大小）
  • get_financial_records_parsed(filename) — gpcw*.zip 解压 + 解析 → FinancialRecord 列表（每股原始字段）
• 新增解析器 codec/block.py、codec/industry.py、codec/financial.py（纯标准库，脱网可单测）
• 新增模型 TdxBlock / IndustryInfo / FinancialFileInfo / FinancialRecord
• 修复财报索引市场字段解析（<6s1c1L → <6sBL，市场 0=深 / 1=沪 正确，此前恒判深市）
• 公开异步方法 47 → 51，新增接口全部向后兼容（原 bytes 方法保留）
• CLI 新增 4 个命令：tdx block / tdx industry / tdx financial-list / tdx financial
• 新增 tests/test_cli_files.py（11 项 CLI 离线测试，FakeTD 桩）
• README 与 docs/API_REFERENCE.md 同步更新

v0.3.2 (2026-08-17)

• 新增 get_kline_batch(stocks, period, ...) — 批量K线接口，多股票自动并发下载，连接池分配不同服务器
• 新增 get_minute_batch(stocks, ...) — 批量分时接口，多股票自动并发下载

v0.3.1 (2026-08-17)

• get_kline(MIN_1) 切换为 MAC 通道 (0x122E)，解决标准通道 1 分钟K线深度不足问题
• 修复 MAC K线并发分页数据空洞 — 并发分页器将不同页面分配到不同服务器，当服务器数据深度不一致时 stop_when_short 会导致非确定性数据丢失；改用单连接串行分页（_fetch_mac_kline_serial，start 动态偏移，与 easy-tdx 一致）
• 路由更新：router.py 中 KlinePeriod.MIN_1 强制路由到 MAC 通道
• 标准通道其他周期（MIN_5/15/30/60/DAY/WEEK/MONTH）不受影响

v0.3.0 (2026-08-17)

• get_minute 切换为 MAC 通道 (0x122D MacTickChartCmd)，历史分时数据稳定返回完整 240 条（09:30~14:59）
• 新增 protocol/commands/mac_tick.py — MAC 单日分时图命令
• 移除不再使用的 GetHistoryMinuteTimeDataCmd 导入

v0.2.2 及之前

• 初始版本：动态连接池 + 双层TTL缓存 + 3连接并发分页 + 双通道（标准/MAC）+ 扩展市场（港股/美股/期货/期权）