Files
pytdxdata/SKILL.md
T
openbot-coder 1bee6b0fc7 release: v0.5.0(文档站 + README 瘦身 + AI 助手技能)
新增
- 文档站(MkDocs + Material + mkdocstrings),push main 自动构建并部署 GitHub Pages
- SKILL.md:面向 AI 编程助手的技能文件(三条必守约定 / 枚举取值表 / 任务→方法决策表 / 9 条陷阱)
- docs/ai.md:文档站的「AI 助手接入」页
- tests/test_check_docs.py(10 项):漂移检查器自身的自测

变更
- README 361 → 125 行,只保留入口层;CLI 手册 / API 表 / 通道路由 / 架构树 /
  扩展市场 / easy-tdx 对比 / Changelog 全部移交文档站与 CHANGELOG.md
- README 相对链接改为绝对 URL(PyPI 渲染不重写相对链接,原本在 PyPI 页面全 404)
- check_docs.py 扩展为两档:MUST_LIST_ALL(须列全)+ MUST_NOT_BE_STALE(只需无过时引用),
  并把 SKILL.md / README / llms.txt / 教程类页面纳入;白名单放行 config 的模块级函数
- 版本号 0.4.0 → 0.5.0;包元数据 Documentation 指向文档站
- uv.lock 同步

修复
- ExMarket 成员数 52 → 46(实测 IntEnum 成员数),4 处文档同步更正
- docs/ai.md 的 3 处相对链接 + CHANGELOG 的 SKILL.md 链接(会导致 mkdocs --strict 失败)
- README 标注的测试数量 85 → 109(pytest 实际收集用例数)
2026-09-15 14:55:07 +08:00

8.7 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_kline(...)
# 退出即 close

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

2. market 传的是整数枚举值,不是字符串

这是最高频的错误来源。不要传 "sh" / "SH" / "1",要用枚举(它就是 IntEnum,所以传 1 也能跑,但可读性差):

from pytdxdata.models import Market, KlinePeriod, Adjust

await td.get_kline(Market.SH, "600000", 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 Market, KlinePeriod, Adjust

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

        # 前复权日线(复权自动走 MAC 通道)
        qfq = await td.get_kline(Market.SZ, "300308", KlinePeriod.DAY,
                                 count=500, adjust=Adjust.QFQ)

        # 五档报价:入参是 (market, code) 元组列表,一次可传多只(>80 只自动切批)
        quotes = await td.get_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
        print(quotes[0].price, quotes[0].bid[0], quotes[0].ask[0])

        # 逐笔成交(MAC 通道,支持历史日期,含 trade_count 成交笔数)
        ticks = await td.get_transactions(Market.SZ, "000001", date=20260811)
        print(sum(r.trade_count for r in ticks))     # 当日总成交笔数

        # 分时(MAC 通道,今日或历史)
        minute = await td.get_minute(Market.SH, "600000")

        # 批量 K 线:多股票自动并发,池子会分配到不同服务器
        batch = await td.get_kline_batch(
            [(Market.SH, "600000"), (Market.SZ, "000001")],
            KlinePeriod.DAY, count=240,
        )                                            # -> {"600000": [...], "000001": [...]}

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 通道)

常用几个:HK_MAIN_BOARD=31、US_STOCK=74、CFFEX_FUTURES=47、SH_STOCK_OPTION=8、SZ_STOCK_OPTION=9。 完整表见 https://openbot-coder.github.io/pytdxdata/api/enums/。

from pytdxdata.models import ExMarket

await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)   # 港股,5 位代码
await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)         # 美股,ticker
await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700)    # 期货合约

想做什么 → 用哪个方法

需求 方法
日/周/月/分钟 K 线 get_kline(market, code, period, *, count, adjust)
增量更新(从某天往后) get_kline_since(market, code, period, since, adjust)
一次拉多只股票 K 线 get_kline_batch(stocks, period, *, count, adjust, concurrency)
指数 K 线 get_index_kline(market, code, period, *, count)
K 线 + MACD/KDJ/RSI/BOLL get_stock_kline_with_indicators(market, code, indicators, ...)
实时五档报价 get_quotes(stocks)
逐笔成交 get_transactions(market, code, *, date)
分时图 get_minute(market, code, *, date)
全市场股票列表 get_security_list_all(market)(缓存 1 天)
除权除息 / 财务快照 get_xdxr(...) / get_finance(...)
板块列表 / 成分股 / 涨跌排行 get_board_list / get_board_members / get_board_ranking
个股所属板块 get_belong_board(market, code)
集合竞价 / 异动 / 资金流 get_auction / get_unusual / get_capital_flow
板块成分文件(离线快照) get_block_parsed("block_gn.dat")
行业分类(通达信 + 申万) get_industry_map()
历史专业财报(gpcw 全字段) get_financial_file_infos() + get_financial_records_parsed(fn)
涨跌停价 get_price_limits(market, code, name, pre_close, listed_days)(本地算,无网络)
全市场涨跌家数/成交额 get_market_stat()

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

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

  • 数据有 15 分钟延时(通达信公开服务器特性)。要实时数据请用券商行情。
  • 复权 K 线与 1 分钟 K 线走 MAC 通道。get_kline(..., adjust=Adjust.QFQ) 自动切换。
  • count 很大时会自动多连接并发分页,无需手动翻页。但标准通道 K 线 count < 100 部分服务器会返回空——内部已强制 min_page=100 规避。
  • get_quotes 一次 >80 只自动切批;而 MAC 的 get_stock_quotes 上限就是 80 只/次。
  • 历史逐笔没有笔数字段,只有当日逐笔的 trade_count 有效。
  • 板块文件(block_*.dat)/ 行业(tdxhy.cfg)/ 财报(gpcw*.zip)是服务器上的静态文件,解析后是普通 dataclass,落 JSON 后完全脱网可用——适合做离线快照。

陷阱清单

坑 后果 正确做法
market 传 "sh" 字符串 直接报错或路由到错误市场 用 Market.SH 枚举
以为 KlinePeriod.DAY == 0 拿到的是 5 分钟线 DAY=4,对照上面的表
忘了 async with / start() 无连接池,运行时报错 一律 async with TdxData() as td:
等在返回值上找 .to_dataframe() 不存在 pd.DataFrame([asdict(x) for x in bars])
把 close 当成分 数值差 100 倍 价格单位是元(float)
SH 000001 当成平安银行 拿到的是上证指数 代码不唯一:(Market.SH, "000001")=上证指数,(Market.SZ, "000001")=平安银行
用 get_block_info 又自己拆二进制 白写解析器 用 get_block_parsed,已经解析好了
循环里逐个 await get_kline 慢 用 get_kline_batch 让它并发
依赖实时性做信号 数据是 15 分钟前的 换券商实时源

深入参考

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