release: v0.6.0(统一对外接口重构)
按「数据类型」合并同类查询接口:一个数据类型 = 一个方法,跨市场自动选路。 - 28 个统一接口(get_universe/get_quotes/get_bars/get_indicators/get_ticks/ get_minutes/get_f10/get_file/get_boards/get_board_of/get_snapshot 等), 标的统一字符串写法(sz000001 / hk00700 / usAAPL / cffex:IFL0); 同名旧方法不再兼容 (market, code) 元组。 - 旧 51 个按通道/市场分裂的接口:33 个保留为 deprecated 别名(1.0 移除), 18 个同名升级为统一接口。公开方法共 63 个。 - 新增库层标的解析 pytdxdata.symbols;数据模型追加 symbol/name/fields 兜底字段。 - 修复:分页器连接泄漏、日期区间 K线返回 0 条(偏移方向探测)、池子全冷却死等。 - 文档/README/SKILL/llms.txt 全量同步;新增 docs/refactor-audit.md 审查报告。 - 测试 127 个用例全绿(含 tests/test_all_interfaces.py 全 63 方法回归)。
This commit is contained in:
1 parent
1bee6b0fc7
commit
3e0beb27a6
33 files changed
+2789
-1270
No files matched your search
+54
-69
@@ -1,8 +1,9 @@
|
||||
# 接口总览
|
||||
|
||||
对外唯一入口是 **`TdxData`** 类,共 **51 个数据方法**
|
||||
(另有 `start()` / `close()` 两个生命周期方法,以及 `__aenter__` / `__aexit__`)。
|
||||
所有方法都可以直接 `await`,返回的是标准库 `dataclass` 组成的 `list`,没有自定义容器类型。
|
||||
对外唯一入口是 **`TdxData`** 类,所有方法都可直接 `await`,返回标准库 `dataclass` 组成的 `list`。
|
||||
|
||||
**v0.6+** 推荐使用**统一接口**(一个数据类型 = 一个方法,跨市场自动选路);
|
||||
旧的按通道/市场分裂的接口仍可调用,但会发出 `DeprecationWarning`,**1.0 移除**。
|
||||
|
||||
```python
|
||||
from pytdxdata import TdxData
|
||||
@@ -21,100 +22,84 @@ from pytdxdata import TdxData
|
||||
| `async close()` | 关闭全部连接池与缓存 |
|
||||
| `async with TdxData() as td:` | 上下文管理器,自动 start / close |
|
||||
|
||||
## K 线(6)
|
||||
---
|
||||
|
||||
## 统一接口(v0.6+ 推荐){#unified}
|
||||
|
||||
标的一律用**字符串写法**(`sz000001` / `hk00700` / `usAAPL` / `cffex:IFL0`,
|
||||
裸 6 位数字 = 沪市指数)。跨市场按通道自动分组并发,返回值统一带 `symbol` 字段。
|
||||
|
||||
### 标的清单
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_kline(market, code, period, *, start, count, adjust, start_date, end_date)` | `list[SecurityBar]` | 主接口。`count > 页大小` 自动并发分页;复权走 MAC;支持日期区间(内部二分定位) |
|
||||
| `get_kline_since(market, code, period, since, adjust)` | `list[SecurityBar]` | 增量便捷方法(≥`since`,含当天) |
|
||||
| `get_kline_batch(stocks, period, *, start, count, adjust, concurrency)` | `dict[str, list[SecurityBar]]` | 多股票并发,返回 `{code: bars}` |
|
||||
| `get_index_kline(market, code, period, *, start, count)` | `list[SecurityBar]` | 指数 K 线(多涨跌家数字段已处理) |
|
||||
| `get_stock_kline_with_indicators(market, code, indicators, ...)` | `dict` | K 线 + 技术指标(MACD / KDJ / RSI / BOLL / MA / EMA) |
|
||||
| `get_kline_offset(offset, count)` | `tuple[int, int]` | K 线偏移信息(MAC) |
|
||||
| `get_universe(market=None)` | `list[SecurityInfo]` | 跨市场标的清单(A 股 + 港股 + 美股 + 期货/期权),EX 通道结果一次拉全后内存过滤 |
|
||||
|
||||
## 报价(4)
|
||||
### 报价
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_quotes(stocks)` | `list[SecurityQuote]` | 五档报价;`>80` 只自动切批;TTL 5s |
|
||||
| `get_stock_quotes(stocks, bits)` | `list[MemberQuote]` | MAC 自定义字段报价(≤80 只/次) |
|
||||
| `get_stock_quotes_list(category, *, start, count, sort_type)` | `list[MemberQuote]` | 市场分类报价列表(0沪A / 6全A / 8科创 / 14创业) |
|
||||
| `get_quotes(symbols, *, fields=None)` | `list[SecurityQuote]` | 跨市场混合报价(A 股标准通道有五档 bid/ask + 涨跌停价;给了 `fields` 走 MAC/EX 字段位通道有 name) |
|
||||
| `get_snapshot(symbols)` | `list[SymbolSnapshot]` | 个股特征快照(当日/换手/活跃度,A 股) |
|
||||
| `get_auction(symbols)` | `list[AuctionItem]` | 集合竞价(A 股) |
|
||||
| `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向(A 股) |
|
||||
| `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数 / 总额 / 市值 / 涨跌停数) |
|
||||
|
||||
## 逐笔与分时(4)
|
||||
### K 线
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_transactions(market, code, *, date, start, count)` | `list[TransactionRecord]` | 逐笔成交(MAC,**含 `trade_count` 成交笔数**),支持历史回溯 |
|
||||
| `get_minute(market, code, *, date)` | `list[MinuteBar]` | 分时(今日 / 历史,MAC `0x122D`) |
|
||||
| `get_minute_batch(stocks, *, date, concurrency)` | `dict[str, list[MinuteBar]]` | 批量分时 |
|
||||
| `get_chart_sampling(market, code)` | `list[float]` | 分时缩略采样(A 股走 MAC `0x254D`) |
|
||||
| `get_bars(symbols, period, *, start, count, adjust, start_date, end_date, concurrency)` | `list[SecurityBar]` | 跨市场 K 线(自动判指数、复权走 MAC、并发分页、日期区间二分定位,支持混合 A 股+港股+期货) |
|
||||
| `get_indicators(symbols, indicators, *, period, count, adjust, params)` | `list[IndicatorSet]` | K 线 + 技术指标(MACD / KDJ / RSI / BOLL / MA / EMA),返回 `bars + indicators` 组合 |
|
||||
|
||||
## 证券列表(3)
|
||||
### 逐笔与分时
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_security_count(market)` | `int` | 市场证券数量 |
|
||||
| `get_security_list(market, *, start, count)` | `list[SecurityInfo]` | `count=None` = 全部(先查总数防死循环) |
|
||||
| `get_security_list_all(market)` | `list[SecurityInfo]` | 全市场列表(高并发一次拉完,缓存 1 天) |
|
||||
| `get_ticks(symbols, *, date, start, count, concurrency)` | `list[TransactionRecord]` | 跨市场逐笔成交(A 股 MAC `0x122F` 含 `trade_count`;港股 EX `0x23FC` / `0x2406`;其他扩展市场 MAC) |
|
||||
| `get_minutes(symbols, *, date, sampling, concurrency)` | `list[MinuteBar]` | 跨市场分时(A 股 MAC `0x122D` 支持历史;`sampling=True` 取缩略采样约 240 点) |
|
||||
|
||||
## 除权 / 财务 / F10 / 文件(15) {#file-methods}
|
||||
### 公司信息 / 除权 / 财务 / 文件
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_xdxr(market, code)` | `list[XdxrRecord]` | 除权除息历史(标准) |
|
||||
| `get_finance(market, code)` | `FinanceRecord \| None` | 财务快照(标准) |
|
||||
| `get_price_limits(market, code, name, pre_close, listed_days)` | `tuple[float \| None, float \| None]` | 涨跌停价(**本地计算**,无网络) |
|
||||
| `get_company_info_category(market, code)` | `list` | F10 目录 |
|
||||
| `get_company_info_content(market, code, filename, offset, length)` | `str` | F10 内容(分块) |
|
||||
| `get_block_info(filename)` | `bytes` | 板块文件**原始字节** |
|
||||
| `get_report_file(filename)` | `bytes` | 报告 / 财务文件**原始字节** |
|
||||
| `get_financial_file_list()` | `list[str]` | 财务文件列表**原始行** |
|
||||
| `get_financial_records(filename)` | `bytes` | 财务文件内容**原始字节** |
|
||||
| `get_file_meta(filename)` | `FileMeta` | 远程文件元信息(MAC `0x1215`) |
|
||||
| `download_file(filename, filesize)` | `bytes` | 下载完整远程文件(MAC `0x1217`,分块) |
|
||||
| **`get_block_parsed(filename)`** | `list[TdxBlock]` | 板块文件**下载 + 解析**为成分股 |
|
||||
| **`get_industry_map()`** | `dict[str, IndustryInfo]` | `tdxhy.cfg` **下载 + 解析**:通达信 + 申万行业 |
|
||||
| **`get_financial_file_infos()`** | `list[FinancialFileInfo]` | `gpcw.txt` **下载 + 解析**:文件名 / MD5 / 大小 |
|
||||
| **`get_financial_records_parsed(filename)`** | `list[FinancialRecord]` | `gpcw*.zip` **解压 + 解析**:每股原始字段 |
|
||||
| `get_f10(symbol, section=None, *, offset, length)` | `list \| str` | F10 公司资料(`section=None` 返回目录,给了返回正文) |
|
||||
| `get_xdxr(symbols)` | `list[XdxrRecord]` | 除权除息历史(A 股) |
|
||||
| `get_finance(symbols)` | `list[FinanceRecord]` | 财务快照(A 股,返回列表,无数据的标的跳过) |
|
||||
| `get_price_limits(symbol, name, pre_close, listed_days)` | `tuple[float\|None, float\|None]` | 涨跌停价(本地计算,无网络) |
|
||||
| `get_file(name)` | `bytes` | 服务器文件原始字节(`block_*.dat` / `tdxhy.cfg` / `tdxfin/*` / MAC 远程文件) |
|
||||
| `get_block_parsed(filename)` | `list[TdxBlock]` | 板块文件**下载 + 解析**为成分股 |
|
||||
| `get_industry_map()` | `dict[str, IndustryInfo]` | `tdxhy.cfg` **下载 + 解析** |
|
||||
| `get_financial_file_infos()` | `list[FinancialFileInfo]` | `gpcw.txt` **下载 + 解析** |
|
||||
| `get_financial_records_parsed(filename)` | `list[FinancialRecord]` | `gpcw*.zip` **解压 + 解析** |
|
||||
|
||||
!!! note "原始字节通道保留"
|
||||
返回 `bytes` 的那 4 个方法**保持向后兼容**,解析版是**新增**方法而不是替换。
|
||||
解析器在 `pytdxdata.codec`,纯标准库,可以脱网单独复用(见 [文件解析器](codec.md))。
|
||||
|
||||
## 板块(6)
|
||||
### 市场 / 板块
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_board_list(board_type, count)` | `list[BoardInfo]` | 板块列表(0全部 / 1行业 / 2概念) |
|
||||
| `get_board_members(board_symbol, count, sort_type)` | `list[MemberQuote]` | 板块成分股报价(如 `881001`) |
|
||||
| `get_belong_board(market, code)` | `list[BelongBoard]` | 个股所属板块 |
|
||||
| `get_board_summary(board_symbol)` | `dict` | 成分数 / 成交额 / 主力净流入 / 涨跌家数 |
|
||||
| `get_board_ranking(board_type, top_n)` | `list[dict]` | 板块涨跌幅排行 |
|
||||
| `get_board_change_ranking(board_type, days, top_n)` | `list[dict]` | 板块 N 日涨跌幅排行 |
|
||||
| `get_unusual(market="all", *, start, count)` | `list[UnusualItem]` | 市场异动(A 股,`"all"` = 深 + 沪) |
|
||||
| `get_server_info()` | `ServerInfo` | 服务器交易时段信息 |
|
||||
| `get_kline_offset(offset, count)` | `tuple[int, int]` | K 线偏移信息(MAC) |
|
||||
| `get_boards(kind="all", *, count)` | `list[BoardInfo]` | 板块列表(`"all"` / `"industry"` / `"concept"` / `"style"`) |
|
||||
| `get_board_members(board, *, fields, count)` | `list[SecurityQuote]` | 板块成分股报价(返回归一报价模型) |
|
||||
| `get_board_of(symbols)` | `list[BelongBoard]` | 个股所属板块(A 股) |
|
||||
| `get_board_summary(board)` | `dict` | 板块汇总(成分数 / 成交额 / 主力净流入 / 涨跌家数) |
|
||||
| `get_board_ranking(kind="industry", *, top_n)` | `list[dict]` | 板块当日涨跌幅排行 |
|
||||
| `get_board_change_ranking(kind="industry", *, days, top_n)` | `list[dict]` | 板块 N 日涨跌幅排行 |
|
||||
|
||||
## 竞价 / 异动 / 快照 / 资金流 / 服务器(5)
|
||||
---
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_auction(market, code)` | `list[AuctionItem]` | 集合竞价 |
|
||||
| `get_unusual(market, start, count)` | `list[UnusualItem]` | 市场异动 |
|
||||
| `get_symbol_info(market, code)` | `SymbolSnapshot` | 个股特征快照 |
|
||||
| `get_capital_flow(market, code)` | `CapitalFlow` | 个股资金流向(主力 / 散户 + 5 档) |
|
||||
| `get_server_info()` | `ServerInfo` | 服务器交易时段 |
|
||||
## 旧接口(deprecated,1.0 移除){#legacy}
|
||||
|
||||
## 扩展市场 EX:港股 / 美股 / 期货 / 期权(8)
|
||||
旧接口按通道/市场分裂(33 个 deprecated 别名),保留向后兼容但仍可用。
|
||||
完整旧方法列表见 `docs/API_REFERENCE.md`。
|
||||
|
||||
| 方法 | 返回 | 说明 |
|
||||
|------|------|------|
|
||||
| `get_goods_list(market, start, count)` | `list[dict]` | 扩展市场商品列表(`0x23F5`,二分定位市场) |
|
||||
| `get_goods_count(market)` | `int` | 商品数量(`None` = 全市场) |
|
||||
| `get_goods_quotes(stocks, bits)` | `list[MemberQuote]` | 扩展市场报价(`0x122B`) |
|
||||
| `get_goods_quotes_list(market, count)` | `list[MemberQuote]` | 商品列表 + 报价组合 |
|
||||
| `get_goods_chart_sampling(market, code)` | `list[float]` | 扩展市场分时采样(`0x254D`) |
|
||||
| `get_goods_tick_chart(market, code, ymd)` | `list[dict]` | 扩展市场分时 tick |
|
||||
| `get_goods_transaction(market, code, *, ymd, start, count)` | `list[dict]` | 扩展市场逐笔(港股 `0x23FC` / `0x2406`) |
|
||||
| `get_goods_transaction_all(market, code, ymd)` | `list[dict]` | 港股全量逐笔(自动翻页,≤50 页 / 9 万条) |
|
||||
!!! warning "迁移建议"
|
||||
各通道独立方法(如 `get_kline` / `get_transactions`)在 v0.6 内仍可调用,且仍接受
|
||||
`(market, code)` 写法,但会发出 `DeprecationWarning`。
|
||||
统一接口(`get_quotes` / `get_bars` / `get_ticks` / `get_xdxr` / `get_finance` /
|
||||
`get_auction` / `get_capital_flow` 等)一律只接受字符串标的(如 `"sz000001"`)。
|
||||
迁移对照见 [更新日志](../changelog.md)。
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
Reference in new issue
Block a user