Files
pytdxdata/docs/api/models.md
T
openbotandopenbot-coder b2f899df49 fix(models): 修复美股分钟K线 datetime 时区拼接错位,还原为北京时间 (#2)
通达信 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 无日期分量可承载跨日信息。

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-13 16:47:57 +08:00

4.2 KiB
Raw Blame History

数据模型

全部数据模型位于 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

!!! warning "FinanceRecord vs FinancialRecord 只差一个字母" 但它们完全不同:

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

!!! tip "SecurityBar.datetime 的时间戳口径(v0.6.2 起)" 时间统一为北京时间。A股 / 港股 / 期货的原始时间戳即为北京时间;美股的原始报文 混用了「美东交易日日期」与「北京时间时分」两个时区,库在构造时已自动归一化 (凌晨段日期 +1 天),因此 bar.datetime 可直接排序 / 比较 / 过滤。

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

```python
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 线](../faq.md)。

完整字段定义

以下由 mkdocstrings 从源码实时渲染(以源码为准):

::: pytdxdata.models options: members_order: source show_root_heading: false show_root_toc_entry: false filters: - "!^_"

下一步