数据模型¶

全部数据模型位于 pytdxdata.models，统一为 @dataclass(slots=True)。

选择 dataclass 而不是 pandas DataFrame 是刻意的：零依赖 + 零转换开销，需要 DataFrame 时你自己转（一行的事，见场景示例 → 转成 pandas）。

导入方式¶

包级只导出 4 个枚举 + 6 个核心模型：

from pytdxdata import Market, ExMarket, KlinePeriod, Adjust
from pytdxdata import (
    SecurityBar, SecurityQuote, TransactionRecord,
    MinuteBar, XdxrRecord, FinanceRecord,
)

其余模型需要从子模块导入：

from pytdxdata.models import TdxBlock, IndustryInfo, FinancialFileInfo, FinancialRecord
from pytdxdata.models import BoardInfo, MemberQuote, AuctionItem, CapitalFlow

模型地图¶

模型	代表什么	从哪来
`SecurityBar`	一根 K 线	`get_bars` / `get_indicators`
`IndexBar`	指数 K 线（继承 `SecurityBar`）	`get_bars`
`SecurityQuote`	五档报价快照	`get_quotes` / `get_board_members`
`SecurityInfo`	证券列表条目（代码 / 名称 / 前收）	`get_universe`
`TransactionRecord`	一笔成交	`get_ticks`
`MinuteBar`	一分钟分时点	`get_minutes`
`XdxrRecord`	一次除权除息事件	`get_xdxr`
`FinanceRecord`	财务快照（最新一期，36 字段）	`get_finance`
`FinancialRecord`	历史专业财报（`gpcw*.zip`，多报告期）	`get_financial_records_parsed`
`FinancialFileInfo`	财报文件索引条目	`get_financial_file_infos`
`TdxBlock`	一个板块及其成分股	`get_block_parsed`
`IndustryInfo`	一只股票的行业归属	`get_industry_map`
`BoardInfo`	板块列表条目（含领涨股）	`get_boards`
`MemberQuote`	成分股报价（MAC 原始字段）	旧 `get_stock_quotes` / `get_stock_quotes_list`
`BelongBoard`	个股所属板块	`get_board_of`
`AuctionItem`	集合竞价撮合点	`get_auction`
`UnusualItem`	一笔市场异动	`get_unusual`
`SymbolSnapshot`	个股特征快照	`get_snapshot`
`GoodsItem`	扩展市场商品	旧 `get_goods_list`
`ServerInfo`	服务器交易时段	`get_server_info`
`CapitalFlow`	个股资金流向	`get_capital_flow`
`MarketStat`	全市场统计	`get_market_stat`
`FileMeta`	远程文件元信息	`get_file_meta`

FinanceRecord vs FinancialRecord 只差一个字母

但它们完全不同：

	`FinanceRecord`	`FinancialRecord`
来源	`get_finance()` — 标准通道	`get_financial_records_parsed()` — 服务器文件
内容	最新一期财务快照	历史多报告期专业财报
结构	具名属性（`zongguben`、`jingzichan` ...）	`fields: list[float]`，原始字段数组
单位	万元 / 万股	原始 float，需自行按字段语义换算

SecurityBar.datetime 的时间戳口径（v0.6.2 起）

时间统一为北京时间。A股 / 港股 / 期货的原始时间戳即为北京时间；美股的原始报文混用了「美东交易日日期」与「北京时间时分」两个时区，库在构造时已自动归一化（凌晨段日期 +1 天），因此 bar.datetime 可直接排序 / 比较 / 过滤。

但要注意美股一个交易日横跨两个北京自然日，按交易日聚合请用 bar.trading_date：

bars = await td.get_bars("usAAPL", KlinePeriod.MIN_1, count=390)
bars[0].datetime        # 2026-10-12 21:31:00（北京时间）
bars[-1].datetime       # 2026-10-13 04:00:00（次日）
bars[0].trading_date    # "2026-10-12" —— 归属的美东交易日

bar.is_us 可判定是否美股。详见常见问题 → 美股分钟 K 线。

完整字段定义¶

以下由 mkdocstrings 从源码实时渲染（以源码为准）：

数据模型：K线/报价/列表/逐笔/分时/财务（全部dataclass，性能优先不依赖pandas）

类¶

ExMarket ¶

Bases: IntEnum

扩展市场代码（港股/期货/期权，通达信EX通道）

KlinePeriod ¶

Bases: IntEnum

通达信K线周期编码（KlineCategory，与 easy-tdx 一致）

Adjust ¶

Bases: IntEnum

复权方式（MAC通道）

SecurityBar `dataclass` ¶

SecurityBar(
    market: int,
    code: str,
    open: float,
    high: float,
    low: float,
    close: float,
    vol: float,
    amount: float,
    year: int,
    month: int,
    day: int,
    hour: int = 0,
    minute: int = 0,
    symbol: str = "",
)

K线记录（价格单位：元）。跨市场统一模型（A股/港股/美股/期货共用）。

时间戳口径统一为北京时间：A股/港股/期货原始即为北京时间；美股原始是「日期=美东交易日 + 时分=北京时间」的混合值，构造时已还原为真实北京时间（见 __post_init__）。该 bar 归属的交易日见 :attr:trading_date。

属性¶

is_us `property` ¶

is_us: bool

是否美股（EX 通道 US_STOCK）。

datetime `property` ¶

datetime: datetime

bar 的时刻（北京时间）。

trading_date `property` ¶

trading_date: str

该 bar 归属的交易日，YYYY-MM-DD。

美股：datetime 已还原为北京时间，凌晨段（北京 hour < 12）属于前一天 的美东交易日，故回退一天；A股/港股/期货的交易日即自然日。按交易日聚合（如分钟线合成日线）时应当用本字段，而不是 datetime.date()。

IndexBar `dataclass` ¶

IndexBar(
    market: int,
    code: str,
    open: float,
    high: float,
    low: float,
    close: float,
    vol: float,
    amount: float,
    year: int,
    month: int,
    day: int,
    hour: int = 0,
    minute: int = 0,
    symbol: str = "",
)

Bases: SecurityBar

指数K线（多涨跌家数字段，结构同K线仅解析时跳过4字节）

IndicatorSet `dataclass` ¶

IndicatorSet(
    symbol: str,
    bars: list[SecurityBar] = list(),
    indicators: dict[str, list[float | None]] = dict(),
)

K线 + 技术指标组合（TdxData.get_indicators 的返回单元）。

indicators 里每个序列与 bars 等长、尾部对齐；预热期为 None 的指标（如 BOLL 前三档）保留 None。

SecurityQuote `dataclass` ¶

SecurityQuote(
    market: int,
    code: str,
    price: float,
    pre_close: float,
    open: float,
    high: float,
    low: float,
    vol: float,
    amount: float,
    s_vol: float,
    b_vol: float,
    bid: list[tuple[float, float]] = list(),
    ask: list[tuple[float, float]] = list(),
    server_time: str = "",
    trading_status: int = 0,
    cur_vol: float = 0.0,
    rise_speed: float = 0.0,
    limit_up: float = 0.0,
    limit_down: float = 0.0,
    decimal_point: int = 2,
    open_amount: float = 0.0,
    symbol: str = "",
    name: str = "",
    fields: dict[str, float] = dict(),
)

报价（跨市场统一模型）。

A股（标准通道）：五档 bid/ask + 买卖量 + 涨跌停价齐全，name 为空。 A股（fields=[...] 走 MAC 0x122B）：name 与 fields 齐全，五档为空。扩展市场（港股/美股/期货）：name + 基础价量在属性上，其余字段位在 fields。

SecurityInfo `dataclass` ¶

SecurityInfo(
    market: int,
    code: str,
    name: str,
    volunit: int,
    decimal_point: int,
    pre_close: float,
    symbol: str = "",
    kind: str = "",
)

标的清单条目（跨市场统一模型：A股证券列表 + 扩展市场商品列表）

TransactionRecord `dataclass` ¶

TransactionRecord(
    market: int,
    code: str,
    time: str,
    price: float,
    vol: float,
    trade_count: int,
    bs_flag: int,
    symbol: str = "",
    fields: dict[str, float] = dict(),
)

逐笔成交（跨市场统一模型；A股 MAC 通道含 trade_count=成交笔数）

MinuteBar `dataclass` ¶

MinuteBar(
    price: float,
    vol: float,
    avg_price: float = 0.0,
    hour: int = 0,
    minute: int = 0,
    symbol: str = "",
    market: int = 0,
    code: str = "",
    date: int = 0,
    fields: dict[str, float] = dict(),
)

分时（跨市场统一模型；A股 MAC 0x122D / 扩展市场 0x122D 同构）

XdxrRecord `dataclass` ¶

XdxrRecord(
    market: int,
    code: str,
    year: int,
    month: int,
    day: int,
    category: int,
    name: str,
    fenhong: float = 0.0,
    peigujia: float = 0.0,
    songzhuangu: float = 0.0,
    peigu: float = 0.0,
    suogu: float = 0.0,
    xingquanjia: float = 0.0,
    fenshu: float = 0.0,
    panqian_liutong: float = 0.0,
    qian_zongguben: float = 0.0,
    panhou_liutong: float = 0.0,
    hou_zongguben: float = 0.0,
    symbol: str = "",
)

除权除息记录

属性¶

date `property` ¶

date: str

日期字符串 YYYY-MM-DD。

FinanceRecord `dataclass` ¶

FinanceRecord(
    market: int,
    code: str,
    liutong_guben: float = 0.0,
    zong_guben: float = 0.0,
    guojia_gu: float = 0.0,
    faqiren_faren_gu: float = 0.0,
    faren_gu: float = 0.0,
    b_gu: float = 0.0,
    h_gu: float = 0.0,
    zhigong_gu: float = 0.0,
    province: int = 0,
    industry: int = 0,
    updated_date: int = 0,
    ipo_date: int = 0,
    gudong_renshu: float = 0.0,
    zong_zichan: float = 0.0,
    liudong_zichan: float = 0.0,
    guding_zichan: float = 0.0,
    wuxing_zichan: float = 0.0,
    liudong_fuzhai: float = 0.0,
    changqi_fuzhai: float = 0.0,
    ziben_gongjijin: float = 0.0,
    jing_zichan: float = 0.0,
    zhuying_shouru: float = 0.0,
    zhuying_lirun: float = 0.0,
    yingshou_zhangkuan: float = 0.0,
    yingye_lirun: float = 0.0,
    touzi_shouyu: float = 0.0,
    jingying_xianjinliu: float = 0.0,
    zong_xianjinliu: float = 0.0,
    cunhuo: float = 0.0,
    lirun_zonghe: float = 0.0,
    shuihou_lirun: float = 0.0,
    jing_lirun: float = 0.0,
    weifen_lirun: float = 0.0,
    meigujing_zichan: float = 0.0,
    reserve2: float = 0.0,
    symbol: str = "",
)

财务快照（股本/金额单位：万股/万元）

BoardInfo `dataclass` ¶

BoardInfo(
    market: int,
    code: str,
    name: str,
    price: float,
    rise_speed: float,
    pre_close: float,
    symbol_market: int = 0,
    symbol_code: str = "",
    symbol_name: str = "",
    symbol_price: float = 0.0,
    symbol_rise_speed: float = 0.0,
    symbol_pre_close: float = 0.0,
    symbol: str = "",
)

板块列表条目（含领涨股信息）

MemberQuote `dataclass` ¶

MemberQuote(
    market: int,
    code: str,
    name: str,
    fields: dict[str, float] = dict(),
    symbol: str = "",
)

板块成分/自定义字段报价的协议层原始记录。

API 层会把它归一成 :class:SecurityQuote（fields 原样保留、基础字段位填进属性），所以普通调用不会看到本类。

BelongBoard `dataclass` ¶

BelongBoard(
    market: int,
    board_code: str,
    board_name: str,
    close: float,
    pre_close: float,
    symbol: str = "",
)

个股所属板块

AuctionItem `dataclass` ¶

AuctionItem(
    time: str,
    price: float,
    matched: int,
    unmatched: int,
    symbol: str = "",
)

集合竞价

UnusualItem `dataclass` ¶

UnusualItem(
    market: int,
    code: str,
    name: str,
    type: int,
    desc: str,
    value: float,
    time: str,
    symbol: str = "",
)

市场异动

SymbolSnapshot `dataclass` ¶

SymbolSnapshot(
    market: int,
    code: str,
    name: str,
    date: int,
    time: int,
    activity: int,
    pre_close: float,
    open: float,
    high: float,
    low: float,
    close: float,
    vol: float,
    amount: float,
    turnover: float,
    avg_price: float,
    symbol: str = "",
)

个股特征快照

GoodsItem `dataclass` ¶

GoodsItem(
    category: int,
    name: str,
    code: float,
    switch: int,
    index: int,
)

扩展市场商品（期货/期权）

ServerInfo `dataclass` ¶

ServerInfo(
    date: int,
    last_trade_date: int,
    sessions: list[tuple[int, int]] = list(),
)

服务器交易时段信息

CapitalFlow `dataclass` ¶

CapitalFlow(
    market: int,
    code: str,
    main_buy: float,
    main_sell: float,
    retail_buy: float,
    retail_sell: float,
    buy5: float,
    sell5: float,
    big5: float,
    mid5: float,
    symbol: str = "",
)

资金流向

TdxBlock `dataclass` ¶

TdxBlock(
    name: str,
    category: int,
    count: int,
    codes: list[str] = list(),
)

通达信板块条目（解析自 block_zs/gn/fg.dat）。

category: 0=行业 1=地域 2=概念 3=风格（按文件名推断） count: 文件内声明的成分股数量（可能大于 codes 实际解析数）

IndustryInfo `dataclass` ¶

IndustryInfo(
    code: str, tdx_industry: str, sw_industry: str = ""
)

个股行业分类（解析自 tdxhy.cfg）

FinancialFileInfo `dataclass` ¶

FinancialFileInfo(filename: str, hash: str, filesize: int)

历史专业财报文件索引条目（解析自 tdxfin/gpcw.txt）

FinancialRecord `dataclass` ¶

FinancialRecord(
    code: str,
    market: int,
    report_date: int,
    fields: list[float] = list(),
)

历史专业财报记录（解析自 gpcw*.zip 内 .dat）。

注意与 FinanceRecord（最新财务快照）区分：本类保留协议原始 float 字段，字段含义随 report_size 变化，需结合 gpcw.txt 字段字典解释。

下一步¶

枚举速查 — market / period 参数取值
TdxData 方法 — 哪个方法返回哪个模型

数据模型¶

导入方式¶

模型地图¶

完整字段定义¶

类¶

ExMarket ¶

KlinePeriod ¶

Adjust ¶

SecurityBar dataclass ¶

属性¶

is_us property ¶

datetime property ¶

trading_date property ¶

IndexBar dataclass ¶

IndicatorSet dataclass ¶

SecurityQuote dataclass ¶

SecurityInfo dataclass ¶

TransactionRecord dataclass ¶

MinuteBar dataclass ¶

XdxrRecord dataclass ¶

属性¶

date property ¶

FinanceRecord dataclass ¶

BoardInfo dataclass ¶

MemberQuote dataclass ¶

BelongBoard dataclass ¶

AuctionItem dataclass ¶

UnusualItem dataclass ¶

SymbolSnapshot dataclass ¶

GoodsItem dataclass ¶

ServerInfo dataclass ¶

CapitalFlow dataclass ¶

TdxBlock dataclass ¶

IndustryInfo dataclass ¶

FinancialFileInfo dataclass ¶

FinancialRecord dataclass ¶

下一步¶

SecurityBar `dataclass` ¶

is_us `property` ¶

datetime `property` ¶

trading_date `property` ¶

IndexBar `dataclass` ¶

IndicatorSet `dataclass` ¶

SecurityQuote `dataclass` ¶

SecurityInfo `dataclass` ¶

TransactionRecord `dataclass` ¶

MinuteBar `dataclass` ¶

XdxrRecord `dataclass` ¶

date `property` ¶

FinanceRecord `dataclass` ¶

BoardInfo `dataclass` ¶

MemberQuote `dataclass` ¶

BelongBoard `dataclass` ¶

AuctionItem `dataclass` ¶

UnusualItem `dataclass` ¶

SymbolSnapshot `dataclass` ¶

GoodsItem `dataclass` ¶

ServerInfo `dataclass` ¶

CapitalFlow `dataclass` ¶

TdxBlock `dataclass` ¶

IndustryInfo `dataclass` ¶

FinancialFileInfo `dataclass` ¶

FinancialRecord `dataclass` ¶