通达信 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 无日期分量可承载跨日信息。
4.2 KiB
4.2 KiB
数据模型
全部数据模型位于 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: - "!^_"
下一步
- 枚举速查 —
market/period参数取值 - TdxData 方法 — 哪个方法返回哪个模型