From 3e0beb27a6bda2e7f83da628892f0740edf876ed Mon Sep 17 00:00:00 2001 From: openbot-coder Date: Thu, 17 Sep 2026 11:34:52 +0800 Subject: [PATCH] =?UTF-8?q?release:=20v0.6.0=EF=BC=88=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E5=AF=B9=E5=A4=96=E6=8E=A5=E5=8F=A3=E9=87=8D=E6=9E=84=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按「数据类型」合并同类查询接口:一个数据类型 = 一个方法,跨市场自动选路。 - 28 个统一接口(get_universe/get_quotes/get_bars/get_indicators/get_ticks/ get_minutes/get_f10/get_file/get_boards/get_board_of/get_snapshot 等), 标的统一字符串写法(sz000001 / hk00700 / usAAPL / cffex:IFL0); 同名旧方法不再兼容 (market, code) 元组。 - 旧 51 个按通道/市场分裂的接口:33 个保留为 deprecated 别名(1.0 移除), 18 个同名升级为统一接口。公开方法共 63 个。 - 新增库层标的解析 pytdxdata.symbols;数据模型追加 symbol/name/fields 兜底字段。 - 修复:分页器连接泄漏、日期区间 K线返回 0 条(偏移方向探测)、池子全冷却死等。 - 文档/README/SKILL/llms.txt 全量同步;新增 docs/refactor-audit.md 审查报告。 - 测试 127 个用例全绿(含 tests/test_all_interfaces.py 全 63 方法回归)。 --- CHANGELOG.md | 66 +- README.md | 19 +- SKILL.md | 93 +- docs/API_REFERENCE.md | 78 +- docs/ai.md | 19 +- docs/api/codec.md | 2 +- docs/api/enums.md | 14 +- docs/api/index.md | 123 +- docs/api/models.md | 22 +- docs/api/tdxdata.md | 4 +- docs/contributing.md | 12 +- docs/cookbook.md | 63 +- docs/index.md | 7 +- docs/internals/architecture.md | 9 +- docs/internals/cache-pool.md | 2 +- docs/internals/routing.md | 10 +- docs/llms.txt | 41 +- docs/refactor-audit.md | 148 ++ examples/quickstart.py | 9 +- mkdocs.yml | 1 + pyproject.toml | 2 +- scripts/check_docs.py | 6 +- src/pytdxdata/__init__.py | 2 +- src/pytdxdata/api.py | 2243 +++++++++++++++----------- src/pytdxdata/cache/key.py | 11 +- src/pytdxdata/cli.py | 74 +- src/pytdxdata/models/__init__.py | 57 +- src/pytdxdata/pool/pool.py | 11 +- src/pytdxdata/scheduler/paginator.py | 58 +- src/pytdxdata/symbols.py | 240 +++ tests/test_all_interfaces.py | 597 +++++++ tests/test_codec_files.py | 14 +- uv.lock | 2 +- 33 files changed, 2789 insertions(+), 1270 deletions(-) create mode 100644 docs/refactor-audit.md create mode 100644 src/pytdxdata/symbols.py create mode 100644 tests/test_all_interfaces.py 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]