openbot-coder 9183c3294f v0.4.0: 初始开源发布
通达信(TDX)行情数据客户端 —— 动态连接池 + 双层TTL缓存 + 3连接并发分页,
纯 asyncio、零运行时依赖。一套接口覆盖 A股(沪/深/北) / 港股 / 美股 / 期货 / 期权。

主要能力:
- 四层架构:api → pool(标准/MAC/EX 三池) → protocol(16 命令模块) → cache(内存+SQLite)
- TdxData 提供 51 个公开异步方法;CLI(tdx) 提供 19 个子命令
- 服务器文件下载 + 解析:板块 block_*.dat / 行业 tdxhy.cfg / 历史财报 gpcw*.zip
- 85 个离线测试(协议 / 连接池 / 缓存 / 分页 / API / 文件解析 / CLI)

协议层参照 easy-tdx 的字节级格式独立实现,不依赖 easy-tdx 包。
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00
2026-09-15 11:38:44 +08:00

pytdxdata

PyPI version Python License PyPI downloads

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

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

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

特性

特性 说明
🧩 动态连接池 启动时对服务器真实K线探测选优(剔除握手正常但数据返回空的坏节点),按等待队列/空闲时长动态扩缩容,健康分(失败×0.5/成功+0.2/冷却120s)+EWMA延迟选路,跨服务器故障转移
🗄️ 双层TTL缓存 内存LRU + 磁盘SQLite(WAL),TTL分级:报价5s / 分钟K线60s / 日线当天 / 复权K线1天 / 历史逐笔永久;single-flight 并发同键去重(只回源一次);缓存"已解析记录"(重复请求0网络0解析)
⚡ 并发分页 单请求拆N页(每页显式start偏移→无状态可并行),多连接并行拉取、按序拼接、失败换连接重试;1分钟K线走 MAC 单连接串行分页(避免多服务器数据空洞)
🔀 双通道整合 标准通道(经典行情)+ MAC通道(逐笔/复权/1分钟K线),按命令自动选路
📦 零重型依赖 纯 asyncio + stdlib(socket/zlib/struct/sqlite3),返回 list[dataclass],pandas 由调用方按需转换
🚀 批量下载 get_kline_batch / get_minute_batch — 多股票自动并发,连接池分配不同服务器
📄 服务器文件解析 板块 block_*.dat / 行业 tdxhy.cfg / 历史财报 gpcw*.zip 下载即解析成 dataclass(纯 stdlib),无需自己拆二进制

安装

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。

连接管理

方法 说明
start() / close() 启动(服务器探测+预建连接+缓存)/ 关闭
__aenter__ / __aexit__ 异步上下文管理器

行情接口

方法 返回 说明
get_kline(market, code, period, *, start, count, adjust) list[SecurityBar] K线(count>800自动并发分页;adjust≠NONE走MAC复权;88/000/399指数走指数命令)
get_index_kline(market, code, period, *, start, count) list[SecurityBar] 指数K线(多涨跌家数字段已处理)
get_quotes(stocks) list[SecurityQuote] 五档报价(>80只自动切批,缓存键=规范化股票集)
get_transactions(market, code, *, date, start, count) list[TransactionRecord] 逐笔成交(MAC,含 trade_count 成交笔数),支持历史回溯
get_minute(market, code, *, date) list[MinuteBar] 分时(今日/历史,MAC通道)
get_kline_batch(stocks, period, *, start, count, adjust, concurrency) dict[str, list[SecurityBar]] 批量K线(多股票自动并发,连接池分配不同服务器)
get_minute_batch(stocks, *, date, concurrency) dict[str, list[MinuteBar]] 批量分时(多股票自动并发)
get_security_count(market) int 市场证券数量
get_security_list(market, *, start, count) list[SecurityInfo] 证券列表(count=None=全部,先查总数分页)
get_security_list_all(market) list[SecurityInfo] 全市场列表(缓存1天)
get_xdxr(market, code) list[XdxrRecord] 除权除息历史(标准)
get_finance(market, code) FinanceRecord | None 财务快照(标准)

板块/竞价/异动(MAC)

方法 返回 说明
get_board_list(board_type, count) list[BoardInfo] 板块列表(0=全部 1=行业 2=概念)
get_board_members(board_symbol, count, sort_type) list[MemberQuote] 板块成分股报价(自定义字段)
get_board_summary(board_symbol) dict 板块汇总(成分数/成交额/主力净流入/涨跌家数)
get_board_ranking(board_type, top_n) list[dict] 板块涨跌幅排行
get_board_change_ranking(board_type, days, top_n) list[dict] 板块N日涨跌幅排行(板块指数K线)
get_belong_board(market, code) list[BelongBoard] 个股所属板块
get_auction(market, code) list[AuctionItem] 集合竞价
get_unusual(market, start, count) list[UnusualItem] 市场异动
get_capital_flow(market, code) CapitalFlow 资金流向

快照/服务器/扩展(MAC)

方法 返回 说明
get_symbol_info(market, code) SymbolSnapshot 个股特征快照
get_stock_quotes(stocks, bits) list[MemberQuote] MAC自定义字段报价
get_stock_quotes_list(category, count) list[MemberQuote] 市场分类报价列表(0沪A/6全A/8科创/14创业)
get_stock_kline_with_indicators(market, code, indicators, ...) dict K线+指标(MACD/KDJ/RSI/BOLL/MA/EMA)
get_goods_list(market, start, count) list[GoodsItem] 扩展市场商品(期货/期权)
get_server_info() ServerInfo 服务器交易时段
get_kline_offset(offset, count) tuple[int,int] K线偏移
get_chart_sampling(market, code) list[float] 分时采样(扩展市场命令,A股不适用)

文件/信息(标准+MAC)

方法 返回 说明
get_company_info_category/content(...) list / str F10公司信息(标准)
get_block_info(filename) bytes 板块文件下载(标准)
get_report_file(filename) bytes 报告/财务文件下载(标准)
get_financial_file_list() list[str] 财务文件列表(tdxfin/gpcw.txt,原始行)
get_financial_records(filename) bytes 财务文件内容(gpcw*.zip,原始字节)
get_block_parsed(filename) list[TdxBlock] 板块文件下载+解析:板块名/类别/成分股代码
get_industry_map() dict[str, IndustryInfo] tdxhy.cfg 下载+解析:通达信行业+申万行业
get_financial_file_infos() list[FinancialFileInfo] gpcw.txt 下载+解析:文件名/MD5/大小
get_financial_records_parsed(filename) list[FinancialRecord] gpcw*.zip 解压+解析:每股原始字段
get_file_meta(filename) / download_file(filename) FileMeta / bytes 远程文件(MAC)
get_price_limits(market, code, name, pre_close, listed_days) tuple 涨跌停价(本地计算)
get_market_stat() MarketStat 全市场统计(涨跌家数/总额/市值/涨跌停数)

数据模型(dataclass)

模型 关键字段
SecurityBar market/code/open/high/low/close/vol/amount/year/month/day/hour/minute + datetime属性
SecurityQuote price/pre_close/OHLC/vol/amount/s_vol/b_vol/bid[5]/ask[5]/server_time/trading_status
TransactionRecord time/price/vol/trade_count/bs_flag
SecurityInfo code/name(GBK)/volunit/decimal_point/pre_close
XdxrRecord category/分红送转/缩股/行权等(除权除息)
MinuteBar price/vol
FinanceRecord 股本/资产/营收/利润(万元/万股,最新快照)
TdxBlock name/category/count/codes(板块成分,block_*.dat)
IndustryInfo code/tdx_industry/sw_industry(tdxhy.cfg)
FinancialFileInfo filename/hash/filesize(gpcw.txt)
FinancialRecord code/market/report_date/fields(历史专业财报)

枚举

  • 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(后复权)

通道路由

命令 默认通道 说明
K线(复权) MAC 支持QFQ/HFQ
K线(MIN_1不复权) MAC 0x122E,串行分页,避免多服务器数据空洞
K线(其他周期不复权)/指数 标准 价格小数位规则已验证
报价 标准 股票2位/指数ETF转债3位
逐笔成交 MAC 含trade_count,支持历史日期
分时 MAC 0x122D,完整历史分时
列表/数量/除权/财务 标准 仅标准通道提供

架构

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_parsed(filename) list[TdxBlock] 板块成分:板块名 / 类别 / 成分股代码
get_industry_map() dict[str, IndustryInfo] 通达信行业 + 申万行业(GBK 解析)
get_financial_file_infos() list[FinancialFileInfo] gpcw 文件索引(文件名 / MD5 / 大小)
get_financial_records_parsed(filename) list[FinancialRecord] 解压 zip + 解析每股原始字段

不解析的原始字节通道仍保留(向后兼容):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 对比

维度 easy-tdx pytdxdata
并发分页 ❌ 串行 while 循环 ✅ 3连接并行
连接池 ❌ 单连接单锁 ✅ 动态池+故障转移
缓存 仅证券列表(1天) ✅ 双层TTL+single-flight
数据正确性 基准 ✅ K线6字段/报价7字段逐字段一致(实测)
2400根日K耗时 0.31s 0.16s(1.97x)
缓存命中重取 — 0.016s(0网络)
接口覆盖 基准 36/36 全覆盖
依赖 pandas等 零运行时依赖

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