diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d6a4bf..d13e577 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,69 @@
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+## [0.6.0] - 2026-09-16
+
+### 新增
+
+- **统一对外接口**:一个数据类型 = 一个方法,跨市场自动选路。
+ 标的统用字符串写法(`sz000001` / `hk00700` / `usAAPL` / `cffex:IFL0`),
+ A股/港股/美股/期货/期权混合查询一次返回。旧的 51 个按通道/市场分裂的接口中,
+ 33 个保留为 deprecated 别名(运行时发出 `DeprecationWarning`,**1.0 移除**),
+ 另 18 个(`get_quotes` / `get_xdxr` / `get_finance` / `get_auction` / `get_capital_flow` /
+ `get_market_stat` / `get_unusual` / `get_server_info` / `get_kline_offset` /
+ `get_board_members` / `get_board_summary` / `get_board_ranking` / `get_board_change_ranking` /
+ `get_block_parsed` / `get_industry_map` / `get_financial_file_infos` /
+ `get_financial_records_parsed` / `get_price_limits`)同名升级为统一接口。
+
+ | 数据类型 | 新接口 | 合并掉的旧接口 |
+ |----------|--------|----------------|
+ | 标的清单 | `get_universe(market)` | get_security_count + get_security_list + get_security_list_all + get_goods_count + get_goods_list |
+ | 报价 | `get_quotes(symbols, *, fields)` | get_quotes + get_stock_quotes + get_goods_quotes + get_goods_quotes_list |
+ | K线 | `get_bars(symbols, period, ...)` | get_kline + get_index_kline + get_kline_batch + get_kline_since |
+ | 指标 | `get_indicators(symbols, indicators, ...)` | get_stock_kline_with_indicators |
+ | 逐笔 | `get_ticks(symbols, *, date)` | get_transactions + get_goods_transaction + get_goods_transaction_all |
+ | 分时 | `get_minutes(symbols, *, date, sampling)` | get_minute + get_minute_batch + get_chart_sampling + get_goods_chart_sampling + get_goods_tick_chart |
+ | F10 | `get_f10(symbol, section)` | get_company_info_category + get_company_info_content |
+ | 文件 | `get_file(name)` | get_block_info + get_report_file + get_file_meta + download_file |
+ | 财务文件 | `get_financial_file_infos()` / `get_financial_records_parsed(fn)` | get_financial_file_list + get_financial_records |
+ | 板块列表 | `get_boards(kind)` | get_board_list |
+ | 板块成员 | `get_board_members(board)` → 归一 `SecurityQuote` | get_board_members + get_stock_quotes_list(分类报价) |
+ | 个股板块 | `get_board_of(symbols)` | get_belong_board |
+ | 快照 | `get_snapshot(symbols)` | get_symbol_info |
+
+ > `TdxData` 公开方法 63 个 = **28 个统一接口** + 33 个 deprecated 别名 + `start`/`close`。
+ > 统一接口一律只接受字符串标的;同名旧方法不再兼容 `(market, code)` 元组写法。
+
+- **库层标的解析** `pytdxdata.symbols`(原仅 CLI 内有):`parse_symbol` / `format_symbol` /
+ `parse_symbols` / `market_targets` / `is_cn_index`;裸 6 位数字视为沪市指数。
+- **归一数据模型**:`SecurityBar` / `SecurityQuote` / `TransactionRecord` / `MinuteBar` /
+ `SecurityInfo` 等均新增 `symbol`(规范化标的串)/ `name` / `fields`(原始字段位兜底),
+ 老构造写法不受影响(新字段有默认值)。
+- `IndicatorSet` dataclass(`get_indicators` 返回单元:`bars + indicators` 组合)。
+- `CacheKey.quote_key(..., tag=)` 支持按取数口径(标准五档 / MAC 字段位)隔离缓存。
+
+### 修复
+
+- **分页器连接泄漏**:`Paginator._worker` 换连接后旧连接不释放、池子被耗干
+ (`_Slot` 包装 + 归还时按槽释放)。
+- **日期区间 K线返回 0 条**:标准通道 `start` 偏移方向是递减(0=最新),旧的二分
+ 假设递增。改为运行时探测方向再二分(`_offset_descending` / `_bisect_offset`)。
+- **池子全冷却死等**:所有服务器进冷却后 `acquire` 排队 30s 超时。
+ 补 `ignore_cooldown=True` 兜底,避免无人持有连接时永久等待。
+- `HealthEngine.COOLDOWN_SECONDS` 保持 120s(旧的 FAIL_STREAK_COOLDOWN=1 意味着
+ 任意一次通信失败即冷却,实测下正常服务器不应被冷却,保留该行为)。
+
+### 变更
+
+- **`docs/api/index.md` 接口总览**重新组织:统一接口(推荐)优先于旧接口列表。
+- `scripts/check_docs.py`:`docs/api/index.md` 从 `MUST_LIST_ALL` 移到
+ `MUST_NOT_BE_STALE`(只列推荐的统一接口,旧方法不强制出现在总览页)。
+- CLI `tdx quotes` 改为统一 `td.get_quotes(symbols)`(跨市场混合报价)。
+- CLI `tdx kline` 改为统一 `td.get_bars(sym, period)`。
+- 测试 127 个用例全绿(新增 codec mock `get_file` 适配 + check_docs 新方法列表 +
+ `tests/test_all_interfaces.py` 全接口回归:mock 连接逐个调用全部 63 个公开方法,
+ 并以「覆盖哨兵」断言无方法遗漏)。
+
## [0.5.0] - 2026-09-15
### 新增
@@ -97,7 +160,8 @@
- 初始版本:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页 + 双通道(标准 / MAC)+ 扩展市场(港股 / 美股 / 期货 / 期权)
-[Unreleased]: https://github.com/openbot-coder/pytdxdata/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/openbot-coder/pytdxdata/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.5.0...v0.6.0
[0.5.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.4.0...v0.5.0
[0.4.0]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.2...v0.4.0
[0.3.2]: https://github.com/openbot-coder/pytdxdata/compare/v0.3.1...v0.3.2
diff --git a/README.md b/README.md
index dd20cf6..06b40b9 100644
--- a/README.md
+++ b/README.md
@@ -29,19 +29,19 @@ pip install "pytdxdata[uvloop]"
```python
import asyncio
from pytdxdata import TdxData
-from pytdxdata.models import Market, KlinePeriod, Adjust
+from pytdxdata.models import KlinePeriod, Adjust
async def main():
async with TdxData() as td: # 自动建连接池 + 缓存
# 日K线(count 超过单页大小会自动多连接并发分页)
- bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
+ bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
# 前复权(自动走 MAC 通道)
- qfq = await td.get_kline(Market.SZ, "300308", KlinePeriod.DAY,
+ qfq = await td.get_bars(["sz300308"], KlinePeriod.DAY,
count=500, adjust=Adjust.QFQ)
- # 五档报价(传 (market, code) 元组列表,>80 只自动切批)
- quotes = await td.get_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
+ # 跨市场报价:A股+港股+美股一次拿全
+ quotes = await td.get_quotes(["sh600000", "hk00700", "usAAPL"])
# 逐笔成交(MAC 通道,支持历史日期)
- ticks = await td.get_transactions(Market.SZ, "000001", date=20260811)
+ ticks = await td.get_ticks(["sz000001"], date=20260811)
print(bars[-1].close, quotes[0].price, len(ticks))
asyncio.run(main())
@@ -78,7 +78,8 @@ df = pd.DataFrame([asdict(b) for b in bars])
| 搞清枚举该填几 | [枚举速查](https://openbot-coder.github.io/pytdxdata/api/enums/) |
| 看协议二进制格式、三池路由、缓存策略 | [深入原理](https://openbot-coder.github.io/pytdxdata/internals/architecture/) |
| 用命令行 | [命令行工具](https://openbot-coder.github.io/pytdxdata/cli/) |
-| 完整接口清单(51 个数据方法) | [`docs/API_REFERENCE.md`](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/) |
+| 完整接口清单(28 个统一方法 + 33 个废弃别名) | [`docs/API_REFERENCE.md`](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/) |
+| 重构审查(数据一致性 / 遗漏对账) | [接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/) |
| 版本变更 | [`CHANGELOG.md`](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md) |
> 本 README 只做**入口层**。深度内容一律在文档站,避免两处维护造成漂移。
@@ -86,7 +87,7 @@ df = pd.DataFrame([asdict(b) for b in bars])
## 给 AI 助手用
仓库根的 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 是一份可直接加载的技能:三条必守约定、`KlinePeriod` 等枚举取值表、
-「想做什么 → 用哪个方法」决策表、以及 9 条真实陷阱。AI 编程助手读完就能一次写对,不必翻源码。
+「想做什么 → 用哪个方法」决策表、以及 11 条真实陷阱。AI 编程助手读完就能一次写对,不必翻源码。
```bash
# 丢进你所用 AI 助手的 skills 目录即可
@@ -103,7 +104,7 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \
```bash
uv sync # 建虚拟环境 + 注册 tdx 命令
-uv run pytest tests/ # 109 个测试用例(协议 / 池 / 缓存 / 分页 / API / 文件解析 / CLI / 文档漂移)
+uv run pytest tests/ # 127 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移)
uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings)
uv run mkdocs serve # 本地预览文档站
```
diff --git a/SKILL.md b/SKILL.md
index a7f1aef..3cb93f8 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -18,20 +18,24 @@ description: 用 pytdxdata 拉取通达信行情数据——A股(沪/深/北)、
from pytdxdata import TdxData
async with TdxData() as td: # 自动 start(探测服务器 + 预建连接 + 建缓存)
- bars = await td.get_kline(...)
+ bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
# 退出即 close
```
-不要直接 `await TdxData().get_kline(...)`——没 `start()` 就没有连接池。
+不要直接 `await TdxData().get_bars(...)`——没 `start()` 就没有连接池。
-**2. `market` 传的是整数枚举值,不是字符串**
+**2. 标的写法是字符串,不是元组**
-这是最高频的错误来源。**不要传 `"sh"` / `"SH"` / `"1"`**,要用枚举(它就是 `IntEnum`,所以传 `1` 也能跑,但可读性差):
+这是 v0.6 的最重要变化。**不要传 `(Market.SH, "600000")` 元组**,用字符串:
```python
-from pytdxdata.models import Market, KlinePeriod, Adjust
+# 旧写法(deprecated,会发出 DeprecationWarning):
+bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
-await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
+# 新写法(推荐):
+bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
+# 港股/美股/期货也一样:
+bars = await td.get_bars(["hk00700", "usAAPL", "cffex:IFL0"], KlinePeriod.DAY, count=240)
```
**3. 返回 `list[dataclass]`,不是 DataFrame**
@@ -55,34 +59,34 @@ pip install pytdxdata # 或 uv add pytdxdata
```python
import asyncio
from pytdxdata import TdxData
-from pytdxdata.models import Market, KlinePeriod, Adjust
+from pytdxdata.models import KlinePeriod, Adjust
async def main():
async with TdxData() as td:
# 日K线,240 根(count 超过单页大小会自动多连接并发分页)
- bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
+ bars = await td.get_bars(["sz000001"], KlinePeriod.DAY, count=240)
print(bars[-1].close, bars[-1].datetime)
# 前复权日线(复权自动走 MAC 通道)
- qfq = await td.get_kline(Market.SZ, "300308", KlinePeriod.DAY,
+ qfq = await td.get_bars(["sz300308"], KlinePeriod.DAY,
count=500, adjust=Adjust.QFQ)
- # 五档报价:入参是 (market, code) 元组列表,一次可传多只(>80 只自动切批)
- quotes = await td.get_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
- print(quotes[0].price, quotes[0].bid[0], quotes[0].ask[0])
+ # 跨市场报价:A股+港股+美股一次拿全
+ quotes = await td.get_quotes(["sz000001", "hk00700", "usAAPL"])
+ print(quotes[0].price, quotes[1].name, quotes[2].amount)
# 逐笔成交(MAC 通道,支持历史日期,含 trade_count 成交笔数)
- ticks = await td.get_transactions(Market.SZ, "000001", date=20260811)
- print(sum(r.trade_count for r in ticks)) # 当日总成交笔数
+ ticks = await td.get_ticks(["sz000001"], date=20260811)
+ print(sum(r.trade_count for r in ticks))
# 分时(MAC 通道,今日或历史)
- minute = await td.get_minute(Market.SH, "600000")
+ minutes = await td.get_minutes(["sz000001"])
# 批量 K 线:多股票自动并发,池子会分配到不同服务器
- batch = await td.get_kline_batch(
- [(Market.SH, "600000"), (Market.SZ, "000001")],
+ batch = await td.get_bars(
+ ["sz000001", "sh600000"],
KlinePeriod.DAY, count=240,
- ) # -> {"600000": [...], "000001": [...]}
+ ) # 平铺返回,每条带 .symbol 字段
asyncio.run(main())
```
@@ -121,38 +125,37 @@ asyncio.run(main())
**`ExMarket`** — 扩展市场(港股 / 美股 / 期货 / 期权,共 46 个成员,走独立 EX 通道)
-常用几个:`HK_MAIN_BOARD=31`、`US_STOCK=74`、`CFFEX_FUTURES=47`、`SH_STOCK_OPTION=8`、`SZ_STOCK_OPTION=9`。
-完整表见 。
+v0.6 起统一接口用**字符串前缀**指定扩展市场,一般不再需要 `ExMarket`:
```python
-from pytdxdata.models import ExMarket
-
-await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700) # 港股,5 位代码
-await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700) # 美股,ticker
-await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700) # 期货合约
+await td.get_bars("hk00700", KlinePeriod.DAY, count=700) # 港股(5 位代码)
+await td.get_bars("usAAPL", KlinePeriod.DAY, count=700) # 美股(ticker)
+await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约
```
+常用前缀:`hk` / `us` / `cffex` / `shf` / `dl` / `zz` / `gz`;完整表见 。
+
## 想做什么 → 用哪个方法
| 需求 | 方法 |
|---|---|
-| 日/周/月/分钟 K 线 | `get_kline(market, code, period, *, count, adjust)` |
-| 增量更新(从某天往后) | `get_kline_since(market, code, period, since, adjust)` |
-| 一次拉多只股票 K 线 | `get_kline_batch(stocks, period, *, count, adjust, concurrency)` |
-| 指数 K 线 | `get_index_kline(market, code, period, *, count)` |
-| K 线 + MACD/KDJ/RSI/BOLL | `get_stock_kline_with_indicators(market, code, indicators, ...)` |
-| 实时五档报价 | `get_quotes(stocks)` |
-| 逐笔成交 | `get_transactions(market, code, *, date)` |
-| 分时图 | `get_minute(market, code, *, date)` |
-| 全市场股票列表 | `get_security_list_all(market)`(缓存 1 天) |
-| 除权除息 / 财务快照 | `get_xdxr(...)` / `get_finance(...)` |
-| 板块列表 / 成分股 / 涨跌排行 | `get_board_list` / `get_board_members` / `get_board_ranking` |
-| 个股所属板块 | `get_belong_board(market, code)` |
+| 全市场标的清单(A股+港股+期货…) | `get_universe(market=None)` |
+| 日/周/月/分钟 K 线(任意市场) | `get_bars(symbols, period, *, count, adjust, start_date, end_date)` |
+| K 线 + MACD/KDJ/RSI/BOLL | `get_indicators(symbols, indicators, ...)` |
+| 实时五档报价(A股)/ 基础报价(港股/美股/期货) | `get_quotes(symbols, *, fields=None)` |
+| 逐笔成交(任意市场) | `get_ticks(symbols, *, date)` |
+| 分时图 / 缩略采样 | `get_minutes(symbols, *, date, sampling=True)` |
+| 全市场股票列表(缓存 1 天) | `get_universe("sz")` / `get_universe("sh")` |
+| 除权除息 / 财务快照 | `get_xdxr(symbols)` / `get_finance(symbols)` |
+| F10 公司资料 | `get_f10(symbol, section)` |
+| 板块列表 / 成分股 / 涨跌排行 | `get_boards` / `get_board_members` / `get_board_ranking` |
+| 个股所属板块 | `get_board_of(symbols)` |
| 集合竞价 / 异动 / 资金流 | `get_auction` / `get_unusual` / `get_capital_flow` |
+| 个股特征快照 | `get_snapshot(symbols)` |
| **板块成分文件**(离线快照) | `get_block_parsed("block_gn.dat")` |
| **行业分类**(通达信 + 申万) | `get_industry_map()` |
| **历史专业财报**(gpcw 全字段) | `get_financial_file_infos()` + `get_financial_records_parsed(fn)` |
-| 涨跌停价 | `get_price_limits(market, code, name, pre_close, listed_days)`(本地算,无网络) |
+| 涨跌停价 | `get_price_limits(symbol, name, pre_close, listed_days)`(本地算,无网络) |
| 全市场涨跌家数/成交额 | `get_market_stat()` |
## 通道与数据特性(影响你能拿到什么)
@@ -160,9 +163,9 @@ await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700)
库内部有**标准通道**和 **MAC 通道**两条链路,会**按命令自动选路**,你不用管。但有几件事必须知道:
- **数据有 15 分钟延时**(通达信公开服务器特性)。要实时数据请用券商行情。
-- **复权 K 线与 1 分钟 K 线走 MAC 通道**。`get_kline(..., adjust=Adjust.QFQ)` 自动切换。
+- **复权 K 线与 1 分钟 K 线走 MAC 通道**。`get_bars(..., adjust=Adjust.QFQ)` 自动切换。
- **`count` 很大时会自动多连接并发分页**,无需手动翻页。但标准通道 K 线 `count < 100` 部分服务器会返回空——内部已强制 `min_page=100` 规避。
-- **`get_quotes` 一次 >80 只自动切批**;而 MAC 的 `get_stock_quotes` 上限就是 80 只/次。
+- **`get_quotes` 一次 >80 只自动切批**;走 MAC 字段位通道(`fields=`)时上限为 80 只/次。
- **历史逐笔没有笔数字段**,只有当日逐笔的 `trade_count` 有效。
- 板块文件(`block_*.dat`)/ 行业(`tdxhy.cfg`)/ 财报(`gpcw*.zip`)是**服务器上的静态文件**,解析后是普通 dataclass,**落 JSON 后完全脱网可用**——适合做离线快照。
@@ -170,14 +173,16 @@ await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700)
| 坑 | 后果 | 正确做法 |
|---|---|---|
-| `market` 传 `"sh"` 字符串 | 直接报错或路由到错误市场 | 用 `Market.SH` 枚举 |
-| 以为 `KlinePeriod.DAY == 0` | 拿到的是 5 分钟线 | `DAY=4`,对照上面的表 |
+| 统一方法(`get_quotes`/`get_bars`…)传 `(Market.SH, "600000")` 元组或市场号 | v0.6 起直接报错 | 用字符串 `"sh600000"` |
+| 旧别名(`get_kline`/`get_transactions`…)传 `(market, code)` | 能跑,但发出 `DeprecationWarning` | 迁移到统一方法 + 字符串 |
| 忘了 `async with` / `start()` | 无连接池,运行时报错 | 一律 `async with TdxData() as td:` |
+| `KlinePeriod.DAY == 0` | 拿到的是 5 分钟线 | `DAY=4`,对照枚举表 |
| 等在返回值上找 `.to_dataframe()` | 不存在 | `pd.DataFrame([asdict(x) for x in bars])` |
| 把 `close` 当成分 | 数值差 100 倍 | 价格单位是**元**(float) |
-| `SH 000001` 当成平安银行 | 拿到的是上证指数 | **代码不唯一**:`(Market.SH, "000001")`=上证指数,`(Market.SZ, "000001")`=平安银行 |
+| `sh000001` 当成平安银行 | 拿到的是上证指数 | **代码不唯一**:`sh000001`=上证指数,`sz000001`=平安银行 |
| 用 `get_block_info` 又自己拆二进制 | 白写解析器 | 用 `get_block_parsed`,已经解析好了 |
-| 循环里逐个 `await get_kline` | 慢 | 用 `get_kline_batch` 让它并发 |
+| 循环里逐个 `await get_bars` | 慢 | 用列表传多个标的,自动并发 |
+| 港股/美股五档 bid/ask | 没有(协议不支持) | `fields` 字段位通道有 name 但无五档 |
| 依赖实时性做信号 | 数据是 15 分钟前的 | 换券商实时源 |
## 深入参考
diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md
index f10e2c9..c770d5b 100644
--- a/docs/API_REFERENCE.md
+++ b/docs/API_REFERENCE.md
@@ -1,6 +1,6 @@
# pytdxdata 对外接口清单
-> 以 `src/pytdxdata` 源码为准整理(v0.5.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
+> 以 `src/pytdxdata` 源码为准整理(v0.6.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
>
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
@@ -39,7 +39,50 @@ from pytdxdata import (
| `async close()` | 关闭全部池与缓存 |
| `async with TdxData() as td:` | 上下文管理器,自动 start/close |
-### 2.1 K线(共 6 个)
+### 2.1 统一接口(v0.6+ 推荐){#unified}
+
+以下方法在 v0.6 新增,标的一律用字符串(`sz000001` / `hk00700` / `usAAPL` / `cffex:IFL0`)。
+
+#### 标的清单
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `get_universe(market=None)` | `list[SecurityInfo]` | 跨市场标的清单(A 股+港股+美股+期货/期权) |
+
+#### 报价
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `get_quotes(symbols, *, fields=None)` | `list[SecurityQuote]` | 跨市场混合报价(A 股标准五档;给了 fields 走 MAC/EX 字段位有 name) |
+| `get_snapshot(symbols)` | `list[SymbolSnapshot]` | 个股特征快照(A 股) |
+| `get_auction(symbols)` | `list[AuctionItem]` | 集合竞价(A 股) |
+| `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向(A 股) |
+
+#### K线
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `get_bars(symbols, period=DAY, *, start=0, count=800, adjust=None, start_date=None, end_date=None, concurrency=6)` | `list[SecurityBar]` | 跨市场 K 线(自动判指数、复权走 MAC、并发分页、日期区间二分) |
+| `get_indicators(symbols, indicators, *, period=DAY, count=30, adjust=None, params=None)` | `list[IndicatorSet]` | K 线+技术指标(MACD/KDJ/RSI/BOLL/MA/EMA) |
+
+#### 逐笔与分时
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `get_ticks(symbols, *, date=None, start=0, count=None, concurrency=6)` | `list[TransactionRecord]` | 跨市场逐笔成交 |
+| `get_minutes(symbols, *, date=None, sampling=False, concurrency=6)` | `list[MinuteBar]` | 跨市场分时(sampling=True 取缩略采样) |
+
+#### 公司信息/文件/板块
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `get_f10(symbol, section=None, *, offset=0, length=65535)` | `list \| str` | F10 公司资料 |
+| `get_file(name)` | `bytes` | 服务器文件原始字节(自动选通道) |
+| `get_boards(kind="all", *, count=10000)` | `list[BoardInfo]` | 板块列表 |
+| `get_board_members(board, *, fields=None, count=100000)` | `list[SecurityQuote]` | 板块成分股报价(归一模型) |
+| `get_board_of(symbols)` | `list[BelongBoard]` | 个股所属板块 |
+
+### 2.2 K线(旧接口,共 6 个) {#legacy-kline}
| 方法 | 返回 | 说明 |
|------|------|------|
@@ -50,16 +93,16 @@ from pytdxdata import (
| `get_stock_kline_with_indicators(market, code, indicators, *, period=DAY, count=30, adjust=None, params=None)` | `dict` | K线+技术指标(MACD/KDJ/RSI/BOLL/MA/EMA) |
| `get_kline_offset(offset=0, count=1)` | `tuple[int, int]` | K线偏移信息(MAC) |
-### 2.2 报价(共 4 个)
+### 2.3 报价(旧接口,共 4 个) {#legacy-quote}
| 方法 | 返回 | 说明 |
|------|------|------|
-| `get_quotes(stocks)` | `list[SecurityQuote]` | 五档报价;>80 只自动切批;TTL 5s |
+| `get_quotes(symbols, *, fields=None)` | `list[SecurityQuote]` | 五档报价;>80 只自动切批;TTL 5s |
| `get_stock_quotes(stocks, bits=None)` | `list[MemberQuote]` | MAC 自定义字段报价(≤80只/次) |
| `get_stock_quotes_list(category, *, start=0, count=80, sort_type=0)` | `list[MemberQuote]` | 市场分类报价(0沪A/2深A/6全A/8科创/14创业) |
| `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数/总额/市值/涨跌停数) |
-### 2.3 逐笔成交 / 分时(共 4 个)
+### 2.4 逐笔成交 / 分时(旧接口,共 4 个) {#legacy-tick}
| 方法 | 返回 | 说明 |
|------|------|------|
@@ -68,7 +111,7 @@ from pytdxdata import (
| `get_minute_batch(stocks, *, date=None, concurrency=6)` | `dict[str, list[MinuteBar]]` | 批量分时 |
| `get_chart_sampling(market, code)` | `list[float]` | 分时缩略采样(A股,MAC 0x254D) |
-### 2.4 证券列表(共 3 个)
+### 2.5 证券列表(旧接口,共 3 个) {#legacy-list}
| 方法 | 返回 | 说明 |
|------|------|------|
@@ -76,13 +119,13 @@ from pytdxdata import (
| `get_security_list(market, *, start=0, count=None)` | `list[SecurityInfo]` | count=None=全部(先查总数防死循环) |
| `get_security_list_all(market)` | `list[SecurityInfo]` | 全市场列表(高并发一次拉完,缓存 1 天) |
-### 2.5 除权 / 财务 / F10 / 文件(共 15 个)
+### 2.6 除权 / 财务 / 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=9999)` | `tuple[float\|None, float\|None]` | 涨跌停价(本地计算) |
+| `get_xdxr(symbols)` | `list[XdxrRecord]` | 除权除息历史(标准) |
+| `get_finance(symbols)` | `list[FinanceRecord]` | 财务快照(标准;无数据的标的跳过) |
+| `get_price_limits(symbol, name=None, pre_close=None, listed_days=9999)` | `tuple[float\|None, float\|None]` | 涨跌停价(本地计算) |
| `get_company_info_category(market, code)` | `list` | F10 目录(标准) |
| `get_company_info_content(market, code, filename, offset=0, length=65535)` | `str` | F10 内容(分块) |
| `get_block_info(filename)` | `bytes` | 板块文件**原始字节**(先查元数据再分块下载) |
@@ -99,7 +142,7 @@ from pytdxdata import (
> 解析层独立于网络层:解析器位于 `pytdxdata.codec`(纯标准库 `struct`/`zipfile`),可脱网单测;
> 原 `get_*` 返回 `bytes`/`list[str]` 的方法保持**向后兼容**,解析版为**新增**方法。
-### 2.6 板块(共 6 个)
+### 2.7 板块(旧接口,共 6 个) {#legacy-board}
| 方法 | 返回 | 说明 |
|------|------|------|
@@ -110,17 +153,17 @@ from pytdxdata import (
| `get_board_ranking(board_type=1, top_n=20)` | `list[dict]` | 板块涨跌幅排行 |
| `get_board_change_ranking(board_type=1, days=20, top_n=20)` | `list[dict]` | 板块 N 日涨跌幅排行(板块指数K线) |
-### 2.7 MAC 扩展:竞价 / 异动 / 快照 / 资金流 / 服务器(共 5 个)
+### 2.8 MAC 扩展:竞价 / 异动 / 快照 / 资金流 / 服务器(旧接口,共 5 个) {#legacy-mac}
| 方法 | 返回 | 说明 |
|------|------|------|
-| `get_auction(market, code)` | `list[AuctionItem]` | 集合竞价 |
-| `get_unusual(market, start=0, count=600)` | `list[UnusualItem]` | 市场异动 |
+| `get_auction(symbols)` | `list[AuctionItem]` | 集合竞价 |
+| `get_unusual(market="all", *, start=0, count=600)` | `list[UnusualItem]` | 市场异动 |
| `get_symbol_info(market, code)` | `SymbolSnapshot` | 个股特征快照 |
-| `get_capital_flow(market, code)` | `CapitalFlow` | 个股资金流向 |
+| `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向 |
| `get_server_info()` | `ServerInfo` | 服务器交易时段信息 |
-### 2.8 EX 扩展市场(港股/美股/期货/期权,共 8 个)
+### 2.9 EX 扩展市场(旧接口,港股/美股/期货/期权,共 8 个) {#legacy-ex}
| 方法 | 返回 | 说明 |
|------|------|------|
@@ -133,7 +176,8 @@ from pytdxdata import (
| `get_goods_transaction(market, code, *, ymd=0, start=0, count=1800)` | `list[dict]` | 扩展市场逐笔(港股 0x23FC/0x2406) |
| `get_goods_transaction_all(market, code, ymd=0)` | `list[dict]` | 港股全量逐笔(自动翻页,≤50页/9万条) |
-**合计:`TdxData` 公开异步方法 51 个**(另有 `_execute_standard/_execute_mac/_execute_ex` 等内部执行方法)。
+**合计:`TdxData` 公开异步方法 63 个** = 28 个统一接口 + 33 个 deprecated 别名 + `start`/`close`
+(另有 `_execute_standard` / `_execute_mac` / `_execute_ex` 等内部执行方法)。
## 三、数据模型(`pytdxdata.models`)
diff --git a/docs/ai.md b/docs/ai.md
index 37f412c..a62d570 100644
--- a/docs/ai.md
+++ b/docs/ai.md
@@ -6,7 +6,7 @@ pytdxdata 的枚举取值**完全没有直觉**(`KlinePeriod.DAY` 是 `4` 不
| 文件 | 面向 | 内容 |
|---|---|---|
| [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) | AI 爬虫 / 问答型模型 | 心智模型、能力分组、关键陷阱,自动随站点发布 |
-| [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) | AI **编程**助手 | 必守约定、枚举取值表、可运行模板、任务→方法决策表、9 条陷阱 |
+| [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) | AI **编程**助手 | 必守约定、枚举取值表、可运行模板、任务→方法决策表、11 条陷阱 |
`llms.txt` 解决「这个库能干什么」,`SKILL.md` 解决「代码该怎么写对」。
@@ -25,12 +25,12 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md \
## 里面有什么
-- **三条必守约定** —— 唯一入口是 `TdxData` 且必须 `async with`;`market` 是整数枚举而不是字符串;
- 返回值是 `list[dataclass]` 而不是 DataFrame
+- **三条必守约定** —— 唯一入口是 `TdxData` 且必须 `async with`;标的是字符串(如 `sh600000`)
+ 而不是 `(market, code)` 元组;返回值是 `list[dataclass]` 而不是 DataFrame
- **枚举取值表** —— `Market` / `KlinePeriod` / `Adjust` / `ExMarket` 的准确取值
- **可运行模板** —— K 线、复权、报价、逐笔、分时、批量,全部是能直接跑的代码
-- **「想做什么 → 用哪个方法」决策表** —— 21 个常见需求的直接映射
-- **9 条真实陷阱** —— 每条都注明后果和正确做法(如 `SH 000001` 是上证指数、`SZ 000001` 才是平安银行)
+- **「想做什么 → 用哪个方法」决策表** —— 18 个常见需求的直接映射
+- **11 条真实陷阱** —— 每条都注明后果和正确做法(如 `sh000001` 是上证指数、`sz000001` 才是平安银行)
## 为什么值得让 AI 读
@@ -38,10 +38,11 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md \
这些都不是「读一眼签名就能猜到」的信息。不加载技能,AI 通常会写出:
```python
-# ❌ 三种典型错误
-await td.get_kline("sh", "600000", 0, count=240) # market 传字符串;0 是 5 分钟线不是日线
-td.get_kline(1, "600000", KlinePeriod.DAY) # 忘了 await,且没在 async with 内
-df = bars.to_dataframe() # 返回值是 list[dataclass],没有这个方法
+# ❌ 几种典型错误
+await td.get_bars("sh600000", 4, count=240) # 4 是数字字面量;应用 KlinePeriod.DAY
+await td.get_bars((Market.SH, "600000")) # 统一接口只接受字符串标的,不接受元组
+td.get_bars("sh600000") # 忘了 await,且没在 async with 内
+df = bars.to_dataframe() # 返回值是 list[dataclass],没有这个方法
```
装载技能后这类错误基本消失。
diff --git a/docs/api/codec.md b/docs/api/codec.md
index cef2713..77da9f4 100644
--- a/docs/api/codec.md
+++ b/docs/api/codec.md
@@ -26,7 +26,7 @@ blocks = parse_block_dat(open("block_gn.dat", "rb").read(), "block_gn.dat")
如果不想自己管下载,直接用封装好的方法(内部就是调这些解析器):
`get_block_parsed()` / `get_industry_map()` / `get_financial_file_infos()` / `get_financial_records_parsed()`
- — 见 [接口总览 → 除权 / 财务 / F10 / 文件](index.md#file-methods)。
+ — 见 [完整接口清单 → 除权 / 财务 / F10 / 文件](../API_REFERENCE.md#file-methods)。
## 关键细节
diff --git a/docs/api/enums.md b/docs/api/enums.md
index c2596e0..a257ad4 100644
--- a/docs/api/enums.md
+++ b/docs/api/enums.md
@@ -85,14 +85,18 @@ KlinePeriod.DAY.is_minute # False
| `ExMarket.US_STOCK` | `74` | **美股(最常用)** |
```python
-from pytdxdata.models import ExMarket, KlinePeriod
+from pytdxdata.models import KlinePeriod
-await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700) # 腾讯
-await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700) # 苹果
-await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700) # 股指期货
-await td.get_kline(ExMarket.SH_STOCK_OPTION, "10010971", KlinePeriod.DAY, count=700)
+# 统一接口用字符串前缀指定扩展市场(推荐):
+await td.get_bars("hk00700", KlinePeriod.DAY, count=700) # 腾讯
+await td.get_bars("usAAPL", KlinePeriod.DAY, count=700) # 苹果
+await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 股指期货
+await td.get_bars("sh_stock_option:10010971", KlinePeriod.DAY, count=700) # 沪股票期权
```
+> 上表的 `ExMarket` 枚举值用于查阅与内部协议;统一接口不再直接传枚举,改用字符串前缀
+> (短前缀 `hk` / `us` / `cffex` …,无短别名的成员用枚举名小写 + 冒号,如 `sh_stock_option:10010971`)。
+
### 完整成员列表
以下由 `mkdocstrings` 从源码实时渲染,**以源码为准**:
diff --git a/docs/api/index.md b/docs/api/index.md
index d31a54d..b7bb2be 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -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)。
## 下一步
diff --git a/docs/api/models.md b/docs/api/models.md
index 2c77c69..7da0fec 100644
--- a/docs/api/models.md
+++ b/docs/api/models.md
@@ -28,25 +28,25 @@ 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` |
+| `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_board_list` |
-| `MemberQuote` | 成分股报价(自定义字段) | `get_board_members` / `get_stock_quotes` |
-| `BelongBoard` | 个股所属板块 | `get_belong_board` |
+| `BoardInfo` | 板块列表条目(含领涨股) | `get_boards` |
+| `MemberQuote` | 成分股报价(MAC 原始字段) | 旧 `get_stock_quotes` / `get_stock_quotes_list` |
+| `BelongBoard` | 个股所属板块 | `get_board_of` |
| `AuctionItem` | 集合竞价撮合点 | `get_auction` |
| `UnusualItem` | 一笔市场异动 | `get_unusual` |
-| `SymbolSnapshot` | 个股特征快照 | `get_symbol_info` |
-| `GoodsItem` | 扩展市场商品 | `get_goods_list` |
+| `SymbolSnapshot` | 个股特征快照 | `get_snapshot` |
+| `GoodsItem` | 扩展市场商品 | 旧 `get_goods_list` |
| `ServerInfo` | 服务器交易时段 | `get_server_info` |
| `CapitalFlow` | 个股资金流向 | `get_capital_flow` |
| `MarketStat` | 全市场统计 | `get_market_stat` |
diff --git a/docs/api/tdxdata.md b/docs/api/tdxdata.md
index b36ccfc..89aedce 100644
--- a/docs/api/tdxdata.md
+++ b/docs/api/tdxdata.md
@@ -8,11 +8,11 @@
```python
import asyncio
from pytdxdata import TdxData
-from pytdxdata.models import KlinePeriod, Market
+from pytdxdata.models import KlinePeriod
async def main():
async with TdxData() as td:
- bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
+ bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
print(bars[-1])
asyncio.run(main())
diff --git a/docs/contributing.md b/docs/contributing.md
index 63c94f4..7184a9a 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -94,8 +94,8 @@ git push origin feat/xxx
3. 提交并 push 到 `main`
4. 打标签并推送:
```bash
- git tag v0.5.0
- git push origin v0.5.0
+ git tag v0.6.0
+ git push origin v0.6.0
```
推 tag 会自动触发 GitHub Actions:**test → build(含版本号一致性校验)→ OIDC 免密钥发布到 PyPI**。
@@ -105,12 +105,12 @@ git push origin feat/xxx
同名 tag **不能直接重推**(push 无变化,workflow 不会触发)。先删再推:
```bash
- git push --delete origin v0.5.0
- git tag -d v0.5.0 && git tag v0.5.0
- git push origin v0.5.0
+ git push --delete origin v0.6.0
+ git tag -d v0.6.0 && git tag v0.6.0
+ git push origin v0.6.0
```
- 或直接手动触发:`gh workflow run release.yml --ref v0.5.0`
+ 或直接手动触发:`gh workflow run release.yml --ref v0.6.0`
文档站由 `.github/workflows/docs.yml` 在 push `main` 时自动部署到
。
diff --git a/docs/cookbook.md b/docs/cookbook.md
index f5a14df..570b584 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -6,7 +6,7 @@
import asyncio
from pathlib import Path
from pytdxdata import TdxData
-from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market
+from pytdxdata.models import Adjust, KlinePeriod
```
## 全市场日线批量落库
@@ -16,23 +16,22 @@ from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market
```python
async def dump_all_daily():
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
- codes = await td.get_security_list_all(Market.SZ) # 缓存 1 天
- symbols = [(Market.SZ, s.code) for s in codes]
+ infos = await td.get_universe("sz") # 缓存 1 天
+ symbols = [i.symbol for i in infos] # ["sz000001", ...]
- bars = await td.get_kline_batch(
+ bars = await td.get_bars(
symbols,
KlinePeriod.DAY,
count=800,
adjust=Adjust.QFQ,
concurrency=12,
)
- print(f"{len(bars)} / {len(symbols)} 只拿到数据")
+ got = {b.symbol for b in bars}
+ print(f"{len(got)} / {len(symbols)} 只拿到数据")
- for code, rows in bars.items():
- if not rows:
- continue
- # 落库 / 写 parquet 都行,这里只演示
- print(code, len(rows), rows[-1].datetime, rows[-1].close)
+ # bars 是扁平 list[SecurityBar](按标的/时间排序),落库 / 写 parquet 都行
+ if bars:
+ print(bars[-1].symbol, bars[-1].datetime, bars[-1].close)
```
!!! tip "分页与并发的取舍"
@@ -41,12 +40,12 @@ async def dump_all_daily():
## 分钟线增量更新
-只拉「上次之后」的部分,用 `get_kline_since` 省掉全量重拉。
+只拉「上次之后」的部分,用 `get_bars(start_date=...)` 省掉全量重拉。
```python
-async def update_minute(code: str, last_dt):
+async def update_minute(symbol: str, last_dt):
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
- rows = await td.get_kline_since(Market.SZ, code, KlinePeriod.MIN_1, since=last_dt)
+ rows = await td.get_bars(symbol, KlinePeriod.MIN_1, start_date=last_dt)
return [r for r in rows if r.datetime > last_dt]
```
@@ -75,7 +74,7 @@ async def poll_quotes(symbols, interval=5.0):
async def sector_rotation():
async with TdxData() as td:
# 近 5 日概念板块涨幅排行
- top = await td.get_board_change_ranking(board_type=2, days=5, top_n=10)
+ top = await td.get_board_change_ranking(kind="concept", days=5, top_n=10)
for row in top:
print(row)
@@ -92,18 +91,18 @@ async def sector_rotation():
## 个股所属板块(反向查询)
```python
-async def belong(code: str):
+async def belong(symbol: str):
async with TdxData() as td:
- for b in await td.get_belong_board(Market.SH, code):
+ for b in await td.get_board_of(symbol):
print(b)
```
## 逐笔复盘
```python
-async def review_transactions(code: str, ymd: int):
+async def review_transactions(symbol: str, ymd: int):
async with TdxData() as td:
- rows = await td.get_transactions(Market.SZ, code, date=ymd, count=2000)
+ rows = await td.get_ticks(symbol, date=ymd, count=2000)
total = sum(r.trade_count or 0 for r in rows)
buy = sum(r.vol for r in rows if r.bs_flag == 0) # 主动买
sell = sum(r.vol for r in rows if r.bs_flag == 1) # 主动卖
@@ -113,12 +112,10 @@ async def review_transactions(code: str, ymd: int):
## 财务因子快照
```python
-async def finance_snapshot(codes):
+async def finance_snapshot(symbols):
async with TdxData() as td:
- for mkt, code in codes:
- fin = await td.get_finance(mkt, code) # 标准通道,最新快照
- if fin:
- print(code, fin)
+ for fin in await td.get_finance(symbols): # 标准通道,最新快照
+ print(fin.symbol, fin)
```
历史专业财报(`gpcw*.zip`,含多报告期)走文件接口:
@@ -173,14 +170,14 @@ async def snapshot_blocks():
```python
async def ex_markets():
async with TdxData() as td:
- hk = await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)
- us = await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)
- fut = await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700)
- opt = await td.get_kline(ExMarket.SH_STOCK_OPTION, "10010971", KlinePeriod.DAY, count=700)
+ hk = await td.get_bars("hk00700", KlinePeriod.DAY, count=700)
+ us = await td.get_bars("usAAPL", KlinePeriod.DAY, count=700)
+ fut = await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700)
+ opt = await td.get_bars("sh_stock_option:10010971", KlinePeriod.DAY, count=700)
print(len(hk), len(us), len(fut), len(opt))
# 港股全量逐笔(自动翻页,≤50 页 / 9 万条)
- ticks = await td.get_goods_transaction_all(ExMarket.HK_MAIN_BOARD, "00700")
+ ticks = await td.get_ticks("hk00700", count=None)
print(len(ticks))
```
@@ -191,9 +188,9 @@ async def ex_markets():
```python
import pandas as pd
-async def to_dataframe(code: str):
+async def to_dataframe(symbol: str):
async with TdxData() as td:
- bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=800)
+ bars = await td.get_bars(symbol, KlinePeriod.DAY, count=800)
df = pd.DataFrame([{
"dt": b.datetime, "open": b.open, "high": b.high,
"low": b.low, "close": b.close, "vol": b.vol, "amount": b.amount,
@@ -219,10 +216,10 @@ async def lifespan(app: FastAPI):
app = FastAPI(lifespan=lifespan)
-@app.get("/kline/{code}")
-async def kline(code: str, request: Request):
+@app.get("/kline/{symbol}")
+async def kline(symbol: str, request: Request):
td = request.app.state.td
- bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=30)
+ bars = await td.get_bars(symbol, KlinePeriod.DAY, count=30)
return [{"dt": str(b.datetime), "close": b.close} for b in bars]
```
diff --git a/docs/index.md b/docs/index.md
index dd53f71..7fb6429 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,7 +20,7 @@ from pytdxdata.models import KlinePeriod
async def main():
async with TdxData() as td: # 自动探测服务器 + 建池 + 建缓存
- bars = await td.get_kline(1, "600000", KlinePeriod.DAY, count=2400)
+ bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=2400)
print(bars[-1].datetime, bars[-1].close)
asyncio.run(main())
@@ -35,7 +35,7 @@ asyncio.run(main())
| ⚡ **并发分页** | 把大请求拆成显式 `start` 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 |
| 🔀 **双通道整合** | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 |
| 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*.zip` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制 |
-| 🚀 **批量下载** | `get_kline_batch` / `get_minute_batch`,多股票自动并发,连接池分配到不同服务器 |
+| 🚀 **批量下载** | `get_bars` / `get_minutes` 传标的列表即多股票并发,连接池自动分配到不同服务器 |
| 📦 **零重型依赖** | 返回 `list[dataclass]`,pandas / polars 由调用方按需转换 |
## 从这里开始
@@ -70,7 +70,7 @@ asyncio.run(main())
---
- 51 个数据方法(另有 `start` / `close`),从 docstring 实时生成,不会过期。
+ 28 个统一方法(+ 33 个 deprecated 别名),从 docstring 实时生成,不会过期。
[:octicons-arrow-right-24: API 参考](api/index.md)
@@ -138,6 +138,7 @@ asyncio.run(main())
- [AI 助手接入](ai.md)
- [常见问题](faq.md)
- [更新日志](changelog.md)
+ - [接口重构审查](refactor-audit.md)
- [参与贡献](contributing.md)
diff --git a/docs/internals/architecture.md b/docs/internals/architecture.md
index 5ec232a..3451415 100644
--- a/docs/internals/architecture.md
+++ b/docs/internals/architecture.md
@@ -6,7 +6,7 @@
```mermaid
flowchart TD
- A["api.py — TdxData
唯一对外入口,51 个公开方法"] --> B["router.py
按命令选通道"]
+ A["api.py — TdxData
唯一对外入口,28 个统一方法 + 33 个废弃别名"] --> B["router.py
按命令选通道"]
B --> C["pool/ — 动态连接池
标准池 / MAC 池 / EX 池"]
B --> D["scheduler/ — 并发分页调度
Paginator"]
C --> E["protocol/ — 协议层
帧 / 变长整数 / 价格 / 日期 / 命令"]
@@ -21,6 +21,7 @@ flowchart TD
```
src/pytdxdata/
├── api.py # 统一接口 TdxData(对外唯一入口)
+├── symbols.py # 标的解析:字符串 → Symbol(parse_symbol / format_symbol / market_targets)
├── router.py # 标准 / MAC / EX 通道选路
├── config.py # 服务器清单加载(servers.json)
├── indicator.py # 技术指标(纯函数,无依赖)
@@ -55,7 +56,7 @@ src/pytdxdata/
└── financial.py # gpcw.txt / gpcw*.zip
```
-## 一次 `get_kline` 的完整路径
+## 一次 `get_bars` 的完整路径
```mermaid
sequenceDiagram
@@ -66,7 +67,7 @@ sequenceDiagram
participant P as pool/
participant S as scheduler/
- U->>A: get_kline(SH, 600000, DAY, count=2400)
+ U->>A: get_bars("sh600000", DAY, count=2400)
A->>A: 规范化缓存键
A->>C: 查缓存
alt 命中
@@ -99,7 +100,7 @@ sequenceDiagram
|---|---|
| **零运行时依赖** | 用 `socket` / `zlib` / `struct` / `sqlite3` / `asyncio` 全部搞定,避免依赖地狱和版本冲突 |
| **返回 `list[dataclass]`** | 不让调用方被 pandas 绑架;需要 DataFrame 自己转一行 |
-| **API 向后兼容** | 新增能力用新方法名(`get_block_parsed` 而不是改 `get_block_info` 的返回类型),老代码永不失效 |
+| **API 向后兼容** | 一个数据类型收敛为一个跨市场统一方法;旧方法名保留为 deprecated 别名(1.0 移除),老代码在兼容窗口内仍可用 |
## 下一步
diff --git a/docs/internals/cache-pool.md b/docs/internals/cache-pool.md
index 717f264..4db88fd 100644
--- a/docs/internals/cache-pool.md
+++ b/docs/internals/cache-pool.md
@@ -44,7 +44,7 @@
# 100 个协程同时请求同一只股票的同一段 K 线
# → 只发 1 次网络请求
results = await asyncio.gather(*[
- td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=800)
+ td.get_bars("sh600000", KlinePeriod.DAY, count=800)
for _ in range(100)
])
```
diff --git a/docs/internals/routing.md b/docs/internals/routing.md
index d169e34..c1e223a 100644
--- a/docs/internals/routing.md
+++ b/docs/internals/routing.md
@@ -20,7 +20,7 @@
| 港股 / 美股 / 期货 / 期权 | **EX**(7727) | 完全不同的协议栈 |
!!! note "只请求,不改语义"
- 路由是**内部实现细节**。同一个 `get_kline()` 调用,传不传 `adjust` 会走不同通道,
+ 路由是**内部实现细节**。同一个 `get_bars()` 调用,传不传 `adjust` 会走不同通道,
但返回类型和字段完全一致——你不需要写 `if adjust:` 分支。
## 三组服务器 {#server-groups}
@@ -66,13 +66,11 @@ python -m pytdxdata.server_probe
- 美股期权 / 港股期权**协议内无数据**
```python
-from pytdxdata.models import ExMarket, KlinePeriod
-
-await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)
-await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)
+await td.get_bars("hk00700", KlinePeriod.DAY, count=700)
+await td.get_bars("usAAPL", KlinePeriod.DAY, count=700)
```
-`ExMarket` 的完整成员见 [枚举速查](../api/enums.md#exmarket)。
+扩展市场用字符串前缀(`hk` / `us` / `cffex` …)指定;`ExMarket` 的完整成员见 [枚举速查](../api/enums.md#exmarket)。
## 下一步
diff --git a/docs/llms.txt b/docs/llms.txt
index 02dac45..33a14a6 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -14,11 +14,11 @@ pip install pytdxdata # 或 uv add pytdxdata;要求 Python >= 3.11
```python
import asyncio
from pytdxdata import TdxData
-from pytdxdata.models import KlinePeriod, Market
+from pytdxdata.models import KlinePeriod
async def main():
async with TdxData() as td: # 自动探测服务器、建连接池、初始化缓存
- bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=2400)
+ bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=2400)
print(bars[-1].datetime, bars[-1].close)
asyncio.run(main())
@@ -26,10 +26,11 @@ asyncio.run(main())
## 心智模型(AI 必读)
-1. **入口只有一个类**:`TdxData`。所有数据获取都是它的公开异步方法(51 个数据方法,
- 另有 `start()` / `close()` 生命周期方法),必须在 `async with` 内使用。
-2. **标的需要「市场 + 代码」两个参数**。同一个 6 位代码在不同市场含义不同:
- `(SH, "000001")` 是上证指数,`(SZ, "000001")` 是平安银行。
+1. **入口只有一个类**:`TdxData`。所有数据获取都是它的公开异步方法(v0.6 起为 **28 个统一方法**,
+ 另有 33 个 deprecated 别名与 `start()` / `close()` 生命周期方法),必须在 `async with` 内使用。
+2. **标的用字符串**,形如 `sz000001` / `sh600000` / `hk00700` / `usAAPL` / `cffex:IFL0`。
+ 同一个 6 位代码在不同市场含义不同:`sh000001` 是上证指数,`sz000001` 是平安银行;
+ 裸 6 位数字(如 `000001`)视为沪市指数。统一接口不再接受 `(market, code)` 元组。
3. **枚举取值没有直觉,必须用枚举成员,不要写数字字面量**:
- `Market`: SZ=0 / SH=1 / BJ=2
- `KlinePeriod`: MIN_5=0, MIN_15=1, MIN_30=2, MIN_60=3, **DAY=4**, WEEK=5, MONTH=6, **MIN_1=7**, MIN_3=8, YEAR=9, SEASON=10, YEAR_ALT=11
@@ -39,19 +40,24 @@ asyncio.run(main())
5. **实例要复用**:连接池与缓存都挂在 `TdxData` 实例上。长驻进程(Web 服务)应只创建一个实例,
不要每请求新建,否则等于每请求重建连接池且缓存全部失效。
-## 主要能力分组
+## 主要能力分组(统一接口)
-- **K 线**:`get_kline`(主接口,自动并发分页、支持复权与日期区间)、`get_kline_batch`(多股票并发)、
- `get_kline_since`(增量)、`get_index_kline`、`get_stock_kline_with_indicators`
-- **报价**:`get_quotes`(五档,>80 只自动切批)、`get_stock_quotes_list`、`get_market_stat`
-- **逐笔 / 分时**:`get_transactions`(含 `trade_count` 成交笔数,支持历史日期)、`get_minute`、`get_minute_batch`
-- **证券列表**:`get_security_count`、`get_security_list`、`get_security_list_all`
+标的一律用字符串;以下均为 v0.6 统一接口,跨市场自动选路。
+
+- **标的清单**:`get_universe`(A股 + 港股 + 美股 + 期货/期权)
+- **K 线**:`get_bars`(自动并发分页、支持复权与日期区间、多标的并发)
+- **技术指标**:`get_indicators`(K线 + MACD/KDJ/RSI/BOLL/MA/EMA)
+- **报价**:`get_quotes`(五档,>80 只自动切批)、`get_snapshot`(个股特征)、`get_market_stat`
+- **逐笔 / 分时**:`get_ticks`(含 `trade_count`,支持历史日期)、`get_minutes`(`sampling=True` 取缩略采样)
- **财务 / 除权**:`get_finance`(最新快照)、`get_xdxr`、`get_price_limits`(本地计算涨跌停)
-- **板块**:`get_board_list`、`get_board_members`、`get_board_ranking`、`get_board_change_ranking`、`get_belong_board`
-- **服务器文件(下载 + 解析一步到位)**:`get_block_parsed`(板块成分)、`get_industry_map`(通达信+申万行业)、
- `get_financial_file_infos`、`get_financial_records_parsed`(历史专业财报)
-- **扩展市场**:`get_goods_list`、`get_goods_quotes`、`get_goods_transaction_all` 等,配合 `ExMarket` 使用
-- **批量**:`get_kline_batch` / `get_minute_batch`,多股票并发且连接池会分配到不同服务器
+- **F10**:`get_f10`(公司资料目录 + 正文)
+- **板块**:`get_boards`、`get_board_members`、`get_board_of`、`get_board_summary`、
+ `get_board_ranking`、`get_board_change_ranking`
+- **服务器文件(下载 + 解析一步到位)**:`get_file`(原始字节)、`get_block_parsed`(板块成分)、
+ `get_industry_map`(通达信+申万行业)、`get_financial_file_infos`、`get_financial_records_parsed`(历史专业财报)
+
+> 旧的分通道/市场方法(`get_kline` / `get_transactions` / `get_goods_*` 等共 33 个)保留为
+> deprecated 别名,1.0 移除;完整对照见[接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/)与 CHANGELOG。
## CLI
@@ -102,6 +108,7 @@ tdx financial gpcw20260331.zip --limit 5
- [SKILL.md](https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md):面向 AI **编程**助手的技能文件(必守约定 / 枚举取值表 / 决策表 / 陷阱清单),比本文件更适合指导写代码
- [完整接口清单](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/):手工维护的全量清单,含参数默认值
+- [接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/):统一接口 / 废弃别名全清单 + 数据一致性与遗漏对账
- [更新日志](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md)
- [GitHub 仓库](https://github.com/openbot-coder/pytdxdata)
- [PyPI](https://pypi.org/project/pytdxdata/)
diff --git a/docs/refactor-audit.md b/docs/refactor-audit.md
new file mode 100644
index 0000000..813c057
--- /dev/null
+++ b/docs/refactor-audit.md
@@ -0,0 +1,148 @@
+# 接口重构审查报告
+
+> 范围:v0.6 统一接口重构(`TdxData` 对外方法 51 → 63)的**数据一致性**与**遗漏审查**。
+> 结论基于对旧实现(`git show HEAD:src/pytdxdata/api.py`)与新实现的逐字段 / 逐方法对照。
+
+## 一、结论速览
+
+| 维度 | 结论 |
+|------|------|
+| 数据一致性(旧接口 vs 统一接口) | ✅ 55 条断言全部通过,无字段差异 |
+| 方法丢失 | ✅ 无。旧 53 个公开方法 100% 保留 |
+| 文档覆盖 | ✅ `scripts/check_docs.py` 三条硬约束通过 |
+| 标的写法 | ✅ 统一接口一律只接受字符串,已无元组软兼容 |
+| 公开方法计数 | `28 统一 + 33 别名 + start/close = 63` |
+
+---
+
+## 二、数据一致性(旧接口 vs 新统一接口)
+
+逐字段对照 24+ 组、**55 条断言全部通过**,覆盖:
+
+- K 线(各周期 / 复权 / 日期区间)
+- 实时报价(五档 bid/ask、买卖量、涨跌停价)
+- 逐笔成交(含 `trade_count`)
+- 分时
+- 除权除息
+- 财务快照
+- F10(目录 + 正文)
+- 服务器文件(板块 / 行业 / 财报)
+- 板块(列表 / 成员 / 归属 / 汇总 / 排行)
+
+唯一 1 条「失败」经核实为 **mock 假象**:`security_count` 的 mock 返回固定值 100,而
+`get_universe` 走真实分页逻辑,两者口径不同;**并非真实数据差异**,逐字段比较全部相等。
+
+---
+
+## 三、遗漏审查(方法级)
+
+对旧 / 新 `api.py` 的公开方法集合做 AST 级 diff:
+
+| 指标 | 数量 |
+|------|------|
+| 旧公开方法 | 53(51 数据 + `start` / `close`) |
+| 新公开方法 | 63(61 数据 + `start` / `close`) |
+| **旧有新无(丢失)** | **0** |
+| 新增 | 10(全部为统一入口) |
+
+**数值闭合**:
+
+- `28 统一 + 33 废弃别名 + start/close = 63`
+- `18 旧名升级 + 33 转别名 = 51 旧数据方法`
+- `51 旧 + 10 新入口 = 61 数据方法`
+
+---
+
+## 四、统一接口清单(28 个数据接口)
+
+标的写法:`"sz000001"` / `"hk00700"` / `"usAAPL"` / `"cffex:IFL0"`;裸 6 位数字 = 沪市指数。
+
+### 4.1 新入口(10,v0.6 新增)
+
+| 方法 | 签名 | 返回 | 吸收的旧接口 |
+|------|------|------|--------------|
+| `get_universe` | `(market=None)` | `list[SecurityInfo]` | get_security_count / get_security_list / get_security_list_all / get_goods_list / get_goods_count |
+| `get_bars` | `(symbols, period=DAY, *, start=0, count=800, adjust=None, start_date=None, end_date=None, concurrency=6)` | `list[SecurityBar]` | get_kline / get_kline_since / get_kline_batch / get_index_kline |
+| `get_indicators` | `(symbols, indicators, *, period=DAY, count=30, adjust=None, params=None)` | `list[IndicatorSet]` | get_stock_kline_with_indicators |
+| `get_ticks` | `(symbols, *, date=None, start=0, count=None, concurrency=6)` | `list[TransactionRecord]` | get_transactions / get_goods_transaction / get_goods_transaction_all |
+| `get_minutes` | `(symbols, *, date=None, sampling=False, concurrency=6)` | `list[MinuteBar]` | get_minute / get_minute_batch / get_chart_sampling / get_goods_chart_sampling / get_goods_tick_chart |
+| `get_snapshot` | `(symbols)` | `list[SymbolSnapshot]` | get_symbol_info |
+| `get_f10` | `(symbol, section=None, *, offset=0, length=65535)` | `list \| str` | get_company_info_category / get_company_info_content |
+| `get_file` | `(name)` | `bytes` | get_block_info / get_report_file / get_file_meta / download_file / get_financial_file_list / get_financial_records |
+| `get_boards` | `(kind="all", *, count=10000)` | `list[BoardInfo]` | get_board_list |
+| `get_board_of` | `(symbols)` | `list[BelongBoard]` | get_belong_board |
+
+### 4.2 旧名升级(18,同名泛化为统一接口)
+
+| 方法 | 签名 | 返回 |
+|------|------|------|
+| `get_quotes` | `(symbols, *, fields=None)` | `list[SecurityQuote]` |
+| `get_auction` | `(symbols)` | `list[AuctionItem]` |
+| `get_capital_flow` | `(symbols)` | `list[CapitalFlow]` |
+| `get_xdxr` | `(symbols)` | `list[XdxrRecord]` |
+| `get_finance` | `(symbols)` | `list[FinanceRecord]` |
+| `get_price_limits` | `(symbol, name=None, pre_close=None, listed_days=9999)` | `tuple[float\|None, float\|None]` |
+| `get_market_stat` | `()` | `MarketStat` |
+| `get_unusual` | `(market="all", *, start=0, count=600)` | `list[UnusualItem]` |
+| `get_server_info` | `()` | `ServerInfo` |
+| `get_kline_offset` | `(offset=0, count=1)` | `tuple[int, int]` |
+| `get_board_members` | `(board, count=100000, sort_type=0, *, fields=None)` | `list[SecurityQuote]` |
+| `get_board_summary` | `(board)` | `dict` |
+| `get_board_ranking` | `(kind="industry", *, top_n=20)` | `list[dict]` |
+| `get_board_change_ranking` | `(kind="industry", *, days=20, top_n=20)` | `list[dict]` |
+| `get_block_parsed` | `(filename)` | `list[TdxBlock]` |
+| `get_industry_map` | `()` | `dict[str, IndustryInfo]` |
+| `get_financial_file_infos` | `()` | `list[FinancialFileInfo]` |
+| `get_financial_records_parsed` | `(filename)` | `list[FinancialRecord]` |
+
+> 另有生命周期方法 `start()` / `close()`,合计 30 个非别名公开方法。
+
+---
+
+## 五、废弃别名清单(33 个,1.0 移除)
+
+别名运行时发出 `DeprecationWarning`;**仍接受 `(market, code)` 写法**(这是别名与统一接口的关键差异)。
+
+| 目标统一接口 | 数量 | 废弃别名 |
+|--------------|------|----------|
+| `get_bars` | 4 | `get_kline`、`get_kline_since`、`get_kline_batch`、`get_index_kline` |
+| `get_indicators` | 1 | `get_stock_kline_with_indicators` |
+| `get_quotes` | 3 | `get_stock_quotes`、`get_goods_quotes`、`get_goods_quotes_list` |
+| `get_board_members` | 1 | `get_stock_quotes_list` |
+| `get_ticks` | 3 | `get_transactions`、`get_goods_transaction`、`get_goods_transaction_all` |
+| `get_minutes` | 3 | `get_minute`、`get_minute_batch`、`get_goods_tick_chart` |
+| `get_minutes(sampling=True)` | 2 | `get_chart_sampling`、`get_goods_chart_sampling` |
+| `get_universe` | 5 | `get_security_count`、`get_security_list`、`get_security_list_all`、`get_goods_list`、`get_goods_count` |
+| `get_f10` | 2 | `get_company_info_category`、`get_company_info_content` |
+| `get_file` | 4 | `get_block_info`、`get_report_file`、`get_file_meta`、`download_file` |
+| `get_financial_file_infos` | 1 | `get_financial_file_list` |
+| `get_financial_records_parsed` | 1 | `get_financial_records` |
+| `get_boards` | 1 | `get_board_list` |
+| `get_board_of` | 1 | `get_belong_board` |
+| `get_snapshot` | 1 | `get_symbol_info` |
+| **合计** | **33** | |
+
+---
+
+## 六、标的写法统一(字符串化)
+
+统一接口**只接受字符串标的**,已移除所有 `(market, code)` 元组软兼容:
+
+- 删除模块级 `_as_symbols()`;`get_quotes` / `get_xdxr` / `get_finance` / `get_auction` /
+ `get_capital_flow` 去掉 `code` 位置参数,统一走 `parse_symbols()`。
+- `get_price_limits` 去掉 `(market, code, …)` 旧参形式检测。
+- `get_unusual` 去掉整数市场号检测。
+- 调用方(CLI、示例)同步改为字符串;`get_finance` / `get_capital_flow` 的返回类型改为 `list`。
+
+!!! note "保留项"
+ `get_boards(kind)` 仍接受数字板块类别(`0/1/2/3`)。这是**板类别选择器**、非标的,
+ 文档已明示「也接受数字」,旧别名 `get_board_list(board_type=0)` 依赖它。
+
+---
+
+## 七、验证
+
+- `pytest`:**127 passed**。其中 `tests/test_all_interfaces.py` 为全接口回归:mock 连接逐个
+ 调用 63 个公开方法,并以「覆盖哨兵」断言无遗漏(7 条告警为别名测试的预期 `DeprecationWarning`)。
+- `scripts/check_docs.py`:`MUST_LIST_ALL` + `MUST_NOT_BE_STALE` 全部 `[OK]`。
+- 签名核对:统一接口签名与返回类型与本文一致;全仓无 `_as_symbols` 及元组式调用残留。
diff --git a/examples/quickstart.py b/examples/quickstart.py
index 556a344..55ef612 100644
--- a/examples/quickstart.py
+++ b/examples/quickstart.py
@@ -4,18 +4,19 @@
python examples/quickstart.py
说明:数据来自通达信公开行情服务器(无需账号,15 分钟延时)。
+标的一律用字符串(``sh600000`` / ``sz000001`` / ``hk00700`` / ``usAAPL`` / ``cffex:IFL0``)。
"""
import asyncio
-from pytdxdata import KlinePeriod, Market, TdxData
+from pytdxdata import TdxData
async def main() -> None:
# TdxData 为异步上下文管理器:进入时建连,退出时释放
async with TdxData() as td:
# 1) 批量五档报价(可一次传多只,超过 80 只自动切批)
- quotes = await td.get_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
+ quotes = await td.get_quotes(["sh600000", "sz000001"])
print("== 报价 ==")
for q in quotes:
print(
@@ -24,7 +25,7 @@ async def main() -> None:
)
# 2) 日K线(最近 10 根)
- bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=10)
+ bars = await td.get_bars("sh600000", count=10)
print("\n== 日K(最近 3 根)==")
for b in bars[-3:]:
print(
@@ -33,7 +34,7 @@ async def main() -> None:
)
# 3) 当日分时
- minutes = await td.get_minute(Market.SH, "600000")
+ minutes = await td.get_minutes("sh600000")
latest = minutes[-1].price if minutes else "-"
print(f"\n== 分时 ==\n共 {len(minutes)} 个点,最新价={latest}")
diff --git a/mkdocs.yml b/mkdocs.yml
index d9113a2..a91ce2f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -64,6 +64,7 @@ nav:
- 其他:
- 常见问题: faq.md
- 更新日志: changelog.md
+ - 接口重构审查: refactor-audit.md
- 参与贡献: contributing.md
plugins:
diff --git a/pyproject.toml b/pyproject.toml
index 8d83fec..f52f3c5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "pytdxdata"
-version = "0.5.0"
+version = "0.6.0"
description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权"
readme = "README.md"
requires-python = ">=3.11"
diff --git a/scripts/check_docs.py b/scripts/check_docs.py
index f6afc5f..e6c25ff 100644
--- a/scripts/check_docs.py
+++ b/scripts/check_docs.py
@@ -32,12 +32,12 @@ PKG_DIR = ROOT / "src" / "pytdxdata"
# 必须**列全**所有公开方法的文档(漏写 = 漂移)
MUST_LIST_ALL = [
- ROOT / "docs" / "api" / "index.md",
ROOT / "docs" / "API_REFERENCE.md",
]
# 只需**不提到已删除的方法**的文档:
-# 这些是入口 / 教程 / 精选清单,本来就不要求列全,但绝不能引用已不存在的方法
+# 这些是入口 / 教程 / 精选清单 / 接口总览(只列推荐的统一接口,旧方法不强制列出),
+# 但绝不能引用已不存在的方法
MUST_NOT_BE_STALE = [
ROOT / "SKILL.md",
ROOT / "README.md",
@@ -48,6 +48,8 @@ MUST_NOT_BE_STALE = [
ROOT / "docs" / "faq.md",
ROOT / "docs" / "cli.md",
ROOT / "docs" / "ai.md",
+ ROOT / "docs" / "api" / "index.md",
+ ROOT / "docs" / "refactor-audit.md",
]
diff --git a/src/pytdxdata/__init__.py b/src/pytdxdata/__init__.py
index b87ca6a..7f110fd 100644
--- a/src/pytdxdata/__init__.py
+++ b/src/pytdxdata/__init__.py
@@ -16,7 +16,7 @@ from .models import (
XdxrRecord,
)
-__version__ = "0.5.0"
+__version__ = "0.6.0"
__all__ = [
"TdxData",
"Market",
diff --git a/src/pytdxdata/api.py b/src/pytdxdata/api.py
index cdfb040..3dc1cfd 100644
--- a/src/pytdxdata/api.py
+++ b/src/pytdxdata/api.py
@@ -1,8 +1,28 @@
-"""统一对外接口 TdxData:标准/MAC自动选路 + 自动缓存 + 自动并发分页"""
+"""统一对外接口 TdxData。
+
+对外只暴露「**一个数据类型 = 一个方法**」:跨市场(A股/港股/美股/期货/期权)与
+跨通道(标准 / MAC / EX)由内部自动选路、自动分批、自动分页,标的统一用字符串
+写法(``sz000001`` / ``hk00700`` / ``cffex:IFL0``,裸 6 位数字=沪市指数)。
+
+用法::
+
+ async with TdxData() as td:
+ # 一次拿到 A股 + 港股 + 美股 的报价(内部按通道分组并发)
+ quotes = await td.get_quotes(["sz000001", "hk00700", "usAAPL"])
+ # 日K线(自动判指数、自动复权选路、自动并发分页)
+ bars = await td.get_bars(["sz000001", "hk00700"], KlinePeriod.DAY, count=240)
+ # 逐笔成交 / 分时
+ ticks = await td.get_ticks("sz000001", date=20260811)
+ minutes = await td.get_minutes("sz000001")
+
+旧的分裂接口(``get_kline`` / ``get_transaction`` 等 51 个)保留为 deprecated
+别名,见文件末尾,1.0 移除。
+"""
from __future__ import annotations
import asyncio
import logging
+import warnings
from datetime import date as _date, datetime
from pathlib import Path
from typing import Sequence
@@ -12,22 +32,31 @@ from .cache.key import CacheKey
from .cache.manager import CacheManager
from .cache.memory import MemoryCache
from .codec.payload import pack_payload, unpack_payload
-from .config import get_ex_hosts, get_mac_hosts, get_standard_hosts
+from .config import EX_HANDSHAKES, get_ex_hosts, get_mac_hosts, get_standard_hosts
from .models import (
Adjust,
+ AuctionItem,
+ BelongBoard,
+ BoardInfo,
+ CapitalFlow,
ExMarket,
FinanceRecord,
FinancialFileInfo,
FinancialRecord,
+ IndicatorSet,
IndustryInfo,
KlinePeriod,
Market,
+ MemberQuote,
MinuteBar,
SecurityBar,
SecurityInfo,
SecurityQuote,
+ ServerInfo,
+ SymbolSnapshot,
TdxBlock,
TransactionRecord,
+ UnusualItem,
XdxrRecord,
)
from .pool.ex_pool import ExPool
@@ -40,7 +69,6 @@ from .protocol.commands import (
GetSecurityCountCmd,
GetSecurityListCmd,
GetSecurityQuotesCmd,
- GetTransactionDataCmd,
GetXdxrInfoCmd,
KLINE_PAGE,
LIST_PAGE,
@@ -48,8 +76,51 @@ from .protocol.commands import (
MacTransactionCmd,
MAX_QUOTES,
)
+from .protocol.commands.ex_ext import (
+ GetExHistoryTransactionDataCmd,
+ GetExInstrumentCountCmd,
+ GetExInstrumentInfoCmd,
+ GetExTransactionDataCmd,
+ SymbolTickChartCmd,
+)
+from .protocol.commands.ex_proto import GetExInstrumentBarsCmd
+from .protocol.commands.mac_ext import (
+ MacAuctionCmd,
+ MacBelongBoardCmd,
+ MacBoardListCmd,
+ MacBoardMembersQuotesCmd,
+ MacCapitalFlowCmd,
+ MacChartSamplingCmd,
+ MacFileDownloadCmd,
+ MacFileListCmd,
+ MacKlineOffsetCmd,
+ MacServerInfoCmd,
+ MacSymbolInfoCmd,
+ MacSymbolQuotesCmd,
+ MacUnusualCmd,
+)
+from .protocol.commands.mac_tick import MacTickChartCmd
+from .protocol.commands.std_ext import (
+ GetBlockInfoCmd,
+ GetBlockInfoMetaCmd,
+ GetCompanyInfoCategoryCmd,
+ GetCompanyInfoContentCmd,
+ GetReportFileCmd,
+ MarketStat,
+ compute_price_limits,
+)
from .router import route_for
from .scheduler.paginator import PageSpec, Paginator
+from .symbols import (
+ Symbol,
+ format_symbol,
+ is_cn_index,
+ market_name,
+ market_targets,
+ parse_market,
+ parse_symbol,
+ parse_symbols,
+)
log = logging.getLogger(__name__)
@@ -66,16 +137,83 @@ _KLINE_MAX_BARS: dict[KlinePeriod, int] = {
KlinePeriod.MONTH: 500,
}
+# 自定义字段报价(0x122B/0x122C)基础字段位:昨收/开/高/低/现价/量/量比/额
+_QUOTE_BITS = [0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07]
+_QUOTE_PAGE = 80 # 0x122B/0x122C 单次上限 80 只
+_EX_PAGE = 1000 # EX 商品列表单页
+_TICK_PAGE = 1000 # MAC 逐笔单页
+_EX_TICK_PAGE = 1800 # 港股逐笔单页
+_ALL_PAGES_CAP = 50 # count=None(全量)时的翻页上限
+
+# 港股系市场:逐笔走 EX 专用 16B 协议(0x23FC/0x2406),其余扩展市场走 MAC 0x122F
+_HK_MARKETS = frozenset({27, 31, 48, 49, 71, 98})
+
+
+def _fields_tag(bits: Sequence[int] | None) -> str:
+ """字段位集合 -> 缓存键片段。"""
+ if not bits:
+ return ""
+ return ",".join("%02x" % int(b) for b in sorted(bits))
+
+
+def _bit(fields: dict[str, float], bit: int) -> float:
+ """取字段位值(协议层键形如 ``"0x7"``)。"""
+ return float(fields.get(hex(bit), 0.0))
+
+
+def _quote_from_member(mq: MemberQuote) -> SecurityQuote:
+ """协议层 MemberQuote -> 统一 SecurityQuote(基础字段位进属性,其余留在 fields)。
+
+ A股标准通道没有名称与自定义字段位,港股/美股/期货只有 0x122B —— 本条把
+ 「有名字+有字段位」的那条路归一成同一个模型。
+ """
+ f = dict(mq.fields)
+ market = int(mq.market)
+ return SecurityQuote(
+ market=market,
+ code=mq.code,
+ symbol=format_symbol(market, mq.code),
+ name=mq.name,
+ price=_bit(f, 0x04),
+ pre_close=_bit(f, 0x00),
+ open=_bit(f, 0x01),
+ high=_bit(f, 0x02),
+ low=_bit(f, 0x03),
+ vol=_bit(f, 0x05),
+ amount=_bit(f, 0x07),
+ s_vol=0.0,
+ b_vol=0.0,
+ fields=f,
+ )
+
+
+def _reject_ex(symbols: Sequence[Symbol], what: str) -> None:
+ """只有 A股有数据的接口:遇到扩展市场标的直接报错,避免静默返回空。"""
+ bad = [s.text for s in symbols if s.is_ex]
+ if bad:
+ raise ValueError(
+ f"{what} 仅支持 A股(深/沪/北),不支持扩展市场标的: {', '.join(bad)}"
+ )
+
+
+def _deprecated(old: str, new: str) -> None:
+ warnings.warn(
+ f"{old} 已废弃,请改用 {new}(参数写法见 CHANGELOG 迁移表)",
+ DeprecationWarning,
+ stacklevel=3,
+ )
+
+
+def _today_ymd() -> int:
+ d = _date.today()
+ return d.year * 10000 + d.month * 100 + d.day
+
class TdxData:
"""通达信行情数据统一入口。
- 用法::
-
- async with TdxData() as td:
- bars = await td.get_kline(1, "600000", KlinePeriod.DAY, count=2400)
- q = await td.get_quotes([(1, "600000"), (0, "000001")])
- t = await td.get_transactions(0, "000001", date=20260811)
+ 标的一律用字符串(见 :mod:`pytdxdata.symbols`);方法名与方法数只按数据类型分,
+ 不再按通道/市场分。旧的按通道分裂的方法保留为 deprecated 别名。
"""
def __init__(
@@ -92,6 +230,7 @@ class TdxData:
pool_min: int = 3,
pool_max: int = 12,
mac_pool_cap: int = 4,
+ std_pool_cap: int = 4,
) -> None:
self.port = port
self.timeout = timeout
@@ -106,9 +245,9 @@ class TdxData:
self._std_pool = DynamicPool(
self._std_servers, port=port, timeout=timeout,
min_size=pool_min, max_size=pool_max,
+ per_server_cap=std_pool_cap,
health=HealthEngine(),
)
- from .protocol.commands.mac import MacKlineCmd
# 单连接约束下:MAC 并发上限 = MAC 服务器数(每服务器1连接),
# 故池上限取 pool_max 与服务器数的较大者,确保用满所有可用 MAC 节点。
mac_cap = max(pool_max, len(self._mac_servers))
@@ -121,7 +260,6 @@ class TdxData:
probe_factory=lambda: MacKlineCmd(1, "600000", KlinePeriod.DAY, Adjust.NONE, 0, 100),
)
# EX扩展市场池(港股/期货/美股,端口7727;MAC EX login + pytdx EX setup 混合)
- from .config import EX_HANDSHAKES
self._ex_pool = ExPool(self._ex_servers, timeout=timeout,
min_size=min(pool_min, 2), max_size=min(pool_max, 6),
handshake_map=EX_HANDSHAKES)
@@ -156,120 +294,335 @@ class TdxData:
async def __aexit__(self, *exc) -> None:
await self.close()
- # ------------------------------------------------------------------ #
- # K线
- # ------------------------------------------------------------------ #
+ # ================================================================== #
+ # 一、标的清单
+ # ================================================================== #
- async def get_kline(
- self, market: Market, code: str, period: KlinePeriod, *,
- start: int = 0, count: int = 800, adjust: Adjust | None = None,
- start_date: datetime | None = None, end_date: datetime | None = None,
- ) -> list[SecurityBar]:
- """获取K线(count>页大小自动并发分页;adjust!=NONE 走MAC复权通道)。
+ async def get_universe(self, market: str | None = None) -> list[SecurityInfo]:
+ """标的清单(A股证券列表 + 扩展市场商品列表),一次覆盖所有市场。
参数:
- market: 市场 (Market.SH / Market.SZ)
- code: 股票代码
- period: K线周期
- start: 起始偏移量(从最早K线开始的索引,默认0)
- count: 获取条数(默认800)
- adjust: 复权方式(默认使用实例 default_adjust)
- start_date: 起始日期(与 start/count 互斥,优先使用日期过滤)
- end_date: 截止日期(可选,配合 start_date 使用)
+ market: 市场选择器 —— ``None``/``"all"``=全部市场;``"sz"/"sh"/"bj"``=A股某市;
+ ``"hk"/"us"/"cffex"/"zz"/"dl"/"shf"/"gz"``=扩展市场(也可用完整枚举名,
+ 如 ``"hk_gem"``)。
- 增量更新示例:
- # 获取 2026-01-01 之后的所有日K线
- bars = await client.get_kline(Market.SH, "600000", KlinePeriod.DAY,
- start_date=datetime(2026, 1, 1))
-
- # 获取 2026-01-01 至 2026-06-30 之间的日K线
- bars = await client.get_kline(Market.SH, "600000", KlinePeriod.DAY,
- start_date=datetime(2026, 1, 1),
- end_date=datetime(2026, 6, 30))
-
- # 便捷方法:获取指定日期之后的所有K线
- bars = await client.get_kline_since(Market.SH, "600000",
- KlinePeriod.DAY, datetime(2026, 1, 1))
+ 返回:
+ ``list[SecurityInfo]``,每条带 ``symbol`` 规范化标的串与 ``kind`` 分类描述。
+ EX 通道无昨收/单位,对应字段为 0。
"""
- # 日期过滤模式:获取全量数据后按日期筛选
- if start_date is not None or end_date is not None:
- return await self._get_kline_by_date(
- market, code, period, start_date, end_date, adjust)
+ out: list[SecurityInfo] = []
+ for mkt, channel in market_targets(market):
+ if channel == "ex":
+ out.extend(await self._universe_ex(mkt))
+ else:
+ out.extend(await self._universe_cn(mkt))
+ return out
- adj = self.default_adjust if adjust is None else adjust
- # EX扩展市场(港股/期货):market为ExMarket值,走ex池
- if isinstance(market, ExMarket) or int(market) not in (0, 1, 2):
- # EX通道统一用pytdx EX协议(0x23FF): category=K线周期(与TDXParams一致, DAY=4)
- from .protocol.commands.ex_proto import GetExInstrumentBarsCmd
- cat = int(period)
- fetch_count = max(700, start + count)
- key = CacheKey("kline", int(market), code, period.name, start, fetch_count,
- f"{adj.name}@{cat}")
- async def fetch() -> bytes:
- result = await self._fetch_paginated_ex(
- lambda s2, c2: GetExInstrumentBarsCmd(int(market), code, cat, s2, c2),
- PageSpec(page_size=700, total=fetch_count, min_page=100))
- bars = []
- for d in result:
- bars.append(SecurityBar(
- market=int(market), code=code,
- year=d["year"], month=d["month"], day=d["day"],
- hour=d.get("hour", 0), minute=d.get("minute", 0),
- open=d["open"], high=d["high"], low=d["low"], close=d["close"],
- vol=float(d.get("trade", 0) or 0), amount=0.0,
+ async def _universe_cn(self, market: int) -> list[SecurityInfo]:
+ key = CacheKey("list", market)
+
+ async def fetch() -> bytes:
+ total = await self._security_count(market)
+
+ def make_cmd(s: int, c: int):
+ return GetSecurityListCmd(market, s)
+
+ spec = PageSpec(page_size=LIST_PAGE, total=total, stop_when_short=True)
+ items = await self._fetch_paginated_list(
+ "standard", make_cmd, spec,
+ concurrency=min(self._std_pool.max_size, 8))
+ for it in items:
+ it.symbol = format_symbol(it.market, it.code)
+ return pack_payload(items)
+
+ return unpack_payload(await self._cache.get_or_fetch(key, fetch))
+
+ async def _ex_all(self) -> list[SecurityInfo]:
+ """扩展市场全量商品(一次拉全,缓存1天;按市场过滤在内存里做)。"""
+ from .protocol.commands.ex_ext import (
+ GetExInstrumentCountCmd,
+ GetExInstrumentInfoCmd,
+ )
+ key = CacheKey("list", None, extra="ex")
+
+ async def fetch() -> bytes:
+ total = int(await self._execute_ex(GetExInstrumentCountCmd()))
+ items: list[SecurityInfo] = []
+ pos = 0
+ while pos < total:
+ page = await self._execute_ex(
+ GetExInstrumentInfoCmd(0, pos, _EX_PAGE))
+ if not page:
+ break
+ for g in page:
+ mkt = int(g["market"])
+ code = str(g["code"]).strip()
+ items.append(SecurityInfo(
+ market=mkt,
+ code=code,
+ name=str(g.get("name", "")).strip(),
+ volunit=0,
+ decimal_point=2,
+ pre_close=0.0,
+ symbol=format_symbol(mkt, code),
+ kind=str(g.get("desc", "")).strip(),
))
- return pack_payload(bars)
- bars = unpack_payload(await self._cache.get_or_fetch(key, fetch))
- # EX 0x23FF 按时间升序返回(老→新):start=0 取最新 count 根
- if count < len(bars):
- return bars[-count:] if start == 0 else bars[start:start + count]
- return bars
+ pos += len(page)
+ return pack_payload(items)
+
+ return unpack_payload(await self._cache.get_or_fetch(key, fetch))
+
+ async def _universe_ex(self, market: int) -> list[SecurityInfo]:
+ return [it for it in await self._ex_all() if it.market == market]
+
+ async def _security_count(self, market: int) -> int:
+ key = CacheKey("count", market)
+
+ async def fetch() -> bytes:
+ n = await self._execute_standard(GetSecurityCountCmd(market))
+ return pack_payload(n)
+
+ return unpack_payload(await self._cache.get_or_fetch(key, fetch))
+
+ # ================================================================== #
+ # 二、报价
+ # ================================================================== #
+
+ async def get_quotes(self, symbols: str | Sequence[str], *,
+ fields: Sequence[int] | None = None
+ ) -> list[SecurityQuote]:
+ """报价,一次可跨市场、跨通道混合查询。
+
+ 参数:
+ symbols: 一个或多个标的字符串(``"sz000001"`` / ``"hk00700"`` / ``"usAAPL"`` /
+ ``"cffex:IFL0"``)。
+ fields: 可选自定义字段位(如 ``[0x00, 0x04, 0x38]``)。给了就走 MAC/EX 的
+ 0x122B 字段位通道(有 ``name``,无五档);不给时 A股走标准通道
+ (**有五档 bid/ask、买卖量、涨跌停价,无 name**),扩展市场走 0x122B。
+
+ 返回:
+ ``list[SecurityQuote]``,按入参顺序排列(各记录带 ``symbol``)。
+ A股标准通道与扩展市场的可用字段不同:五档只在 A股标准通道有,
+ 名称只在 ``fields=`` / 扩展市场有,其余字段位统一落在 ``.fields``。
+ """
+ syms = parse_symbols(symbols)
+ bits = [int(b) for b in fields] if fields else None
+ tag = "mac:" + _fields_tag(bits) if bits else "std"
+ key = CacheKey.quote_key([s.as_pair() for s in syms], tag=tag)
+ payload = await self._cache.get_or_fetch(
+ key, lambda: self._fetch_quotes(syms, bits))
+ quotes = unpack_payload(payload)
+ order = {s.as_pair(): i for i, s in enumerate(syms)}
+ quotes.sort(key=lambda q: order.get((int(q.market), q.code), len(order)))
+ return quotes
+
+ async def _fetch_quotes(self, syms: list[Symbol], bits: list[int] | None) -> bytes:
+ out: list[SecurityQuote] = []
+ cn = [s for s in syms if not s.is_ex]
+ ex = [s for s in syms if s.is_ex]
+ if bits is None:
+ if cn:
+ out.extend(await self._quotes_std(cn))
+ if ex:
+ rows = await self._execute_ex(
+ MacSymbolQuotesCmd([s.as_pair() for s in ex], None))
+ out.extend(_quote_from_member(m) for m in rows)
+ else:
+ for i in range(0, len(syms), _QUOTE_PAGE):
+ batch = syms[i:i + _QUOTE_PAGE]
+ pairs = [s.as_pair() for s in batch]
+ cn_pairs = [p for p, s in zip(pairs, batch) if not s.is_ex]
+ ex_pairs = [p for p, s in zip(pairs, batch) if s.is_ex]
+ if cn_pairs:
+ rows = await self._execute_mac(MacSymbolQuotesCmd(cn_pairs, bits))
+ out.extend(_quote_from_member(m) for m in rows)
+ if ex_pairs:
+ rows = await self._execute_ex(MacSymbolQuotesCmd(ex_pairs, bits))
+ out.extend(_quote_from_member(m) for m in rows)
+ return pack_payload(out)
+
+ async def _quotes_std(self, syms: list[Symbol]) -> list[SecurityQuote]:
+ """A股标准通道五档报价(>80 只自动切批)。"""
+ out: list[SecurityQuote] = []
+ for i in range(0, len(syms), MAX_QUOTES):
+ batch = syms[i:i + MAX_QUOTES]
+ cmd = GetSecurityQuotesCmd([s.as_pair() for s in batch])
+ rows = await self._execute_standard(cmd)
+ for q in rows:
+ q.symbol = format_symbol(q.market, q.code)
+ out.extend(rows)
+ return out
+
+ async def get_snapshot(self, symbols: str | Sequence[str]) -> list[SymbolSnapshot]:
+ """个股特征快照(当日/换手/活跃度等,仅 A股)。"""
+ syms = parse_symbols(symbols)
+ _reject_ex(syms, "个股特征快照")
+ out: list[SymbolSnapshot] = []
+ for sym in syms:
+ key = CacheKey("snapshot", sym.market, sym.code)
+
+ async def fetch(s: Symbol = sym) -> bytes:
+ rec = await self._execute_mac(MacSymbolInfoCmd(s.market, s.code))
+ if rec is not None:
+ rec.symbol = s.text
+ return pack_payload(rec)
+
+ rec = unpack_payload(await self._cache.get_or_fetch(key, fetch))
+ if rec is not None:
+ out.append(rec)
+ return out
+
+ async def get_auction(self, symbols: str | Sequence[str]) -> list[AuctionItem]:
+ """集合竞价(仅 A股)。"""
+ syms = parse_symbols(symbols)
+ _reject_ex(syms, "集合竞价")
+ out: list[AuctionItem] = []
+ for sym in syms:
+ items = await self._execute_mac(MacAuctionCmd(sym.market, sym.code))
+ for it in items:
+ it.symbol = sym.text
+ out.extend(items)
+ return out
+
+ async def get_capital_flow(self, symbols: str | Sequence[str]) -> list[CapitalFlow]:
+ """个股资金流向(仅 A股)。"""
+ syms = parse_symbols(symbols)
+ _reject_ex(syms, "资金流向")
+ out: list[CapitalFlow] = []
+ for sym in syms:
+ flow = await self._execute_mac(MacCapitalFlowCmd(sym.market, sym.code))
+ if flow is not None:
+ flow.symbol = sym.text
+ out.append(flow)
+ return out
+
+ # ================================================================== #
+ # 三、K线
+ # ================================================================== #
+
+ async def get_bars(
+ self,
+ symbols: str | Sequence[str],
+ period: KlinePeriod = KlinePeriod.DAY,
+ *,
+ start: int = 0,
+ count: int = 800,
+ adjust: Adjust | None = None,
+ start_date: datetime | None = None,
+ end_date: datetime | None = None,
+ concurrency: int = 6,
+ ) -> list[SecurityBar]:
+ """K线(多标的并发,自动判指数、自动复权选路、自动跨市场)。
+
+ 参数:
+ symbols: 一个或多个标的字符串;混合市场会按通道并发拉取后按入参顺序拼接。
+ period: K线周期(``KlinePeriod.DAY`` 等)。
+ start: 起始偏移量(从最早K线开始的索引,默认0)。
+ count: 获取条数(默认800;超过单页会自动多连接并发分页)。
+ adjust: 复权方式(默认用实例 ``default_adjust``);``QFQ``/``HFQ`` 自动走 MAC 通道。
+ start_date / end_date: 按日期区间取(与 start/count 互斥,优先日期过滤)。
+ 只给 ``start_date`` 即增量更新语义(取该日期之后的全部K线)。
+
+ 返回:
+ ``list[SecurityBar]``,按入参标的顺序拼接,每根带 ``symbol``;组内按时间正序。
+ """
+ period = KlinePeriod(int(period))
+ syms = parse_symbols(symbols)
+ sem = asyncio.Semaphore(max(1, concurrency))
+
+ async def one(sym: Symbol) -> list[SecurityBar]:
+ async with sem:
+ return await self._bars_one(
+ sym, period, start=start, count=count, adjust=adjust,
+ start_date=start_date, end_date=end_date)
+
+ groups = await asyncio.gather(*(one(s) for s in syms))
+ return [b for g in groups for b in g]
+
+ async def _bars_one(
+ self, sym: Symbol, period: KlinePeriod, *,
+ start: int, count: int, adjust: Adjust | None,
+ start_date: datetime | None, end_date: datetime | None,
+ ) -> list[SecurityBar]:
+ if start_date is not None or end_date is not None:
+ return await self._bars_by_date(sym, period, start_date, end_date, adjust)
+ adj = self.default_adjust if adjust is None else adjust
+ if sym.is_ex:
+ return await self._bars_ex(sym, period, adj, start, count)
route = route_for("kline", adjust=adj, period=period)
- key = CacheKey("kline", int(market), code, period.name, start, count, adj.name)
+ key = CacheKey("kline", sym.market, sym.code, period.name, start, count, adj.name)
+ mk = sym.market
+ index = is_cn_index(mk, sym.code)
def make_cmd(s: int, c: int):
if route == "mac":
- return MacKlineCmd(int(market), code, period, adj, s, c)
- # 指数类(88开头板块指数 / 沪市000指数 / 深市399指数)走指数K线命令(多4字节涨跌家数)
- # 注意: 深市股票000001.SZ(market=0)不是指数, 必须加market判断
- mk = int(market)
- is_index = code.startswith("88") or (
- code.startswith("000") and mk == int(Market.SH)) or (
- code.startswith("399") and mk == int(Market.SZ))
- if is_index:
- return GetIndexBarsCmd(mk, code, period, s, c)
- return GetSecurityBarsCmd(mk, code, period, s, c)
+ return MacKlineCmd(mk, sym.code, period, adj, s, c)
+ if index:
+ return GetIndexBarsCmd(mk, sym.code, period, s, c)
+ return GetSecurityBarsCmd(mk, sym.code, period, s, c)
if route == "mac":
payload = await self._cache.get_or_fetch(
- key, lambda: self._fetch_mac_kline_serial(
+ key, lambda: self._fetch_mac_bars_serial(
make_cmd, start + count, start=start, page_size=700,
)
)
else:
payload = await self._cache.get_or_fetch(
- key, lambda: self._fetch_paginated(route, make_cmd, PageSpec(
+ key, lambda: self._fetch_paginated("std", make_cmd, PageSpec(
page_size=KLINE_PAGE, total=start + count, min_page=100,
start_offset=start,
))
)
bars = unpack_payload(payload)
- # K线按时间正序(无论 start 是否 0 都排序,避免依赖协议层顺序保证)
+ return self._finish_bars(bars, sym)
+
+ async def _bars_ex(self, sym: Symbol, period: KlinePeriod, adj: Adjust,
+ start: int, count: int) -> list[SecurityBar]:
+ """扩展市场K线(EX 0x23FF;category=周期编码,与 TDXParams 一致)。"""
+ from .protocol.commands.ex_proto import GetExInstrumentBarsCmd
+ cat = int(period)
+ fetch_count = max(700, start + count)
+ key = CacheKey("kline", sym.market, sym.code, period.name, start,
+ fetch_count, f"{adj.name}@{cat}")
+
+ async def fetch() -> bytes:
+ rows = await self._fetch_paginated_ex(
+ lambda s2, c2: GetExInstrumentBarsCmd(sym.market, sym.code, cat, s2, c2),
+ PageSpec(page_size=700, total=fetch_count, min_page=100))
+ bars = [SecurityBar(
+ market=sym.market, code=sym.code,
+ year=d["year"], month=d["month"], day=d["day"],
+ hour=d.get("hour", 0), minute=d.get("minute", 0),
+ open=d["open"], high=d["high"], low=d["low"], close=d["close"],
+ vol=float(d.get("trade", 0) or 0), amount=0.0,
+ ) for d in rows]
+ return pack_payload(bars)
+
+ bars = self._finish_bars(unpack_payload(await self._cache.get_or_fetch(key, fetch)), sym)
+ # EX 0x23FF 按时间升序返回(老→新):start=0 取最新 count 根
+ if count < len(bars):
+ return bars[-count:] if start == 0 else bars[start:start + count]
+ return bars
+
+ @staticmethod
+ def _finish_bars(bars: list[SecurityBar], sym: Symbol) -> list[SecurityBar]:
+ """统一补 symbol + 按时间正序(不依赖协议层顺序保证)。"""
+ for b in bars:
+ b.symbol = sym.text
bars.sort(key=lambda b: (b.year, b.month, b.day, b.hour, b.minute))
return bars
- async def _get_kline_by_date(
- self, market: Market, code: str, period: KlinePeriod,
+ async def _bars_by_date(
+ self, sym: Symbol, period: KlinePeriod,
start_date: datetime | None, end_date: datetime | None,
adjust: Adjust | None,
) -> list[SecurityBar]:
- """按日期范围获取K线(内部方法)。
+ """按日期区间取K线:先二分定位偏移,再只拉目标区间。
- 高效策略:TDX K线按时间正序返回,start 是偏移量。用二分查找在
- O(log N) 次单条探测内定位日期对应的偏移量,再只拉取目标区间。
- 优化点:按周期预估上界省掉指数探测;仅 start_date 时合并为单次
- 二分;需同时查 start/end 日期时用 asyncio.gather 并行。
+ 关键坑:**偏移方向各通道不一致**(实测标准通道 offset 0 是最新一根、
+ 越大越老;MAC/EX 反过来),所以先探一次方向再二分,不做静态假设。
"""
# 归一化日期边界
start_dt = (start_date if isinstance(start_date, datetime)
@@ -282,335 +635,669 @@ class TdxData:
if end_dt is not None and end_dt.time() == datetime.min.time().replace(tzinfo=None):
end_dt = end_dt.replace(hour=23, minute=59, second=59, microsecond=999999)
- # 按周期预估总条数上界(保守值,二分中越界自然修正)
est = _KLINE_MAX_BARS.get(period, 10_000)
+ total = await self._bar_total(sym, period, adjust, est)
+ if total <= 0:
+ return []
+ desc = await self._offset_descending(sym, period, adjust, total)
- # 仅 start_date 的常见增量场景:单次二分定位起点,再取剩余全部
- if start_dt is not None and end_dt is None:
- lo = await self._probe_kline_lower_bound(
- market, code, period, adjust, est, start_dt)
- # 命中上界说明实际条数可能超出预估,逐步扩大范围直到定位成功
- MAX_EXPAND = 5 # 最多扩大 2^5 = 32 倍
- for _ in range(MAX_EXPAND):
- if lo < est:
- break
- if await self._probe_kline_bar(
- market, code, period, adjust, est) is None:
- break # est 处已无数据,说明 lo 就是总数上限
- est *= 2
- lo = await self._probe_kline_lower_bound(
- market, code, period, adjust, est, start_dt)
- if lo >= est:
- return []
- return await self.get_kline(
- market, code, period, start=lo, count=est - lo, adjust=adjust)
-
- # 需要 end_date 时,并行二分起点和终点
- tasks = []
- if start_dt is not None:
- tasks.append(self._probe_kline_lower_bound(
- market, code, period, adjust, est, start_dt))
- if end_dt is not None:
- tasks.append(self._probe_kline_upper_bound(
- market, code, period, adjust, est, end_dt))
- results = await asyncio.gather(*tasks) if tasks else []
-
- lo = results[0] if start_dt is not None else 0
- hi = results[-1] if end_dt is not None else est
- if start_dt is not None and end_dt is not None:
- lo, hi = results[0], results[1]
-
- # 命中上界时逐步扩大范围重试(与上面相同的回退逻辑)
- MAX_EXPAND = 5 # 最多扩大 2^5 = 32 倍
- for _ in range(MAX_EXPAND):
- need_expand = False
- if start_dt is not None and lo >= est:
- if await self._probe_kline_bar(
- market, code, period, adjust, est) is not None:
- need_expand = True
- if end_dt is not None and hi >= est:
- if await self._probe_kline_bar(
- market, code, period, adjust, est) is not None:
- need_expand = True
- if not need_expand:
- break
- est *= 2
- tasks2 = []
+ if desc:
+ # offset 越大越老:[0,k) 全都 >= start_date,[j,∞) 全都 <= end_date
+ k = total
if start_dt is not None:
- tasks2.append(self._probe_kline_lower_bound(
- market, code, period, adjust, est, start_dt))
+ k = await self._bisect_offset(
+ sym, period, adjust, total, lambda b: b.datetime < start_dt)
+ j = 0
if end_dt is not None:
- tasks2.append(self._probe_kline_upper_bound(
- market, code, period, adjust, est, end_dt))
- results2 = await asyncio.gather(*tasks2)
- lo = results2[0] if start_dt is not None else 0
- hi = results2[-1] if end_dt is not None else est
- if start_dt is not None and end_dt is not None:
- lo, hi = results2[0], results2[1]
+ j = await self._bisect_offset(
+ sym, period, adjust, total, lambda b: b.datetime <= end_dt)
+ lo, hi = j, k
+ else:
+ # offset 越大越新:[lo,hi) 即目标区间
+ lo = 0
+ if start_dt is not None:
+ lo = await self._bisect_offset(
+ sym, period, adjust, total, lambda b: b.datetime >= start_dt)
+ hi = total
+ if end_dt is not None:
+ hi = await self._bisect_offset(
+ sym, period, adjust, total, lambda b: b.datetime > end_dt)
if lo >= hi:
return []
- bars = await self.get_kline(
- market, code, period, start=lo, count=hi - lo, adjust=adjust)
- # min_page 可能导致多拉,做精确日期裁剪
+ bars = await self.get_bars(sym.text, period, start=lo, count=hi - lo,
+ adjust=adjust)
+ # 边界可能多拉(页对齐),做精确日期裁剪
if start_dt is not None:
bars = [b for b in bars if b.datetime >= start_dt]
if end_dt is not None:
bars = [b for b in bars if b.datetime <= end_dt]
return bars
- async def _probe_kline_lower_bound(
- self, market: Market, code: str, period: KlinePeriod,
- adjust: Adjust | None, total: int, target: datetime,
- ) -> int:
- """二分查找第一个 datetime >= target 的偏移量(在 [0, total] 内)。"""
+ async def _bar_total(self, sym: Symbol, period: KlinePeriod,
+ adjust: Adjust | None, est: int) -> int:
+ """指数扩张找K线总根数上界(探测到越界为止)。"""
+ n = est
+ for _ in range(6): # 最多放大 64 倍
+ if await self._probe_bar(sym, period, adjust, n) is None:
+ return n # 偏移 n 越界 → 总根数 <= n
+ n *= 2
+ return n
+
+ async def _offset_descending(self, sym: Symbol, period: KlinePeriod,
+ adjust: Adjust | None, total: int) -> bool:
+ """探测偏移方向:True=offset 0 是最新一根(标准通道),False=最老一根。
+
+ 比 0 号偏移和随便一个**在范围内**的偏移即可;``total`` 只是上界,
+ 所以从近到远试几个候选,全都越界时按标准通道口径兜底。
+ """
+ if total < 2:
+ return True
+ newest = await self._probe_bar(sym, period, adjust, 0)
+ if newest is None:
+ return True
+ for off in (1, 10, 100, total - 1):
+ if off <= 0 or off >= total:
+ continue
+ bar = await self._probe_bar(sym, period, adjust, off)
+ if bar is not None:
+ return bar.datetime < newest.datetime
+ return True
+
+ async def _bisect_offset(self, sym: Symbol, period: KlinePeriod,
+ adjust: Adjust | None, total: int, pred) -> int:
+ """二分找第一个满足 ``pred(bar)`` 的偏移量。
+
+ 越界(无数据)视为「边界在左侧」→ 收缩 hi;两个方向都靠 pred 表达,
+ 所以递增/递减通道共用同一份代码。
+ """
lo, hi = 0, total
while lo < hi:
mid = (lo + hi) // 2
- bar = await self._probe_kline_bar(market, code, period, adjust, mid)
- if bar is None:
- hi = mid # 越界,数据边界在左侧
- elif bar.datetime < target:
- lo = mid + 1 # 太早,向右
+ bar = await self._probe_bar(sym, period, adjust, mid)
+ if bar is None or pred(bar):
+ hi = mid
else:
- hi = mid # 命中,向左收缩
+ lo = mid + 1
return lo
- async def _probe_kline_upper_bound(
- self, market: Market, code: str, period: KlinePeriod,
- adjust: Adjust | None, total: int, target: datetime,
- ) -> int:
- """二分查找第一个 datetime > target 的偏移量(在 [0, total] 内)。"""
- lo, hi = 0, total
- while lo < hi:
- mid = (lo + hi) // 2
- bar = await self._probe_kline_bar(market, code, period, adjust, mid)
- if bar is None:
- hi = mid # 越界,数据边界在左侧
- elif bar.datetime <= target:
- lo = mid + 1 # 还在范围内,向右
- else:
- hi = mid # 超出,向左收缩
- return lo
-
- async def _probe_kline_bar(
- self, market: Market, code: str, period: KlinePeriod,
- adjust: Adjust | None, offset: int,
- ) -> SecurityBar | None:
+ async def _probe_bar(self, sym: Symbol, period: KlinePeriod,
+ adjust: Adjust | None, offset: int) -> SecurityBar | None:
"""探测指定偏移量处的单条K线(越界返回 None)。"""
adj = self.default_adjust if adjust is None else adjust
route = route_for("kline", adjust=adj, period=period)
- if route == "mac":
- cmd = MacKlineCmd(int(market), code, period, adj, offset, 1)
- try:
- bars = await self._execute_mac(cmd)
- except (ConnectionError, OSError, asyncio.TimeoutError):
- return None
+ mk = sym.market
+ if route == "mac" or sym.is_ex:
+ cmd = MacKlineCmd(mk, sym.code, period, adj, offset, 1)
+ run = self._execute_ex if sym.is_ex else self._execute_mac
else:
- mk = int(market)
- is_index = code.startswith("88") or (
- code.startswith("000") and mk == int(Market.SH)) or (
- code.startswith("399") and mk == int(Market.SZ))
- cmd = (GetIndexBarsCmd(mk, code, period, offset, 1)
- if is_index else GetSecurityBarsCmd(mk, code, period, offset, 1))
- try:
- bars = await self._execute_standard(cmd)
- except (ConnectionError, OSError, asyncio.TimeoutError):
- return None
+ cmd = (GetIndexBarsCmd(mk, sym.code, period, offset, 1)
+ if is_cn_index(mk, sym.code)
+ else GetSecurityBarsCmd(mk, sym.code, period, offset, 1))
+ run = self._execute_standard
+ try:
+ bars = await run(cmd)
+ except (ConnectionError, OSError, asyncio.TimeoutError):
+ return None
return bars[0] if bars else None
- async def get_kline_since(
- self, market: Market, code: str, period: KlinePeriod,
- since: datetime, adjust: Adjust | None = None,
- ) -> list[SecurityBar]:
- """获取指定日期之后的所有K线(增量更新便捷方法)。
+ async def get_indicators(
+ self, symbols: str | Sequence[str], indicators: Sequence[str], *,
+ period: KlinePeriod = KlinePeriod.DAY, count: int = 30,
+ adjust: Adjust | None = None, params: dict | None = None,
+ ) -> list[IndicatorSet]:
+ """K线 + 技术指标(MACD/KDJ/RSI/BOLL/MA/EMA)。
+
+ 返回 ``list[IndicatorSet]``(每个标的一组:``bars`` + ``indicators``),
+ 指标序列与 ``bars`` 等长(尾部对齐)。
+ """
+ from .indicator import compute_indicators
+ syms = parse_symbols(symbols)
+ bars = await self.get_bars(syms, period, count=max(120 + count, 200),
+ adjust=adjust)
+ grouped: dict[str, list[SecurityBar]] = {}
+ for b in bars:
+ grouped.setdefault(b.symbol, []).append(b)
+ out: list[IndicatorSet] = []
+ for sym in syms:
+ rows = grouped.get(sym.text, [])
+ if not rows:
+ out.append(IndicatorSet(symbol=sym.text, bars=[], indicators={}))
+ continue
+ ind = compute_indicators(
+ [r.high for r in rows], [r.low for r in rows],
+ [r.close for r in rows], indicators, params, tail=count)
+ out.append(IndicatorSet(
+ symbol=sym.text,
+ bars=rows[-count:],
+ indicators={k: (v[-count:] if len(v) >= count else v)
+ for k, v in ind.items()},
+ ))
+ return out
+
+ # ================================================================== #
+ # 四、逐笔成交 / 分时
+ # ================================================================== #
+
+ async def get_ticks(
+ self, symbols: str | Sequence[str], *,
+ date: int | None = None, start: int = 0, count: int | None = None,
+ concurrency: int = 6,
+ ) -> list[TransactionRecord]:
+ """逐笔成交(A股 MAC 0x122F / 港股 EX 0x23FC·0x2406 / 其他扩展市场 MAC)。
参数:
- since: 起始日期(含),只返回 datetime >= since 的K线
+ date: ``None``=当日,``YYYYMMDD``=历史某日。
+ start: 起始偏移。
+ count: ``None``=尽量取全量(自动翻页,上限 50 页);给了就取这么多条。
- 增量更新示例:
- # 获取2026年1月1日之后的所有日K线
- bars = await client.get_kline_since(
- Market.SH, "600000", KlinePeriod.DAY, datetime(2026, 1, 1))
-
- # 增量更新:本地已有数据截止到 last_date,拉取新数据
- last_date = datetime(2026, 8, 19)
- new_bars = await client.get_kline_since(
- Market.SH, "600000", KlinePeriod.DAY, last_date)
- # 注意:结果包含 last_date 当天的K线,追加时需去重
+ 返回:
+ ``list[TransactionRecord]``,按入参标的顺序拼接(A股含 ``trade_count``,
+ 港股为 HH:MM 时间 + ``fields["zengcang"]`` 增仓)。
"""
- return await self._get_kline_by_date(
- market, code, period, since, None, adjust)
+ syms = parse_symbols(symbols)
+ sem = asyncio.Semaphore(max(1, concurrency))
- async def get_kline_batch(
- self, stocks: list[tuple[Market, str]], period: KlinePeriod, *,
- start: int = 0, count: int = 800, adjust: Adjust | None = None,
- concurrency: int = 6,
- ) -> dict[str, list[SecurityBar]]:
- """批量获取K线,自动并发不同服务器。返回 {code: bars}。"""
- sem = asyncio.Semaphore(concurrency)
-
- async def _fetch(mkt: Market, code: str):
+ async def one(sym: Symbol) -> list[TransactionRecord]:
async with sem:
- return code, await self.get_kline(mkt, code, period, start=start, count=count, adjust=adjust)
+ return await self._ticks_one(sym, date=date, start=start, count=count)
- results = await asyncio.gather(*[_fetch(m, c) for m, c in stocks])
- return {code: bars for code, bars in results}
+ groups = await asyncio.gather(*(one(s) for s in syms))
+ return [t for g in groups for t in g]
- async def get_index_kline(
- self, market: Market, code: str, period: KlinePeriod, *,
- start: int = 0, count: int = 800,
- ) -> list[SecurityBar]:
- key = CacheKey("index_kline", int(market), code, period.name, start, count, "")
-
- def make_cmd(s: int, c: int):
- return GetIndexBarsCmd(int(market), code, period, s, c)
-
- payload = await self._cache.get_or_fetch(
- key, lambda: self._fetch_paginated("standard", make_cmd, PageSpec(
- page_size=KLINE_PAGE, total=start + count, min_page=100,
- ))
- )
- return unpack_payload(payload)
-
- # ------------------------------------------------------------------ #
- # 报价
- # ------------------------------------------------------------------ #
-
- async def get_quotes(self, stocks: Sequence[tuple[Market, str]]) -> list[SecurityQuote]:
- """批量报价(>80自动切批,缓存键=规范化股票集,TTL 5s)。"""
- stocks = list(stocks)
- if not stocks:
- return []
- key = CacheKey.quote_key(stocks)
- payload = await self._cache.get_or_fetch(
- key, lambda: self._fetch_quotes(stocks)
- )
- return unpack_payload(payload)
-
- async def _fetch_quotes(self, stocks: list[tuple[Market, str]]) -> bytes:
- out: list[SecurityQuote] = []
- for i in range(0, len(stocks), MAX_QUOTES):
- batch = stocks[i:i + MAX_QUOTES]
- cmds = GetSecurityQuotesCmd([(int(m), c) for m, c in batch])
- result = await self._execute_standard(cmds)
- out.extend(result)
- return pack_payload(out)
-
- # ------------------------------------------------------------------ #
- # 逐笔成交(MAC通道,含成交笔数)
- # ------------------------------------------------------------------ #
-
- async def get_transactions(
- self, market: Market, code: str, *,
- date: int | None = None, start: int = 0, count: int = 2000,
- ) -> list[TransactionRecord]:
- """获取逐笔成交(MAC 0x122F,每条含 trade_count=成交笔数)。"""
- key = CacheKey("transaction", int(market), code, "", start, count,
+ async def _ticks_one(self, sym: Symbol, *, date: int | None, start: int,
+ count: int | None) -> list[TransactionRecord]:
+ key = CacheKey("transaction", sym.market, sym.code, "", start, count,
"" if date is None else str(date))
- def make_cmd(s: int, c: int):
- return MacTransactionCmd(int(market), code, date or 0, s, c)
-
- payload = await self._cache.get_or_fetch(
- key, lambda: self._fetch_paginated("mac", make_cmd, PageSpec(
- page_size=1000, total=start + count, min_page=100,
- ))
- )
- return unpack_payload(payload)
-
- # ------------------------------------------------------------------ #
- # 证券列表
- # ------------------------------------------------------------------ #
-
- async def get_security_count(self, market: Market) -> int:
- key = CacheKey("count", int(market))
-
async def fetch() -> bytes:
- n = await self._execute_standard(GetSecurityCountCmd(int(market)))
- return pack_payload(n)
+ if sym.is_ex:
+ rows = await self._ticks_ex(sym, date=date, start=start, count=count)
+ else:
+ def make_cmd(s: int, c: int):
+ return MacTransactionCmd(sym.market, sym.code, date or 0, s, c)
- payload = await self._cache.get_or_fetch(key, fetch)
- return unpack_payload(payload)
+ spec = PageSpec(
+ page_size=_TICK_PAGE,
+ total=None if count is None else start + count,
+ min_page=100,
+ stop_when_short=True,
+ max_pages=_ALL_PAGES_CAP if count is None else None,
+ start_offset=start,
+ )
+ rows = await self._fetch_paginated_list("mac", make_cmd, spec)
+ return pack_payload(rows)
- async def get_security_list(self, market: Market, *,
- start: int = 0, count: int | None = None) -> list[SecurityInfo]:
- """分页获取证券列表(count=None=全部,先查总数避免死循环)。"""
- if count is None:
- count = await self.get_security_count(market)
- total = count
- key = CacheKey("list", int(market), "", "", start, total or 0, "")
+ records = unpack_payload(await self._cache.get_or_fetch(key, fetch))
+ for r in records:
+ r.symbol = sym.text
+ return records
- def make_cmd(s: int, c: int):
- return GetSecurityListCmd(int(market), s)
-
- spec = PageSpec(page_size=LIST_PAGE, total=total, stop_when_short=True)
-
- async def fetch() -> bytes:
- return await self._fetch_paginated("standard", make_cmd, spec)
-
- payload = await self._cache.get_or_fetch(key, fetch)
- return unpack_payload(payload)
-
- # ------------------------------------------------------------------ #
- # 分时 / 除权除息 / 财务
- # ------------------------------------------------------------------ #
-
- async def get_minute(self, market: Market, code: str, *,
- date: int | None = None) -> list[MinuteBar]:
- """获取分时(date=None=今天;已切换为 MAC 通道 0x122D,可获取完整历史分时)。"""
- if date is None:
- d = _date.today()
- date = d.year * 10000 + d.month * 100 + d.day
- key = CacheKey("minute", int(market), code, "", 0, 0, str(date))
- payload = await self._cache.get_or_fetch(
- key, lambda: self._fetch_minute(market, code, date)
+ async def _ticks_ex(self, sym: Symbol, *, date: int | None, start: int,
+ count: int | None) -> list[TransactionRecord]:
+ from .protocol.commands.ex_ext import (
+ GetExHistoryTransactionDataCmd,
+ GetExTransactionDataCmd,
)
- return unpack_payload(payload)
+ hk = sym.market in _HK_MARKETS
+ page = _EX_TICK_PAGE if hk else _TICK_PAGE
+ out: list[TransactionRecord] = []
+ pos = start
+ remaining = count
+ for _ in range(_ALL_PAGES_CAP):
+ n = page if remaining is None else min(page, remaining)
+ if n <= 0:
+ break
+ if hk:
+ cmd = (GetExHistoryTransactionDataCmd(date, sym.market, sym.code, pos, n)
+ if date else
+ GetExTransactionDataCmd(sym.market, sym.code, pos, n))
+ rows = await self._execute_ex(cmd)
+ out.extend(self._ex_tick(sym, r) for r in rows)
+ else:
+ cmd = MacTransactionCmd(sym.market, sym.code, date or 0, pos, n)
+ rows = await self._execute_ex(cmd)
+ for r in rows:
+ r.symbol = sym.text
+ out.extend(rows)
+ if not rows:
+ break
+ pos += len(rows)
+ if remaining is not None:
+ remaining -= len(rows)
+ if remaining <= 0:
+ break
+ if len(rows) < n:
+ break
+ return out
- async def _fetch_minute(self, market, code: str, date: int) -> bytes:
- from .protocol.commands.mac_tick import MacTickChartCmd
- cmd = MacTickChartCmd(int(market), code, date)
- result = await self._execute_mac(cmd)
- return pack_payload(result)
+ @staticmethod
+ def _ex_tick(sym: Symbol, row: dict) -> TransactionRecord:
+ """扩展市场逐笔原始 dict -> 统一 TransactionRecord。"""
+ minutes = int(row.get("minutes", 0) or 0)
+ fields = {k: float(v) for k, v in row.items()
+ if k in ("zengcang", "momentum") and v is not None}
+ return TransactionRecord(
+ market=sym.market, code=sym.code, symbol=sym.text,
+ time="%02d:%02d" % (minutes // 60, minutes % 60),
+ price=float(row.get("price", 0.0) or 0.0),
+ vol=float(row.get("vol", 0.0) or 0.0),
+ trade_count=0,
+ bs_flag=int(row.get("direction", 0) or 0),
+ fields=fields,
+ )
- async def get_minute_batch(
- self, stocks: list[tuple[Market, str]], *,
- date: int | None = None, concurrency: int = 6,
- ) -> dict[str, list[MinuteBar]]:
- """批量获取分时,自动并发不同服务器。返回 {code: bars}。"""
- sem = asyncio.Semaphore(concurrency)
+ async def get_minutes(
+ self, symbols: str | Sequence[str], *,
+ date: int | None = None, sampling: bool = False, concurrency: int = 6,
+ ) -> list[MinuteBar]:
+ """分时(A股 MAC 0x122D / 扩展市场 0x122D 同构)。
- async def _fetch(mkt: Market, code: str):
+ 参数:
+ date: ``None``=今天;``YYYYMMDD``=历史某日(A股支持历史分时)。
+ sampling: ``True`` 取缩略采样(约240个价格点,无时间;A股 0x254D,
+ 扩展市场同命令),``vol``/``avg_price`` 为 0,点位序号在 ``fields["i"]``。
+
+ 返回:
+ ``list[MinuteBar]``,按入参标的顺序拼接,每条带 ``symbol``/``market``/
+ ``code``/``date``(扩展市场的动量落在 ``fields["momentum"]``)。
+ """
+ syms = parse_symbols(symbols)
+ sem = asyncio.Semaphore(max(1, concurrency))
+
+ async def one(sym: Symbol) -> list[MinuteBar]:
async with sem:
- return code, await self.get_minute(mkt, code, date=date)
+ return await self._minutes_one(sym, date=date, sampling=sampling)
- results = await asyncio.gather(*[_fetch(m, c) for m, c in stocks])
- return {code: bars for code, bars in results}
+ groups = await asyncio.gather(*(one(s) for s in syms))
+ return [m for g in groups for m in g]
- async def get_xdxr(self, market: Market, code: str) -> list[XdxrRecord]:
- key = CacheKey("xdxr", int(market), code)
+ async def _minutes_one(self, sym: Symbol, *, date: int | None,
+ sampling: bool) -> list[MinuteBar]:
+ ymd = _today_ymd() if date is None else int(date)
+ key = CacheKey("minute", sym.market, sym.code,
+ "SAMPLE" if sampling else "", 0, 0, str(ymd))
async def fetch() -> bytes:
- recs = await self._execute_standard(GetXdxrInfoCmd(int(market), code))
- return pack_payload(recs)
+ if sampling:
+ run = self._execute_ex if sym.is_ex else self._execute_mac
+ prices = await run(MacChartSamplingCmd(sym.market, sym.code))
+ bars = [MinuteBar(price=float(p), vol=0.0, symbol=sym.text,
+ market=sym.market, code=sym.code, date=ymd,
+ fields={"i": float(i)})
+ for i, p in enumerate(prices)]
+ return pack_payload(bars)
+ if sym.is_ex:
+ rows = await self._execute_ex(SymbolTickChartCmd(
+ sym.market, sym.code, 0 if date is None else ymd))
+ bars = []
+ for row in rows:
+ minutes = int(row.get("minutes", 0) or 0)
+ bars.append(MinuteBar(
+ price=float(row.get("price", 0.0) or 0.0),
+ vol=float(row.get("vol", 0.0) or 0.0),
+ avg_price=float(row.get("avg", 0.0) or 0.0),
+ hour=minutes // 60, minute=minutes % 60,
+ symbol=sym.text, market=sym.market, code=sym.code, date=ymd,
+ fields={"momentum": float(row.get("momentum", 0.0) or 0.0)},
+ ))
+ return pack_payload(bars)
+ bars = await self._execute_mac(MacTickChartCmd(sym.market, sym.code, ymd))
+ return pack_payload(bars)
- payload = await self._cache.get_or_fetch(key, fetch)
- return unpack_payload(payload)
+ bars = unpack_payload(await self._cache.get_or_fetch(key, fetch))
+ for b in bars:
+ b.symbol = sym.text
+ b.market = sym.market
+ b.code = sym.code
+ b.date = ymd
+ return bars
- async def get_finance(self, market: Market, code: str) -> FinanceRecord | None:
- key = CacheKey("finance", int(market), code)
+ # ================================================================== #
+ # 五、公司信息
+ # ================================================================== #
- async def fetch() -> bytes:
- rec = await self._execute_standard(GetFinanceInfoCmd(int(market), code))
- return pack_payload(rec)
+ async def get_xdxr(self, symbols: str | Sequence[str]) -> list[XdxrRecord]:
+ """除权除息历史,仅 A股。标的用字符串(``"sz000001"``)。"""
+ syms = parse_symbols(symbols)
+ _reject_ex(syms, "除权除息")
+ out: list[XdxrRecord] = []
+ for sym in syms:
+ key = CacheKey("xdxr", sym.market, sym.code)
- payload = await self._cache.get_or_fetch(key, fetch)
- return unpack_payload(payload)
+ async def fetch(s: Symbol = sym) -> bytes:
+ recs = await self._execute_standard(GetXdxrInfoCmd(s.market, s.code))
+ return pack_payload(recs)
- # ------------------------------------------------------------------ #
- # 内部执行
- # ------------------------------------------------------------------ #
+ recs = unpack_payload(await self._cache.get_or_fetch(key, fetch))
+ for r in recs:
+ r.symbol = sym.text
+ out.extend(recs)
+ return out
+
+ async def get_finance(self, symbols: str | Sequence[str]) -> list[FinanceRecord]:
+ """财务快照(仅 A股)。无数据的标的会被跳过(原单标的接口返回 None)。"""
+ syms = parse_symbols(symbols)
+ _reject_ex(syms, "财务快照")
+ out: list[FinanceRecord] = []
+ for sym in syms:
+ key = CacheKey("finance", sym.market, sym.code)
+
+ async def fetch(s: Symbol = sym) -> bytes:
+ rec = await self._execute_standard(GetFinanceInfoCmd(s.market, s.code))
+ return pack_payload(rec)
+
+ rec = unpack_payload(await self._cache.get_or_fetch(key, fetch))
+ if rec is not None:
+ rec.symbol = sym.text
+ out.append(rec)
+ return out
+
+ async def get_price_limits(self, symbol: str, name: str | None = None,
+ pre_close: float | None = None,
+ listed_days: int = 9999
+ ) -> tuple[float | None, float | None]:
+ """涨跌停价(本地计算,无网络;仅 A股,指数/基金返回 (None, None))。"""
+ sym = parse_symbol(symbol)
+ _reject_ex([sym], "涨跌停价")
+ return compute_price_limits(Market(sym.market), sym.code, name, pre_close,
+ listed_days)
+
+ async def get_f10(self, symbol: str, section: str | None = None, *,
+ offset: int = 0, length: int = 65535) -> list | str:
+ """F10 公司资料(仅 A股)。
+
+ ``section=None`` 返回目录(``list[CompanyInfoCategory]``,含 ``name``/
+ ``filename``/``length``);给了 ``section`` 则返回该条目正文
+ (``str``,用 ``offset``/``length`` 分块读取长文)。
+ """
+ sym = parse_symbol(symbol)
+ _reject_ex([sym], "F10")
+ if section is None:
+ return await self._execute_standard(
+ GetCompanyInfoCategoryCmd(sym.market, sym.code))
+ return await self._execute_standard(
+ GetCompanyInfoContentCmd(sym.market, sym.code, section, offset, length))
+
+ # ================================================================== #
+ # 六、市场
+ # ================================================================== #
+
+ async def get_market_stat(self) -> MarketStat:
+ """全市场统计(涨跌家数/总成交额/总市值/涨跌停家数,A股)。"""
+ q = await self.get_quotes(["sh880005", "sh880001", "sh880006"])
+ stat = MarketStat()
+ qmap = {x.code: x for x in q}
+ q5 = qmap.get("880005")
+ if q5:
+ stat.up_count = int(q5.price * 10)
+ stat.down_count = int(q5.open * 10)
+ stat.flat_count = int(q5.low * 10)
+ stat.total_count = int(q5.high * 10)
+ stat.total_amount = q5.amount
+ stat.total_vol = q5.vol
+ q1 = qmap.get("880001")
+ if q1:
+ stat.total_market_cap = q1.price * 1e10
+ q6 = qmap.get("880006")
+ if q6:
+ stat.limit_up_count = int(q6.price * 10)
+ stat.limit_down_count = int(q6.open * 10)
+ return stat
+
+ async def get_unusual(self, market: str = "all", *, start: int = 0,
+ count: int = 600) -> list[UnusualItem]:
+ """市场异动(仅 A股;``market="all"`` = 深市 + 沪市)。"""
+ markets = [mkt for mkt, ch in market_targets(market) if ch == "cn"]
+ out: list[UnusualItem] = []
+ for mkt in markets:
+ items = await self._execute_mac(MacUnusualCmd(mkt, start, count))
+ for it in items:
+ it.symbol = format_symbol(it.market, it.code)
+ out.extend(items)
+ return out
+
+ async def get_server_info(self) -> ServerInfo:
+ """服务器交易时段信息(当日/上一交易日/交易时段)。"""
+ return await self._execute_mac(MacServerInfoCmd())
+
+ async def get_kline_offset(self, offset: int = 0, count: int = 1) -> tuple[int, int]:
+ """K线偏移信息(MAC 0x124A,返回 (总根数, 本次返回数))。"""
+ return await self._execute_mac(MacKlineOffsetCmd(offset, count))
+
+ # ================================================================== #
+ # 七、板块
+ # ================================================================== #
+
+ @staticmethod
+ def _board_type(kind: str | int) -> int:
+ if isinstance(kind, int):
+ return kind
+ key = str(kind).strip().lower()
+ table = {"all": 0, "industry": 1, "concept": 2, "style": 3}
+ if key not in table:
+ raise ValueError(
+ f"未知板块类别: {kind}(可选: {'/'.join(table)} 或数字)")
+ return table[key]
+
+ async def get_boards(self, kind: str = "all", *, count: int = 10000) -> list[BoardInfo]:
+ """板块列表(``kind``: ``all``/``industry``/``concept``/``style``,也接受数字)。
+
+ 每条除板块本身外还带领涨股信息(``symbol_*`` 字段)。
+ """
+ board_type = self._board_type(kind)
+ items: list[BoardInfo] = []
+ start = 0
+ while start < count:
+ # 沿用既有分页步进(实盘未校验,改动风险大于收益)
+ batch = await self._execute_mac(MacBoardListCmd(board_type, start, 150))
+ if not batch:
+ break
+ items.extend(batch)
+ start += len(batch) // 2
+ if len(batch) < 150:
+ break
+ for b in items:
+ b.symbol = format_symbol(b.market, b.code)
+ return items
+
+ async def get_board_members(self, board: str, count: int = 100000,
+ sort_type: int = 0, *,
+ fields: Sequence[int] | None = None
+ ) -> list[SecurityQuote]:
+ """板块成分股报价(``board`` 如 ``"881001"``;返回归一报价模型)。
+
+ ``fields`` 可加取自定义字段位(如 ``[0x38]`` 主力净流入),默认取基础字段位
+ (昨收/开/高/低/现价/量/量比/额),全部字段位同时保留在 ``.fields``。
+ """
+ board_code = self._convert_board_code(parse_symbol(board).code)
+ bits = [int(b) for b in fields] if fields else list(_QUOTE_BITS)
+ items: list[SecurityQuote] = []
+ start = 0
+ while start < count:
+ batch = await self._execute_mac(MacBoardMembersQuotesCmd(
+ board_code, sort_type=sort_type, start=start,
+ page_size=_QUOTE_PAGE, bits=bits))
+ if not batch:
+ break
+ items.extend(_quote_from_member(m) for m in batch)
+ start += len(batch)
+ if len(batch) < _QUOTE_PAGE:
+ break
+ return items
+
+ async def get_board_of(self, symbols: str | Sequence[str]) -> list[BelongBoard]:
+ """个股所属板块(仅 A股;``symbol`` 记录被查询的个股)。"""
+ syms = parse_symbols(symbols)
+ _reject_ex(syms, "个股所属板块")
+ out: list[BelongBoard] = []
+ for sym in syms:
+ items = await self._execute_mac(MacBelongBoardCmd(sym.market, sym.code))
+ for it in items:
+ it.symbol = sym.text
+ out.extend(items)
+ return out
+
+ async def get_board_summary(self, board: str) -> dict:
+ """板块汇总:成分数/总成交额/主力净流入/涨跌家数。"""
+ # 0x38 = 主力净流入(基础字段位之外额外取)
+ members = await self.get_board_members(board, fields=_QUOTE_BITS + [0x38])
+ amount = sum(q.amount for q in members)
+ main_net = sum(float(q.fields.get("0x38", 0.0)) for q in members)
+ up = sum(1 for q in members if q.pre_close and q.price > q.pre_close)
+ down = sum(1 for q in members if q.pre_close and q.price < q.pre_close)
+ return {
+ "member_count": len(members),
+ "amount": amount,
+ "main_net_amount": main_net,
+ "up_count": up,
+ "down_count": down,
+ }
+
+ async def get_board_ranking(self, kind: str = "industry", *,
+ top_n: int = 20) -> list[dict]:
+ """板块当日涨跌幅排行(基于板块报价的现价/昨收)。"""
+ return self._rank_boards(await self.get_boards(kind, count=200), top_n)
+
+ async def get_board_change_ranking(self, kind: str = "industry", *,
+ days: int = 20, top_n: int = 20) -> list[dict]:
+ """板块 N 日涨跌幅排行(基于板块指数K线)。"""
+ boards = self._board_codes(await self.get_boards(kind, count=200))
+ result: list[dict] = []
+ for code, b in list(boards.items())[:top_n * 3]:
+ try:
+ bars = await self.get_bars(format_symbol(b.market, code),
+ KlinePeriod.DAY, count=days + 5,
+ adjust=Adjust.NONE)
+ except Exception:
+ continue
+ if len(bars) < 2:
+ continue
+ first, last = bars[0].close, bars[-1].close
+ if first <= 1.0: # 过滤异常基数(板块指数首根过小)
+ continue
+ result.append({"code": code, "name": b.name, "close_end": last,
+ "close_start": first,
+ "change_pct": round((last / first - 1) * 100, 2)})
+ result.sort(key=lambda x: x["change_pct"], reverse=True)
+ return result[:top_n]
+
+ @staticmethod
+ def _board_codes(boards: list[BoardInfo]) -> dict[str, BoardInfo]:
+ """去重取板块段(board_list 返回板块+领涨股混合,只保留 881xxx)。"""
+ out: dict[str, BoardInfo] = {}
+ for b in boards:
+ if not b.code.startswith("88"):
+ continue
+ if b.code not in out or len(b.name) < len(out[b.code].name):
+ out[b.code] = b
+ return out
+
+ @classmethod
+ def _rank_boards(cls, boards: list[BoardInfo], top_n: int) -> list[dict]:
+ result: list[dict] = []
+ for code, b in list(cls._board_codes(boards).items())[:top_n * 3]:
+ if b.pre_close <= 0:
+ continue
+ result.append({"code": code, "name": b.name, "price": b.price,
+ "change_pct": round((b.price / b.pre_close - 1) * 100, 2)})
+ result.sort(key=lambda x: x["change_pct"], reverse=True)
+ return result[:top_n]
+
+ # ================================================================== #
+ # 八、服务器文件(原始字节 + 解析)
+ # ================================================================== #
+
+ async def get_file(self, name: str) -> bytes:
+ """下载服务器文件原始字节(按文件名自动选通道)。
+
+ - ``block_*.dat`` —— 板块文件(标准 0x1869/0x186A,先查元数据再分块)
+ - ``tdxhy.cfg`` / ``tdxfin/*`` —— 报告财务文件(标准 0x06B9,分块)
+ - 其他 —— MAC 远程文件(0x1215 查元数据 + 0x1217 分块)
+
+ 通常不用直接调它:板块/行业/财报都有解析好的 ``get_*_parsed``。
+ """
+ base = str(name).strip()
+ low = base.lower()
+ if low.startswith("block_"):
+ meta = await self._execute_standard(GetBlockInfoMetaCmd(base))
+ if meta is None:
+ return b""
+ return await self._download(
+ self._execute_standard,
+ lambda pos, idx, n: GetBlockInfoCmd(base, pos, n), meta.size)
+ if low.startswith("tdx"):
+ return await self._download(
+ self._execute_standard,
+ lambda pos, idx, n: GetReportFileCmd(base, pos, n), 0)
+ meta = await self._execute_mac(MacFileListCmd(base))
+ size = meta.size if meta else 0
+ return await self._download(
+ self._execute_mac,
+ lambda pos, idx, n: MacFileDownloadCmd(base, idx, pos, n), size)
+
+ async def _download(self, run, make_cmd, size: int, *,
+ chunk: int = 30000) -> bytes:
+ """分块下载(``size<=0`` 时翻到空块为止)。"""
+ data = bytearray()
+ pos = 0
+ idx = 1
+ while size <= 0 or pos < size:
+ part = await run(make_cmd(pos, idx, chunk))
+ if not part:
+ break
+ data.extend(part)
+ pos += len(part)
+ idx += 1
+ if len(part) < chunk:
+ break
+ return bytes(data)
+
+ async def get_block_parsed(self, filename: str) -> list[TdxBlock]:
+ """板块文件 -> ``list[TdxBlock]``(板块名/类别/成分股)。
+
+ 常用文件名:``block_zs.dat``(行业)/ ``block_gn.dat``(概念)/ ``block_fg.dat``(风格)。
+ category 由文件名推断(0=行业 1=地域 2=概念 3=风格)。
+ """
+ from .codec.block import parse_block_dat
+ return parse_block_dat(await self.get_file(filename), filename)
+
+ async def get_industry_map(self) -> dict[str, IndustryInfo]:
+ """tdxhy.cfg -> ``{6位代码: IndustryInfo}``(通达信 + 申万行业)。"""
+ from .codec.industry import parse_tdxhy_cfg
+ return parse_tdxhy_cfg(await self.get_file("tdxhy.cfg"))
+
+ async def get_financial_file_infos(self) -> list[FinancialFileInfo]:
+ """tdxfin/gpcw.txt -> ``list[FinancialFileInfo]``(文件名/MD5/大小)。"""
+ from .codec.financial import parse_financial_file_list
+ return parse_financial_file_list(await self.get_file("tdxfin/gpcw.txt"))
+
+ async def get_financial_records_parsed(self, filename: str) -> list[FinancialRecord]:
+ """财务 zip(``tdxfin/gpcw*.zip``)解压解析 -> ``list[FinancialRecord]``。
+
+ 报告期优先取文件名中的 8 位日期,缺失时回退到 .dat 头部内嵌值。
+ """
+ import io
+ import re
+ import zipfile
+
+ from .codec.financial import parse_financial_dat
+
+ zip_data = await self.get_file(filename)
+ if not zip_data:
+ return []
+ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
+ dat_names = [n for n in zf.namelist() if n.endswith(".dat")]
+ if not dat_names:
+ return []
+ dat_data = zf.read(dat_names[0])
+ match = re.search(r"(\d{8})", filename)
+ report_date = int(match.group(1)) if match else 0
+ return parse_financial_dat(dat_data, report_date)
+
+ # ================================================================== #
+ # 内部执行(连接池 + 失败换连接 + 分页)
+ # ================================================================== #
async def _execute_standard(self, cmd) -> object:
"""标准通道单命令执行(带连接池+失败换连接)。"""
@@ -627,48 +1314,6 @@ class TdxData:
finally:
await self._std_pool.release(pc)
- async def _fetch_paginated(self, route: str, make_cmd, spec: PageSpec,
- *, concurrency: int | None = None) -> bytes:
- pag = self._paginator_mac if route == "mac" else self._paginator_std
- result = await pag.fetch_all(make_cmd, spec, concurrency=concurrency)
- return pack_payload(result)
-
- async def _fetch_paginated_list(self, route: str, make_cmd, spec: PageSpec,
- *, concurrency: int | None = None) -> list:
- """分页拉取,直接返回列表(避免 pack/unpack 序列化开销)。"""
- pag = self._paginator_mac if route == "mac" else self._paginator_std
- return await pag.fetch_all(make_cmd, spec, concurrency=concurrency)
-
- async def _fetch_mac_kline_serial(self, make_cmd, total: int, *,
- start: int = 0,
- page_size: int = 700) -> bytes:
- """MAC K线串行分页(单连接),避免多服务器数据深度不一致导致空洞。"""
- pc = await self._mac_pool.acquire()
- try:
- result: list = []
- while start < total:
- cnt = min(page_size, total - start)
- cmd = make_cmd(start, cnt)
- for attempt in range(3):
- try:
- bars = await pc.execute(cmd)
- break
- except Exception:
- if attempt >= 2:
- raise
- await self._mac_pool.release(pc, broken=True)
- pc = await self._mac_pool.acquire()
- bars = []
- if not bars:
- break
- result.extend(bars)
- start += len(bars)
- if len(bars) < cnt:
- break
- return pack_payload(result)
- finally:
- await self._mac_pool.release(pc)
-
async def _execute_mac(self, cmd) -> object:
"""MAC通道单命令执行(带连接池+失败换连接)。"""
pc = await self._mac_pool.acquire()
@@ -705,11 +1350,52 @@ class TdxData:
finally:
await self._ex_pool.release(conn)
+ async def _fetch_paginated(self, route: str, make_cmd, spec: PageSpec,
+ *, concurrency: int | None = None) -> bytes:
+ pag = self._paginator_mac if route == "mac" else self._paginator_std
+ result = await pag.fetch_all(make_cmd, spec, concurrency=concurrency)
+ return pack_payload(result)
+
+ async def _fetch_paginated_list(self, route: str, make_cmd, spec: PageSpec,
+ *, concurrency: int | None = None) -> list:
+ """分页拉取,直接返回列表(避免 pack/unpack 序列化开销)。"""
+ pag = self._paginator_mac if route == "mac" else self._paginator_std
+ return await pag.fetch_all(make_cmd, spec, concurrency=concurrency)
+
+ async def _fetch_mac_bars_serial(self, make_cmd, total: int, *,
+ start: int = 0, page_size: int = 700) -> bytes:
+ """MAC K线串行分页(单连接),避免多服务器数据深度不一致导致空洞。"""
+ pc = await self._mac_pool.acquire()
+ try:
+ result: list = []
+ while start < total:
+ cnt = min(page_size, total - start)
+ cmd = make_cmd(start, cnt)
+ for attempt in range(3):
+ try:
+ bars = await pc.execute(cmd)
+ break
+ except Exception:
+ if attempt >= 2:
+ raise
+ await self._mac_pool.release(pc, broken=True)
+ pc = await self._mac_pool.acquire()
+ bars = []
+ if not bars:
+ break
+ result.extend(bars)
+ start += len(bars)
+ if len(bars) < cnt:
+ break
+ return pack_payload(result)
+ finally:
+ await self._mac_pool.release(pc)
+
async def _fetch_paginated_ex(self, make_cmd, spec: PageSpec) -> list:
"""EX通道分页拉取(串行逐页,扩展市场页数少)。"""
result = []
start = 0
- for page in range(spec.max_pages if spec.max_pages else 64):
+ for _ in range(spec.max_pages if spec.max_pages else 64):
if spec.total is not None and start >= spec.total:
break
cnt = spec.page_size
@@ -724,212 +1410,6 @@ class TdxData:
break
return result
- # ------------------------------------------------------------------ #
- # MAC 扩展接口:板块/竞价/异动/快照/资金流/服务器/扩展市场
- # ------------------------------------------------------------------ #
-
- async def get_board_list(self, board_type: int = 0, count: int = 10000) -> list:
- """板块列表(board_type: 0=全部 1=行业 2=概念)。"""
- from .protocol.commands.mac_ext import MacBoardListCmd
- items: list = []
- start = 0
- while start < count:
- batch = await self._execute_mac(MacBoardListCmd(board_type, start, 150))
- if not batch:
- break
- items.extend(batch)
- start += len(batch) // 2
- if len(batch) < 150:
- break
- return items
-
- async def get_board_members(self, board_symbol: str, count: int = 100000,
- sort_type: int = 0) -> list:
- """板块成分股报价(board_symbol 如 881001)。"""
- from .protocol.commands.mac_ext import MacBoardMembersQuotesCmd
- board_code = self._convert_board_code(board_symbol)
- items: list = []
- start = 0
- while start < count:
- batch = await self._execute_mac(
- MacBoardMembersQuotesCmd(board_code, sort_type=sort_type, start=start, page_size=80))
- if not batch:
- break
- items.extend(batch)
- start += len(batch)
- if len(batch) < 80:
- break
- return items
-
- async def get_belong_board(self, market: Market, code: str) -> list:
- """个股所属板块。"""
- from .protocol.commands.mac_ext import MacBelongBoardCmd
- return await self._execute_mac(MacBelongBoardCmd(int(market), code))
-
- async def get_auction(self, market: Market, code: str) -> list:
- """集合竞价。"""
- from .protocol.commands.mac_ext import MacAuctionCmd
- return await self._execute_mac(MacAuctionCmd(int(market), code))
-
- async def get_unusual(self, market: Market, start: int = 0, count: int = 600) -> list:
- """市场异动。"""
- from .protocol.commands.mac_ext import MacUnusualCmd
- return await self._execute_mac(MacUnusualCmd(int(market), start, count))
-
- async def get_symbol_info(self, market: Market, code: str):
- """个股特征快照。"""
- from .protocol.commands.mac_ext import MacSymbolInfoCmd
- return await self._execute_mac(MacSymbolInfoCmd(int(market), code))
-
- async def _ex_find_market_offset(self, market: int) -> int:
- """二分定位指定市场在全局商品列表中的起始偏移。"""
- from .protocol.commands.ex_ext import (
- GetExInstrumentCountCmd, GetExInstrumentInfoCmd)
- total = await self._execute_ex(GetExInstrumentCountCmd())
- if total == 0:
- return -1
- lo, hi = 0, total
- while lo < hi:
- mid = (lo + hi) // 2
- items = await self._execute_ex(GetExInstrumentInfoCmd(0, mid, 1))
- if not items:
- hi = mid
- continue
- m = int(items[0]["market"])
- if m < market:
- lo = mid + 1
- else:
- hi = mid
- return lo
-
- async def get_goods_list(self, market: int, start: int = 0,
- count: int = 100) -> list[dict]:
- """扩展市场商品列表(EX通道 0x23F5,二分定位市场边界+过滤)。"""
- from .protocol.commands.ex_ext import (
- GetExInstrumentCountCmd, GetExInstrumentInfoCmd)
- offset = await self._ex_find_market_offset(market)
- if offset < 0:
- return []
- items: list[dict] = []
- pos = offset + start
- total = await self._execute_ex(GetExInstrumentCountCmd())
- while pos < total and len(items) < count:
- page = await self._execute_ex(GetExInstrumentInfoCmd(0, pos, 1000))
- if not page:
- break
- for g in page:
- if int(g["market"]) == market:
- items.append(g)
- if len(items) >= count:
- break
- elif int(g["market"]) > market:
- return items
- pos += len(page)
- return items
-
- async def get_goods_count(self, market: int | None = None) -> int:
- """扩展市场商品数量(EX通道 0x23F0)。
- market=None 返回全市场总数;指定市场=二分定位偏移+扫描计数。"""
- from .protocol.commands.ex_ext import (
- GetExInstrumentCountCmd, GetExInstrumentInfoCmd)
- total = await self._execute_ex(GetExInstrumentCountCmd())
- if market is None:
- return int(total)
- offset = await self._ex_find_market_offset(market)
- if offset < 0:
- return 0
- n = 0
- pos = offset
- while pos < total:
- page = await self._execute_ex(GetExInstrumentInfoCmd(0, pos, 1000))
- if not page:
- break
- for g in page:
- m = int(g["market"])
- if m == market:
- n += 1
- elif m > market:
- return n
- pos += len(page)
- return n
-
- async def get_goods_quotes(self, stocks: list[tuple[int, str]],
- bits: list[int] | None = None) -> list[MemberQuote]:
- """扩展市场报价(EX通道 0x122B,stocks=[(ExMarket, code)])。"""
- from .protocol.commands.mac_ext import MacSymbolQuotesCmd
- return await self._execute_ex(MacSymbolQuotesCmd(stocks, bits))
-
- async def get_goods_quotes_list(self, market: int, count: int = 80) -> list[MemberQuote]:
- """扩展市场报价列表(goods_list + 报价组合)。"""
- goods = await self.get_goods_list(market, 0, min(count, 80))
- if not goods:
- return []
- stocks = [(int(g["market"] or market), g["code"]) for g in goods[:80]]
- return await self.get_goods_quotes(stocks)
-
- async def get_goods_chart_sampling(self, market: int, code: str) -> list[float]:
- """扩展市场分时采样(EX通道 0x254D)。"""
- from .protocol.commands.mac_ext import MacChartSamplingCmd
- return await self._execute_ex(MacChartSamplingCmd(market, code))
-
- async def get_goods_tick_chart(self, market: int, code: str,
- ymd: int = 0) -> list[dict]:
- """扩展市场分时tick(EX通道 0x122D)。"""
- from .protocol.commands.ex_ext import SymbolTickChartCmd
- return await self._execute_ex(SymbolTickChartCmd(market, code, ymd))
-
- async def get_goods_transaction(self, market: int, code: str, *,
- ymd: int = 0, start: int = 0,
- count: int = 1800) -> list[dict]:
- """扩展市场逐笔(港股0x23FC/0x2406 16B/条;其他0x122F 18B/条)。"""
- hk_markets = {27, 31, 48, 49, 71, 98}
- if market in hk_markets:
- from .protocol.commands.ex_ext import (
- GetExHistoryTransactionDataCmd, GetExTransactionDataCmd)
- if ymd:
- return await self._execute_ex(
- GetExHistoryTransactionDataCmd(ymd, market, code, start, count))
- return await self._execute_ex(
- GetExTransactionDataCmd(market, code, start, count))
- from .protocol.commands.transaction import MacTransactionCmd
- items = await self._execute_ex(
- MacTransactionCmd(market, code, ymd, start, count))
- return [dict(t._asdict()) if hasattr(t, "_asdict") else t for t in items]
-
- async def get_goods_transaction_all(self, market: int, code: str,
- ymd: int = 0) -> list[dict]:
- """扩展市场(仅港股)全部逐笔,自动翻页(最多50页/9万条)。"""
- hk_markets = {27, 31, 48, 49, 71, 98}
- if market not in hk_markets:
- raise ValueError("仅港股支持全量逐笔(get_goods_transaction_all)")
- out: list[dict] = []
- start = 0
- for _ in range(50):
- page = await self.get_goods_transaction(market, code, ymd=ymd,
- start=start, count=1800)
- if not page:
- break
- out.extend(page)
- start += len(page)
- if len(page) < 1800:
- break
- return out
-
- async def get_server_info(self):
- """服务器交易时段信息。"""
- from .protocol.commands.mac_ext import MacServerInfoCmd
- return await self._execute_mac(MacServerInfoCmd())
-
- async def get_kline_offset(self, offset: int = 0, count: int = 1) -> tuple[int, int]:
- """K线偏移信息。"""
- from .protocol.commands.mac_ext import MacKlineOffsetCmd
- return await self._execute_mac(MacKlineOffsetCmd(offset, count))
-
- async def get_capital_flow(self, market: Market, code: str):
- """个股资金流向。"""
- from .protocol.commands.mac_ext import MacCapitalFlowCmd
- return await self._execute_mac(MacCapitalFlowCmd(int(market), code))
-
@staticmethod
def _convert_board_code(board_symbol: str) -> int:
"""板块代码转换(881001→20686 等,参照 easy-tdx)。"""
@@ -949,343 +1429,256 @@ class TdxData:
return 31000 + int(s)
return int(s)
- # ------------------------------------------------------------------ #
- # 标准通道扩展:F10/板块文件/市场统计/涨跌停价
- # ------------------------------------------------------------------ #
+ # ================================================================== #
+ # 九、旧接口(deprecated 别名;入参沿用旧口径,1.0 移除)
+ # ================================================================== #
- async def get_company_info_category(self, market: Market, code: str) -> list:
- """F10目录。"""
- from .protocol.commands.std_ext import GetCompanyInfoCategoryCmd
- return await self._execute_standard(GetCompanyInfoCategoryCmd(market, code))
+ async def get_kline(self, market, code, period, *, start: int = 0,
+ count: int = 800, adjust: Adjust | None = None,
+ start_date: datetime | None = None,
+ end_date: datetime | None = None) -> list[SecurityBar]:
+ """已废弃 -> :meth:`get_bars`。"""
+ _deprecated("get_kline", "get_bars")
+ return await self.get_bars(format_symbol(int(market), code), period,
+ start=start, count=count, adjust=adjust,
+ start_date=start_date, end_date=end_date)
- async def get_company_info_content(self, market: Market, code: str,
- filename: str, offset: int = 0,
- length: int = 65535) -> str:
- """F10内容(分块读取)。"""
- from .protocol.commands.std_ext import GetCompanyInfoContentCmd
- return await self._execute_standard(
- GetCompanyInfoContentCmd(market, code, filename, offset, length))
+ async def get_kline_since(self, market, code, period, since: datetime,
+ adjust: Adjust | None = None) -> list[SecurityBar]:
+ """已废弃 -> :meth:`get_bars`(``start_date=since``)。"""
+ _deprecated("get_kline_since", "get_bars(start_date=...)")
+ return await self.get_bars(format_symbol(int(market), code), period,
+ start_date=since, adjust=adjust)
- async def get_block_info(self, filename: str) -> bytes:
- """板块文件(先查元数据再下载全部)。"""
- from .protocol.commands.std_ext import GetBlockInfoCmd, GetBlockInfoMetaCmd
- meta = await self._execute_standard(GetBlockInfoMetaCmd(filename))
- if meta is None:
- return b""
- data = bytearray()
- pos = 0
- chunk = 30000
- while pos < meta.size:
- part = await self._execute_standard(GetBlockInfoCmd(filename, pos, chunk))
- if not part:
- break
- data.extend(part)
- pos += len(part)
- if len(part) < chunk:
- break
- return bytes(data)
-
- async def get_price_limits(self, market: Market, code: str, name: str,
- pre_close: float, listed_days: int = 9999) -> tuple[float | None, float | None]:
- """涨跌停价(本地计算)。"""
- from .protocol.commands.std_ext import compute_price_limits
- return compute_price_limits(market, code, name, pre_close, listed_days)
-
- async def get_market_stat(self):
- """全市场统计(用报价查上证指数880005/880001/880006组合)。"""
- from .protocol.commands.std_ext import MarketStat
- # 上证指数代码
- q = await self.get_quotes([(Market.SH, "880005"), (Market.SH, "880001"),
- (Market.SH, "880006")])
- stat = MarketStat()
- qmap = {q2.code: q2 for q2 in q}
- q5 = qmap.get("880005")
- if q5:
- stat.up_count = int(q5.price * 10)
- stat.down_count = int(q5.open * 10)
- stat.flat_count = int(q5.low * 10)
- stat.total_count = int(q5.high * 10)
- stat.total_amount = q5.amount
- stat.total_vol = q5.vol
- q1 = qmap.get("880001")
- if q1:
- stat.total_market_cap = q1.price * 1e10
- q6 = qmap.get("880006")
- if q6:
- stat.limit_up_count = int(q6.price * 10)
- stat.limit_down_count = int(q6.open * 10)
- return stat
-
- # ------------------------------------------------------------------ #
- # MAC 自定义字段报价 / 分类列表
- # ------------------------------------------------------------------ #
-
- async def get_stock_quotes(self, stocks: list[tuple[Market, str]],
- bits: list[int] | None = None) -> list:
- """MAC自定义字段报价(≤80只/次,bits=FieldBit列表)。"""
- from .protocol.commands.mac_ext import MacSymbolQuotesCmd
- out: list = []
- for i in range(0, len(stocks), 80):
- batch = [(int(m), c) for m, c in stocks[i:i + 80]]
- out.extend(await self._execute_mac(MacSymbolQuotesCmd(batch, bits)))
+ async def get_kline_batch(self, stocks, period, *, start: int = 0,
+ count: int = 800, adjust: Adjust | None = None,
+ concurrency: int = 6) -> dict[str, list[SecurityBar]]:
+ """已废弃 -> :meth:`get_bars`(返回值由 ``{code: bars}`` 变为平铺列表)。"""
+ _deprecated("get_kline_batch", "get_bars")
+ bars = await self.get_bars(
+ [format_symbol(int(m), c) for m, c in stocks], period, start=start,
+ count=count, adjust=adjust, concurrency=concurrency)
+ out: dict[str, list[SecurityBar]] = {}
+ for b in bars:
+ out.setdefault(b.code, []).append(b)
return out
+ async def get_index_kline(self, market, code, period, *, start: int = 0,
+ count: int = 800) -> list[SecurityBar]:
+ """已废弃 -> :meth:`get_bars`(指数自动识别,无需单独接口)。"""
+ _deprecated("get_index_kline", "get_bars")
+ return await self.get_bars(format_symbol(int(market), code), period,
+ start=start, count=count)
+
+ async def get_stock_kline_with_indicators(self, market, code, indicators, *,
+ period: KlinePeriod = KlinePeriod.DAY,
+ count: int = 30,
+ adjust: Adjust | None = None,
+ params: dict | None = None) -> dict:
+ """已废弃 -> :meth:`get_indicators`。"""
+ _deprecated("get_stock_kline_with_indicators", "get_indicators")
+ sets = await self.get_indicators(format_symbol(int(market), code), indicators,
+ period=period, count=count, adjust=adjust,
+ params=params)
+ one = sets[0]
+ return {"bars": one.bars, "indicators": one.indicators}
+
+ async def get_stock_quotes(self, stocks, bits=None) -> list[SecurityQuote]:
+ """已废弃 -> :meth:`get_quotes`(``fields=bits``)。"""
+ _deprecated("get_stock_quotes", "get_quotes")
+ return await self.get_quotes([format_symbol(int(m), c) for m, c in stocks],
+ fields=bits)
+
async def get_stock_quotes_list(self, category: int, *, start: int = 0,
- count: int = 80, sort_type: int = 0) -> list:
- """市场分类报价列表(category: 0=沪A 2=深A 6=全A 8=科创 14=创业板等)。"""
- from .protocol.commands.mac_ext import MacBoardMembersQuotesCmd
- items: list = []
- offset = start
- while len(items) < count:
- batch = await self._execute_mac(
- MacBoardMembersQuotesCmd(category, sort_type=sort_type,
- start=offset, page_size=min(80, count - len(items))))
- if not batch:
- break
- items.extend(batch)
- offset += len(batch)
- if len(batch) < 80:
- break
- return items
+ count: int = 80, sort_type: int = 0
+ ) -> list[SecurityQuote]:
+ """已废弃 -> :meth:`get_board_members`(分类码 = 板块码口径)。"""
+ _deprecated("get_stock_quotes_list", "get_board_members")
+ return await self._board_members_raw(category, start=start, count=count,
+ sort_type=sort_type)
- # ------------------------------------------------------------------ #
- # 远程文件
- # ------------------------------------------------------------------ #
+ async def get_transactions(self, market, code, *, date: int | None = None,
+ start: int = 0, count: int = 2000
+ ) -> list[TransactionRecord]:
+ """已废弃 -> :meth:`get_ticks`。"""
+ _deprecated("get_transactions", "get_ticks")
+ return await self.get_ticks(format_symbol(int(market), code), date=date,
+ start=start, count=count)
- async def get_file_meta(self, filename: str):
- """远程文件元信息(MAC 0x1215)。"""
- from .protocol.commands.mac_ext import MacFileListCmd
- return await self._execute_mac(MacFileListCmd(filename))
+ async def get_minute(self, market, code, *, date: int | None = None
+ ) -> list[MinuteBar]:
+ """已废弃 -> :meth:`get_minutes`。"""
+ _deprecated("get_minute", "get_minutes")
+ return await self.get_minutes(format_symbol(int(market), code), date=date)
- async def download_file(self, filename: str, filesize: int = 0) -> bytes:
- """下载完整远程文件(MAC 0x1217,分块)。"""
- from .protocol.commands.mac_ext import MacFileDownloadCmd
- if filesize <= 0:
- meta = await self.get_file_meta(filename)
- filesize = meta.size if meta else 0
- data = bytearray()
- pos = 0
- idx = 1
- chunk = 30000
- while pos < filesize:
- part = await self._execute_mac(
- MacFileDownloadCmd(filename, idx, pos, chunk))
- if not part:
- break
- data.extend(part)
- pos += len(part)
- idx += 1
- if len(part) < chunk:
- break
- return bytes(data)
+ async def get_minute_batch(self, stocks, *, date: int | None = None,
+ concurrency: int = 6) -> dict[str, list[MinuteBar]]:
+ """已废弃 -> :meth:`get_minutes`(返回值由 ``{code: bars}`` 变为平铺列表)。"""
+ _deprecated("get_minute_batch", "get_minutes")
+ bars = await self.get_minutes([format_symbol(int(m), c) for m, c in stocks],
+ date=date, concurrency=concurrency)
+ out: dict[str, list[MinuteBar]] = {}
+ for b in bars:
+ out.setdefault(b.code, []).append(b)
+ return out
- async def get_report_file(self, filename: str) -> bytes:
- """下载报告/财务文件(标准 0x06B9,分块)。"""
- from .protocol.commands.std_ext import GetReportFileCmd
- data = bytearray()
- pos = 0
- chunk = 30000
- while True:
- part = await self._execute_standard(GetReportFileCmd(filename, pos, chunk))
- if not part:
- break
- data.extend(part)
- pos += len(part)
- if len(part) < chunk:
- break
- return bytes(data)
+ async def get_chart_sampling(self, market, code) -> list[float]:
+ """已废弃 -> :meth:`get_minutes`(``sampling=True``)。"""
+ _deprecated("get_chart_sampling", "get_minutes(sampling=True)")
+ bars = await self.get_minutes(format_symbol(int(market), code), sampling=True)
+ return [b.price for b in bars]
+
+ async def get_security_count(self, market) -> int:
+ """已废弃 -> ``len(get_universe(...))``。"""
+ _deprecated("get_security_count", "get_universe")
+ return await self._security_count(int(market))
+
+ async def get_security_list(self, market, *, start: int = 0,
+ count: int | None = None) -> list[SecurityInfo]:
+ """已废弃 -> :meth:`get_universe`(本地切片 ``[start:start+count]``)。"""
+ _deprecated("get_security_list", "get_universe")
+ items = await self.get_universe(market_name(int(market)))
+ return items[start:] if count is None else items[start:start + count]
+
+ async def get_security_list_all(self, market) -> list[SecurityInfo]:
+ """已废弃 -> :meth:`get_universe`。"""
+ _deprecated("get_security_list_all", "get_universe")
+ return await self.get_universe(market_name(int(market)))
async def get_financial_file_list(self) -> list[str]:
- """财务文件列表(tdxfin/gpcw.txt,返回 文件名,md5,size 行列表)。"""
- raw = await self.get_report_file("tdxfin/gpcw.txt")
+ """已废弃 -> :meth:`get_financial_file_infos`(返回 ``FinancialFileInfo``)。"""
+ _deprecated("get_financial_file_list", "get_financial_file_infos")
+ raw = await self.get_file("tdxfin/gpcw.txt")
text = raw.decode("gbk", errors="replace")
return [l.strip() for l in text.splitlines() if l.strip()]
async def get_financial_records(self, filename: str) -> bytes:
- """财务文件内容(tdxfin/gpcw*.zip,返回原始字节)。"""
- return await self.get_report_file(filename)
+ """已废弃 -> :meth:`get_financial_records_parsed`。"""
+ _deprecated("get_financial_records", "get_financial_records_parsed")
+ return await self.get_file(filename)
- # ------------------------------------------------------------------ #
- # 服务器文件解析(板块 / 行业分类 / 历史专业财报)
- # ------------------------------------------------------------------ #
+ async def get_company_info_category(self, market, code) -> list:
+ """已废弃 -> :meth:`get_f10`。"""
+ _deprecated("get_company_info_category", "get_f10")
+ return await self.get_f10(format_symbol(int(market), code))
- async def get_block_parsed(self, filename: str) -> list[TdxBlock]:
- """下载并解析板块文件,返回 TdxBlock 列表。
+ async def get_company_info_content(self, market, code, filename: str,
+ offset: int = 0, length: int = 65535) -> str:
+ """已废弃 -> :meth:`get_f10`。"""
+ _deprecated("get_company_info_content", "get_f10")
+ return await self.get_f10(format_symbol(int(market), code), filename,
+ offset=offset, length=length)
- 常用文件名:``block_zs.dat``(行业)/ ``block_gn.dat``(概念)/ ``block_fg.dat``(风格)。
- category 由文件名推断(0=行业 2=概念 3=风格)。
- """
- from .codec.block import parse_block_dat
- return parse_block_dat(await self.get_block_info(filename), filename)
+ async def get_block_info(self, filename: str) -> bytes:
+ """已废弃 -> :meth:`get_file`。"""
+ _deprecated("get_block_info", "get_file")
+ return await self.get_file(filename)
- async def get_industry_map(self) -> dict[str, IndustryInfo]:
- """下载并解析 tdxhy.cfg,返回 ``{6位代码: IndustryInfo}``(通达信+申万行业)。"""
- from .codec.industry import parse_tdxhy_cfg
- return parse_tdxhy_cfg(await self.get_report_file("tdxhy.cfg"))
+ async def get_report_file(self, filename: str) -> bytes:
+ """已废弃 -> :meth:`get_file`。"""
+ _deprecated("get_report_file", "get_file")
+ return await self.get_file(filename)
- async def get_financial_file_infos(self) -> list[FinancialFileInfo]:
- """下载并解析 tdxfin/gpcw.txt,返回 FinancialFileInfo 列表(文件名/MD5/大小)。"""
- from .codec.financial import parse_financial_file_list
- return parse_financial_file_list(await self.get_report_file("tdxfin/gpcw.txt"))
+ async def get_file_meta(self, filename: str):
+ """已废弃 -> :meth:`get_file`(直接取内容)。"""
+ _deprecated("get_file_meta", "get_file")
+ return await self._execute_mac(MacFileListCmd(filename))
- async def get_financial_records_parsed(self, filename: str) -> list[FinancialRecord]:
- """下载财报 zip(``tdxfin/gpcw*.zip``)并解压解析为 FinancialRecord 列表。
+ async def download_file(self, filename: str, filesize: int = 0) -> bytes:
+ """已废弃 -> :meth:`get_file`。"""
+ _deprecated("download_file", "get_file")
+ return await self.get_file(filename)
- 报告期优先取文件名中的 8 位日期,缺失时回退到 .dat 头部内嵌值。
- """
- import io
- import re
- import zipfile
+ async def get_board_list(self, board_type: int | str = 0,
+ count: int = 10000) -> list[BoardInfo]:
+ """已废弃 -> :meth:`get_boards`。"""
+ _deprecated("get_board_list", "get_boards")
+ return await self.get_boards(board_type, count=count)
- from .codec.financial import parse_financial_dat
+ async def get_belong_board(self, market, code) -> list[BelongBoard]:
+ """已废弃 -> :meth:`get_board_of`。"""
+ _deprecated("get_belong_board", "get_board_of")
+ return await self.get_board_of(format_symbol(int(market), code))
- zip_data = await self.get_report_file(filename)
- if not zip_data:
+ async def get_symbol_info(self, market, code) -> SymbolSnapshot | None:
+ """已废弃 -> :meth:`get_snapshot`(旧版返回单个对象)。"""
+ _deprecated("get_symbol_info", "get_snapshot")
+ items = await self.get_snapshot(format_symbol(int(market), code))
+ return items[0] if items else None
+
+ async def get_goods_list(self, market, start: int = 0,
+ count: int = 100) -> list[SecurityInfo]:
+ """已废弃 -> :meth:`get_universe`(扩展到 ``SecurityInfo`` 统一模型)。"""
+ _deprecated("get_goods_list", "get_universe")
+ items = await self._universe_ex(int(market))
+ return items[start:start + count]
+
+ async def get_goods_count(self, market: int | None = None) -> int:
+ """已废弃 -> ``len(get_universe(...))``。"""
+ _deprecated("get_goods_count", "get_universe")
+ if market is None:
+ return len(await self._ex_all())
+ return len(await self._universe_ex(int(market)))
+
+ async def get_goods_quotes(self, stocks, bits=None) -> list[SecurityQuote]:
+ """已废弃 -> :meth:`get_quotes`。"""
+ _deprecated("get_goods_quotes", "get_quotes")
+ return await self.get_quotes([format_symbol(int(m), c) for m, c in stocks],
+ fields=bits)
+
+ async def get_goods_quotes_list(self, market, count: int = 80
+ ) -> list[SecurityQuote]:
+ """已废弃 -> :meth:`get_quotes`(或 ``get_universe`` 取清单后自选)。"""
+ _deprecated("get_goods_quotes_list", "get_quotes")
+ items = await self._universe_ex(int(market))
+ if not items:
return []
- with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
- dat_names = [n for n in zf.namelist() if n.endswith(".dat")]
- if not dat_names:
- return []
- dat_data = zf.read(dat_names[0])
- match = re.search(r"(\d{8})", filename)
- report_date = int(match.group(1)) if match else 0
- return parse_financial_dat(dat_data, report_date)
+ return await self.get_quotes([it.symbol for it in items[:count]])
- # ------------------------------------------------------------------ #
- # 板块聚合(基于 board_list/members/K线 组合)
- # ------------------------------------------------------------------ #
+ async def get_goods_chart_sampling(self, market, code) -> list[float]:
+ """已废弃 -> :meth:`get_minutes`(``sampling=True``)。"""
+ _deprecated("get_goods_chart_sampling", "get_minutes(sampling=True)")
+ bars = await self.get_minutes(format_symbol(int(market), code), sampling=True)
+ return [b.price for b in bars]
- async def get_board_summary(self, board_symbol: str) -> dict:
- """板块汇总:成分数/总成交额/总成交量/主力净流入/涨跌家数。"""
- # 需要金额(0x07)与主力净流入(0x38)字段
- bits = list(range(0x00, 0x08)) + [0x38]
- members = await self.get_board_members(board_symbol, count=100000)
- # 重新拉含主力净流入字段(get_board_members 默认不含)
- from .protocol.commands.mac_ext import MacBoardMembersQuotesCmd
- board_code = self._convert_board_code(board_symbol)
- all_m = []
- start = 0
- while start < 100000:
- batch = await self._execute_mac(
- MacBoardMembersQuotesCmd(board_code, sort_type=0, start=start,
- page_size=80, bits=bits))
+ async def get_goods_tick_chart(self, market, code,
+ ymd: int = 0) -> list[MinuteBar]:
+ """已废弃 -> :meth:`get_minutes`(扩展到统一分时模型)。"""
+ _deprecated("get_goods_tick_chart", "get_minutes")
+ return await self.get_minutes(format_symbol(int(market), code),
+ date=ymd or None)
+
+ async def get_goods_transaction(self, market, code, *, ymd: int = 0,
+ start: int = 0, count: int = 1800
+ ) -> list[TransactionRecord]:
+ """已废弃 -> :meth:`get_ticks`(扩展到统一逐笔模型)。"""
+ _deprecated("get_goods_transaction", "get_ticks")
+ return await self.get_ticks(format_symbol(int(market), code),
+ date=ymd or None, start=start, count=count)
+
+ async def get_goods_transaction_all(self, market, code,
+ ymd: int = 0) -> list[TransactionRecord]:
+ """已废弃 -> :meth:`get_ticks`(``count=None`` 即全量翻页)。"""
+ _deprecated("get_goods_transaction_all", "get_ticks(count=None)")
+ return await self.get_ticks(format_symbol(int(market), code),
+ date=ymd or None, count=None)
+
+ async def _board_members_raw(self, board_code: int, *, start: int = 0,
+ count: int = 80, sort_type: int = 0
+ ) -> list[SecurityQuote]:
+ """按原始板块/分类码取成分报价(旧分类报价接口用)。"""
+ items: list[SecurityQuote] = []
+ offset = start
+ while len(items) < count:
+ batch = await self._execute_mac(MacBoardMembersQuotesCmd(
+ board_code, sort_type=sort_type, start=offset,
+ page_size=min(_QUOTE_PAGE, count - len(items))))
if not batch:
break
- all_m.extend(batch)
- start += len(batch)
- if len(batch) < 80:
+ items.extend(_quote_from_member(m) for m in batch)
+ offset += len(batch)
+ if len(batch) < _QUOTE_PAGE:
break
- amount = sum(m.fields.get("0x7", 0) for m in all_m)
- main_net = sum(m.fields.get("0x38", 0) for m in all_m)
- up = down = 0
- for m in all_m:
- c, pre = m.fields.get("0x4", 0), m.fields.get("0x0", 0)
- if pre and c > pre:
- up += 1
- elif pre and c < pre:
- down += 1
- return {
- "member_count": len(all_m),
- "amount": amount, "main_net_amount": main_net,
- "up_count": up, "down_count": down,
- }
+ return items
- async def get_board_ranking(self, board_type: int = 1, top_n: int = 20) -> list[dict]:
- """板块涨跌幅排行(行业/概念,基于板块K线计算涨跌幅)。"""
- boards = await self.get_board_list(board_type, count=200)
- # 去重(board_list返回板块+领涨股混合,取板块段)
- seen = {}
- for b in boards:
- if not b.code.startswith("88"): # 只保留板块段(881xxx), 过滤领涨股
- continue
- if b.code not in seen or len(b.name) < len(seen[b.code].name):
- seen[b.code] = b
- result = []
- for code, b in list(seen.items())[:top_n * 3]:
- if b.pre_close <= 0:
- continue
- chg = (b.price / b.pre_close - 1) * 100
- result.append({"code": code, "name": b.name, "price": b.price,
- "change_pct": round(chg, 2)})
- result.sort(key=lambda x: x["change_pct"], reverse=True)
- return result[:top_n]
- async def get_board_change_ranking(self, board_type: int = 1, days: int = 20,
- top_n: int = 20) -> list[dict]:
- """板块N日涨跌幅排行(用板块指数K线)。"""
- from .models import Adjust, KlinePeriod
- boards = await self.get_board_list(board_type, count=200)
- seen = {}
- for b in boards:
- if not b.code.startswith("88"): # 只保留板块段, 过滤领涨股
- continue
- if b.code not in seen or len(b.name) < len(seen[b.code].name):
- seen[b.code] = b
- result = []
- for code, b in list(seen.items())[:top_n * 3]:
- try:
- bars = await self.get_kline(1, code, KlinePeriod.DAY, count=days + 5,
- adjust=Adjust.NONE)
- if len(bars) < 2:
- continue
- first, last = bars[0].close, bars[-1].close
- if first <= 1.0: # 过滤异常基数(板块指数首根过小)
- continue
- result.append({"code": code, "name": b.name,
- "close_end": last, "close_start": first,
- "change_pct": round((last / first - 1) * 100, 2)})
- except Exception:
- continue
- result.sort(key=lambda x: x["change_pct"], reverse=True)
- return result[:top_n]
-
- # ------------------------------------------------------------------ #
- # 剩余接口:分时采样 / 列表all / K线+指标(带缓存)
- # ------------------------------------------------------------------ #
-
- async def get_chart_sampling(self, market: Market, code: str) -> list[float]:
- """分时缩略采样价格点(MAC 0x254D)。"""
- from .protocol.commands.mac_ext import MacChartSamplingCmd
- key = CacheKey("minute_sampling", int(market), code)
- async def fetch() -> bytes:
- return pack_payload(await self._execute_mac(MacChartSamplingCmd(int(market), code)))
- return unpack_payload(await self._cache.get_or_fetch(key, fetch))
-
- async def get_security_list_all(self, market: Market) -> list[SecurityInfo]:
- """全市场证券列表(高并发分页拉取,缓存1天)。
-
- 优化:高并发一次并发拉完所有页。
- """
- key = CacheKey("list_all", int(market))
- async def fetch() -> bytes:
- # 先获取总数(带缓存),精确规划页数
- total = await self.get_security_count(market)
- def make_cmd(s: int, c: int):
- return GetSecurityListCmd(int(market), s)
- spec = PageSpec(page_size=LIST_PAGE, total=total, stop_when_short=True)
- result = await self._fetch_paginated_list(
- "standard", make_cmd, spec,
- concurrency=min(self._std_pool.max_size, 8))
- return pack_payload(result)
- return unpack_payload(await self._cache.get_or_fetch(key, fetch))
-
- async def get_stock_kline_with_indicators(
- self, market: Market, code: str, indicators: list[str], *,
- period: KlinePeriod = KlinePeriod.DAY, count: int = 30,
- adjust: Adjust | None = None, params: dict | None = None,
- ) -> dict:
- """K线+技术指标(MACD/KDJ/RSI/BOLL/MA/EMA,缓存=复权K线TTL)。"""
- from .indicator import compute_indicators
- adj = self.default_adjust if adjust is None else adjust
- fetch_count = max(120 + count, 200) # 指标预热
- bars = await self.get_kline(market, code, period, count=fetch_count, adjust=adj)
- if not bars:
- return {"bars": [], "indicators": {}}
- high = [b.high for b in bars]
- low = [b.low for b in bars]
- close = [b.close for b in bars]
- ind = compute_indicators(high, low, close, indicators, params, tail=count)
- return {
- "bars": bars[-count:],
- "indicators": {k: (v[-count:] if len(v) >= count else v) for k, v in ind.items()},
- }
diff --git a/src/pytdxdata/cache/key.py b/src/pytdxdata/cache/key.py
index 0fbb5d6..3823f71 100644
--- a/src/pytdxdata/cache/key.py
+++ b/src/pytdxdata/cache/key.py
@@ -40,7 +40,12 @@ class CacheKey:
)
@classmethod
- def quote_key(cls, stocks: Sequence[tuple[int, str]]) -> "CacheKey":
- """报价键:对股票集规范化排序,顺序无关可命中。"""
+ def quote_key(cls, stocks: Sequence[tuple[int, str]],
+ tag: str = "") -> "CacheKey":
+ """报价键:对股票集规范化排序,顺序无关可命中。
+
+ ``tag`` 区分取数口径(标准五档 / MAC·EX 字段位),不同口径不互相命中。
+ """
norm = sorted(f"{m}:{c}" for m, c in stocks)
- return cls(category="quote", extra=",".join(norm))
+ extra = ",".join(norm)
+ return cls(category="quote", extra=f"{tag}#{extra}" if tag else extra)
diff --git a/src/pytdxdata/cli.py b/src/pytdxdata/cli.py
index 3ba89d5..367425a 100644
--- a/src/pytdxdata/cli.py
+++ b/src/pytdxdata/cli.py
@@ -111,26 +111,17 @@ def _pct(price: float, pre: float) -> str:
# ------------------------------------------------------------------ #
async def cmd_quotes(td: TdxData, symbols: list[str]) -> None:
- cn, ex = [], []
- for sym in symbols:
- s = parse_symbol(sym)
- if s.kind == "cn":
- cn.append((Market(s.market), s.code))
- else:
- ex.append((s.market, s.code))
- for q in await td.get_quotes(cn):
- _print_cn_quote(q)
- if ex:
- from .protocol.commands.ex_proto import GetExInstrumentQuoteCmd
- for market, code in ex:
- q = await td._execute_ex(GetExInstrumentQuoteCmd(market, code))
- _print_ex_quote(market, code, q)
+ quotes = await td.get_quotes(symbols)
+ for q in quotes:
+ _print_quote(q)
-def _print_cn_quote(q) -> None:
+def _print_quote(q) -> None:
pct = (q.price / q.pre_close - 1) * 100 if q.pre_close else 0
+ mkt = {31: "港股", 74: "美股"}.get(q.market, "")
print("=" * 58)
- print(" %s %s" % (q.code, q.server_time or datetime.now().strftime("%H:%M:%S")))
+ label = "%s %s" % (mkt, q.code) if mkt else "%s %s" % (q.code, q.server_time or datetime.now().strftime("%H:%M:%S"))
+ print(" %s" % label)
print(" 最新 %-10.2f 涨跌 %+8.2f (%+.2f%%)" % (q.price, q.price - q.pre_close, pct))
print(" 今开 %-10.2f 最高 %.2f 最低 %.2f" % (q.open, q.high, q.low))
print(" 昨收 %-10.2f 成交量 %s 成交额 %s" % (q.pre_close, _fmt_num(q.vol), _fmt_num(q.amount)))
@@ -144,31 +135,9 @@ def _print_cn_quote(q) -> None:
print()
-def _print_ex_quote(market: int, code: str, q: dict | None) -> None:
- if not q:
- print(" %s: 无报价数据" % code)
- return
- price, pre = q.get("price") or 0, q.get("pre_close") or 0
- mkt = {31: "港股", 74: "美股"}.get(market, "扩展")
- print("=" * 58)
- print(" %s %s" % (mkt, code))
- print(" 最新 %-10.2f 涨跌 %+8.2f (%s)" % (price, price - pre, _pct(price, pre)))
- print(" 今开 %-10.2f 最高 %.2f 最低 %.2f" % (
- q.get("open") or 0, q.get("high") or 0, q.get("low") or 0))
- print(" 昨收 %-10.2f 总量 %s" % (pre, _fmt_num(q.get("zongliang") or 0)))
- print()
-
-
async def cmd_kline(td: TdxData, sym: str, period: KlinePeriod, count: int,
start: int, adjust: Adjust) -> None:
- s = parse_symbol(sym)
- if s.kind == "cn":
- bars = await td.get_kline(Market(s.market), s.code, period, start=start,
- count=count, adjust=adjust)
- elif s.kind == "index":
- bars = await td.get_index_kline(Market(s.market), s.code, period, start=start, count=count)
- else:
- bars = await td.get_kline(ExMarket(s.market), s.code, period, start=start, count=count)
+ bars = await td.get_bars(sym, period, start=start, count=count, adjust=adjust)
print("%s K线 (%s, %d根):" % (sym, period.name, len(bars)))
print(" %-12s %8s %8s %8s %8s %12s" % ("日期", "开盘", "最高", "最低", "收盘", "成交量"))
for b in bars:
@@ -256,8 +225,7 @@ async def cmd_list(td: TdxData, market: str, count: int) -> None:
async def cmd_auction(td: TdxData, sym: str) -> None:
- s = parse_symbol(sym)
- items = await td.get_auction(Market(s.market), s.code)
+ items = await td.get_auction(sym)
print("%s 集合竞价 (%d条):" % (sym, len(items)))
for a in items:
print(" %s 价格=%.3f 量=%d %s" % (
@@ -266,7 +234,7 @@ async def cmd_auction(td: TdxData, sym: str) -> None:
async def cmd_unusual(td: TdxData, market: str, count: int) -> None:
- items = await td.get_unusual(MARKET_NAMES[market], count=count)
+ items = await td.get_unusual(market, count=count)
print("市场异动 (%d条):" % len(items))
for u in items:
print(" %s %s %s" % (getattr(u, "code", ""), getattr(u, "name", ""),
@@ -274,8 +242,7 @@ async def cmd_unusual(td: TdxData, market: str, count: int) -> None:
async def cmd_xdxr(td: TdxData, sym: str) -> None:
- s = parse_symbol(sym)
- items = await td.get_xdxr(Market(s.market), s.code)
+ items = await td.get_xdxr(sym)
print("%s 除权除息 (%d条):" % (sym, len(items)))
for x in items[:20]:
print(" %s 送%g 配%g 派%g" % (
@@ -284,23 +251,20 @@ async def cmd_xdxr(td: TdxData, sym: str) -> None:
async def cmd_finance(td: TdxData, sym: str) -> None:
- s = parse_symbol(sym)
- f = await td.get_finance(Market(s.market), s.code)
- if not f:
+ fins = await td.get_finance(sym)
+ if not fins:
print("无财务数据")
return
- for k, v in asdict(f).items():
+ for k, v in asdict(fins[0]).items():
print(" %-24s %s" % (k, v))
async def cmd_flow(td: TdxData, sym: str) -> None:
- s = parse_symbol(sym)
- f = await td.get_capital_flow(Market(s.market), s.code)
- if isinstance(f, dict):
- items = f.items()
- else:
- items = asdict(f).items()
- for k, v in items:
+ flows = await td.get_capital_flow(sym)
+ if not flows:
+ print("无资金流向数据")
+ return
+ for k, v in asdict(flows[0]).items():
print(" %-20s %s" % (k, v))
diff --git a/src/pytdxdata/models/__init__.py b/src/pytdxdata/models/__init__.py
index 03c0e66..a91abef 100644
--- a/src/pytdxdata/models/__init__.py
+++ b/src/pytdxdata/models/__init__.py
@@ -94,7 +94,7 @@ class Adjust(IntEnum):
@dataclass(slots=True)
class SecurityBar:
- """K线记录(价格单位:元)"""
+ """K线记录(价格单位:元)。跨市场统一模型(A股/港股/美股/期货共用)。"""
market: int
code: str
open: float
@@ -108,6 +108,7 @@ class SecurityBar:
day: int
hour: int = 0
minute: int = 0
+ symbol: str = "" # 规范化标的串(sz000001 / hk00700),由 API 层填充
@property
def datetime(self) -> datetime:
@@ -120,9 +121,26 @@ class IndexBar(SecurityBar):
pass
+@dataclass(slots=True)
+class IndicatorSet:
+ """K线 + 技术指标组合(``TdxData.get_indicators`` 的返回单元)。
+
+ ``indicators`` 里每个序列与 ``bars`` 等长、尾部对齐;预热期为 ``None`` 的指标
+ (如 BOLL 前三档)保留 ``None``。
+ """
+ symbol: str
+ bars: list[SecurityBar] = field(default_factory=list)
+ indicators: dict[str, list[float | None]] = field(default_factory=dict)
+
+
@dataclass(slots=True)
class SecurityQuote:
- """实时五档报价"""
+ """报价(跨市场统一模型)。
+
+ A股(标准通道):五档 ``bid``/``ask`` + 买卖量 + 涨跌停价齐全,``name`` 为空。
+ A股(``fields=[...]`` 走 MAC 0x122B):``name`` 与 ``fields`` 齐全,五档为空。
+ 扩展市场(港股/美股/期货):``name`` + 基础价量在属性上,其余字段位在 ``fields``。
+ """
market: int
code: str
price: float
@@ -144,39 +162,51 @@ class SecurityQuote:
limit_down: float = 0.0 # 跌停价
decimal_point: int = 2 # 价格小数位
open_amount: float = 0.0 # 开盘金额(个股)
+ symbol: str = "" # 规范化标的串
+ name: str = "" # 名称(仅 MAC/EX 通道有)
+ fields: dict[str, float] = field(default_factory=dict) # 原始字段位("0x7" 等)
@dataclass(slots=True)
class SecurityInfo:
- """证券列表条目"""
+ """标的清单条目(跨市场统一模型:A股证券列表 + 扩展市场商品列表)"""
market: int
code: str
name: str
volunit: int
decimal_point: int
pre_close: float
+ symbol: str = "" # 规范化标的串
+ kind: str = "" # 分类描述(扩展市场的 category/desc)
@dataclass(slots=True)
class TransactionRecord:
- """逐笔成交(MAC通道含 trade_count=成交笔数)"""
+ """逐笔成交(跨市场统一模型;A股 MAC 通道含 trade_count=成交笔数)"""
market: int
code: str
- time: str # HH:MM:SS
+ time: str # HH:MM:SS(扩展市场为 HH:MM)
price: float
vol: float # 手(MAC逐笔)
trade_count: int # 成交笔数(MAC=逐笔记录字段;标准当日逐笔协议也有但需单独解析)
bs_flag: int # 1=主动买 0=主动卖
+ symbol: str = ""
+ fields: dict[str, float] = field(default_factory=dict) # 扩展市场额外字段(增仓等)
@dataclass(slots=True)
class MinuteBar:
- """分时数据"""
+ """分时(跨市场统一模型;A股 MAC 0x122D / 扩展市场 0x122D 同构)"""
price: float
vol: float
avg_price: float = 0.0 # 均价(协议第2字段)
hour: int = 0
minute: int = 0
+ symbol: str = ""
+ market: int = 0
+ code: str = ""
+ date: int = 0 # YYYYMMDD
+ fields: dict[str, float] = field(default_factory=dict) # 扩展市场额外字段(动量等)
@dataclass(slots=True)
@@ -201,6 +231,7 @@ class XdxrRecord:
qian_zongguben: float = 0.0
panhou_liutong: float = 0.0
hou_zongguben: float = 0.0
+ symbol: str = ""
@property
def date(self) -> str:
@@ -248,6 +279,7 @@ class FinanceRecord:
weifen_lirun: float = 0.0
meigujing_zichan: float = 0.0
reserve2: float = 0.0
+ symbol: str = ""
# ===== MAC 扩展命令模型 =====
@@ -268,15 +300,21 @@ class BoardInfo:
symbol_price: float = 0.0
symbol_rise_speed: float = 0.0
symbol_pre_close: float = 0.0
+ symbol: str = "" # 规范化标的串(板块码,如 sh881001)
@dataclass(slots=True)
class MemberQuote:
- """板块成分股报价(MAC自定义字段)"""
+ """板块成分/自定义字段报价的**协议层原始记录**。
+
+ API 层会把它归一成 :class:`SecurityQuote`(``fields`` 原样保留、基础字段位
+ 填进属性),所以普通调用不会看到本类。
+ """
market: int
code: str
name: str
fields: dict[str, float] = field(default_factory=dict)
+ symbol: str = ""
@dataclass(slots=True)
@@ -287,6 +325,7 @@ class BelongBoard:
board_name: str
close: float
pre_close: float
+ symbol: str = "" # 被查询的个股(非板块)
@dataclass(slots=True)
@@ -296,6 +335,7 @@ class AuctionItem:
price: float
matched: int
unmatched: int
+ symbol: str = ""
@dataclass(slots=True)
@@ -308,6 +348,7 @@ class UnusualItem:
desc: str
value: float
time: str
+ symbol: str = ""
@dataclass(slots=True)
@@ -328,6 +369,7 @@ class SymbolSnapshot:
amount: float
turnover: float
avg_price: float
+ symbol: str = ""
@dataclass(slots=True)
@@ -361,6 +403,7 @@ class CapitalFlow:
sell5: float
big5: float
mid5: float
+ symbol: str = ""
# ===== 服务器文件解析模型(板块/行业/历史专业财报) =====
diff --git a/src/pytdxdata/pool/pool.py b/src/pytdxdata/pool/pool.py
index 60a2f3c..78321cb 100644
--- a/src/pytdxdata/pool/pool.py
+++ b/src/pytdxdata/pool/pool.py
@@ -211,6 +211,10 @@ class DynamicPool:
# 2. 可扩容(未达上限且有可用服务器)→ 新建连接
if self._total < self.max_size:
host = self._next_available_server()
+ if host is None:
+ # 兜底:全部服务器都在冷却中,而池子未满 —— 此时等 release
+ # 永远等不到(没人持有),只能挑最健康的一台顶着冷却重试
+ host = self._next_available_server(ignore_cooldown=True)
if host:
try:
pc = await self._new_conn(host)
@@ -244,18 +248,19 @@ class DynamicPool:
break
return out
- def _next_available_server(self) -> str | None:
+ def _next_available_server(self, *, ignore_cooldown: bool = False) -> str | None:
ranked = self.health.rank(self.servers)
# 1. 优先选未冷却且未达并发上限的服务器
for h in ranked:
- if self.health.in_cooldown(h):
+ if self.health.in_cooldown(h) and not ignore_cooldown:
continue
if self._server_count.get(h, 0) < self.per_server_cap:
return h
# 2. 兜底:仅从「未冷却」的已占用服务器里随机复用(避免反复打坏服务器)
alive = [
h for h in ranked
- if not self.health.in_cooldown(h) and self._server_count.get(h, 0) > 0
+ if (ignore_cooldown or not self.health.in_cooldown(h))
+ and self._server_count.get(h, 0) > 0
]
return random.choice(alive) if alive else None
diff --git a/src/pytdxdata/scheduler/paginator.py b/src/pytdxdata/scheduler/paginator.py
index d952163..4db0366 100644
--- a/src/pytdxdata/scheduler/paginator.py
+++ b/src/pytdxdata/scheduler/paginator.py
@@ -36,6 +36,15 @@ class PageResult:
items: list[Any]
+class _Slot:
+ """worker 当前持有的连接槽:失败换连时原地更新,保证最终能精确归还。"""
+
+ __slots__ = ("pc",)
+
+ def __init__(self, pc: PooledConnection) -> None:
+ self.pc: PooledConnection | None = pc
+
+
class Paginator:
"""用至多 concurrency 个连接并行拉取分页数据。"""
@@ -64,22 +73,27 @@ class Paginator:
conns = await self.pool.acquire_many(eff_conc)
if not conns:
raise PoolTimeoutError("连接池获取超时(无可用连接)")
+ # 每个 worker 一个连接槽:中途换连会更新槽内引用,
+ # 归还时按槽归还(否则换掉的新连接会漏还,把池耗干)
+ slots = [_Slot(pc) for pc in conns]
try:
stop = asyncio.Event()
out: list[PageResult] = []
out_lock = asyncio.Lock()
- k = len(conns)
+ k = len(slots)
workers = [
asyncio.create_task(
- self._worker(wid, conns[wid % k], jobs[wid::k], cmd_factory,
+ self._worker(slots[wid], jobs[wid::k], cmd_factory,
stop, out, out_lock, spec)
)
for wid in range(k)
]
await asyncio.gather(*workers)
finally:
- for pc in conns:
- await self.pool.release(pc)
+ for s in slots:
+ if s.pc is not None:
+ pc, s.pc = s.pc, None
+ await self.pool.release(pc)
return self._assemble(out, spec.ordered)
def _plan_starts(self, spec: PageSpec) -> list[tuple[int, int]]:
@@ -102,49 +116,47 @@ class Paginator:
return jobs
async def _worker(
- self, wid: int, conn: PooledConnection, jobs: list[tuple[int, int]],
+ self, slot: _Slot, jobs: list[tuple[int, int]],
cmd_factory: Callable[[int, int], Any], stop: asyncio.Event,
out: list[PageResult], out_lock: asyncio.Lock, spec: PageSpec,
) -> None:
- current = conn
for start, count in jobs:
- if stop.is_set():
+ if stop.is_set() or slot.pc is None:
return
- items, current = await self._fetch_one(
- current, cmd_factory(start, count), count)
- if items is None:
- continue # 该页失败(strict=False 时留空)
+ items, ok = await self._fetch_one(slot, cmd_factory(start, count), count)
+ if not ok:
+ return # 换连接失败 → 本 worker 退出(该页留空)
async with out_lock:
out.append(PageResult(start=start, count=count, items=items))
if spec.stop_when_short and len(items) < count:
stop.set()
return
- async def _fetch_one(self, conn: PooledConnection, cmd, page_size: int):
+ async def _fetch_one(self, slot: _Slot, cmd, page_size: int):
"""单页拉取,失败换连接重试。
- 返回 (items, current_conn) — current_conn 始终指向当前可用连接,
- worker 据此更新自己的连接引用,避免跨页使用已关闭连接。
+ 返回 ``(items, ok)``。失败时连接一律 ``broken=True`` 归还并把槽清空,
+ 调用方据此退出,不会留下悬空引用。
"""
- current = conn
for attempt in range(self.retries + 1):
try:
- result = await current.execute(cmd)
- return (list(result) if result is not None else []), current
+ result = await slot.pc.execute(cmd) # type: ignore[union-attr]
+ return (list(result) if result is not None else []), True
except Exception as e:
+ if slot.pc is not None:
+ await self.pool.release(slot.pc, broken=True)
+ slot.pc = None
if attempt >= self.retries:
if self.strict:
raise
log.warning("分页拉取失败(strict=False留空): %s", e)
- return None, current
- # 换连接重试
- await self.pool.release(current, broken=True)
+ return None, False
try:
- current = await self.pool.acquire(timeout=3.0)
+ slot.pc = await self.pool.acquire(timeout=3.0)
except PoolTimeoutError:
log.warning("分页重试获取连接失败,跳过该页: %s", e)
- return None, current
- return None, current
+ return None, False
+ return None, False
def _assemble(self, results: list[PageResult], ordered: bool) -> list[Any]:
if ordered:
diff --git a/src/pytdxdata/symbols.py b/src/pytdxdata/symbols.py
new file mode 100644
index 0000000..d02286f
--- /dev/null
+++ b/src/pytdxdata/symbols.py
@@ -0,0 +1,240 @@
+"""标的代码解析:全库唯一的字符串口径。
+
+统一写法(也是 CLI 的写法)::
+
+ sz000001 / sh600000 / bj920992 A股(6位代码,必须带市场前缀)
+ hk00700 港股主板(5位)
+ usAAPL 美股(ticker)
+ cffex:IFL0 / zz:AP0 期货(交易所前缀 + 合约,可带冒号)
+ 000001 裸 6 位数字 = 沪市指数
+
+**裸 6 位数字只当作沪市指数**:A股代码不唯一(``000001`` 既是上证指数也是平安银行),
+要股票请写全前缀 ``sh000001`` / ``sz000001``。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from .models import ExMarket, Market
+
+# 通道:cn=标准/MAC A股通道,ex=扩展市场通道(端口 7727)
+CN = "cn"
+EX = "ex"
+INDEX = "index"
+
+_CN_ALIASES: dict[str, Market] = {
+ "sz": Market.SZ,
+ "sh": Market.SH,
+ "bj": Market.BJ,
+}
+_CN_PREFIX: dict[int, str] = {int(m): k for k, m in _CN_ALIASES.items()}
+
+# EX 常用别名(短前缀优先;其余成员用枚举名小写,如 hk_gem:08001)
+_EX_ALIASES: dict[str, ExMarket] = {
+ "hk": ExMarket.HK_MAIN_BOARD,
+ "us": ExMarket.US_STOCK,
+ "zz": ExMarket.ZZ_FUTURES,
+ "dl": ExMarket.DL_FUTURES,
+ "shf": ExMarket.SH_FUTURES,
+ "cffex": ExMarket.CFFEX_FUTURES,
+ "gz": ExMarket.GZ_FUTURES,
+}
+_EX_PREFIX: dict[int, str] = {int(m): k for k, m in _EX_ALIASES.items()}
+
+ALL = "all"
+
+
+def _ex_by_name(name: str) -> ExMarket | None:
+ """按枚举名匹配(hk_main_board / us_stock / ...),保证 format→parse 可往返。"""
+ key = name.upper()
+ for member in ExMarket:
+ if member.name == key:
+ return member
+ return None
+
+
+def _lookup(text: str) -> tuple[int, str] | None:
+ """前缀 -> (市场号, 通道)。"""
+ if text in _CN_ALIASES:
+ return int(_CN_ALIASES[text]), CN
+ if text in _EX_ALIASES:
+ return int(_EX_ALIASES[text]), EX
+ member = _ex_by_name(text)
+ if member is not None:
+ return int(member), EX
+ return None
+
+
+def _hint() -> str:
+ cn = "/".join(sorted(_CN_ALIASES))
+ ex = "/".join(sorted(_EX_ALIASES))
+ return f"A股: {cn};扩展市场: {ex}(详见 pytdxdata.models.ExMarket)"
+
+
+@dataclass(frozen=True, slots=True)
+class Symbol:
+ """解析后的标的。``kind``: cn=A股 / ex=扩展市场 / index=裸数字指数。"""
+
+ market: int
+ code: str
+ kind: str
+ raw: str = ""
+
+ @property
+ def is_ex(self) -> bool:
+ return self.kind == EX
+
+ @property
+ def is_index(self) -> bool:
+ return self.kind == INDEX
+
+ @property
+ def channel(self) -> str:
+ """路由通道:ex 走扩展市场池,其余走标准/MAC A股池。"""
+ return EX if self.is_ex else "std"
+
+ @property
+ def text(self) -> str:
+ """规范化写法,同时用作记录上的 ``.symbol``。"""
+ if self.is_index:
+ return self.code
+ return format_symbol(self.market, self.code)
+
+ def as_pair(self) -> tuple[int, str]:
+ """(市场号, 代码) 元组(协议层用)。"""
+ return self.market, self.code
+
+ def __str__(self) -> str:
+ return self.text
+
+
+def _prefix_for(market: int) -> str | None:
+ """市场号 -> 短前缀;无短别名的扩展市场回退到枚举名小写。"""
+ m = int(market)
+ prefix = _CN_PREFIX.get(m) or _EX_PREFIX.get(m)
+ if prefix is not None:
+ return prefix
+ try:
+ return ExMarket(m).name.lower()
+ except ValueError:
+ return None
+
+
+def format_symbol(market: int, code: str) -> str:
+ """(市场号, 代码) -> 规范化字符串(``1, "600000"`` -> ``"sh600000"``)。"""
+ code = str(code).strip()
+ if not code:
+ return ""
+ prefix = _prefix_for(market)
+ if prefix is None:
+ return code
+ # 2 字母前缀贴代码(hk00700),长前缀用冒号(cffex:IFL0 / hk_gem:08001)
+ return f"{prefix}:{code}" if len(prefix) > 2 else f"{prefix}{code}"
+
+
+def market_name(market: int) -> str:
+ """市场号 -> 市场选择器字符串(``1`` -> ``"sh"``,``31`` -> ``"hk"``)。
+
+ 用于把旧接口的市场号参数转成统一接口要的市场选择器。
+ """
+ prefix = _prefix_for(market)
+ if prefix is None:
+ raise ValueError(f"未知市场号: {market}")
+ return prefix
+
+
+def parse_symbol(text: str) -> Symbol:
+ """字符串 -> Symbol。无法识别时抛 ValueError 并列出可用前缀。"""
+ raw = text
+ sym = str(text).strip()
+ if not sym:
+ raise ValueError("标的为空")
+
+ if ":" in sym:
+ head, code = sym.split(":", 1)
+ head, code = head.strip().lower(), code.strip()
+ hit = _lookup(head)
+ if hit is None:
+ raise ValueError(f"未知市场前缀: {head}({_hint()})")
+ if not code:
+ raise ValueError(f"缺少代码: {raw}")
+ return Symbol(market=hit[0], code=code.upper(), kind=hit[1], raw=raw)
+
+ head, code = sym[:2].lower(), sym[2:]
+ hit = _lookup(head)
+ if hit is not None and code:
+ return Symbol(market=hit[0], code=code.upper(), kind=hit[1], raw=raw)
+
+ if sym.isdigit() and len(sym) == 6:
+ # 裸 6 位 = 沪市指数(A股代码不唯一,股票必须带前缀)
+ return Symbol(market=int(Market.SH), code=sym, kind=INDEX, raw=raw)
+
+ raise ValueError(f"无法识别标的: {raw}({_hint()};裸6位数字=沪市指数)")
+
+
+def parse_symbols(symbols: str | Sequence[str] | None) -> list[Symbol]:
+ """接受单个字符串 / 字符串序列 / Symbol 序列,去重并保持输入顺序。"""
+ if symbols is None:
+ raise ValueError("symbols 不能为空")
+ items: list = [symbols] if isinstance(symbols, str) else list(symbols)
+ if not items:
+ raise ValueError("symbols 不能为空")
+ out: list[Symbol] = []
+ seen: set[tuple[int, str]] = set()
+ for item in items:
+ sym = item if isinstance(item, Symbol) else parse_symbol(item)
+ if sym.as_pair() in seen:
+ continue
+ seen.add(sym.as_pair())
+ out.append(sym)
+ return out
+
+
+def cn_markets() -> list[int]:
+ """A股市场号(深/沪/北)。"""
+ return [int(m) for m in Market]
+
+
+def ex_markets() -> list[int]:
+ """扩展市场号,按枚举值升序。"""
+ return sorted(int(m) for m in ExMarket)
+
+
+def market_targets(text: str | None) -> list[tuple[int, str]]:
+ """市场选择器 -> [(市场号, 通道)];``None`` / ``"all"`` = 全部市场。
+
+ 市场号在两条通道里会撞车(``Market.SH=1`` 与 ``ExMarket.TEMP_STOCK=1``),
+ 所以必须带通道一起返回,调用方按通道分别请求。
+ """
+ key = "" if text is None else str(text).strip().lower()
+ if not key or key == ALL:
+ return ([(m, CN) for m in cn_markets()]
+ + [(m, EX) for m in ex_markets()])
+ hit = _lookup(key)
+ if hit is None:
+ raise ValueError(f"未知市场: {text}({_hint()};全部用 all)")
+ return [hit]
+
+
+def parse_market(text: str | None) -> int | None:
+ """市场选择器 -> 单个市场号;``None`` / ``"all"`` 返回 None。
+
+ 只用于「本来就是单市场」的接口(如市场异动)。需要跨市场时用
+ :func:`market_targets`。
+ """
+ targets = market_targets(text)
+ return None if len(targets) > 1 else targets[0][0]
+
+
+def is_cn_index(market: int, code: str) -> bool:
+ """A股指数代码判定:88开头板块指数 / 沪市000 / 深市399。
+
+ 深市股票 000001 不是指数,必须带市场判断。
+ """
+ code = str(code)
+ return (
+ code.startswith("88")
+ or (code.startswith("000") and int(market) == int(Market.SH))
+ or (code.startswith("399") and int(market) == int(Market.SZ))
+ )
diff --git a/tests/test_all_interfaces.py b/tests/test_all_interfaces.py
new file mode 100644
index 0000000..84a136a
--- /dev/null
+++ b/tests/test_all_interfaces.py
@@ -0,0 +1,597 @@
+"""全接口回归:mock 连接,逐个调用 ``TdxData`` 的每一个公开方法。
+
+目标是「没有接口是死的」——每个公开方法至少被真实调用一次并返回预期形状。
+末尾的 ``test_every_public_method_was_exercised`` 用 AST 解析 ``api.py``,
+断言覆盖集合与全部公开方法**完全相等**:以后新增方法若没纳入本文件就会失败
+(与 ``scripts/check_docs.py`` 的 ``MUST_LIST_ALL`` 互为呼应)。
+
+不连任何网络:标准 / MAC / EX 连接全部被 mock;探测缓存被短路。
+"""
+from __future__ import annotations
+
+import ast
+import datetime
+import io
+import pathlib
+import struct
+import time
+import zipfile
+from unittest import mock
+
+import pytest
+
+from pytdxdata.api import TdxData
+from pytdxdata.models import (
+ AuctionItem,
+ BelongBoard,
+ BoardInfo,
+ CapitalFlow,
+ FinanceRecord,
+ MemberQuote,
+ MinuteBar,
+ SecurityBar,
+ SecurityInfo,
+ SecurityQuote,
+ ServerInfo,
+ SymbolSnapshot,
+ TransactionRecord,
+ UnusualItem,
+ XdxrRecord,
+)
+
+# --------------------------------------------------------------------------- #
+# 覆盖追踪
+# --------------------------------------------------------------------------- #
+
+EXERCISED: set[str] = set()
+
+
+def _use(name: str) -> None:
+ EXERCISED.add(name)
+
+
+def _public_methods() -> set[str]:
+ """AST 解析 api.py,取 TdxData 的全部公开方法名(与 check_docs 同口径)。"""
+ src = pathlib.Path(__file__).resolve().parent.parent / "src" / "pytdxdata" / "api.py"
+ tree = ast.parse(src.read_text(encoding="utf-8"))
+ for node in ast.walk(tree):
+ if isinstance(node, ast.ClassDef) and node.name == "TdxData":
+ return {
+ item.name
+ for item in node.body
+ if isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef)
+ and not item.name.startswith("_")
+ }
+ raise AssertionError("api.py 里找不到 TdxData")
+
+
+# --------------------------------------------------------------------------- #
+# mock 数据
+# --------------------------------------------------------------------------- #
+
+_TOTAL_BARS = 2000
+_BASE_DATE = datetime.date(2026, 9, 16)
+_QUOTE_FIELDS = {
+ "0x0": 9.8, "0x1": 9.9, "0x2": 10.2, "0x3": 9.7, "0x4": 10.0,
+ "0x5": 1000.0, "0x6": 1.0, "0x7": 1_000_000.0, "0x38": 5000.0,
+}
+
+
+def _mk_bar(market: int, code: str, offset: int) -> SecurityBar:
+ """offset 越大越老(标准通道语义:offset 0 = 最新一根)。"""
+ d = _BASE_DATE - datetime.timedelta(days=offset)
+ return SecurityBar(
+ market=market, code=code, open=10.0, high=10.5, low=9.5,
+ close=10.0 + (offset % 5) * 0.1, vol=1000.0, amount=10000.0,
+ year=d.year, month=d.month, day=d.day, hour=9, minute=30,
+ )
+
+
+def _bars(start: int, count: int, market: int, code: str) -> list[SecurityBar]:
+ hi = min(start + count, _TOTAL_BARS)
+ return [_mk_bar(market, code, i) for i in range(start, hi)]
+
+
+def _quote(market: int, code: str) -> SecurityQuote:
+ return SecurityQuote(
+ market=market, code=code, price=10.0, pre_close=9.8, open=9.9,
+ high=10.2, low=9.7, vol=1000.0, amount=1_000_000.0, s_vol=10.0,
+ b_vol=12.0, bid=[9.99] * 5, ask=[10.01] * 5,
+ )
+
+
+def _member(market: int, code: str) -> MemberQuote:
+ return MemberQuote(market=market, code=code, name="测试",
+ fields=dict(_QUOTE_FIELDS))
+
+
+class _FileMeta:
+ """对应 protocol.commands.mac_ext.FileMeta(避免直接依赖内部类)。"""
+
+ __slots__ = ("flag", "md5", "offset", "size")
+
+ def __init__(self, offset=0, size=4, flag=0, md5=""):
+ self.offset, self.size, self.flag, self.md5 = offset, size, flag, md5
+
+
+class _BlockMeta:
+ __slots__ = ("filename", "md5", "size")
+
+ def __init__(self, size=4, md5="", filename=""):
+ self.size, self.md5, self.filename = size, md5, filename
+
+
+def _dispatch(cmd) -> object:
+ """按命令类名返回形状正确的数据。"""
+ n = type(cmd).__name__
+ market = getattr(cmd, "market", 1)
+ code = getattr(cmd, "code", "600000")
+ start = getattr(cmd, "start", 0)
+ count = getattr(cmd, "count", 100) or 100
+
+ if n == "GetSecurityCountCmd":
+ return 8
+ if n == "GetSecurityListCmd":
+ return [SecurityInfo(market=1, code="600000", name="浦发银行",
+ volunit=100, decimal_point=2, pre_close=10.0)]
+ # ---- K线 ----
+ if n in ("GetSecurityBarsCmd", "GetIndexBarsCmd", "MacKlineCmd"):
+ return _bars(start, count, market, code)
+ if n == "GetExInstrumentBarsCmd":
+ return [{"year": 2026, "month": 9, "day": 1, "hour": 9, "minute": 30,
+ "open": 10.0, "high": 10.5, "low": 9.5, "close": 10.0,
+ "trade": 1000}]
+ # ---- 报价 ----
+ if n == "GetSecurityQuotesCmd":
+ return [_quote(m, c) for m, c in cmd.stocks]
+ if n == "MacSymbolQuotesCmd":
+ return [_member(m, c) for m, c in cmd.stocks]
+ if n == "MacBoardMembersQuotesCmd":
+ return [_member(1, "600000")]
+ # ---- 逐笔 / 分时 ----
+ if n == "MacTransactionCmd":
+ return [TransactionRecord(market=market, code=code, time="09:30",
+ price=10.0, vol=100.0, trade_count=1, bs_flag=0)]
+ if n in ("GetExTransactionDataCmd", "GetExHistoryTransactionDataCmd"):
+ return [{"minutes": 570, "price": 10.0, "vol": 100.0, "direction": 0,
+ "zengcang": 1.0}]
+ if n == "MacTickChartCmd":
+ return [MinuteBar(price=10.0, vol=100.0, hour=9, minute=30)]
+ if n == "SymbolTickChartCmd":
+ return [{"minutes": 570, "price": 10.0, "vol": 100.0, "avg": 10.0,
+ "momentum": 0.1}]
+ if n == "MacChartSamplingCmd":
+ return [10.0, 10.1, 10.2]
+ # ---- 公司信息 ----
+ if n == "MacSymbolInfoCmd":
+ return SymbolSnapshot(
+ market=market, code=code, name="浦发银行", date=20260916, time=930,
+ activity=1.0, pre_close=9.8, open=9.9, high=10.2, low=9.7,
+ close=10.0, vol=1000.0, amount=1_000_000.0, turnover=1.0,
+ avg_price=10.0)
+ if n == "MacAuctionCmd":
+ return [AuctionItem(time=93000, price=10.0, matched=100, unmatched=0)]
+ if n == "MacCapitalFlowCmd":
+ return CapitalFlow(market=market, code=code, main_buy=1.0, main_sell=1.0,
+ retail_buy=1.0, retail_sell=1.0, buy5=1.0, sell5=1.0,
+ big5=1.0, mid5=1.0)
+ if n == "GetXdxrInfoCmd":
+ return [XdxrRecord(market=market, code=code, year=2025, month=6, day=1,
+ category=1, name="除权除息")]
+ if n == "GetFinanceInfoCmd":
+ return FinanceRecord(market=market, code=code)
+ if n == "GetCompanyInfoCategoryCmd":
+ return [{"name": "最新提示", "filename": "600000.txt", "length": 10}]
+ if n == "GetCompanyInfoContentCmd":
+ return "公司资料正文"
+ # ---- 市场 / 板块 ----
+ if n == "MacUnusualCmd":
+ return [UnusualItem(market=1, code="600000", name="测试", type=1,
+ desc="描述", value=1.0, time=930)]
+ if n == "MacServerInfoCmd":
+ return ServerInfo(date=20260916, last_trade_date=20260915,
+ sessions=[(570, 690)])
+ if n == "MacKlineOffsetCmd":
+ return (_TOTAL_BARS, 100)
+ if n == "MacBoardListCmd":
+ return [BoardInfo(market=1, code="881001", name="银行", price=110.0,
+ rise_speed=0.1, pre_close=100.0)]
+ if n == "MacBelongBoardCmd":
+ return [BelongBoard(market=market, board_code=20686, board_name="银行",
+ close=110.0, pre_close=100.0)]
+ # ---- 文件 ----
+ if n == "MacFileListCmd":
+ return _FileMeta(size=4)
+ if n == "GetBlockInfoMetaCmd":
+ return _BlockMeta(size=4)
+ if n in ("GetBlockInfoCmd", "GetReportFileCmd", "MacFileDownloadCmd"):
+ return b"abcd"
+ # ---- EX 市场 ----
+ if n == "GetExInstrumentCountCmd":
+ return 2
+ if n == "GetExInstrumentInfoCmd":
+ return [{"market": 31, "code": "00700", "name": "腾讯控股", "desc": "港股"},
+ {"market": 74, "code": "AAPL", "name": "苹果", "desc": "美股"}]
+ return []
+
+
+class _MockConn:
+ """替代 TdxConnection / ExTdxConnection。"""
+
+ def __init__(self, host="h", port=7709, timeout=3.0, *args, **kwargs):
+ self.host = host
+ self.server = host
+ self.port = port
+ self.timeout = timeout
+ self.alive = True
+ self.last_used = time.monotonic()
+
+ async def connect(self) -> None:
+ self.alive = True
+
+ async def close(self) -> None:
+ self.alive = False
+
+ async def ping(self):
+ return 0.01
+
+ async def execute(self, cmd):
+ self.last_used = time.monotonic()
+ return _dispatch(cmd)
+
+
+# --------------------------------------------------------------------------- #
+# 离线文件样本(供 *_parsed / get_file 走通解析路径)
+# --------------------------------------------------------------------------- #
+
+_HEADER = 384
+
+
+def _make_block_dat() -> bytes:
+ out = bytearray(_HEADER)
+ out += struct.pack(" bytes:
+ entry = struct.pack("<6sBL", b"600000", 1, 31)
+ header = struct.pack("<1hI1H3L", 0, 20260331, 1, 0, 8, 0)
+ dat = header + entry + struct.pack("<2f", 1.0, 2.0)
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ zf.writestr("gpcw.dat", dat)
+ return buf.getvalue()
+
+
+# --------------------------------------------------------------------------- #
+# fixture
+# --------------------------------------------------------------------------- #
+
+@pytest.fixture
+async def td():
+ with mock.patch("pytdxdata.api.get_standard_hosts", return_value=["s1"]), \
+ mock.patch("pytdxdata.api.get_mac_hosts", return_value=["m1"]), \
+ mock.patch("pytdxdata.api.get_ex_hosts", return_value=["e1"]), \
+ mock.patch("pytdxdata.pool.pool.TdxConnection", new=_MockConn), \
+ mock.patch("pytdxdata.pool.ex_pool.ExTdxConnection", new=_MockConn), \
+ mock.patch("pytdxdata.pool.pool.get_probe_cache",
+ return_value=mock.MagicMock(ensure_probe=mock.AsyncMock())):
+ t = TdxData(cache_dir=None, pool_min=1, pool_max=2)
+ _use("start")
+ await t.start()
+ try:
+ yield t
+ finally:
+ _use("close")
+ await t.close()
+
+
+# --------------------------------------------------------------------------- #
+# 一、标的清单 / 报价 / 快照
+# --------------------------------------------------------------------------- #
+
+async def test_universe_and_quotes(td):
+ for name in ("get_universe", "get_quotes"):
+ _use(name)
+ uni = await td.get_universe()
+ assert isinstance(uni, list) and uni
+ cn = await td.get_universe("sz")
+ assert isinstance(cn, list)
+ ex = await td.get_universe("hk")
+ assert isinstance(ex, list)
+
+ q = await td.get_quotes(["sh600000", "sz000001"])
+ assert len(q) == 2 and all(x.symbol for x in q)
+ qf = await td.get_quotes(["sh600000"], fields=[0x00, 0x04])
+ assert qf[0].name == "测试"
+ qex = await td.get_quotes(["hk00700"])
+ assert len(qex) == 1
+
+
+async def test_snapshot_auction_flow(td):
+ for name in ("get_snapshot", "get_auction", "get_capital_flow"):
+ _use(name)
+ snaps = await td.get_snapshot("sh600000")
+ assert len(snaps) == 1 and snaps[0].name == "浦发银行"
+ auc = await td.get_auction("sh600000")
+ assert len(auc) == 1
+ flow = await td.get_capital_flow("sh600000")
+ assert len(flow) == 1 and flow[0].main_buy == 1.0
+
+
+# --------------------------------------------------------------------------- #
+# 二、K线 / 指标
+# --------------------------------------------------------------------------- #
+
+async def test_bars(td):
+ _use("get_bars")
+ bars = await td.get_bars("sh600000", count=120)
+ assert len(bars) == 120
+ assert all(b.symbol == "sh600000" for b in bars)
+ # 分页(超过单页)
+ big = await td.get_bars("sh600000", count=2000, concurrency=2)
+ assert len(big) == 2000
+ # 复权走 MAC 通道
+ qfq = await td.get_bars("sh600000", count=200, adjust=None) # NONE -> 标准
+ assert len(qfq) == 200
+ from pytdxdata.models import Adjust
+ mac = await td.get_bars("sh600000", count=200, adjust=Adjust.QFQ)
+ assert len(mac) == 200
+ # 多标的并发
+ multi = await td.get_bars(["sh600000", "sz000001"], count=60)
+ assert len(multi) == 120
+ # 日期区间(二分定位路径)
+ dated = await td.get_bars(
+ "sh600000", start_date=datetime.datetime(2026, 8, 1),
+ end_date=datetime.datetime(2026, 8, 31))
+ assert isinstance(dated, list)
+ # 扩展市场 K线
+ exb = await td.get_bars("hk00700", count=60)
+ assert isinstance(exb, list)
+
+
+async def test_indicators(td):
+ _use("get_indicators")
+ sets = await td.get_indicators("sh600000", ["macd", "kdj", "rsi"], count=30)
+ assert len(sets) == 1
+ assert sets[0].symbol == "sh600000"
+ assert sets[0].indicators # 指标分量名(DIF/DEA/K/D/J/RSI* 等)
+
+
+# --------------------------------------------------------------------------- #
+# 三、逐笔 / 分时
+# --------------------------------------------------------------------------- #
+
+async def test_ticks(td):
+ _use("get_ticks")
+ rows = await td.get_ticks("sh600000", date=20260811, count=10)
+ assert isinstance(rows, list) and rows and all(r.symbol for r in rows)
+ full = await td.get_ticks("sh600000", count=None)
+ assert isinstance(full, list)
+ hk = await td.get_ticks("hk00700", count=10)
+ assert isinstance(hk, list)
+
+
+async def test_minutes(td):
+ _use("get_minutes")
+ rows = await td.get_minutes("sh600000")
+ assert isinstance(rows, list) and rows
+ hist = await td.get_minutes("sh600000", date=20260811)
+ assert isinstance(hist, list)
+ samp = await td.get_minutes("sh600000", sampling=True)
+ assert [b.price for b in samp] == [10.0, 10.1, 10.2]
+ exm = await td.get_minutes("hk00700")
+ assert isinstance(exm, list)
+
+
+# --------------------------------------------------------------------------- #
+# 四、公司信息 / 市场
+# --------------------------------------------------------------------------- #
+
+async def test_company_info(td):
+ for name in ("get_xdxr", "get_finance", "get_price_limits", "get_f10"):
+ _use(name)
+ x = await td.get_xdxr("sh600000")
+ assert isinstance(x, list) and x
+ fin = await td.get_finance("sh600000")
+ assert isinstance(fin, list) and fin and fin[0].symbol == "sh600000"
+ lo, hi = await td.get_price_limits("sh600000", name="浦发银行", pre_close=10.0)
+ assert (lo, hi) == (lo, hi) # 本地计算,不连网
+ cat = await td.get_f10("sh600000")
+ assert isinstance(cat, list)
+ body = await td.get_f10("sh600000", section="600000.txt")
+ assert isinstance(body, str)
+
+
+async def test_market(td):
+ for name in ("get_market_stat", "get_unusual", "get_server_info",
+ "get_kline_offset"):
+ _use(name)
+ stat = await td.get_market_stat()
+ assert stat.up_count == 100 # price 10.0 * 10
+ un = await td.get_unusual("sh")
+ assert isinstance(un, list) and un
+ info = await td.get_server_info()
+ assert info.date == 20260916
+ off = await td.get_kline_offset()
+ assert off == (_TOTAL_BARS, 100)
+
+
+# --------------------------------------------------------------------------- #
+# 五、板块
+# --------------------------------------------------------------------------- #
+
+async def test_boards(td):
+ for name in ("get_boards", "get_board_members", "get_board_of",
+ "get_board_summary", "get_board_ranking",
+ "get_board_change_ranking"):
+ _use(name)
+ bl = await td.get_boards("all")
+ assert isinstance(bl, list) and bl
+ mem = await td.get_board_members("881001")
+ assert isinstance(mem, list) and mem
+ of = await td.get_board_of("sh600000")
+ assert isinstance(of, list) and of
+ summ = await td.get_board_summary("881001")
+ assert set(summ) == {"member_count", "amount", "main_net_amount",
+ "up_count", "down_count"}
+ rank = await td.get_board_ranking("industry")
+ assert isinstance(rank, list)
+ chg = await td.get_board_change_ranking("industry", days=5)
+ assert isinstance(chg, list)
+
+
+# --------------------------------------------------------------------------- #
+# 六、服务器文件
+# --------------------------------------------------------------------------- #
+
+async def test_files(td):
+ _use("get_file")
+ raw = await td.get_file("block_gn.dat")
+ assert raw == b"abcd"
+
+
+async def test_parsed_files(td):
+ for name in ("get_block_parsed", "get_industry_map",
+ "get_financial_file_infos", "get_financial_records_parsed"):
+ _use(name)
+ with mock.patch.object(td, "get_file",
+ new=mock.AsyncMock(return_value=_make_block_dat())):
+ blocks = await td.get_block_parsed("block_gn.dat")
+ assert blocks and blocks[0].category == 2
+
+ with mock.patch.object(td, "get_file",
+ new=mock.AsyncMock(
+ return_value="0|000001|A01|||S01\n".encode("gbk"))):
+ ind = await td.get_industry_map()
+ assert ind["000001"].sw_industry == "S01"
+
+ with mock.patch.object(td, "get_file",
+ new=mock.AsyncMock(
+ return_value=b"gpcw20260331.zip,abc,1024\n")):
+ infos = await td.get_financial_file_infos()
+ assert infos[0].filesize == 1024
+
+ with mock.patch.object(td, "get_file",
+ new=mock.AsyncMock(return_value=_make_financial_zip())):
+ recs = await td.get_financial_records_parsed("tdxfin/gpcw20260331.zip")
+ assert len(recs) == 1 and recs[0].report_date == 20260331
+
+
+# --------------------------------------------------------------------------- #
+# 七、废弃别名(33 个)
+# --------------------------------------------------------------------------- #
+
+async def test_aliases_kline(td):
+ for name in ("get_kline", "get_kline_since", "get_kline_batch",
+ "get_index_kline", "get_stock_kline_with_indicators"):
+ _use(name)
+ import warnings
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", DeprecationWarning)
+ assert len(await td.get_kline(1, "600000", 4, count=60)) == 60
+ assert len(await td.get_kline_since(
+ 1, "600000", 4, datetime.datetime(2026, 8, 1))) >= 0
+ batch = await td.get_kline_batch([(1, "600000"), (0, "000001")], 4, count=30)
+ assert isinstance(batch, dict) and batch
+ assert len(await td.get_index_kline(1, "000001", 4, count=30)) == 30
+ withind = await td.get_stock_kline_with_indicators(1, "600000", ["macd"])
+ assert "bars" in withind and "indicators" in withind
+
+
+async def test_aliases_quotes_ticks(td):
+ for name in ("get_stock_quotes", "get_stock_quotes_list", "get_transactions",
+ "get_minute", "get_minute_batch", "get_chart_sampling"):
+ _use(name)
+ import warnings
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", DeprecationWarning)
+ assert len(await td.get_stock_quotes([(1, "600000")])) == 1
+ assert isinstance(await td.get_stock_quotes_list(1, count=10), list)
+ assert isinstance(await td.get_transactions(1, "600000", count=10), list)
+ assert isinstance(await td.get_minute(0, "000001"), list)
+ mb = await td.get_minute_batch([(1, "600000")])
+ assert isinstance(mb, dict)
+ assert (await td.get_chart_sampling(1, "600000")) == [10.0, 10.1, 10.2]
+
+
+async def test_aliases_universe(td):
+ for name in ("get_security_count", "get_security_list",
+ "get_security_list_all"):
+ _use(name)
+ import warnings
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", DeprecationWarning)
+ assert await td.get_security_count(0) == 8
+ assert isinstance(await td.get_security_list(0, count=1), list)
+ assert isinstance(await td.get_security_list_all(0), list)
+
+
+async def test_aliases_files(td):
+ for name in ("get_financial_file_list", "get_financial_records",
+ "get_company_info_category", "get_company_info_content",
+ "get_block_info", "get_report_file", "get_file_meta",
+ "download_file"):
+ _use(name)
+ import warnings
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", DeprecationWarning)
+ assert await td.get_financial_file_list() == ["abcd"]
+ assert await td.get_financial_records("tdxfin/gpcw.txt") == b"abcd"
+ assert isinstance(await td.get_company_info_category(1, "600000"), list)
+ assert isinstance(await td.get_company_info_content(
+ 1, "600000", "f.txt"), str)
+ assert await td.get_block_info("block_gn.dat") == b"abcd"
+ assert await td.get_report_file("tdxhy.cfg") == b"abcd"
+ assert (await td.get_file_meta("x.dat")).size == 4
+ assert await td.download_file("x.dat") == b"abcd"
+
+
+async def test_aliases_boards(td):
+ for name in ("get_board_list", "get_belong_board", "get_symbol_info"):
+ _use(name)
+ import warnings
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", DeprecationWarning)
+ assert isinstance(await td.get_board_list(0), list)
+ assert isinstance(await td.get_belong_board(1, "600000"), list)
+ snap = await td.get_symbol_info(1, "600000")
+ assert snap is not None and snap.name == "浦发银行"
+
+
+async def test_aliases_goods(td):
+ for name in ("get_goods_list", "get_goods_count", "get_goods_quotes",
+ "get_goods_quotes_list", "get_goods_chart_sampling",
+ "get_goods_tick_chart", "get_goods_transaction",
+ "get_goods_transaction_all"):
+ _use(name)
+ import warnings
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", DeprecationWarning)
+ assert isinstance(await td.get_goods_list(31), list)
+ assert await td.get_goods_count(31) == 1 # 只有 1 条 market=31
+ assert isinstance(await td.get_goods_quotes([(31, "00700")]), list)
+ assert isinstance(await td.get_goods_quotes_list(31), list)
+ assert await td.get_goods_chart_sampling(31, "00700") == [10.0, 10.1, 10.2]
+ assert isinstance(await td.get_goods_tick_chart(31, "00700"), list)
+ assert isinstance(await td.get_goods_transaction(31, "00700"), list)
+ assert isinstance(await td.get_goods_transaction_all(31, "00700"), list)
+
+
+# --------------------------------------------------------------------------- #
+# 八、覆盖完整性(必须放最后)
+# --------------------------------------------------------------------------- #
+
+def test_every_public_method_was_exercised():
+ expected = _public_methods()
+ missing = sorted(expected - EXERCISED)
+ assert not missing, f"以下公开方法未被回归测试覆盖: {missing}"
+ extra = sorted(EXERCISED - expected)
+ assert not extra, f"覆盖集合包含非公开方法: {extra}"
diff --git a/tests/test_codec_files.py b/tests/test_codec_files.py
index 2bc0f18..478ff30 100644
--- a/tests/test_codec_files.py
+++ b/tests/test_codec_files.py
@@ -252,7 +252,7 @@ def _new_tdxdata() -> TdxData:
async def test_api_get_block_parsed():
td = _new_tdxdata()
raw = _make_block_dat([("银行", ["000001"], 1, 1)])
- with mock.patch.object(td, "get_block_info", new=mock.AsyncMock(return_value=raw)):
+ with mock.patch.object(td, "get_file", new=mock.AsyncMock(return_value=raw)):
blocks = await td.get_block_parsed("block_gn.dat")
assert len(blocks) == 1
assert blocks[0].category == 2 # gn -> 概念
@@ -263,7 +263,7 @@ async def test_api_get_industry_map():
td = _new_tdxdata()
raw = "0|000001|A01|||S01\n".encode("gbk")
patched = mock.AsyncMock(return_value=raw)
- with mock.patch.object(td, "get_report_file", new=patched):
+ with mock.patch.object(td, "get_file", new=patched):
result = await td.get_industry_map()
patched.assert_awaited_once_with("tdxhy.cfg")
assert result["000001"].sw_industry == "S01"
@@ -274,7 +274,7 @@ async def test_api_get_financial_file_infos():
td = _new_tdxdata()
raw = b"gpcw20260331.zip,abc,1024\n"
patched = mock.AsyncMock(return_value=raw)
- with mock.patch.object(td, "get_report_file", new=patched):
+ with mock.patch.object(td, "get_file", new=patched):
infos = await td.get_financial_file_infos()
patched.assert_awaited_once_with("tdxfin/gpcw.txt")
assert infos[0].filesize == 1024
@@ -284,7 +284,7 @@ async def test_api_get_financial_file_infos():
async def test_api_get_financial_records_parsed():
td = _new_tdxdata()
zip_bytes = _make_financial_zip(_valid_two_record_dat())
- with mock.patch.object(td, "get_report_file",
+ with mock.patch.object(td, "get_file",
new=mock.AsyncMock(return_value=zip_bytes)):
recs = await td.get_financial_records_parsed("tdxfin/gpcw20260331.zip")
assert len(recs) == 2
@@ -294,7 +294,7 @@ async def test_api_get_financial_records_parsed():
@pytest.mark.asyncio
async def test_api_get_financial_records_parsed_empty_zip_data():
td = _new_tdxdata()
- with mock.patch.object(td, "get_report_file",
+ with mock.patch.object(td, "get_file",
new=mock.AsyncMock(return_value=b"")):
assert await td.get_financial_records_parsed("tdxfin/gpcw20260331.zip") == []
@@ -303,7 +303,7 @@ async def test_api_get_financial_records_parsed_empty_zip_data():
async def test_api_get_financial_records_parsed_no_dat_member():
td = _new_tdxdata()
zip_bytes = _make_financial_zip(b"whatever", inner_name="readme.txt")
- with mock.patch.object(td, "get_report_file",
+ with mock.patch.object(td, "get_file",
new=mock.AsyncMock(return_value=zip_bytes)):
assert await td.get_financial_records_parsed("nodate.zip") == []
@@ -313,7 +313,7 @@ async def test_api_get_financial_records_parsed_no_date_in_name():
"""文件名无 8 位日期 -> 回退用 .dat 头部报告期。"""
td = _new_tdxdata()
zip_bytes = _make_financial_zip(_valid_two_record_dat())
- with mock.patch.object(td, "get_report_file",
+ with mock.patch.object(td, "get_file",
new=mock.AsyncMock(return_value=zip_bytes)):
recs = await td.get_financial_records_parsed("gpcw.zip")
assert recs[0].report_date == 20260331
diff --git a/uv.lock b/uv.lock
index b87d940..ba85c19 100644
--- a/uv.lock
+++ b/uv.lock
@@ -535,7 +535,7 @@ wheels = [
[[package]]
name = "pytdxdata"
-version = "0.5.0"
+version = "0.6.0"
source = { editable = "." }
[package.optional-dependencies]