- 新增 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/
81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 数据模型
|
||
|
||
全部数据模型位于 `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_kline` / `get_kline_batch` |
|
||
| `IndexBar` | 指数 K 线(继承 `SecurityBar`) | `get_index_kline` |
|
||
| `SecurityQuote` | 五档报价快照 | `get_quotes` |
|
||
| `SecurityInfo` | 证券列表条目(代码 / 名称 / 前收) | `get_security_list` |
|
||
| `TransactionRecord` | 一笔成交 | `get_transactions` |
|
||
| `MinuteBar` | 一分钟分时点 | `get_minute` |
|
||
| `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_board_list` |
|
||
| `MemberQuote` | 成分股报价(自定义字段) | `get_board_members` / `get_stock_quotes` |
|
||
| `BelongBoard` | 个股所属板块 | `get_belong_board` |
|
||
| `AuctionItem` | 集合竞价撮合点 | `get_auction` |
|
||
| `UnusualItem` | 一笔市场异动 | `get_unusual` |
|
||
| `SymbolSnapshot` | 个股特征快照 | `get_symbol_info` |
|
||
| `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,需自行按字段语义换算 |
|
||
|
||
## 完整字段定义
|
||
|
||
以下由 `mkdocstrings` 从源码实时渲染(**以源码为准**):
|
||
|
||
::: pytdxdata.models
|
||
options:
|
||
members_order: source
|
||
show_root_heading: false
|
||
show_root_toc_entry: false
|
||
filters:
|
||
- "!^_"
|
||
|
||
## 下一步
|
||
|
||
- [枚举速查](enums.md) — `market` / `period` 参数取值
|
||
- [TdxData 方法](tdxdata.md) — 哪个方法返回哪个模型
|