Files
pytdxdata/SKILL.md
T
openbot-coder 5408903a4c fix(models): 修复美股分钟K线 datetime 时区拼接错位,还原为北京时间
通达信 EX 通道对美股返回的分钟级 K线把两个时区拼进同一个五元组:日期分量是
美东交易日(zipday),时分分量是北京时间(tminutes)。直拼出的 datetime 会把
同一交易日的下午半场排到上午半场之前——单日 390 根首末颠倒,且全部落在同一个
北京自然日里,导致排序 / count 切片 / 日期区间二分与过滤 / 增量水位线全部不可用。

在 SecurityBar.__post_init__ 统一归一化为北京时间(凌晨段日期 +1 天,含月末与
年末进位),EX 的两条 K线命令路径(_bars_ex 的 0x23FF 与二分所依赖的 MAC 0x122E)
因此共用同一口径,不会出现"取数按一套时间、二分按另一套时间"的错位。

新增两个只读属性:trading_date(归属交易日;美股一个交易日横跨两个北京自然日,
按交易日聚合必须用它,不能用 datetime.date())与 is_us。

实测(安装 wheel 0.6.2,非源码树):10-06 ~ 10-12 五个完整交易日各 390 根、
严格单调,首根 open / 末根 close 与日线逐位相同,成交量差 <= 1;A股 / 港股零回归。

- 版本 0.6.1 -> 0.6.2(pyproject / __init__ / uv.lock)
- tests/test_protocol.py 新增 9 项回归测试(分界点 / 月末年末进位 / 390 根整日单调性 / MAC 路径),全量 191 passed
- CHANGELOG / README / SKILL.md / docs(faq、llms.txt、api/models)同步口径说明

遗留(本版未含,待决策):EX 分时对美股返回的 MinuteBar.hour 是未取模的连续分钟数
(实测可达 27,即次日 03:xx),且 MinuteBar 无日期分量可承载跨日信息。
2026-10-13 15:10:22 +08:00

9.8 KiB
Raw Blame History

name, description
name description
pytdxdata 用 pytdxdata 拉取通达信行情数据——A股(沪/深/北)、港股、美股、期货、期权的 K线 / 报价 / 逐笔 / 分时 / 板块 / 除权 / 财报文件。触发词:通达信数据、tdx 行情、A股日线下载、分钟K线、批量拉K线、板块成分股、行业分类、港股美股行情、pytdx、easy-tdx、pytdxdata。

pytdxdata 使用技能

pytdxdata 是通达信公开行情服务器的纯 asyncio 客户端:动态连接池 + 双层 TTL 缓存 + 多连接并发分页,零运行时依赖。 本技能让你一次写对——重点是那三条一眼看不出来的约定,以及一张必须背下来的枚举表。

需要精确签名时查 https://openbot-coder.github.io/pytdxdata/api/tdxdata/(由 docstring 实时生成,不可能过期)。

三条必守约定

1. 唯一入口是 TdxData,且必须 async with

from pytdxdata import TdxData

async with TdxData() as td:      # 自动 start(探测服务器 + 预建连接 + 建缓存)
    bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
# 退出即 close

不要直接 await TdxData().get_bars(...)——没 start() 就没有连接池。

2. 标的写法是字符串,不是元组

这是 v0.6 的最重要变化。不要传 (Market.SH, "600000") 元组,用字符串:

# 旧写法(deprecated,会发出 DeprecationWarning):
bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)

# 新写法(推荐):
bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
# 港股/美股/期货也一样:
bars = await td.get_bars(["hk00700", "usAAPL", "cffex:IFL0"], KlinePeriod.DAY, count=240)

3. 返回 list[dataclass],不是 DataFrame

库刻意不依赖 pandas。要 DataFrame 自己转一行:

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

安装

pip install pytdxdata        # 或 uv add pytdxdata

可运行模板

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

async def main():
    async with TdxData() as td:
        # 日K线,240 根(count 超过单页大小会自动多连接并发分页)
        bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
        print(bars[-1].close, bars[-1].datetime)

        # 前复权日线(复权自动走 MAC 通道)
        qfq = await td.get_bars(["sz300308"], KlinePeriod.DAY,
                                 count=500, adjust=Adjust.QFQ)

        # 跨市场报价:A股+港股+美股一次拿全
        quotes = await td.get_quotes(["sz000001", "hk00700", "usAAPL"])
        print(quotes[0].price, quotes[1].name, quotes[2].amount)

        # 逐笔成交(MAC 通道,支持历史日期,含 trade_count 成交笔数)
        ticks = await td.get_ticks(["sz000001"], date=20260811)
        print(sum(r.trade_count for r in ticks))

        # 分时(MAC 通道,今日或历史)
        minutes = await td.get_minutes(["sz000001"])

        # 批量 K 线:多股票自动并发,池子会分配到不同服务器
        batch = await td.get_bars(
            ["sz000001", "sh600000"],
            KlinePeriod.DAY, count=240,
        )  # 平铺返回,每条带 .symbol 字段

asyncio.run(main())

枚举取值表(别猜,对照着填)

Market — A 股市场

值 名称 含义
0 SZ 深市
1 SH 沪市
2 BJ 北交所

KlinePeriod — 周期编码,与通达信协议字节一致,不是顺序编号

值 名称 值 名称
0 MIN_5 7 MIN_1
1 MIN_15 8 MIN_3
2 MIN_30 9 YEAR
3 MIN_60 10 SEASON
4 DAY 11 YEAR_ALT
5 WEEK
6 MONTH

⚠️ DAY=4 不是 0,MIN_1=7 也不是 0。凭直觉填 0 会拿到 5 分钟线。

Adjust — 复权方式

值 名称 含义
0 NONE 不复权
1 QFQ 前复权
2 HFQ 后复权

ExMarket — 扩展市场(港股 / 美股 / 期货 / 期权,共 46 个成员,走独立 EX 通道)

v0.6 起统一接口用字符串前缀指定扩展市场,一般不再需要 ExMarket:

await td.get_bars("hk00700", KlinePeriod.DAY, count=700)      # 港股(5 位代码)
await td.get_bars("usAAPL", KlinePeriod.DAY, count=700)       # 美股(ticker)
await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700)   # 期货合约

常用前缀:hk / us / cffex / shf / dl / zz / gz;完整表见 https://openbot-coder.github.io/pytdxdata/api/enums/。

想做什么 → 用哪个方法

需求 方法
全市场标的清单(A股+港股+期货…) get_universe(market=None)
日/周/月/分钟 K 线(任意市场) get_bars(symbols, period, *, count, adjust, start_date, end_date)
K 线 + MACD/KDJ/RSI/BOLL get_indicators(symbols, indicators, ...)
实时五档报价(A股)/ 基础报价(港股/美股/期货) get_quotes(symbols, *, fields=None)
逐笔成交(任意市场) get_ticks(symbols, *, date)
分时图 / 缩略采样 get_minutes(symbols, *, date, sampling=True)
全市场股票列表(缓存 1 天) get_universe("sz") / get_universe("sh")
除权除息 / 财务快照 get_xdxr(symbols) / get_finance(symbols)
F10 公司资料 get_f10(symbol, section)
板块列表 / 成分股 / 涨跌排行 get_boards / get_board_members / get_board_ranking
个股所属板块 get_board_of(symbols)
集合竞价 / 异动 / 资金流 get_auction / get_unusual / get_capital_flow
个股特征快照 get_snapshot(symbols)
板块成分文件(离线快照) get_block_parsed("block_gn.dat")
行业分类(通达信 + 申万) get_industry_map()
历史专业财报(gpcw 全字段) get_financial_file_infos() + get_financial_records_parsed(fn)
涨跌停价 get_price_limits(symbol, name, pre_close, listed_days)(本地算,无网络)
全市场涨跌家数/成交额 get_market_stat()

通道与数据特性(影响你能拿到什么)

库内部有标准通道和 MAC 通道两条链路,会按命令自动选路,你不用管。但有几件事必须知道:

  • 数据有 15 分钟延时(通达信公开服务器特性)。要实时数据请用券商行情。
  • 复权 K 线与 1 分钟 K 线走 MAC 通道。get_bars(..., adjust=Adjust.QFQ) 自动切换。
  • K 线时间戳统一为北京时间(v0.6.2 起)。美股原始报文里日期是美东交易日、时分是北京时间(两个时区拼在一起),库已自动归一化,bar.datetime 可直接排序 / 比较 / 过滤。但美股一个交易日横跨两个北京自然日,按交易日聚合(分钟线合成日线、日内统计)必须用 bar.trading_date。
  • count 很大时会自动多连接并发分页,无需手动翻页。但标准通道 K 线 count < 100 部分服务器会返回空——内部已强制 min_page=100 规避。
  • get_quotes 一次 >80 只自动切批;走 MAC 字段位通道(fields=)时上限为 80 只/次。
  • 历史逐笔没有笔数字段,只有当日逐笔的 trade_count 有效。
  • 板块文件(block_*.dat)/ 行业(tdxhy.cfg)/ 财报(gpcw*.zip)是服务器上的静态文件,解析后是普通 dataclass,落 JSON 后完全脱网可用——适合做离线快照。

陷阱清单

坑 后果 正确做法
统一方法(get_quotes/get_bars…)传 (Market.SH, "600000") 元组或市场号 v0.6 起直接报错 用字符串 "sh600000"
旧别名(get_kline/get_transactions…)传 (market, code) 能跑,但发出 DeprecationWarning 迁移到统一方法 + 字符串
忘了 async with / start() 无连接池,运行时报错 一律 async with TdxData() as td:
KlinePeriod.DAY == 0 拿到的是 5 分钟线 DAY=4,对照枚举表
等在返回值上找 .to_dataframe() 不存在 pd.DataFrame([asdict(x) for x in bars])
把 close 当成分 数值差 100 倍 价格单位是元(float)
sh000001 当成平安银行 拿到的是上证指数 代码不唯一:sh000001=上证指数,sz000001=平安银行
用 get_block_info 又自己拆二进制 白写解析器 用 get_block_parsed,已经解析好了
循环里逐个 await get_bars 慢 用列表传多个标的,自动并发
港股/美股五档 bid/ask 没有(协议不支持) fields 字段位通道有 name 但无五档
美股分钟线用 datetime.date() 分组做日聚合 一个交易日被拆成两天(美股跨北京零点) 用 bar.trading_date;bar.datetime 是归一化后的北京时间
依赖实时性做信号 数据是 15 分钟前的 换券商实时源
手动改包内 servers.json / 写死 IP 容器只读、升级被覆盖、快节点捞不回来 日常靠内置的当日测速缓存自动选路;要强制指定就用 PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS 环境变量

深入参考

数据来自通达信公开接口,仅供技术研究与教育用途,不构成投资建议。