Files
pytdxdata/docs/cookbook.md
T
openbot-coder c4dd61665b docs: 建立 MkDocs 文档站与 AI 层文档
- 新增 MkDocs + Material 文档站(19 页):入门、CLI、场景示例、FAQ、
  Contributing、Changelog、API 参考(mkdocstrings 自动渲染)、内部原理
  (架构 / 协议 / 三池路由 / 缓存)
- 新增 docs/llms.txt:面向 LLM 的结构化摘要(枚举取值、方法速查、常见陷阱)
- 新增 scripts/check_docs.py:校验文档与 api.py 公开方法清单是否漂移
- 新增根 CHANGELOG.md 作为版本记录唯一来源,docs/changelog.md 用 snippet 引入
- 新增 .github/workflows/docs.yml:push main 自动构建并部署 GitHub Pages
- 修正文档口径:TdxData 公开方法 53 个(51 数据方法 + start/close);
  API_REFERENCE 版本号 v0.3.2 -> v0.4.0
- pyproject.toml 新增 docs 依赖组;.gitignore 忽略 site/
2026-09-15 13:57:31 +08:00

7.6 KiB
Raw Blame History

场景示例

每个片段都是完整可跑的。共同前提:

import asyncio
from pathlib import Path
from pytdxdata import TdxData
from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market

全市场日线批量落库

连接池会把不同股票分配到不同服务器,这是 *_batch 存在的意义。

async def dump_all_daily():
    async with TdxData(cache_dir=Path("./tdx_cache")) as td:
        codes = await td.get_security_list_all(Market.SZ)      # 缓存 1 天
        symbols = [(Market.SZ, s.code) for s in codes]

        bars = await td.get_kline_batch(
            symbols,
            KlinePeriod.DAY,
            count=800,
            adjust=Adjust.QFQ,
            concurrency=12,
        )
        print(f"{len(bars)} / {len(symbols)} 只拿到数据")

        for code, rows in bars.items():
            if not rows:
                continue
            # 落库 / 写 parquet 都行,这里只演示
            print(code, len(rows), rows[-1].datetime, rows[-1].close)

!!! tip "分页与并发的取舍" concurrency 不是越大越好。单台服务器有连接上限,concurrency 超过 pool_max × 服务器数 之后只会排队。实践值:8~16。

分钟线增量更新

只拉「上次之后」的部分,用 get_kline_since 省掉全量重拉。

async def update_minute(code: str, last_dt):
    async with TdxData(cache_dir=Path("./tdx_cache")) as td:
        rows = await td.get_kline_since(Market.SZ, code, KlinePeriod.MIN_1, since=last_dt)
        return [r for r in rows if r.datetime > last_dt]

!!! warning "1 分钟 K 线走 MAC 单连接串行分页" 这是刻意设计:并发分页会把不同页分到不同服务器,而各服务器历史深度不一致, 拼接后会出现非确定性数据空洞。所以 MIN_1 强制单连接串行(见 通道与数据源)。

报价轮询

async def poll_quotes(symbols, interval=5.0):
    async with TdxData() as td:
        while True:
            quotes = await td.get_quotes(symbols)      # >80 只自动切批;缓存 TTL 5s
            for q in quotes:
                print(q.code, q.price, q.bid[0], q.ask[0])
            await asyncio.sleep(interval)

缓存 TTL 与轮询间隔对齐时,重复轮询几乎 0 网络开销。但注意通达信公开源本身是 15 分钟延时数据,别拿它做实时交易决策。

板块轮动 / 领涨股

async def sector_rotation():
    async with TdxData() as td:
        # 近 5 日概念板块涨幅排行
        top = await td.get_board_change_ranking(board_type=2, days=5, top_n=10)
        for row in top:
            print(row)

        # 拿第一名板块的成分股
        symbol = top[0]["symbol"] if "symbol" in top[0] else "881001"
        members = await td.get_board_members(symbol, count=20)
        for m in members[:5]:
            print(m.code, m.name, m.fields)

        # 板块资金汇总
        print(await td.get_board_summary(symbol))

个股所属板块(反向查询)

async def belong(code: str):
    async with TdxData() as td:
        for b in await td.get_belong_board(Market.SH, code):
            print(b)

逐笔复盘

async def review_transactions(code: str, ymd: int):
    async with TdxData() as td:
        rows = await td.get_transactions(Market.SZ, code, date=ymd, count=2000)
        total = sum(r.trade_count or 0 for r in rows)
        buy = sum(r.vol for r in rows if r.bs_flag == 0)     # 主动买
        sell = sum(r.vol for r in rows if r.bs_flag == 1)    # 主动卖
        print(f"{ymd} 总成交笔数={total} 主动买={buy} 主动卖={sell}")

财务因子快照

async def finance_snapshot(codes):
    async with TdxData() as td:
        for mkt, code in codes:
            fin = await td.get_finance(mkt, code)      # 标准通道,最新快照
            if fin:
                print(code, fin)

历史专业财报(gpcw*.zip,含多报告期)走文件接口:

async def history_financials(code: str):
    async with TdxData(cache_dir=Path("./tdx_cache")) as td:
        infos = await td.get_financial_file_infos()             # 索引
        records = await td.get_financial_records_parsed(infos[-1].filename)
        row = next((r for r in records if r.code == code), None)
        if row:
            print(row.report_date, row.fields[:8])

行业分类映射

async def industry_lookup(codes):
    async with TdxData(cache_dir=Path("./tdx_cache")) as td:
        hy = await td.get_industry_map()          # {6位代码: IndustryInfo}
        for c in codes:
            info = hy.get(c)
            if info:
                print(c, info.tdx_industry, info.sw_industry)

板块成分(离线解析)

get_block_parsed 拿到的是纯 dataclass,落成本地 JSON 后完全脱网可用—— 适合做「板块成分快照」的定时任务。

import json

async def snapshot_blocks():
    async with TdxData(cache_dir=Path("./tdx_cache")) as td:
        all_blocks = []
        for fn in ("block_zs.dat", "block_gn.dat", "block_fg.dat"):
            for b in await td.get_block_parsed(fn):
                all_blocks.append({
                    "name": b.name,
                    "category": b.category,
                    "codes": b.codes,
                })
        Path("blocks.json").write_text(
            json.dumps(all_blocks, ensure_ascii=False), encoding="utf-8"
        )

港股 / 美股 / 期货 / 期权

async def ex_markets():
    async with TdxData() as td:
        hk = await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)
        us = await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)
        fut = await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700)
        opt = await td.get_kline(ExMarket.SH_STOCK_OPTION, "10010971", KlinePeriod.DAY, count=700)
        print(len(hk), len(us), len(fut), len(opt))

        # 港股全量逐笔(自动翻页,≤50 页 / 9 万条)
        ticks = await td.get_goods_transaction_all(ExMarket.HK_MAIN_BOARD, "00700")
        print(len(ticks))

转成 pandas

包本身不带 pandas 依赖,但转换是一行的事:

import pandas as pd

async def to_dataframe(code: str):
    async with TdxData() as td:
        bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=800)
    df = pd.DataFrame([{
        "dt": b.datetime, "open": b.open, "high": b.high,
        "low": b.low, "close": b.close, "vol": b.vol, "amount": b.amount,
    } for b in bars])
    return df.set_index("dt")

长驻服务(FastAPI)

!!! danger "不要每次请求都新建 TdxData" 池与缓存都挂在实例上,每请求新建 = 每请求重建连接池 + 缓存全部失效。

from contextlib import asynccontextmanager
from pathlib import Path
from fastapi import FastAPI, Request

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with TdxData(cache_dir=Path("./tdx_cache"), pool_min=4, pool_max=16) as td:
        app.state.td = td
        yield

app = FastAPI(lifespan=lifespan)

@app.get("/kline/{code}")
async def kline(code: str, request: Request):
    td = request.app.state.td
    bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=30)
    return [{"dt": str(b.datetime), "close": b.close} for b in bars]

下一步