Files
pytdxdata/docs/api/models.md
T
openbot-coder 5408903a4c fix(models): 修复美股分钟K线 datetime 时区拼接错位,还原为北京时间
通达信 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 无日期分量可承载跨日信息。
2026-10-13 15:10:22 +08:00

97 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 数据模型
全部数据模型位于 `pytdxdata.models`,统一为 `@dataclass(slots=True)`。
选择 dataclass 而不是 pandas DataFrame 是刻意的:**零依赖 + 零转换开销**,
需要 DataFrame 时你自己转(一行的事,见 [场景示例 → 转成 pandas](../cookbook.md#to-pandas))。
## 导入方式
包级只导出 4 个枚举 + 6 个核心模型:
```python
from pytdxdata import Market, ExMarket, KlinePeriod, Adjust
from pytdxdata import (
SecurityBar, SecurityQuote, TransactionRecord,
MinuteBar, XdxrRecord, FinanceRecord,
)
```
其余模型需要从子模块导入:
```python
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:
- "!^_"
## 下一步
- [枚举速查](enums.md) — `market` / `period` 参数取值
- [TdxData 方法](tdxdata.md) — 哪个方法返回哪个模型