6 Commits
Author SHA1 Message Date
openbot-coder 8951ec2678 fix(api,codec): 修复 BUG-1 分时采样走错命令 + BUG-2 财务文件名纠正
BUG-1: A股 get_minutes(sampling=True) 原走 MacChartSamplingCmd(0x254D)
这是 EX 协议命令,7709 主机无响应(3×8s 超时≈24s)。
修复:A股采样由 MacTickChartCmd(0x122D) 分时数据派生,
EX 市场(hk)仍走 0x254D。4 个 A股 场景均<0.1s 返回 240 点。

BUG-2: tdxfin/gpcw.txt 索引声明 gpcwYYYYMMDD.zip,
但服务器实际只有 tdxfin/gpcwYYYYMMDD.dat(未压缩,~13MB),
.zip 请求返回 0-1 字节空壳。
修复:_fetch_financial_dat() 自动候选回退
tdxfin/*.zip → tdxfin/*.dat → 原始文件名,加 looks_like_gpcw_dat 校验。
实测 gpcw20260630.zip→5568 条,gpcw20260331.zip→5547 条。

新增 codec/financial.py: looks_like_gpcw_dat, extract_gpcw_dat(含 zip/未压缩双通道)。
同步更新 README/API_REFERENCE/docs/cli/cookbook/CHANGELOG 共 6 处文档。
tests: +18(总 182),ruff 无新增 findings,MkDocs strict 通过。
2026-09-21 20:47:48 +08:00
openbot-coder b78d0fabf5 docs: 修正 servers.json 清理后遗留的过时描述(含一处事实反转)
servers.json 复测后三池台数已变(standard 9 / mac 22 / ex 4),但 README 与部分文档
仍停留在旧口径,且有一处因果结论被实测推翻:

- README.md
  - 测试用例数 127 → 164(并补「当日测速缓存」到用例分组说明)
  - 「已知限制」补测速缓存详情的文档站链接
- docs/internals/routing.md
  - 三池台数:标准池「数十台」→ 9 台、MAC 池「数台」→ 22 台(EX 池 4 台不变),
    并标注为 2026-09-21 离线探针实测可达数、实际以当日测速缓存为准
  - **事实反转修正**:原文「MAC 池远小于标准池,这解释了逐笔/分时并发弱于日线」
    与实测不符(mac 22 > standard 9)→ 已改为陈述实测台数,
    并指出两通道单台连接上限默认相同(均 4)
- docs/internals/cache-pool.md
  - 「为什么 MAC 池更小」小节前提已不成立 → 改为「MAC 通道的单台连接上限」,
    保留 mac_pool_cap=4 的可用信息,删除错误因果
- docs/refactor-audit.md
  - 历史快照的 127 passed 标注「审查当时」,避免误读为当前基线

验证:scripts/check_docs.py exit 0;mkdocs build --strict exit 0(无告警)
2026-09-21 19:42:06 +08:00
openbot-coder d422385877 chore(servers): 离线探针复测重写 servers.json,并给探针工具补 --discover
servers.json(真数据复测 2026-09-21,两轮零漂移)
- 剔除历史脏记录 s1;刷新 status/latency/checked_at/checked_date/fast_pool
- 可达 25/33:standard 9 台、mac 22 台、ex 4 台(旧文件 mac 只标了 10 台)
- 关键发现:14 台服务器 0x010C 标准 K 线已成空响应(回 2 字节空壳),
  但同端口同主机的 0x122E MAC 帧正常 → 据实测把 protocols 由 standard/mac 收窄为 mac
- 8 台不可达:华林 4 台(218.106.92.182/183, 220.178.55.71/86)、159.75.55.232、
  117.34.114.13/14/30 → status=fail
- 117.34.114.17 实测 standard+mac 均通(此前只申报 standard)

server_probe.py
- 新增 --discover:三种协议全测并据实修正 protocols(顺带剔除 ip 非法记录)
- 失败重试一次再判定不支持(单次抖动会误删协议,且收窄后不会自动恢复)
- EX 握手模式申报错时换另一种再试(login <=> setup)
- 补写 checked_date / fast_pool / 顶层 version·note,入池规则与运行时缓存一致

验证:164 passed;servers.json 跑测前后 sha 不变;check_docs.py + mkdocs --strict 通过
2026-09-21 19:05:32 +08:00
openbot-coder 7e830c7579 docs: 补齐测速缓存相关文档,并修掉 0.6.0 遗留的过时描述
上一提交只补了 getting-started / routing / llms.txt / SKILL.md 四处,本轮把其余
教程类页面与接口清单补齐,并顺手修正 v0.6.0 统一接口改造后遗留的过时说明。

补齐(当日测速缓存):

- README「已知限制」:说明当日首次启动会自动后台测速并缓存
- FAQ 新增「启动时会变慢吗?会不会在后台偷偷联网?」:无感保证 + 三个环境变量开关
- FAQ「连不上服务器怎么办」:加入"删当日测速缓存 / 环境变量指定主机"两条前置排查
- API_REFERENCE 四、辅助模块:config 补全当日测速相关函数与优先级链说明,
  新增 pytdxdata.pool.probe_cache 一节(ProbeCache / schedule_probe / get_probe_cache)
- internals/architecture.md 目录树:config.py、probe_cache.py 的职责注释更新
- internals/cache-pool.md「下一步」:补「服务器是怎么选出来的」交叉链接

修正(v0.6.0 遗留过时描述):

- FAQ / api/enums.md:删掉「所有接口的第一个参数都是 market」——统一接口已改为字符串标的
- FAQ / cookbook:`*_batch` 已并入 `get_bars`(多标的),不再作为批量入口
- FAQ / getting-started「自建服务器清单」:`standard_servers` 实际是 Sequence[str]
  而非 (host, port) 元组(端口由统一的 port= 指定);原示例照抄会取到错的主机名
  (已实测:字符串写法正确,元组写法不会被解析)

校验:check_docs.py exit 0;mkdocs build --strict 无告警;新增交叉链接
#当日自动测速无感 / #daily-probe 均正确渲染且目标锚点存在;全量 164 项通过;
src/pytdxdata/servers.json 跑测前后逐字节不变。
2026-09-21 18:26:37 +08:00
openbot-coder c7c6c70333 chore(release): 版本号升至 0.6.1
在 v0.6.0 基线上发布当日测速缓存重写(见上一提交)。

版本号四处对齐:pyproject.toml / src/pytdxdata/__init__.py / uv.lock / CHANGELOG.md。
uv lock --check 通过(lockfile 与 pyproject 一致)。

同时修正 0.6.0 全接口回归测试与本次改动的集成冲突:
tests/test_all_interfaces.py 的 td fixture 原先替身 pool.pool.get_probe_cache,
而本次已把池内探针入口改为 pool.pool.schedule_probe,导致 fixture setup 抛
AttributeError(17 个用例 ERROR + 1 个 FAILED)。改为替身 schedule_probe 并返回 None
(与"无事件循环时不排期"的真实语义一致),单测既不再因属性缺失报错,也不会真的发起后台测速。

全量 164 项通过;mkdocs build --strict 通过;src/pytdxdata/servers.json 跑测前后逐字节不变。
2026-09-21 18:05:11 +08:00
openbot-coder 18d9e9a006 fix(pool): 重写当日测速缓存:全量候选 + 用户级缓存 + 真实数据探针
原实现在 v0.5.0 已随包发布,但有三处会"静默失效"的缺陷,等于没真正生效:

- 候选集自指:连接池把自己已过滤后的成员当探针输入,实测只重测了 9 台,
  另外 20+ 台候选(含快节点)永远测不到。改为由 probe_cache 自行枚举
  全量候选(包内清单 ∪ 代码常量 ∪ env),不再接受调用方传入的"当前池成员"。
- 写回安装目录:结果写回 src/pytdxdata/servers.json,容器/系统级安装下只读会
  静默失败、多用户共用一个安装会互相覆盖,且污染随包分发的数据。改为写入
  用户级缓存目录(Win %LOCALAPPDATA% / macOS ~/Library/Caches / Linux $XDG_CACHE_HOME),
  运行时绝不再改写包内清单。
- 探测太弱:只做握手,测不出「握手正常但 K 线空响应」的坏节点。改为发真实业务
  命令并要求返回非空(标准 GetSecurityBarsCmd / MAC MacKlineCmd / EX GetExInstrumentBarsCmd),
  EX 池(4 台,7727)也一并纳入。

无感保证:后台 task 不阻塞 start()、日志全 debug 级、绝不抛异常(取消除外)、
原子写 tmp + os.replace、进程内单例 + asyncio.Lock 单飞;全不可达时不写缓存
(否则"今天全挂"会被缓存一整天)。close() 会取消并 await 后台探针,
避免解释器退出时报 "Task was destroyed but it is pending"。

新增环境变量 PYPYTDX_DATA_CACHE_DIR(覆盖缓存目录)、
PYPYTDX_DATA_DISABLE_PROBE=1(关闭测速)。新增 tests/test_probe_cache.py(37 项)。
2026-09-21 17:54:29 +08:00
28 changed files with 1796 additions and 399 deletions

No files matched your search

+56
View File
@@ -2,6 +2,62 @@
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
## [0.6.1] - 2026-09-21
### 变更
- **重写「当日首次启动测速缓存」,改为对用户完全无感**。原实现在 v0.5.0 已随包发布,但存在
三个会让它**静默失效**的缺陷,本次一并修正:
| 缺陷 | 原实现 | 现在 |
|---|---|---|
| 候选集自指 | 连接池只把自己**已过滤后的成员**交给探针 → 只重测了 9 台,另外 20+ 台候选(含快节点)永远测不到 | 探针内部取**全部候选**(包内清单 ∪ 代码常量 ∪ env) |
| 写回安装目录 | 结果写回 `src/pytdxdata/servers.json` → 容器 / 系统级安装只读、多用户互相覆盖 | 改写入**用户级缓存目录**,包内清单运行时**绝不被改写** |
| 探测太弱 | 只做握手(`TdxConnection.test`),测不出「握手正常但 K 线空响应」的坏节点 | 发**真实业务命令**并要求返回非空(标准 / MAC / EX 各一) |
| EX 池漏测 | EX 的 4 台从未被探测 | EX 一并纳入(7727 + 各自握手模式) |
- 测速结果按**实测延迟升序**被 `config.get_standard_hosts()` 等采用;当天已有缓存则**不再刷新**。
后台执行,不阻塞 `start()`、不打印、失败静默降级。
- 本版基于 **0.6.0 的统一对外接口**构建(`get_bars` + 字符串标的);同时把 0.6.0
全接口回归测试里对旧探针入口(`pool.get_probe_cache`)的替身改为新入口(`pool.schedule_probe`),
保证单测不触发真实网络测速。
### 修复
- **A股分时缩略采样 100% 失败**(`get_minutes(sampling=True)` / `get_chart_sampling()`):
旧实现走 `MacChartSamplingCmd`(**0x254D**),但该 opcode 属于 **EX 协议**,7709 标准 /
MAC 主机对它一律不响应——实测 3 台主机各 10s 超时,叠加连接池 3 次重试约 24s 才抛错。
现改为**由分时(0x122D)数据派生**价格点(分时本身就是 240 点,语义一致),
实测 4 个 A股 场景均在 0.1s 内返回 240 点;EX 通道仍用 0x254D(84 点)。
- **历史专业财报整条链路不可用**(`get_financial_records_parsed()`):
`tdxfin/gpcw.txt` 索引里写的是裸 `gpcwYYYYMMDD.zip`,而服务器**实际只提供未压缩的**
`tdxfin/gpcwYYYYMMDD.dat`。旧实现把索引名直接丢给 `zipfile` → 必然 `BadZipFile`;
废弃别名 `get_financial_records()` 更危险,会**静默返回 0~1 字节空壳**而不报错。
现按候选名(`tdxfin/*.zip` → `tdxfin/*.dat` → 原名)逐个尝试并校验数据形态,
zip 与未压缩 dat 都支持。实测 `gpcw20260630.zip` → **5568 条**、
`gpcw20260331.zip` → **5547 条**(样本 000001,584 个 float 字段),
别名返回 **13,068,116 字节**真实数据;尚未生成的占位条目
(如 `gpcw20260930.zip`,filesize=164)优雅返回空列表而非报错。
### 新增
- `codec.financial` 新增 `looks_like_gpcw_dat()` / `extract_gpcw_dat()`:
财报字节的形态判定与「zip / 未压缩 dat」统一提取(纯标准库,可脱网单测)
- 环境变量 `PYPYTDX_DATA_CACHE_DIR`(覆盖测速缓存目录)、
`PYPYTDX_DATA_DISABLE_PROBE`(关闭测速,CI / 测试用)
- `tests/test_probe_cache.py`(37 项):当日缓存不刷新、跨日重测、
原子写入且不留 tmp、**不改写包内 `servers.json`(逐字节校验)**、
单飞并发、非法主机过滤、`DISABLE_PROBE`、池 `start()` 不阻塞 / `close()` 取消后台探针
### 文档
- [安装与配置](https://openbot-coder.github.io/pytdxdata/getting-started/#当日自动测速无感):
新增「当日自动测速(无感)」小节——缓存路径、优先级链、环境变量一览
- [通道与数据源](https://openbot-coder.github.io/pytdxdata/internals/routing/#daily-probe):
新增「运行时:当日测速缓存」小节,逐条说明必须踩对的实现要点与反例
## [0.6.0] - 2026-09-16
### 新增
+5 -3
View File
@@ -65,7 +65,7 @@ df = pd.DataFrame([asdict(b) for b in bars])
| 🔀 双通道整合 | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1 分钟 K 线),按命令自动选路 |
| 📦 零重型依赖 | 纯 asyncio + stdlib(socket / zlib / struct / sqlite3) |
| 📊 全市场覆盖 | A股、港股、美股、期货、期权(46 个扩展市场) |
| 📄 服务器文件解析 | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 财报 `gpcw*.zip` **下载即解析**成 dataclass |
| 📄 服务器文件解析 | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 财报 `gpcw*` **下载即解析**成 dataclass(索引名与服务器实际文件名不一致时自动纠正) |
| 🤖 AI 助手友好 | 内置 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 与 [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) |
## 文档导航
@@ -104,7 +104,7 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \
```bash
uv sync # 建虚拟环境 + 注册 tdx 命令
uv run pytest tests/ # 127 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移)
uv run pytest tests/ # 182 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移 / 当日测速缓存)
uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings)
uv run mkdocs serve # 本地预览文档站
```
@@ -114,7 +114,9 @@ uv run mkdocs serve # 本地预览文档站
- 行情来自通达信公开服务器,**15 分钟延时**;需实时数据请使用券商行情
- 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避
- 港股 / 美股期权在通达信协议内无数据
- 服务器可用性随时间变化,可用 `python -m pytdxdata.server_probe` 重新探测
- 服务器可用性随时间变化。**当日首次启动会自动在后台测速并缓存**(对调用方无感,当天不再重测);
也可用 `python -m pytdxdata.server_probe` 离线重生成随包清单。
缓存路径与三个开关见 [安装与配置 → 当日自动测速](https://openbot-coder.github.io/pytdxdata/getting-started/#当日自动测速无感)
## 免责声明
+1
View File
@@ -184,6 +184,7 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约
| 循环里逐个 `await get_bars` | 慢 | 用列表传多个标的,自动并发 |
| 港股/美股五档 bid/ask | 没有(协议不支持) | `fields` 字段位通道有 name 但无五档 |
| 依赖实时性做信号 | 数据是 15 分钟前的 | 换券商实时源 |
| 手动改包内 `servers.json` / 写死 IP | 容器只读、升级被覆盖、快节点捞不回来 | 日常靠内置的**当日测速缓存**自动选路;要强制指定就用 `PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS` 环境变量 |
## 深入参考
+29 -10
View File
@@ -70,7 +70,7 @@ from pytdxdata import (
| 方法 | 返回 | 说明 |
|------|------|------|
| `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_minutes(symbols, *, date=None, sampling=False, concurrency=6)` | `list[MinuteBar]` | 跨市场分时(sampling=True 取缩略采样:A股由 0x122D 派生,扩展市场 0x254D) |
#### 公司信息/文件/板块
@@ -109,7 +109,7 @@ from pytdxdata import (
| `get_transactions(market, code, *, date=None, start=0, count=2000)` | `list[TransactionRecord]` | 逐笔成交(MAC,含 trade_count),支持历史日期 |
| `get_minute(market, code, *, date=None)` | `list[MinuteBar]` | 分时(MAC 0x122D,可历史) |
| `get_minute_batch(stocks, *, date=None, concurrency=6)` | `dict[str, list[MinuteBar]]` | 批量分时 |
| `get_chart_sampling(market, code)` | `list[float]` | 分时缩略采样(A股,MAC 0x254D) |
| `get_chart_sampling(market, code)` | `list[float]` | 分时缩略采样(A股由 MAC **0x122D** 派生;0x254D 仅 EX 通道可用) |
### 2.5 证券列表(旧接口,共 3 个) {#legacy-list}
@@ -131,13 +131,13 @@ from pytdxdata import (
| `get_block_info(filename)` | `bytes` | 板块文件**原始字节**(先查元数据再分块下载) |
| `get_report_file(filename)` | `bytes` | 报告/财务文件**原始字节**(标准 0x06B9) |
| `get_financial_file_list()` | `list[str]` | 财务文件列表**原始行**(tdxfin/gpcw.txt) |
| `get_financial_records(filename)` | `bytes` | 财务文件内容(gpcw*.zip 原始字节) |
| `get_financial_records(filename)` | `bytes` | 财报 `.dat` 原始字节(索引写 `.zip` 但服务器只有 `.dat` 时自动回退;取不到返回 `b""`) |
| `get_file_meta(filename)` | `FileMeta` | 远程文件元信息(MAC 0x1215) |
| `download_file(filename, filesize=0)` | `bytes` | 下载完整远程文件(MAC 0x1217,分块) |
| **`get_block_parsed(filename)`** | `list[TdxBlock]` | 板块文件**下载+解析**为板块成分(category 按文件名推断:0行业/2概念/3风格) |
| **`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 **解压+解析**:每股原始 float 字段(报告期取自文件名,缺失回退头部) |
| **`get_financial_records_parsed(filename)`** | `list[FinancialRecord]` | 财报**解析**:每股原始 float 字段。可直接传 `get_financial_file_infos()` 的 `filename`——自动纠正服务器实际文件名(`.zip`/`.dat` 两种形态都支持);报告期取自文件名,缺失回退头部 |
> 解析层独立于网络层:解析器位于 `pytdxdata.codec`(纯标准库 `struct`/`zipfile`),可脱网单测;
> 原 `get_*` 返回 `bytes`/`list[str]` 的方法保持**向后兼容**,解析版为**新增**方法。
@@ -232,17 +232,36 @@ from pytdxdata import (
| `boll(values, period=20, mult=2.0)` | 布林带 |
| `compute_indicators(high, low, close, indicators, params=None, tail=None)` | 统一入口(被 `get_stock_kline_with_indicators` 调用) |
**`pytdxdata.config`**(服务器清单)
**`pytdxdata.config`**(服务器清单与选路)
| 函数 | 说明 |
主机来源优先级链(各协议独立):`PYPYTDX_DATA_*_HOSTS` 环境变量 → **当日测速缓存** →
包内清单 `fast_pool` → 包内清单 → 代码内置常量。
| 函数 / 常量 | 说明 |
|------|------|
| `get_standard_hosts()` | 标准通道服务器列表 |
| `get_standard_hosts()` | 标准通道服务器列表(按上述优先级链解析) |
| `get_mac_hosts()` | MAC 通道服务器列表 |
| `get_ex_hosts()` | EX 扩展市场服务器列表 |
| `get_ex_handshakes()` | EX 握手方式映射 |
| `all_probe_candidates()` | 全量候选主机 `{standard, mac, ex}`(清单 ∪ 常量 ∪ env,**不按状态过滤**) |
| `is_valid_host(host)` | 主机名合法性校验(挡 mock 脏数据 / 非法条目) |
| `probe_cache_dir()` / `probe_cache_file()` | 用户级当日测速缓存目录 / 文件路径 |
| `load_probe_cache(today=None, path=None)` | 读当日测速缓存;缺失 / 损坏 / 非今日 / 版本不符 → `None` |
| `probe_disabled()` | 是否已用 `PYPYTDX_DATA_DISABLE_PROBE` 关闭测速 |
| `PROBE_CACHE_VERSION` | 测速缓存 payload 版本号 |
**`pytdxdata.server_probe`**(服务器探测,可 `python -m pytdxdata.server_probe` 运行)
`load_servers()` / `save_servers(cfg)` / `SERVERS_FILE`
**`pytdxdata.pool.probe_cache`**(当日测速:后台执行、对用户无感)
| 符号 | 说明 |
|------|------|
| `ProbeCache` | 进程内协调器;`ensure_probe()` 为幂等入口(单飞 + 原子写) |
| `schedule_probe(hosts=None)` | 连接池用:挂后台 task 并返回该 task;无事件循环时返回 `None` |
| `get_probe_cache()` | 取进程级单例 |
**`pytdxdata.server_probe`**(离线服务器探测,`python -m pytdxdata.server_probe`)
`load_servers()` / `save_servers(cfg)` / `SERVERS_FILE` / `probe_one(server, timeout, discover)`
CLI 开关:`--discover`(三种协议全测并据实修正 `protocols`,同时剔除脏记录)/
`--group standard|mac|ex` / `--refresh`(只重测 `status=ok` 的)/ `--timeout`
## 五、CLI(`tdx` 命令,来自 `python -m pytdxdata.cli`)
@@ -264,7 +283,7 @@ from pytdxdata import (
| `tdx block [filename] [--limit 30] [--codes]` | 板块文件 下载+解析(block_*.dat → 成分股) |
| `tdx industry [codes...] [--limit 30] [--search 词]` | 行业分类 下载+解析(tdxhy.cfg) |
| `tdx financial-list [--limit 30]` | 历史专业财报文件索引(gpcw.txt) |
| `tdx financial <filename> [--code X] [--limit 5] [--fields 4]` | 历史专业财报记录 下载+解析(gpcw*.zip) |
| `tdx financial <filename> [--code X] [--limit 5] [--fields 4]` | 历史专业财报记录 下载+解析(文件名自动纠正,见 `get_financial_records_parsed`) |
| `tdx server-info` | 服务器交易时段 |
| `tdx market-stat` | 市场统计 |
+2 -2
View File
@@ -18,8 +18,8 @@ from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market
| `Market.BJ` | `2` | 北京(北交所) |
!!! warning "代码不唯一"
**市场 + 代码**才唯一。`(SH, "000001")` 是上证指数,`(SZ, "000001")` 是平安银行。
所有接口的第一个参数都是 `market`,就是为了消歧。
**市场 + 代码**才唯一。`sh000001` 是上证指数,`sz000001` 是平安银行。
统一接口用**字符串标的**把两者一起表达(前缀即市场),避免只写 6 位数字时的歧义。
## KlinePeriod — K 线周期
+1 -1
View File
@@ -97,7 +97,7 @@ tdx industry --limit 30 # 只看前 30 条
# 历史专业财报
tdx financial-list # 索引:文件名 / MD5 / 大小(gpcw.txt)
tdx financial gpcw20260331.zip --limit 5 # 下载 + 解压 + 解析
tdx financial gpcw20260331.zip --limit 5 # 下载 + 解析(服务器实际给 .dat 时自动回退)
tdx financial gpcw20260331.zip --code 600000 --fields 8 # 只取指定股票、打印更多字段
```
+15 -2
View File
@@ -11,7 +11,7 @@ from pytdxdata.models import Adjust, KlinePeriod
## 全市场日线批量落库
连接池会把不同股票分配到不同服务器,这是 `*_batch` 存在的意义。
传多标的时,连接池会把不同股票分配到不同服务器——这正是它比逐个 `await` 快的原因。
```python
async def dump_all_daily():
@@ -118,7 +118,20 @@ async def finance_snapshot(symbols):
print(fin.symbol, fin)
```
历史专业财报(`gpcw*.zip`,含多报告期)走文件接口:
历史专业财报(`gpcw*`,含多报告期)走文件接口。
!!! warning "索引里的文件名与服务器实际不一致"
`tdxfin/gpcw.txt` 索引里写的是 `gpcwYYYYMMDD.zip`,但服务器实际只提供**未压缩的**
`tdxfin/gpcwYYYYMMDD.dat` —— 这些差异已由 `get_financial_records_parsed()` 内部处理,
直接把索引里的 `filename` 传进去即可。
另外索引里**含有尚未生成的占位条目**(`filesize` 只有百来字节),取它们会得到空列表。
想拿最新一期可用数据,先按体积过滤:
```python
usable = [fi for fi in infos if fi.filesize > 500_000] # 排除占位条目
records = await td.get_financial_records_parsed(usable[0].filename)
```
```python
async def history_financials(code: str):
+33 -9
View File
@@ -19,7 +19,8 @@
| SH | `000001` | 上证指数 |
| SZ | `000001` | 平安银行 |
代码不唯一,**市场 + 代码**才唯一。这也是为什么所有接口的第一个参数都是 `market`。
代码不唯一,**市场 + 代码**才唯一。统一接口用**字符串标的**把两者一起表达
(`sh000001` / `sz000001`),避免只写 6 位数字时的歧义。
??? question "为什么报价格式有时候是 2 位小数,有时候是 3 位?"
价格小数位按**品种**推断:股票 2 位,指数 / ETF / 可转债 3 位。
@@ -28,17 +29,40 @@
## 连接与网络
??? question "连不上服务器 / 全部超时怎么办?"
服务器可用性会随时间变化(下线、换 IP、封禁)。按顺序排查:
服务器可用性会随时间变化(下线、换 IP、封禁)。本包**当日首次启动会自动后台测速**并把
可达主机按延迟排序缓存,多数情况下无需手工干预。按顺序排查:
1. 重新探测:`python -m pytdxdata.server_probe`
2. 手工指定清单绕过探测结果:
```python
async with TdxData(standard_servers=[("1.2.3.4", 7709)]) as td: ...
1. **删掉当日测速缓存**,让下次启动重新测速——缓存里可能存着今天刚挂掉的节点
(路径见 [安装与配置](getting-started.md#当日自动测速无感))。
2. 手工指定主机。优先级最高,**直接跳过测速与缓存**:
```bash
PYPYTDX_DATA_STANDARD_HOSTS=1.2.3.4,5.6.7.8 python your_script.py
```
3. 检查出口网络策略——标准 / MAC 端口 **7709**、EX 端口 **7727** 需要放通。
4. 若在用代理软件,注意有些本地代理会劫持回环 TCP,导致 asyncio 建事件循环都卡住
或在代码里传入(**只填主机名**,端口由 `port=` 统一指定):
```python
async with TdxData(standard_servers=["1.2.3.4"]) as td: ...
```
3. 离线重生成随包清单(该脚本会真实拉一段 K 线,剔除「握手正常但返回空」的坏节点):
```bash
python -m pytdxdata.server_probe
```
4. 检查出口网络策略——标准 / MAC 端口 **7709**、EX 端口 **7727** 需要放通。
5. 若在用代理软件,注意有些本地代理会劫持回环 TCP,导致 asyncio 建事件循环都卡住
(见下方「在 Windows 上测试卡死」)。
??? question "启动时会变慢吗?会不会在后台偷偷联网?"
会有一次**当日首次启动测速**,但完全在后台,对调用方无感:
- **不阻塞** `start()`、**不打印**任何东西、失败**静默降级**(绝不抛给调用方)
- 结果只缓存到用户级目录(**不写安装目录**),**当天后续启动直接复用、不再重测**
- 覆盖**全部候选**主机(含暂时被挤下去的),所以「上次慢、这次快」的节点能回来
三个开关:`PYPYTDX_DATA_DISABLE_PROBE=1` 关掉测速、
`PYPYTDX_DATA_CACHE_DIR` 改缓存位置、
`PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS` 强制指定主机。
详见 [安装与配置 → 当日自动测速](getting-started.md#当日自动测速无感)。
??? question "公司网络 / 代理环境下失败"
通达信协议是裸 TCP,不走 HTTP 代理。如果环境强制走代理,需要把 `7709` / `7727`
配成直连(bypass)。云服务器上常见问题是安全组只放通了 80/443。
@@ -49,7 +73,7 @@
| 场景 | 建议 |
|---|---|
| 偶发查询、CLI | 默认即可 |
| 批量落库(`*_batch`) | `pool_max=16`、`concurrency=8~16` |
| 批量落库(`get_bars` 传多标的) | `pool_max=16`、`concurrency=8~16` |
| Web 服务多并发 | `pool_max=24`,并确保单实例复用 |
再大只是排队,不会更快——瓶颈是对端服务器的连接上限。
+45 -2
View File
@@ -96,12 +96,16 @@ asyncio.run(main())
```python
async with TdxData(
standard_servers=[("1.2.3.4", 7709), ("5.6.7.8", 7709)],
mac_servers=[("9.10.11.12", 7709)],
standard_servers=["1.2.3.4", "5.6.7.8"],
mac_servers=["9.10.11.12"],
port=7709,
) as td:
...
```
主机元素**只填主机名**,端口由构造参数 `port=` 统一指定(不写在主机元素里)。
等价的免代码写法是环境变量 `PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS`(逗号分隔)。
## 服务器清单
内置清单随包发布(`src/pytdxdata/servers.json`),由探测脚本生成:
@@ -121,6 +125,45 @@ from pytdxdata.config import get_standard_hosts, get_mac_hosts, get_ex_hosts
print(len(get_standard_hosts()), len(get_mac_hosts()), len(get_ex_hosts()))
```
### 当日自动测速(无感)
除随包发布的静态清单外,`TdxData` 还在**当日首次启动**时做一次**后台全量测速**:
- 覆盖**全部候选**(包内清单 ∪ 代码内置常量 ∪ 环境变量覆盖),而不是只测当前池里的少数节点
——否则「上次慢、这次快」的节点永远捞不回来
- 用**真实 K 线命令**判定可达(标准 / MAC / EX 各发一条业务命令并要求非空),
能剔除「握手正常但返回空数据」的坏节点
- 结果按**实测延迟升序**写入**用户级缓存**,当天后续启动直接复用、**不再重测**
- 全程在后台进行:**不打印、不阻塞 `start()`、失败静默降级**,对调用方完全无感
缓存位置(可用 `PYPYTDX_DATA_CACHE_DIR` 覆盖):
| 平台 | 路径 |
|---|---|
| Windows | `%LOCALAPPDATA%\pytdxdata\hosts-today.json` |
| macOS | `~/Library/Caches/pytdxdata/hosts-today.json` |
| Linux / 其他 | `$XDG_CACHE_HOME/pytdxdata/hosts-today.json`(默认 `~/.cache/…`) |
主机选择的优先级(各协议独立):
1. `PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS` / `…_EX_HOSTS` 环境变量(手工指定,最高优先)
2. **当日测速缓存**中该协议实测可达的主机(按延迟升序)
3. 包内清单里 `status=ok` 的 `fast_pool` 主机
4. 包内清单里 `status=ok` 的主机
5. 代码内置常量
!!! note "缓存绝不写回安装目录"
测速结果只写入上面的**用户级缓存目录**。`site-packages` 在容器 / 系统级安装 / `pipx`
下可能只读,多用户共用一个安装时还会互相覆盖,因此包内 `servers.json` 不会被运行时改写。
环境变量一览:
| 变量 | 作用 |
|---|---|
| `PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS` / `…_EX_HOSTS` | 逗号分隔,手工指定主机(优先级最高,直接跳过测速缓存) |
| `PYPYTDX_DATA_CACHE_DIR` | 覆盖当日测速缓存目录 |
| `PYPYTDX_DATA_DISABLE_PROBE=1` | 关闭当日测速与缓存(CI / 测试用,保证确定性) |
## 生命周期
`TdxData` 必须在 `async with` 内使用,或手动 `await td.start()` / `await td.close()`:
+3 -2
View File
@@ -34,7 +34,7 @@ asyncio.run(main())
| 🗄️ **双层 TTL 缓存** | 内存 LRU + 磁盘 SQLite(WAL);TTL 分级:报价 5s / 分钟K线 60s / 日线当天 / 复权K线 1天 / 历史逐笔永久;`single-flight` 同键并发去重;缓存「已解析记录」,重复请求 0 网络 0 解析 |
| ⚡ **并发分页** | 把大请求拆成显式 `start` 偏移的页,多连接并行拉取、按序拼接、失败换连接重试 |
| 🔀 **双通道整合** | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1分钟K线),按命令自动选路 |
| 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*.zip` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制 |
| 📄 **服务器文件解析** | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 历史财报 `gpcw*` **下载即解析**成 dataclass(纯 stdlib),无需自己拆二进制;文件名与索引不一致时自动纠正 |
| 🚀 **批量下载** | `get_bars` / `get_minutes` 传标的列表即多股票并发,连接池自动分配到不同服务器 |
| 📦 **零重型依赖** | 返回 `list[dataclass]`,pandas / polars 由调用方按需转换 |
@@ -104,7 +104,8 @@ asyncio.run(main())
## 数据来源与限制
- 行情来自通达信**公开**行情服务器(无需账号),**15 分钟延时**;需实时数据请使用券商行情
- 服务器清单由 `python -m pytdxdata.server_probe` 探测生成,可用性随时间变化
- 服务器清单由 `python -m pytdxdata.server_probe` 探测生成;运行时**当日首次启动会自动在后台测速并缓存**
(对调用方无感,当天不再重测),可用性随时间变化
- 港股 / 美股 / 期货 / 期权走通达信 EX 通道(端口 7727),部分市场(美股期权、港股期权)协议内无数据
完整清单见 [常见问题](faq.md)。
+2 -2
View File
@@ -23,7 +23,7 @@ src/pytdxdata/
├── api.py # 统一接口 TdxData(对外唯一入口)
├── symbols.py # 标的解析:字符串 → Symbol(parse_symbol / format_symbol / market_targets)
├── router.py # 标准 / MAC / EX 通道选路
├── config.py # 服务器清单加载(servers.json)
├── config.py # 服务器清单加载 + 选路优先级链 + 用户级测速缓存路径
├── indicator.py # 技术指标(纯函数,无依赖)
├── server_probe.py # 服务器探测,可 python -m 运行
├── protocol/ # 协议层
@@ -39,7 +39,7 @@ src/pytdxdata/
│ ├── pool.py # 标准 / MAC 动态池
│ ├── ex_pool.py # EX 池
│ ├── health.py # 健康分与选路
│ └── probe_cache.py # 探测结果缓存
│ └── probe_cache.py # 当日全量测速 + 用户级缓存(后台、无感)
├── scheduler/
│ └── paginator.py # 并发分页调度(3 连接并行)
├── cache/
+5 -4
View File
@@ -81,11 +81,11 @@ results = await asyncio.gather(*[
EWMA(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。
### 为什么 MAC 池更小
### MAC 通道的单台连接上限
MAC 通道可用服务器只有数台(见 [通道与数据源](routing.md#server-groups)),
所以 `mac_pool_cap` 默认只有 `4`——这是**对端限制**,不是本项目的选择。
逐笔 / 分时的并发能力天然弱于日线,原因就在这里。
`mac_pool_cap` 默认 `4`,与标准池的 `std_pool_cap` 一致——这是**对端单台连接限制**,
不是本项目的选择。两个通道的可用台数见 [通道与数据源](routing.md#server-groups):
实测可达台数会随服务器上下线变化,以**当日测速缓存**为准。
## 并发分页
@@ -110,4 +110,5 @@ count=2400 → 3 页 → 3 个连接并行 → 按序拼接
## 下一步
- [架构总览](architecture.md) — 这些模块在整体里的位置
- [通道与数据源](routing.md#daily-probe) — 服务器是怎么选出来的(当日测速缓存)
- [常见问题](../faq.md) — 缓存与超时的排查
+51 -4
View File
@@ -29,10 +29,13 @@
| 池 | 数量级 | 用途 |
|---|---|---|
| **标准池** | 数十台 | 报价 / K线 / 列表 / 财务 |
| **MAC 池** | 数台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 |
| **标准池** | 9 台 | 报价 / K线 / 列表 / 财务 |
| **MAC 池** | 22 台 | 逐笔 / 分时 / 复权 / 板块 / 资金流 |
| **EX 池** | 4 台 | 港股 / 美股 / 期货 / 期权 |
> 上表为 2026-09-21 离线探针(`python -m pytdxdata.server_probe --discover`)实测**可达**台数。
> 服务器会下线、换 IP 或变更协议,**实际台数以当日测速缓存为准**(见下方「运行时:当日测速缓存」)。
EX 池内部还要再分两类,因为握手方式不同:
| 类型 | 数量 | 握手 |
@@ -42,7 +45,7 @@ EX 池内部还要再分两类,因为握手方式不同:
这就是 `config.get_ex_handshakes()` 存在的原因——EX 的 4 台机器不是同一种握手。
MAC 池远小于标准池,这也解释了为什么逐笔 / 分时的并发能力天然弱于日线。
注意 MAC 池实测**并不比标准池小**(22 台 vs 9 台)。早期版本曾按「MAC 可用节点很少」来解释逐笔 / 分时并发弱于日线,实测已推翻该前提——两者的单台连接上限(`mac_pool_cap` / `std_pool_cap`)默认相同,都是 `4`。
## 为什么这些服务器会被「探测」
@@ -51,12 +54,56 @@ MAC 池远小于标准池,这也解释了为什么逐笔 / 分时的并发能
`server_probe` 的探测逻辑**不是只看 TCP 连通性**,而是真实请求一段 K 线并校验内容:
```bash
python -m pytdxdata.server_probe
python -m pytdxdata.server_probe # 按申报协议全量探测
python -m pytdxdata.server_probe --discover # 三种协议全测,并据实修正 protocols
python -m pytdxdata.server_probe --group ex # 只测 EX
python -m pytdxdata.server_probe --refresh # 只重测当前 status=ok 的
```
普通「只 ping 握手」的探测会把这类坏节点放进来,症状是**偶发的空返回**——
比直接连不上更难查。所以探测必须校验数据。
写回字段:`status` / `latency` / `checked_at` / `checked_date` / `fast_pool`,
以及顶层 `version` / `checked_date` / `note`。其中 `fast_pool` 与运行时缓存里的 `fast`
用同一条规则(整体延迟前 10 名,或延迟 < 200ms),用于**还没有当日缓存时**的冷启动排序。
### 为什么需要 `--discover`
「申报协议」会过期。实测(2026-09-21)有一批服务器的 **`0x010C` 标准 K 线变成空响应
(返回 2 字节空壳),但同端口同主机的 `0x122E` MAC 帧正常**——它们从 `standard` 退化成了
`mac`-only。只测申报协议的话,这类退化永远发现不了,标准池会一直含着一批死节点。
`--discover` 对每台主机把三种协议都测一遍,并据实测结果重写 `protocols`;
配套两个必须处理的细节:
- **失败必须重试一次**再判定不支持。单次抖动会误删协议,而 `protocols` 被收窄后不会自动恢复。
- **EX 握手模式**申报可能错,探测失败时换另一种(`login` ⇄ `setup`)再试。
- 无任何协议可达时**不动 `protocols`**,只把 `status` 置 `fail`——保留"它申报过什么"的信息。
- 顺带剔除 `ip` 非法的脏记录(历史遗留如 `"s1"`)。
## 运行时:当日测速缓存 {#daily-probe}
`python -m pytdxdata.server_probe` 是**离线**重生成随包清单的工具;运行时还有一条**在线**的
轻量路径——`TdxData.start()` 会异步触发一次全量测速,把结果缓存到**用户级目录**
(`…/pytdxdata/hosts-today.json`),当天后续启动直接复用,不再重测。
设计与几个必须踩对的点:
| 关注点 | 正确做法 | 反例(会静默出错) |
|---|---|---|
| 候选集 | 取**全部候选**(清单 ∪ 常量 ∪ env) | 只把「当前池成员」丢给探针 → 上次慢的节点永远捞不回来 |
| 可达判定 | 发**真实 K 线命令**并要求非空 | 只握手 / 只读报文头 → 测不出「空响应」坏节点 |
| 写盘位置 | 用户级缓存目录 | 写回包内 `servers.json` → 容器只读、多用户互相覆盖 |
| 对调用方 | 后台 task + debug 日志 + 绝不抛异常 | 在 `start()` 里 `await` 或打印 → 启动变慢、污染用户输出 |
| 并发 | 进程内单例 + `asyncio.Lock` | 三个池各测一遍 → 三倍流量 |
| 写入 | 临时文件 + `os.replace` 原子替换 | 直接覆写 → 并发进程读到半截 JSON |
全部不可达时**不写缓存**——否则「今天全挂了」会被缓存一整天,明天也不重试。
缓存存在时,`config.get_standard_hosts()` 等按**实测延迟升序**返回该协议的可达主机;
缓存缺失 / 跨日 / 版本不符 / 已损坏时,才回落到包内清单。开关见
[安装与配置 → 环境变量](../getting-started.md#当日自动测速无感)。
## EX 通道细节
- 端口固定 **7727**,与标准 / MAC 的 7709 不同
+13
View File
@@ -59,6 +59,19 @@ asyncio.run(main())
> 旧的分通道/市场方法(`get_kline` / `get_transactions` / `get_goods_*` 等共 33 个)保留为
> deprecated 别名,1.0 移除;完整对照见[接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/)与 CHANGELOG。
## 服务器与配置
服务器主机来源有一条优先级链(各协议独立):环境变量 → **当日测速缓存** → 包内清单
`fast_pool` → 包内清单 → 代码内置常量。
- `TdxData.start()` 会在**当日首次启动**后台触发一次全量测速,用**真实 K 线命令**判定可达
(不是只握手),结果按延迟升序写入**用户级缓存**(Windows `%LOCALAPPDATA%\pytdxdata`、
macOS `~/Library/Caches/pytdxdata`、Linux `$XDG_CACHE_HOME/pytdxdata`),当天复用、不再重测。
- 该操作对调用方**完全无感**:后台执行、不打印、不阻塞 `start()`、失败静默降级。
运行时**绝不改写包内 `servers.json`**。
- 环境变量:`PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS` / `…_EX_HOSTS`(逗号分隔,手工指定,最高优先)、
`PYPYTDX_DATA_CACHE_DIR`(覆盖缓存目录)、`PYPYTDX_DATA_DISABLE_PROBE=1`(关闭测速)。
## CLI
安装后提供 `tdx` 命令,19 个子命令,不写代码即可取数:
+1 -1
View File
@@ -142,7 +142,7 @@
## 七、验证
- `pytest`:**127 passed**。其中 `tests/test_all_interfaces.py` 为全接口回归:mock 连接逐个
- `pytest`:**127 passed**(审查当时的快照;当前基线为 164 passed)。其中 `tests/test_all_interfaces.py` 为全接口回归:mock 连接逐个
调用 63 个公开方法,并以「覆盖哨兵」断言无遗漏(7 条告警为别名测试的预期 `DeprecationWarning`)。
- `scripts/check_docs.py`:`MUST_LIST_ALL` + `MUST_NOT_BE_STALE` 全部 `[OK]`。
- 签名核对:统一接口签名与返回类型与本文一致;全仓无 `_as_symbols` 及元组式调用残留。
+1 -1
View File
@@ -1,6 +1,6 @@
[project]
name = "pytdxdata"
version = "0.6.0"
version = "0.6.1"
description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权"
readme = "README.md"
requires-python = ">=3.11"
+1 -1
View File
@@ -16,7 +16,7 @@ from .models import (
XdxrRecord,
)
__version__ = "0.6.0"
__version__ = "0.6.1"
__all__ = [
"TdxData",
"Market",
+68 -20
View File
@@ -22,6 +22,7 @@ from __future__ import annotations
import asyncio
import logging
import re
import warnings
from datetime import date as _date, datetime
from pathlib import Path
@@ -61,7 +62,7 @@ from .models import (
)
from .pool.ex_pool import ExPool
from .pool.health import HealthEngine
from .pool.pool import DynamicPool
from .pool.pool import DynamicPool, PoolTimeoutError
from .protocol.commands import (
GetFinanceInfoCmd,
GetIndexBarsCmd,
@@ -75,6 +76,7 @@ from .protocol.commands import (
MacKlineCmd,
MacTransactionCmd,
MAX_QUOTES,
TdxDecodeError,
)
from .protocol.commands.ex_ext import (
GetExHistoryTransactionDataCmd,
@@ -895,8 +897,9 @@ class TdxData:
参数:
date: ``None``=今天;``YYYYMMDD``=历史某日(A股支持历史分时)。
sampling: ``True`` 取缩略采样(约240个价格点,无时间;A股 0x254D,
扩展市场同命令),``vol``/``avg_price`` 为 0,点位序号在 ``fields["i"]``。
sampling: ``True`` 取缩略采样(约 240 个价格点,无时间),``vol``/
``avg_price`` 为 0,点位序号在 ``fields["i"]``。A股由分时数据派生,
扩展市场走 0x254D。
返回:
``list[MinuteBar]``,按入参标的顺序拼接,每条带 ``symbol``/``market``/
@@ -920,8 +923,17 @@ class TdxData:
async def fetch() -> bytes:
if sampling:
run = self._execute_ex if sym.is_ex else self._execute_mac
prices = await run(MacChartSamplingCmd(sym.market, sym.code))
if sym.is_ex:
prices = await self._execute_ex(
MacChartSamplingCmd(sym.market, sym.code))
else:
# ⚠️ 不能用 MacChartSamplingCmd(0x254D):那是 **EX 协议**命令,
# A股/标准通道的 7709 主机对它一律不响应(实测 3 台全 8s 超时,
# 叠加连接池 3 次重试 ≈24s 才报错)。改由分时(0x122D)派生价格点:
# 分时本身就是 240 点,语义与「缩略采样」一致且天然可用。
ticks = await self._execute_mac(
MacTickChartCmd(sym.market, sym.code, ymd))
prices = [b.price for b in ticks]
bars = [MinuteBar(price=float(p), vol=0.0, symbol=sym.text,
market=sym.market, code=sym.code, date=ymd,
fields={"i": float(i)})
@@ -1273,28 +1285,60 @@ class TdxData:
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]``。
"""财报数据解析 -> ``list[FinancialRecord]``。
可直接把 :meth:`get_financial_file_infos` 条目里的 ``filename`` 原样传进来:
内部会自动纠正「索引名与服务器实际文件名不一致」的问题(索引写
``gpcwYYYYMMDD.zip`` 且不带 ``tdxfin/`` 前缀,服务器实际只提供未压缩的
``tdxfin/gpcwYYYYMMDD.dat``),并兼容 zip 包与未压缩 dat 两种形态。
报告期优先取文件名中的 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:
dat_data = await self._fetch_financial_dat(filename)
if not dat_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)
match = re.search(r"(\d{8})", str(filename))
report_date = int(match.group(1)) if match else 0
return parse_financial_dat(dat_data, report_date)
async def _fetch_financial_dat(self, filename: str) -> bytes:
"""[内部] 取回 gpcw 财报 ``.dat`` 原始字节,自动纠正服务器文件名差异。
``tdxfin/gpcw.txt`` 索引声明的名字(``gpcwYYYYMMDD.zip``、无目录前缀)与服务器
实际提供的文件(``tdxfin/gpcwYYYYMMDD.dat``、未压缩)不一致,且对不存在的名字
服务器**不报错、只回 0~1 字节空壳**。这里按候选名逐个尝试,并校验取回的字节
是否真的是 ``.dat``,返回第一个有效结果;全部失败返回 ``b""``。
候选顺序:索引声明的 ``.zip`` → 服务器实际的 ``.dat`` → 调用方原样名字(兜底)。
"""
from .codec.financial import extract_gpcw_dat
raw = str(filename).strip().replace("\\", "/")
base = raw.rsplit("/", 1)[-1]
stem = re.sub(r"\.(?:zip|dat)$", "", base, flags=re.IGNORECASE)
candidates = list(dict.fromkeys([
f"tdxfin/{stem}.zip",
f"tdxfin/{stem}.dat",
base,
]))
for name in candidates:
try:
blob = await self.get_file(name)
except (ConnectionError, OSError, TimeoutError,
TdxDecodeError, ValueError, PoolTimeoutError) as exc:
# 单个候选取回失败就换下一个(服务器对不存在的名字不一定报错)
log.debug("财报候选 %s 取回失败: %s", name, str(exc)[:80])
continue
dat = extract_gpcw_dat(blob)
if dat:
log.debug("财报文件命中: %s(%d 字节)", name, len(dat))
return dat
log.debug("财报候选 %s 非有效 gpcw 数据(%d 字节),继续尝试",
name, len(blob))
return b""
# ================================================================== #
# 内部执行(连接池 + 失败换连接 + 分页)
# ================================================================== #
@@ -1553,9 +1597,13 @@ class TdxData:
return [l.strip() for l in text.splitlines() if l.strip()]
async def get_financial_records(self, filename: str) -> bytes:
"""已废弃 -> :meth:`get_financial_records_parsed`。"""
"""已废弃 -> :meth:`get_financial_records_parsed`。
返回 gpcw 财报 ``.dat`` 原始字节(服务器给未压缩 ``.dat`` 时自动回退,
不再像旧实现那样静默返回 0~1 字节空壳);取不到时返回 ``b""``。
"""
_deprecated("get_financial_records", "get_financial_records_parsed")
return await self.get_file(filename)
return await self._fetch_financial_dat(filename)
async def get_company_info_category(self, market, code) -> list:
"""已废弃 -> :meth:`get_f10`。"""
+59 -3
View File
@@ -17,13 +17,19 @@
"""
from __future__ import annotations
import io
import struct
import zipfile
from ..models import FinancialFileInfo, FinancialRecord
_HEADER_FMT = "<1hI1H3L"
_INDEX_FMT = "<6sBL"
_HEADER_SIZE = struct.calcsize(_HEADER_FMT)
_INDEX_SIZE = struct.calcsize(_INDEX_FMT)
_ZIP_MAGIC = b"PK\x03\x04"
def parse_financial_file_list(data: bytes) -> list[FinancialFileInfo]:
"""解析 tdxfin/gpcw.txt 内容(每行 ``filename,md5hash,filesize``)。"""
@@ -46,8 +52,58 @@ def parse_financial_file_list(data: bytes) -> list[FinancialFileInfo]:
return out
def looks_like_gpcw_dat(data: bytes) -> bool:
"""粗略判定字节流是否为 gpcw ``.dat``(校验 20 字节 header 的自洽性)。
用于把「真的取到了财报数据」与「服务器对不存在的文件名回的 0/1 字节空壳」区分开:
空壳要么长度不足、要么 header 全零,一律判否。
Args:
data: 待判定的字节流。
Returns:
可疑时返回 True。
"""
if len(data) < _HEADER_SIZE:
return False
_unknown, _date, max_count, _u1, report_size, _u2 = struct.unpack(
_HEADER_FMT, data[:_HEADER_SIZE]
)
if max_count <= 0 or report_size <= 0 or report_size % 4 != 0:
return False
# 索引区必须放得下 max_count 条 11 字节条目
return _HEADER_SIZE + max_count * _INDEX_SIZE <= len(data)
def extract_gpcw_dat(data: bytes) -> bytes:
"""从「zip 包」或「未压缩 dat」中取出 ``.dat`` 字节;无法识别时返回 ``b""``。
服务器**实际只提供未压缩的** ``tdxfin/gpcwYYYYMMDD.dat``,而 ``tdxfin/gpcw.txt``
索引里写的是 ``gpcwYYYYMMDD.zip``,因此两种形态都要能走通。
Args:
data: zip 包字节或未压缩 ``.dat`` 字节。
Returns:
内层 / 原始的 ``.dat`` 字节;不是有效财报数据时返回 ``b""``。
"""
if not data:
return b""
if data.startswith(_ZIP_MAGIC):
try:
with zipfile.ZipFile(io.BytesIO(data)) as zf:
names = [n for n in zf.namelist() if n.lower().endswith(".dat")]
if not names:
return b""
inner = zf.read(names[0])
except (zipfile.BadZipFile, OSError, KeyError):
return b""
return inner if looks_like_gpcw_dat(inner) else b""
return data if looks_like_gpcw_dat(data) else b""
def parse_financial_dat(data: bytes, report_date: int = 0) -> list[FinancialRecord]:
"""解析 gpcw*.zip 内的 .dat 二进制。
"""解析 gpcw ``.dat`` 二进制(zip 内的或服务器直接给的未压缩形式都行)。
Args:
data: .dat 文件完整字节。
@@ -56,7 +112,7 @@ def parse_financial_dat(data: bytes, report_date: int = 0) -> list[FinancialReco
Returns:
FinancialRecord 列表;数据不足或字段非法时返回空列表。
"""
header_size = struct.calcsize(_HEADER_FMT)
header_size = _HEADER_SIZE
if len(data) < header_size:
return []
@@ -72,7 +128,7 @@ def parse_financial_dat(data: bytes, report_date: int = 0) -> list[FinancialReco
if num_fields <= 0:
return []
index_size = struct.calcsize(_INDEX_FMT)
index_size = _INDEX_SIZE
report_fmt = f"<{num_fields}f"
report_pack_size = struct.calcsize(report_fmt)
+178 -13
View File
@@ -1,12 +1,28 @@
"""服务器清单与默认配置
服务器清单存于包内 servers.json,由 server_probe.py 导入时自动探测可用性与延时。
config.py 加载时只采用 status="ok" 的服务器;环境变量可覆盖;代码内嵌清单为兜底。
服务器清单存于包内 ``servers.json`` —— 它是**随包分发的基线清单,运行期只读**。
每日首次启动的后台测速结果写入**用户级缓存目录**,运行期优先采用当日实测结果。
主机选取优先级(每个协议独立)::
环境变量 PYPYTDX_DATA_*_HOSTS > 当日测速缓存 > 包内清单 fast_pool
> 包内清单 ok > 代码内嵌常量
相关环境变量:
- ``PYPYTDX_DATA_CACHE_DIR`` 覆盖用户级缓存目录(默认见 :func:`probe_cache_dir`)
- ``PYPYTDX_DATA_DISABLE_PROBE`` 置真值时既不读当日缓存也不测速(CI / 测试用,保证确定性)
为什么不把测速结果写回包内 ``servers.json``:安装目录可能是只读的(容器 / 系统级
site-packages / pipx),且多用户共用一份安装时彼此覆盖,运行期改写分发数据本身也不妥。
"""
from __future__ import annotations
import ipaddress
import json
import os
import sys
from datetime import date
from pathlib import Path
DEFAULT_PORT = 7709
@@ -14,19 +30,29 @@ DEFAULT_TIMEOUT = 10.0
_SERVERS_FILE = Path(__file__).resolve().parent / "servers.json" # 包内清单(随包分发)
# 当日测速缓存(结构变更时递增,旧版本缓存自动失效)
PROBE_CACHE_VERSION = 1
_PROBE_CACHE_NAME = "hosts-today.json"
# ---------- 包内清单(只读基线) ----------
def _read_servers_json() -> dict:
"""读取包内清单;文件缺失 / 内容损坏 / 顶层非对象 → 空 dict。"""
try:
cfg = json.loads(_SERVERS_FILE.read_text(encoding="utf-8"))
except (OSError, ValueError):
return {}
return cfg if isinstance(cfg, dict) else {}
def _load_ok_hosts(protocol: str, *, fast_only: bool = False) -> list[str]:
"""从 servers.json 加载 status=ok 且支持指定协议的服务器。
fast_only=True 时只返回当日测速入池(fast_pool)的服务器(排名前N或延迟<阈值),
fast_only=True 时只返回测速入池(fast_pool)的服务器(排名前N或延迟<阈值),
用于动态连接池优先使用优质节点。
"""
try:
cfg = json.loads(_SERVERS_FILE.read_text(encoding="utf-8"))
except (OSError, ValueError):
return []
out = []
for s in cfg.get("servers", []):
for s in _read_servers_json().get("servers", []):
if s.get("status") != "ok":
continue
if protocol not in s.get("protocols", []):
@@ -38,13 +64,90 @@ def _load_ok_hosts(protocol: str, *, fast_only: bool = False) -> list[str]:
def _load_ex_handshakes() -> dict[str, str]:
try:
cfg = json.loads(_SERVERS_FILE.read_text(encoding="utf-8"))
except (OSError, ValueError):
return {}
return {s["ip"]: s.get("handshake", "setup") for s in cfg.get("servers", [])
"""包内清单里 EX 服务器的握手模式。"""
return {s["ip"]: s.get("handshake", "setup")
for s in _read_servers_json().get("servers", [])
if "ex" in s.get("protocols", []) and s.get("status") == "ok"}
# ---------- 用户级当日测速缓存 ----------
def probe_cache_dir() -> Path:
"""用户级缓存目录(保证可写,绝不指向安装目录)。
``PYPYTDX_DATA_CACHE_DIR`` 可覆盖(测试指向临时目录)。按平台约定:
- Windows: ``%LOCALAPPDATA%\\pytdxdata``
- macOS: ``~/Library/Caches/pytdxdata``
- 其他: ``$XDG_CACHE_HOME/pytdxdata`` 或 ``~/.cache/pytdxdata``
"""
env = (os.environ.get("PYPYTDX_DATA_CACHE_DIR") or "").strip()
if env:
return Path(env).expanduser()
if os.name == "nt":
base = os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA")
return (Path(base) if base else Path.home() / "AppData" / "Local") / "pytdxdata"
if sys.platform == "darwin":
return Path.home() / "Library" / "Caches" / "pytdxdata"
base = os.environ.get("XDG_CACHE_HOME")
return (Path(base) if base else Path.home() / ".cache") / "pytdxdata"
def probe_cache_file() -> Path:
"""当日测速缓存文件路径(每次调用重新解析,便于测试改环境变量后立即生效)。"""
return probe_cache_dir() / _PROBE_CACHE_NAME
def probe_disabled() -> bool:
"""是否已通过 ``PYPYTDX_DATA_DISABLE_PROBE`` 关闭当日测速缓存。"""
return os.environ.get("PYPYTDX_DATA_DISABLE_PROBE", "").strip().lower() in {
"1", "true", "yes", "on",
}
def load_probe_cache(today: str | None = None,
path: str | Path | None = None) -> dict | None:
"""读取**当日**测速缓存;缺失 / 损坏 / 非今日 / 版本不符 → ``None``。
返回非 None 即表示"今天已经测过速了",调用方应直接复用而不再刷新。
``path`` 可显式指定缓存文件(默认 :func:`probe_cache_file`),便于注入与测试。
"""
if probe_disabled():
return None
target = Path(path) if path is not None else probe_cache_file()
try:
cfg = json.loads(target.read_text(encoding="utf-8"))
except (OSError, ValueError):
return None
if not isinstance(cfg, dict) or cfg.get("version") != PROBE_CACHE_VERSION:
return None
if str(cfg.get("date", "")) != (today or date.today().isoformat()):
return None
results = cfg.get("results")
if not isinstance(results, dict) or not results:
return None
return cfg
def _load_cached_hosts(protocol: str) -> list[str]:
"""当日测速缓存中该协议**实测可达**的主机,按延迟升序(越快越靠前)。"""
cfg = load_probe_cache()
if cfg is None:
return []
rows: list[tuple[float, str]] = []
for ip, per_proto in cfg["results"].items():
if not isinstance(per_proto, dict):
continue
lat = per_proto.get(protocol)
if isinstance(lat, bool) or not isinstance(lat, (int, float)):
continue
if lat < 0:
continue
rows.append((float(lat), str(ip)))
rows.sort(key=lambda kv: (kv[0], kv[1]))
return [ip for _, ip in rows]
# ---------- 代码内嵌兜底清单 ----------
# 标准行情服务器 —— 真实K线探测验证可用(2026-08-12, GetSecurityBarsCmd 600000 日K)
# 27台可用 = pytdxwrapper券商服务器(国泰君安/中信短线宝/华林/安信等) + 通达信官方主站
# 来源①: pytdxwrapper config.py TDX_HOSTS(券商+官方, 51台探测27可用)
@@ -91,10 +194,66 @@ EX_HANDSHAKES: dict[str, str] = {
}
# ---------- 测速候选枚举 ----------
def is_valid_host(host: object) -> bool:
"""是否是可用作服务器地址的合法主机(IPv4/IPv6 字面量,或含点的域名)。
用于挡住测试 mock 混进来的伪主机名(如 ``"s1"``)被写进缓存 / 清单。
"""
if not isinstance(host, str):
return False
h = host.strip()
if not h or len(h) > 253 or any(c.isspace() for c in h):
return False
try:
ipaddress.ip_address(h)
return True
except ValueError:
pass
return "." in h and all(
part and part[0] != "-" and part[-1] != "-" and part.replace("-", "").isalnum()
for part in h.split(".")
)
def all_probe_candidates() -> dict[str, list[str]]:
"""[测速用] 返回 ``{协议: [候选主机]}`` 全量清单(已校验、去重、保序)。
来源 = 包内清单申报的协议 ∪ 代码内嵌常量 ∪ 环境变量覆盖。
与 ``get_*_hosts()`` 的关键区别:这里**不做 status / 延迟过滤**。
测速必须能看到全部候选,否则"上次慢、这次快"的节点永远捞不回来,
形成自指循环(只重测已在池里的少数节点,其余记录一直过期)。
"""
out: dict[str, list[str]] = {"standard": [], "mac": [], "ex": []}
for s in _read_servers_json().get("servers", []):
ip = s.get("ip")
for protocol in s.get("protocols", []):
if protocol in out:
out[protocol].append(ip)
out["standard"] += STANDARD_HOSTS
out["mac"] += MAC_HOSTS
out["ex"] += EX_HOSTS
for protocol, var in (("standard", "PYPYTDX_DATA_STANDARD_HOSTS"),
("mac", "PYPYTDX_DATA_MAC_HOSTS"),
("ex", "PYPYTDX_DATA_EX_HOSTS")):
env = os.environ.get(var)
if env:
out[protocol] += env.split(",")
return {
protocol: [h for h in dict.fromkeys(hosts) if is_valid_host(h)]
for protocol, hosts in out.items()
}
# ---------- 对外取主机 ----------
def get_standard_hosts() -> list[str]:
env = os.environ.get("PYPYTDX_DATA_STANDARD_HOSTS")
if env:
return [h.strip() for h in env.split(",") if h.strip()]
cached = _load_cached_hosts("standard")
if cached:
return cached
fast = _load_ok_hosts("standard", fast_only=True)
if fast:
return fast
@@ -106,6 +265,9 @@ def get_mac_hosts() -> list[str]:
env = os.environ.get("PYPYTDX_DATA_MAC_HOSTS")
if env:
return [h.strip() for h in env.split(",") if h.strip()]
cached = _load_cached_hosts("mac")
if cached:
return cached
fast = _load_ok_hosts("mac", fast_only=True)
if fast:
return fast
@@ -117,6 +279,9 @@ def get_ex_hosts() -> list[str]:
env = os.environ.get("PYPYTDX_DATA_EX_HOSTS")
if env:
return [h.strip() for h in env.split(",") if h.strip()]
cached = _load_cached_hosts("ex")
if cached:
return cached
from_json = _load_ok_hosts("ex")
return from_json or list(EX_HOSTS)
+18 -9
View File
@@ -6,8 +6,9 @@
- 动态:支持运行时 add() 新服务器;支持后台全量测速入库(当日首次启动)。
- 单连接约束(核心需求):per_server_cap 默认 1 —— 一台服务器只允许建立 1 个连接,
不允许多开,避免对单一券商服务器造成并发压力被限流/封禁。
- 后台测速(核心需求):当日首次启动时,在后台对全量候选服务器测速,按
「排名前 FAST_POOL_TOP_N 或 延迟 < FAST_POOL_MAX_LATENCY」筛选入库,结果写回 servers.json。
- 后台测速(核心需求):当日首次启动时,在后台对**全量候选**服务器测速(覆盖标准/MAC/EX
三个协议,而不是只测当前池内节点),结果缓存到用户级缓存目录;当天已有缓存则跳过、不再刷新。
全程不阻塞 start()、不打印、不抛错(对用户无感)。详见 pool/probe_cache.py。
- 弹性:空闲连接超时后由 reaper 缩容回 min_size;支持 stats 统计。
"""
from __future__ import annotations
@@ -19,7 +20,7 @@ import time
from .connection import TdxConnection
from .health import HealthEngine
from .probe_cache import get_probe_cache
from .probe_cache import schedule_probe
log = logging.getLogger(__name__)
@@ -101,6 +102,7 @@ class DynamicPool:
self._lock = asyncio.Lock()
self._cond = asyncio.Condition(self._lock)
self._reaper_task: asyncio.Task | None = None
self._probe_task: asyncio.Task | None = None
# ---------- 生命周期 ----------
async def start(self) -> None:
@@ -108,13 +110,11 @@ class DynamicPool:
return
self._started = True
# 需求①:当日首次启动 → 后台全量测速入库(不阻塞主流程)
# 需求①:当日首次启动 → 后台全量测速(不阻塞主流程;当天已有缓存则自动跳过)
# 候选清单由 probe_cache 自行枚举全量主机(本池的 servers 只是其中一个子集,
# 不能直接当作测速输入,否则只会重测已在池内的少数节点、其余记录永久过期)。
if self.auto_probe:
hosts = list(self.servers)
asyncio.create_task(
get_probe_cache().ensure_probe(hosts),
name="pytdxdata-daily-probe",
)
self._probe_task = schedule_probe()
targets = self._pick_servers(self.min_size)
for host in targets:
@@ -175,6 +175,15 @@ class DynamicPool:
if self._reaper_task is not None:
self._reaper_task.cancel()
self._reaper_task = None
# 后台测速仍可能持有 socket;取消并等它退场,避免事件循环关闭时冒出
# "Task was destroyed but it is pending"(那会破坏"无感")
if self._probe_task is not None:
self._probe_task.cancel()
try:
await self._probe_task
except (asyncio.CancelledError, Exception):
pass
self._probe_task = None
async with self._lock:
for pc in list(self._conns):
try:
+272 -112
View File
@@ -1,162 +1,322 @@
"""当日首次启动的全量服务器测速与入库缓存。
"""当日首次启动的全量服务器测速与缓存(对用户完全无感)。
设计要点:
- 仅在"当日首次启动"时触发一次后台全量测速(按本地日期判断是否已探测)。
- 测速采用真实握手连通(TdxConnection.test),比单纯 ping 更能反映通达信可用性。
- 入库规则:延迟排名前 FAST_POOL_TOP_N(10) **或** 延迟 < FAST_POOL_MAX_LATENCY(0.2s) 的服务器
才标记为 status="ok" 并写入 servers.json,其余降权(保留但不优先)。
- 结果持久化到 servers.json,供 config / 连接池直接使用。
行为
----
- **当日首次启动**触发一次后台全量测速;当天已有缓存则直接复用,**不再刷新**。
- 测速覆盖**全部候选**(包内清单 ∪ 代码常量 ∪ env 覆盖,见
:func:`pytdxdata.config.all_probe_candidates`),而不是只测当前已在池里的少数节点 ——
否则"上次慢、这次快"的节点永远捞不回来。
- 用**真实业务命令**判定可达(标准: GetSecurityBarsCmd / MAC: MacKlineCmd /
EX: GetExInstrumentBarsCmd)并要求返回非空数据,而不是只做握手回显:
存在"握手正常但 K线空响应"的坏节点(见 ``config.py`` 注释),只有真数据能测出来。
- 结果写入**用户级缓存目录**(见 :func:`pytdxdata.config.probe_cache_file`),
不写安装目录:site-packages 在容器 / 系统级安装 / pipx 下可能只读,
多用户共用一份安装时还会互相覆盖。
- 结果被 :func:`pytdxdata.config.get_standard_hosts` 等按**实测延迟升序**采用。
无感保证
--------
- 不打印任何东西;日志一律 ``debug`` 级(默认不输出)。
- 不抛异常(取消除外);失败只落 debug 日志,下次启动自然重试。
- 由连接池以后台 task 方式调用,不阻塞 ``start()`` 与任何用户请求。
一致性与并发
------------
- 进程内单例 + ``asyncio.Lock``:标准 / MAC / EX 三个池共用一次真正测速。
- 原子写入(tmp + ``os.replace``):进程被杀或多进程并发都不会读到半截 JSON。
- 全部不可达时**不写缓存**,避免把"全挂"状态缓存一整天。
开关
----
- ``PYPYTDX_DATA_DISABLE_PROBE=1`` 关闭(CI / 测试用,保证确定性)。
- ``PYPYTDX_DATA_CACHE_DIR`` 覆盖缓存目录(测试指向临时目录)。
"""
from __future__ import annotations
import asyncio
import json
import logging
import os
import time
from collections import defaultdict
from collections.abc import Awaitable, Callable
from datetime import date
from pathlib import Path
from ..config import _SERVERS_FILE
from ..config import (
PROBE_CACHE_VERSION,
all_probe_candidates,
get_ex_handshakes,
is_valid_host,
load_probe_cache,
probe_cache_file,
probe_disabled,
)
from ..models import Adjust, KlinePeriod
from ..protocol.commands.ex_proto import GetExInstrumentBarsCmd
from ..protocol.commands.kline import GetSecurityBarsCmd
from ..protocol.commands.mac import MacKlineCmd
from .connection import TdxConnection
from .ex_connection import ExTdxConnection
log = logging.getLogger(__name__)
# 入池阈值
FAST_POOL_TOP_N = 10 # 延迟排名前 N
FAST_POOL_MAX_LATENCY = 0.2 # 延迟 < 200ms(秒)也可入池
# 入池阈值(仅用于缓存里的 fast 诊断标记;运行时按实测延迟整体排序,不做硬切)
FAST_POOL_TOP_N = 10
FAST_POOL_MAX_LATENCY = 0.2
# 探针参数
PROBE_PORT = 7709
EX_PORT = 7727
PROBE_TIMEOUT = 3.0
PROBE_CONCURRENCY = 24
PROBE_CONCURRENCY = 12
PROBE_BUDGET = 60.0 # 整轮测速硬上限(秒),防止极端网络下长期占着后台
ProbeFn = Callable[[str, float], Awaitable[float | None]]
# ---------- 三个协议各自的真实数据探针 ----------
async def _probe_standard(host: str, timeout: float) -> float | None:
"""标准通道 7709:取 600000 日K,非空才算可达。"""
conn = TdxConnection(host, PROBE_PORT, timeout)
t0 = time.monotonic()
try:
await conn.connect()
bars = await conn.execute(GetSecurityBarsCmd(1, "600000", KlinePeriod.DAY, 0, 100))
return time.monotonic() - t0 if bars else None
except Exception:
return None
finally:
await conn.close()
async def _probe_mac(host: str, timeout: float) -> float | None:
"""MAC 通道 7709:MAC 帧与标准帧不同,用 MacKlineCmd 取日K。"""
conn = TdxConnection(host, PROBE_PORT, timeout)
t0 = time.monotonic()
try:
await conn.connect()
bars = await conn.execute(
MacKlineCmd(1, "600000", KlinePeriod.DAY, Adjust.NONE, 0, 100)
)
return time.monotonic() - t0 if bars else None
except Exception:
return None
finally:
await conn.close()
async def _probe_ex(host: str, timeout: float) -> float | None:
"""EX 扩展市场 7727:取港股 00700,握手模式按主机取(login / setup)。"""
conn = ExTdxConnection(host, EX_PORT, timeout, get_ex_handshakes().get(host, "setup"))
t0 = time.monotonic()
try:
await conn.connect()
bars = await conn.execute(GetExInstrumentBarsCmd(31, "00700", 0, 0, 5))
return time.monotonic() - t0 if bars else None
except Exception:
return None
finally:
await conn.close()
_DEFAULT_PROBERS: dict[str, ProbeFn] = {
"standard": _probe_standard,
"mac": _probe_mac,
"ex": _probe_ex,
}
class ProbeCache:
"""管理当日测速缓存与 servers.json 入库。
"""当日全量测速的进程内协调器。
一台服务器不论协议(standard/mac/ex),测速结果共享:
只要任一端口可达即视为该主机可用,并以最快端口延迟作为延迟基准。
一台主机不论申报几个协议,都按协议分别探测;缓存里记录
``{host: {protocol: 延迟或 None}}``,``None`` 表示该协议本次不可达。
参数(后 5 个主要供测试注入):
cache_file: 显式指定缓存文件;``None`` 时按 config 的平台规则解析。
probers: 协议 → 探针函数;默认使用真实网络探针。
today_fn: 返回 ``YYYY-MM-DD``;测试可注入假日期来验证跨日重测。
"""
def __init__(self, servers_file: Path | None = None) -> None:
self._file = servers_file or _SERVERS_FILE
def __init__(self, cache_file: Path | str | None = None, *,
timeout: float = PROBE_TIMEOUT,
concurrency: int = PROBE_CONCURRENCY,
budget: float = PROBE_BUDGET,
probers: dict[str, ProbeFn] | None = None,
today_fn: Callable[[], str] | None = None) -> None:
self._file = Path(cache_file) if cache_file is not None else None
self._timeout = timeout
self._concurrency = concurrency
self._budget = budget
self._probers = dict(probers or _DEFAULT_PROBERS)
self._today_fn = today_fn or (lambda: date.today().isoformat())
self._lock = asyncio.Lock()
self._last_probe_date: str | None = None
self._probed_today = False
self._handled = False # 本进程是否已处理过今日测速(含"已有缓存,跳过")
self._task: asyncio.Task | None = None
# ---------- 路径与状态 ----------
def cache_file(self) -> Path:
"""缓存文件路径(构造时显式传入的优先,否则按平台规则解析)。"""
return self._file if self._file is not None else probe_cache_file()
def today(self) -> str:
return self._today_fn()
def read_cache(self) -> dict | None:
"""读取当日缓存;``None`` 表示"今天还没测过"。"""
return load_probe_cache(self.today(), self.cache_file())
# ---- 公开 API ----
def needs_probe_today(self) -> bool:
"""是否有必要在今日执行一次全量测速(文件不存在 / 日期不符 / 无 ok 项)。"""
if not self._file.exists():
return True
try:
cfg = json.loads(self._file.read_text(encoding="utf-8"))
except (OSError, ValueError):
return True
checked = str(cfg.get("checked_date", ""))
today = date.today().isoformat()
if checked != today:
return True
servers = cfg.get("servers", [])
if not any(s.get("status") == "ok" for s in servers):
return True
"""今日是否仍需测速(缓存缺失 / 非今日 / 损坏 / 版本不符 / 无任何可用项)。"""
if probe_disabled():
return False
return self.read_cache() is None
async def ensure_probe(self, hosts: list[str]) -> None:
"""若今日尚未测速,则后台执行一次全量测速并入库(幂等)。"""
def reset(self) -> None:
"""清除"本进程已处理"标记(仅供测试复用单例)。"""
self._handled = False
# ---------- 主入口 ----------
async def ensure_probe(self, hosts: list[str] | None = None) -> None:
"""幂等入口:当日尚未测速则测一次;当天已有缓存则立即返回。
- 不阻塞调用方:正常由连接池以后台 task 调用。
- 绝不抛异常(``CancelledError`` 除外):测速 / 写盘失败只落 debug 日志。
- ``hosts``:为兼容旧签名保留,作为**额外的标准通道候选**并入,
且必须通过 :func:`~pytdxdata.config.is_valid_host` 校验(挡住 mock 脏数据)。
"""
async with self._lock:
if self._probed_today:
if self._handled:
return
self._handled = True # 先占位:并发调用方不必排队等网络
if not self.needs_probe_today():
self._probed_today = True
log.debug("当日测速缓存已存在,跳过测速: %s", self.cache_file())
return
self._probed_today = True
# 在锁外执行(耗时网络 IO),允许并发进入的调用方共享本次结果
try:
await self._run_full_probe(hosts)
except Exception as e: # 测速失败不能阻塞主流程
log.warning("后台全量测速失败,沿用既有清单: %s", str(e)[:80])
payload = await self._run_probe(hosts)
if payload is not None:
self._write(payload)
except asyncio.CancelledError:
raise
except Exception as exc: # 测速绝不能影响主流程
log.debug("后台测速失败,沿用既有清单: %s", str(exc)[:120])
# ---- 内部实现 ----
async def _run_full_probe(self, hosts: list[str]) -> None:
from .connection import TdxConnection
# ---------- 内部实现 ----------
async def _run_probe(self, extra_hosts: list[str] | None = None) -> dict | None:
"""全量并发测速,返回待写入的缓存 payload;无任何可达主机时返回 None。"""
candidates = all_probe_candidates()
if extra_hosts:
extra = [h.strip() for h in extra_hosts
if isinstance(h, str) and is_valid_host(h)]
if extra:
candidates["standard"] = list(dict.fromkeys(candidates["standard"] + extra))
jobs = [(proto, ip) for proto, ips in candidates.items() for ip in ips]
if not jobs:
log.debug("无测速候选,跳过")
return None
log.info("开始当日全量服务器测速 (%d 台)...", len(hosts))
sem = asyncio.Semaphore(PROBE_CONCURRENCY)
results: dict[str, float | None] = {}
log.debug("开始当日全量测速: %d 台主机 / %d 个协议探针",
len({ip for _, ip in jobs}), len(jobs))
sem = asyncio.Semaphore(self._concurrency)
# {host: {protocol: 延迟或 None}}
results: dict[str, dict[str, float | None]] = defaultdict(dict)
async def _probe_one(host: str) -> None:
async def _one(protocol: str, host: str) -> None:
async with sem:
try:
# 使用连接自带的 ping():建连+握手+发1条命令测往返延迟
conn = TdxConnection(host, PROBE_PORT, PROBE_TIMEOUT)
dt = await asyncio.wait_for(conn.ping(), timeout=PROBE_TIMEOUT + 1.0)
results[host] = dt # 失败时为 None
lat = await asyncio.wait_for(
self._probers[protocol](host, self._timeout),
timeout=self._timeout + 2.0,
)
except Exception:
results[host] = None
lat = None
results[host][protocol] = lat
await asyncio.gather(*(_probe_one(h) for h in hosts))
ok_hosts = {h: lt for h, lt in results.items() if lt is not None}
# 按延迟升序排名
ranked = sorted(ok_hosts.items(), key=lambda kv: kv[1])
fast = set()
for i, (h, lt) in enumerate(ranked):
if i < FAST_POOL_TOP_N or lt < FAST_POOL_MAX_LATENCY:
fast.add(h)
log.info("测速完成: 可用 %d 台, 入池 %d 台 (前%d或<%dms)",
len(ok_hosts), len(fast), FAST_POOL_TOP_N,
int(FAST_POOL_MAX_LATENCY * 1000))
self._write_results(results, fast)
def _write_results(self, results: dict[str, float | None], fast: set[str]) -> None:
t0 = time.monotonic()
try:
cfg = json.loads(self._file.read_text(encoding="utf-8"))
except (OSError, ValueError):
cfg = {"servers": []}
servers = cfg.get("servers", [])
by_ip = {s.get("ip"): s for s in servers}
today = date.today().isoformat()
now = time.strftime("%Y-%m-%d %H:%M:%S")
checked_any = False
for host, lt in results.items():
entry = by_ip.get(host)
if entry is None:
entry = {"ip": host, "name": host, "protocols": ["standard"]}
servers.append(entry)
by_ip[host] = entry
if lt is not None:
checked_any = True
entry["status"] = "ok" if host in fast else "slow"
entry["latency"] = round(lt, 3)
entry["fast_pool"] = host in fast
else:
# 探测不可达:不降级已有 ok(避免误杀),仅标记本次不可达
entry.setdefault("status", "unknown")
entry["latency"] = None
entry["fast_pool"] = False
entry["checked_date"] = today
entry["checked_at"] = now
# 若有 ok 服务器写入可入池日期;否则保留今日以免反复重试
cfg["checked_date"] = today
cfg["note"] = (
f"当日全量测速入库({today}): 入池={len(fast)}台 "
f"(排名前{FAST_POOL_TOP_N}或延迟<{int(FAST_POOL_MAX_LATENCY*1000)}ms)"
await asyncio.wait_for(
asyncio.gather(*(_one(p, ip) for p, ip in jobs)),
timeout=self._budget,
)
if not checked_any:
# 全部不可达时不写 checked_date,下次启动重试
cfg.pop("checked_date", None)
except TimeoutError:
# 超时:采用已完成的部分结果(部分可用也强于完全没有)
log.debug("测速整体超过 %.0fs 预算,采用已完成的部分结果", self._budget)
except Exception as exc:
log.debug("测速过程异常: %s", str(exc)[:120])
elapsed = time.monotonic() - t0
self._file.write_text(
json.dumps(cfg, ensure_ascii=False, indent=2), encoding="utf-8"
responsive = {
ip: {p: lat for p, lat in per.items() if lat is not None}
for ip, per in results.items()
}
responsive = {ip: per for ip, per in responsive.items() if per}
if not responsive:
log.debug("测速结束: 无任何可达主机,不写缓存(下次启动重试)")
return None
def _ordered(protocol: str) -> list[str]:
rows = [(per[protocol], ip) for ip, per in responsive.items()
if protocol in per]
rows.sort(key=lambda kv: (kv[0], kv[1]))
return [ip for _, ip in rows]
hosts_by_proto = {p: _ordered(p) for p in ("standard", "mac", "ex")}
overall = sorted(
(min(per.values()), ip) for ip, per in responsive.items()
)
log.info("测速结果已写入 %s", self._file)
fast = {ip for i, (lat, ip) in enumerate(overall)
if i < FAST_POOL_TOP_N or lat < FAST_POOL_MAX_LATENCY}
log.debug("测速完成: 候选 %d 台, 可达 %d 台, fast %d 台, 耗时 %.2fs",
len({ip for _, ip in jobs}), len(responsive), len(fast), elapsed)
return {
"version": PROBE_CACHE_VERSION,
"date": self.today(),
"probed_at": time.strftime("%Y-%m-%d %H:%M:%S"),
"elapsed": round(elapsed, 3),
# 每个协议的完整探测结果(含 None = 本次不可达),便于事后诊断
"results": {ip: dict(per) for ip, per in results.items() if per},
# 按延迟升序的可达主机(运行时即按此顺序取用)
"hosts": hosts_by_proto,
# 诊断用:符合"前N名或<200ms"的可达主机
"fast": {p: [h for h in ips if h in fast]
for p, ips in hosts_by_proto.items()},
}
def _write(self, payload: dict) -> None:
"""原子写入:先写临时文件再 ``os.replace``,避免读到半截 JSON。"""
target = self.cache_file()
tmp = target.with_name(f"{target.name}.tmp{os.getpid()}")
try:
target.parent.mkdir(parents=True, exist_ok=True)
tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2),
encoding="utf-8")
os.replace(tmp, target)
log.debug("当日测速结果已缓存: %s", target)
except OSError as exc:
log.debug("测速结果写入失败(忽略): %s", str(exc)[:120])
try:
tmp.unlink(missing_ok=True)
except OSError:
pass
# 进程级单例(跨池共享,确保当日仅测一次)
# 进程级单例(标准 / MAC / EX 三池共享,确保当日只真正测一次)
_probe_cache = ProbeCache()
def get_probe_cache() -> ProbeCache:
return _probe_cache
def schedule_probe(hosts: list[str] | None = None) -> asyncio.Task | None:
"""[连接池用] 把当日测速挂到后台并返回 Task,供调用方持有 / 取消。
返回 ``None`` 表示当前没有运行中的事件循环(此时无法起后台任务)。
"""
try:
return asyncio.create_task(
get_probe_cache().ensure_probe(hosts), name="pytdxdata-daily-probe"
)
except RuntimeError:
return None
+113 -39
View File
@@ -3,28 +3,43 @@
读 servers.json → 并发探测每台可用性与延时(标准/MAC用7709、EX用7727)→ 写回状态。
用法:
python -m pytdxdata.server_probe # 全量探测
python -m pytdxdata.server_probe # 按申报协议全量探测
python -m pytdxdata.server_probe --discover # 额外测【每种协议】并据实修正 protocols
python -m pytdxdata.server_probe --group ex # 只测EX
python -m pytdxdata.server_probe --refresh # 重新探测(status=ok的)
python -m pytdxdata.server_probe --refresh # 只重测status=ok的
写回的字段
----------
``status`` / ``latency`` / ``checked_at`` / ``checked_date`` / ``fast_pool``
以及顶层 ``checked_date`` / ``note``。其中 ``fast_pool`` 与运行时缓存里的 ``fast``
用同一套规则(整体延迟前 10 名,或延迟 < 200ms),供"还没有当日缓存时"的冷启动排序。
``--discover`` 会顺带剔除 ip 非法的脏记录(如历史遗留的 ``"s1"``)。
"""
from __future__ import annotations
import argparse
import asyncio
import json
import sys
import time
from pathlib import Path
from .config import is_valid_host
from .models import Adjust, KlinePeriod
from .pool.connection import TdxConnection
from .pool.ex_connection import ExTdxConnection
from .protocol.commands.ex_proto import GetExInstrumentBarsCmd
from .protocol.commands.kline import GetSecurityBarsCmd
from .protocol.commands.mac import MacKlineCmd
from .protocol.commands.ex_proto import GetExInstrumentBarsCmd
from .models import KlinePeriod, Adjust
SERVERS_FILE = Path(__file__).resolve().parent / "servers.json"
# 与 pool/probe_cache.py 保持同一套入池规则
FAST_POOL_TOP_N = 10
FAST_POOL_MAX_LATENCY = 0.2
ALL_PROTOCOLS = ("standard", "mac", "ex")
def load_servers() -> dict:
if not SERVERS_FILE.exists():
@@ -41,7 +56,7 @@ async def probe_standard(ip: str, timeout: float = 5.0) -> tuple[bool, float]:
t0 = time.monotonic()
try:
await conn.connect()
bars = await conn.execute(GetSecurityBarsCmd(1, "600000", 5, 0, 100))
bars = await conn.execute(GetSecurityBarsCmd(1, "600000", KlinePeriod.DAY, 0, 100))
return (bool(bars), time.monotonic() - t0)
except Exception:
return (False, time.monotonic() - t0)
@@ -75,25 +90,51 @@ async def probe_ex(ip: str, handshake: str, timeout: float = 5.0) -> tuple[bool,
await conn.close()
async def probe_one(server: dict, timeout: float) -> dict:
ip = server["ip"]
protocols = server.get("protocols", [])
best_lat = None
ok = False
# 逐协议探测(一台多协议: standard/mac同端口可复用连接——简化逐协议测)
for proto in protocols:
async def probe_proto(proto: str, ip: str, handshake: str, timeout: float) -> tuple[bool, float]:
"""按协议分派到具体探针。"""
if proto == "ex":
r, lat = await probe_ex(ip, server.get("handshake", "setup"), timeout)
elif proto == "mac":
r, lat = await probe_mac(ip, timeout)
return await probe_ex(ip, handshake, timeout)
if proto == "mac":
return await probe_mac(ip, timeout)
return await probe_standard(ip, timeout)
async def probe_one(server: dict, timeout: float, discover: bool = False) -> dict:
ip = server["ip"]
declared = server.get("protocols", [])
handshake = server.get("handshake") or "setup"
# discover: 三种协议全测(EX 先按申报握手,失败再试另一种);
# 默认: 只测申报的协议(保持原行为,避免误改人工裁剪的清单)
targets = list(ALL_PROTOCOLS) if discover else list(declared)
per: dict[str, float | None] = {}
for proto in targets:
if proto == "ex":
ok, lat = await probe_ex(ip, handshake, timeout)
if not ok and discover:
# 握手模式申报错的节点:换一种再试(login <-> setup)
alt = "setup" if handshake == "login" else "login"
ok, lat = await probe_ex(ip, alt, timeout)
else:
r, lat = await probe_standard(ip, timeout)
if r:
ok = True
best_lat = lat if best_lat is None else min(best_lat, lat)
server["status"] = "ok" if ok else "fail"
server["latency"] = round(best_lat, 3) if best_lat is not None else None
server["checked_at"] = time.strftime("%Y-%m-%d %H:%M:%S")
ok, lat = await probe_proto(proto, ip, handshake, timeout)
if not ok and discover:
# discover 会据结果**收窄 protocols**,单次抖动就会误删协议 → 失败重试一次
ok, lat = await probe_proto(proto, ip, handshake, timeout)
if ok:
per[proto] = lat
if discover and per:
# 据实测结果修正申报协议(保序:standard / mac / ex)
server["protocols"] = [p for p in ALL_PROTOCOLS if p in per]
server["status"] = "ok" if per else "fail"
server["latency"] = round(min(per.values()), 3) if per else None
now = time.strftime("%Y-%m-%d %H:%M:%S")
server["checked_at"] = now
server["checked_date"] = now[:10]
server.setdefault("fast_pool", False)
# 供表格打印用,不落盘
server["_per_proto"] = {p: (round(v, 3) if v is not None else None) for p, v in per.items()}
return server
@@ -102,10 +143,21 @@ async def main() -> None:
ap.add_argument("--group", choices=["standard", "mac", "ex"], default=None)
ap.add_argument("--timeout", type=float, default=5.0)
ap.add_argument("--refresh", action="store_true", help="只重测status=ok的")
ap.add_argument("--discover", action="store_true",
help="三种协议全测并据实修正 protocols(同时剔除 ip 非法的脏记录)")
args = ap.parse_args()
cfg = load_servers()
servers = cfg["servers"]
all_servers = cfg["servers"]
# --- 清理:ip 不合法的脏记录(历史遗留,如 "s1") ---
junk = [s.get("ip") for s in all_servers if not is_valid_host(s.get("ip"))]
if junk:
cfg["servers"] = [s for s in all_servers if is_valid_host(s.get("ip"))]
all_servers = cfg["servers"]
print("已剔除 ip 非法记录: %s" % ", ".join(map(str, junk)))
servers = all_servers
if args.group:
servers = [s for s in servers if args.group in s.get("protocols", [])]
if args.refresh:
@@ -114,33 +166,55 @@ async def main() -> None:
print("没有待探测的服务器")
return
print("=" * 90)
print("探测 %d 台服务器 (标准/MAC:7709, EX:7727)..." % len(servers))
print("=" * 90)
print("=" * 96)
print("探测 %d 台服务器 (标准/MAC:7709, EX:7727)%s..." % (
len(servers), " [discover: 全协议]" if args.discover else ""))
print("=" * 96)
t0 = time.time()
results = await asyncio.gather(*[probe_one(s, args.timeout) for s in servers])
results = await asyncio.gather(
*[probe_one(s, args.timeout, args.discover) for s in servers]
)
elapsed = time.time() - t0
# 写回
updated = {s["ip"]: s for s in results}
# --- 入池标记:与运行时缓存同一规则(前N名 或 <200ms) ---
ok_list = [s for s in results if s["status"] == "ok"]
ok_list.sort(key=lambda s: s["latency"])
fast_ips = {s["ip"] for i, s in enumerate(ok_list)
if i < FAST_POOL_TOP_N or s["latency"] < FAST_POOL_MAX_LATENCY}
for s in ok_list:
s["fast_pool"] = s["ip"] in fast_ips
fail_list = [s for s in results if s["status"] == "fail"]
for s in fail_list:
s["fast_pool"] = False
# --- 写回(剔除内部诊断字段) ---
today = time.strftime("%Y-%m-%d")
updated = {s["ip"]: {k: v for k, v in s.items() if not k.startswith("_")} for s in results}
for s in cfg["servers"]:
if s["ip"] in updated:
s.update(updated[s["ip"]])
cfg["checked_date"] = today
cfg["version"] = today # 清单基线日期(无代码读取,仅标注本次复测时间)
cfg["note"] = "离线探针复测(%s %s): 可达=%d/%d, 入池fast_pool=%d台" % (
today, time.strftime("%H:%M"), len(ok_list), len(results), len(fast_ips))
save_servers(cfg)
ok_list = [s for s in results if s["status"] == "ok"]
ok_list.sort(key=lambda s: s["latency"])
fail_list = [s for s in results if s["status"] == "fail"]
print("\n可用: %d/%d (%.1fs)" % (len(ok_list), len(results), elapsed))
print("-" * 90)
print("\n可用: %d/%d (%.1fs) 入池: %d台" % (len(ok_list), len(results), elapsed, len(fast_ips)))
print("-" * 96)
for s in ok_list:
print(" [OK] %-16s %-14s %-28s %.3fs %s" % (
s["ip"], "/".join(s.get("protocols", [])), s["name"],
s["latency"], s.get("handshake") or ""))
per = s.get("_per_proto", {})
detail = " ".join(
"%s=%s" % (p, ("%.3fs" % v) if v is not None else "-")
for p, v in per.items()
) or "/".join(s.get("protocols", []))
print(" [OK] %-16s %-24s %-24s %.3fs %s%s" % (
s["ip"], "/".join(s.get("protocols", [])), s["name"], s["latency"],
"★" if s["fast_pool"] else " ", detail))
if fail_list:
print("\n不可用: %d台" % len(fail_list))
for s in fail_list:
print(" [X] %-16s %s" % (s["ip"], "/".join(s.get("protocols", []))))
print(" [X] %-16s %-24s %s" % (
s["ip"], "/".join(s.get("protocols", [])), s["name"]))
print("\n已写回 %s" % SERVERS_FILE)
+236 -150
View File
@@ -1,6 +1,6 @@
{
"version": "2026-08-12",
"note": "当日全量测速入库(2026-09-08): 入池=9台 (排名前10或延迟<200ms)",
"version": "2026-09-21",
"note": "离线探针复测(2026-09-21 19:03): 可达=25/33, 入池fast_pool=10台",
"servers": [
{
"ip": "139.9.52.158",
@@ -11,11 +11,15 @@
],
"handshake": null,
"status": "ok",
"latency": null,
"checked_at": "2026-08-21 11:23:14",
"latency": 0.22,
"checked_at": "2026-09-21 19:03:04",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-21"
"fast_pool": true,
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.226,
"mac": 0.22
}
},
{
"ip": "103.251.85.94",
@@ -25,42 +29,50 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.481,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.366,
"checked_at": "2026-09-21 19:03:04",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.396,
"mac": 0.366
}
},
{
"ip": "58.67.221.146",
"name": "中信短线宝21",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "ok",
"latency": 0.254,
"checked_at": "2026-09-08 10:05:12",
"latency": 0.257,
"checked_at": "2026-09-21 19:03:09",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.257
}
},
{
"ip": "59.36.5.11",
"name": "安信",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "ok",
"latency": 0.254,
"checked_at": "2026-09-08 10:05:12",
"latency": 0.248,
"checked_at": "2026-09-21 19:03:04",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.248
}
},
{
"ip": "103.221.142.82",
@@ -71,12 +83,17 @@
"ex"
],
"handshake": "setup",
"status": "slow",
"latency": 0.487,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.221,
"checked_at": "2026-09-21 19:03:00",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"fast_pool": true,
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.399,
"mac": 0.414,
"ex": 0.221
}
},
{
"ip": "218.106.92.182",
@@ -85,27 +102,30 @@
"standard"
],
"handshake": null,
"status": "ok",
"latency": 0.371,
"checked_at": "2026-09-08 10:05:12",
"status": "fail",
"latency": null,
"checked_at": "2026-09-21 19:03:20",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"fast_pool": false,
"checked_date": "2026-09-21",
"_per_proto": {}
},
{
"ip": "60.12.136.251",
"name": "中信短线宝22",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "ok",
"latency": 0.37,
"checked_at": "2026-09-08 10:05:12",
"latency": 0.363,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.363
}
},
{
"ip": "218.106.92.183",
@@ -114,42 +134,47 @@
"standard"
],
"handshake": null,
"status": "ok",
"latency": 0.377,
"checked_at": "2026-09-08 10:05:12",
"status": "fail",
"latency": null,
"checked_at": "2026-09-21 19:03:20",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"fast_pool": false,
"checked_date": "2026-09-21",
"_per_proto": {}
},
{
"ip": "60.12.136.250",
"name": "中信短线宝26",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "ok",
"latency": 0.373,
"checked_at": "2026-09-08 10:05:12",
"latency": 0.344,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.344
}
},
{
"ip": "115.238.90.170",
"name": "中信短线宝23",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.482,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.404,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.404
}
},
{
"ip": "220.178.55.86",
@@ -158,12 +183,13 @@
"standard"
],
"handshake": null,
"status": "slow",
"latency": 0.479,
"checked_at": "2026-08-19 15:37:35",
"status": "fail",
"latency": null,
"checked_at": "2026-09-21 19:03:24",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {}
},
{
"ip": "220.178.55.71",
@@ -172,87 +198,98 @@
"standard"
],
"handshake": null,
"status": "slow",
"latency": 0.47,
"checked_at": "2026-08-19 15:37:35",
"status": "fail",
"latency": null,
"checked_at": "2026-09-21 19:03:21",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {}
},
{
"ip": "180.153.18.170",
"name": "中信短线宝1",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.438,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.376,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.376
}
},
{
"ip": "115.238.90.165",
"name": "杭州J4",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.476,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.377,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.377
}
},
{
"ip": "60.191.117.167",
"name": "杭州J1",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "ok",
"latency": 0.362,
"checked_at": "2026-09-08 10:05:12",
"latency": 0.401,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"fast_pool": false,
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.401
}
},
{
"ip": "218.75.126.9",
"name": "杭州J3",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.481,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.42,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.42
}
},
{
"ip": "115.238.56.198",
"name": "杭州J2",
"protocols": [
"standard",
"mac"
],
"handshake": null,
"status": "ok",
"latency": 0.362,
"checked_at": "2026-09-08 10:05:12",
"latency": 0.401,
"checked_at": "2026-09-21 19:03:10",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"fast_pool": false,
"checked_date": "2026-09-21",
"_per_proto": {
"mac": 0.401
}
},
{
"ip": "117.34.114.16",
@@ -262,12 +299,16 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 1.575,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.485,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.485,
"mac": 0.605
}
},
{
"ip": "159.75.55.232",
@@ -276,26 +317,32 @@
"standard"
],
"handshake": null,
"status": "ok",
"latency": 0.244,
"checked_at": "2026-09-08 10:05:12",
"status": "fail",
"latency": null,
"checked_at": "2026-09-21 19:03:04",
"source": "probe-2026-08-12",
"fast_pool": true,
"checked_date": "2026-09-08"
"fast_pool": false,
"checked_date": "2026-09-21",
"_per_proto": {}
},
{
"ip": "117.34.114.17",
"name": "国泰君安",
"protocols": [
"standard"
"standard",
"mac"
],
"handshake": null,
"status": "slow",
"latency": 1.573,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.444,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.444,
"mac": 0.903
}
},
{
"ip": "117.34.114.14",
@@ -305,12 +352,13 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.508,
"checked_at": "2026-08-19 15:37:35",
"status": "fail",
"latency": null,
"checked_at": "2026-09-21 19:03:15",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {}
},
{
"ip": "117.34.114.15",
@@ -320,12 +368,16 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.636,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.435,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.463,
"mac": 0.435
}
},
{
"ip": "117.34.114.13",
@@ -335,12 +387,13 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.608,
"checked_at": "2026-08-19 15:37:35",
"status": "fail",
"latency": null,
"checked_at": "2026-09-21 19:03:14",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {}
},
{
"ip": "117.34.114.27",
@@ -350,12 +403,16 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 1.138,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.482,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.482,
"mac": 0.579
}
},
{
"ip": "117.34.114.18",
@@ -365,12 +422,16 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.969,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.609,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.946,
"mac": 0.609
}
},
{
"ip": "117.34.114.20",
@@ -380,12 +441,16 @@
"mac"
],
"handshake": null,
"status": "slow",
"latency": 0.526,
"checked_at": "2026-08-19 15:37:35",
"status": "ok",
"latency": 0.46,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"fast_pool": false,
"checked_date": "2026-08-19"
"checked_date": "2026-09-21",
"_per_proto": {
"standard": 0.46,
"mac": 0.521
}
},
{
"ip": "117.34.114.30",
@@ -396,8 +461,11 @@
"handshake": null,
"status": "fail",
"latency": null,
"checked_at": "2026-08-12 18:36:21",
"source": "probe-2026-08-12"
"checked_at": "2026-09-21 19:03:24",
"source": "probe-2026-08-12",
"checked_date": "2026-09-21",
"fast_pool": false,
"_per_proto": {}
},
{
"ip": "121.37.207.165",
@@ -407,9 +475,14 @@
],
"handshake": null,
"status": "ok",
"latency": 0.249,
"checked_at": "2026-08-12 18:36:17",
"source": "probe-2026-08-12"
"latency": 0.271,
"checked_at": "2026-09-21 19:03:04",
"source": "probe-2026-08-12",
"checked_date": "2026-09-21",
"fast_pool": true,
"_per_proto": {
"mac": 0.271
}
},
{
"ip": "121.36.248.138",
@@ -419,9 +492,14 @@
],
"handshake": null,
"status": "ok",
"latency": 0.436,
"checked_at": "2026-08-12 18:36:17",
"source": "probe-2026-08-12"
"latency": 0.375,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"checked_date": "2026-09-21",
"fast_pool": false,
"_per_proto": {
"mac": 0.375
}
},
{
"ip": "123.60.47.136",
@@ -431,9 +509,14 @@
],
"handshake": null,
"status": "ok",
"latency": 0.476,
"checked_at": "2026-08-12 18:36:17",
"source": "probe-2026-08-12"
"latency": 0.424,
"checked_at": "2026-09-21 19:03:05",
"source": "probe-2026-08-12",
"checked_date": "2026-09-21",
"fast_pool": false,
"_per_proto": {
"mac": 0.424
}
},
{
"ip": "116.205.135.205",
@@ -443,9 +526,14 @@
],
"handshake": "login",
"status": "ok",
"latency": 0.192,
"checked_at": "2026-08-12 18:36:17",
"source": "probe-2026-08-12"
"latency": 0.176,
"checked_at": "2026-09-21 19:03:08",
"source": "probe-2026-08-12",
"checked_date": "2026-09-21",
"fast_pool": true,
"_per_proto": {
"ex": 0.176
}
},
{
"ip": "121.37.232.167",
@@ -455,9 +543,14 @@
],
"handshake": "login",
"status": "ok",
"latency": 0.194,
"checked_at": "2026-08-12 18:36:17",
"source": "probe-2026-08-12"
"latency": 0.148,
"checked_at": "2026-09-21 19:03:08",
"source": "probe-2026-08-12",
"checked_date": "2026-09-21",
"fast_pool": true,
"_per_proto": {
"ex": 0.148
}
},
{
"ip": "116.205.143.214",
@@ -467,22 +560,15 @@
],
"handshake": "setup",
"status": "ok",
"latency": 0.192,
"checked_at": "2026-08-12 18:36:17",
"source": "probe-2026-08-12"
},
{
"ip": "s1",
"name": "s1",
"protocols": [
"standard"
],
"status": "unknown",
"latency": null,
"fast_pool": false,
"checked_date": "2026-08-19",
"checked_at": "2026-08-19 15:34:45"
"latency": 0.166,
"checked_at": "2026-09-21 19:03:08",
"source": "probe-2026-08-12",
"checked_date": "2026-09-21",
"fast_pool": true,
"_per_proto": {
"ex": 0.166
}
}
],
"checked_date": "2026-09-08"
"checked_date": "2026-09-21"
}
+82 -6
View File
@@ -156,12 +156,15 @@ def _dispatch(cmd) -> object:
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)]
return [MinuteBar(price=p, vol=100.0, hour=9, minute=30 + i)
for i, p in enumerate((10.0, 10.1, 10.2))]
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]
# 刻意与 MacTickChartCmd 的 mock 数据不同:A股由分时派生、EX 用 0x254D,
# 靠返回值即可区分实际走了哪条命令(BUG-1 回归用)。
return [99.0, 98.0]
# ---- 公司信息 ----
if n == "MacSymbolInfoCmd":
return SymbolSnapshot(
@@ -270,6 +273,13 @@ def _make_financial_zip() -> bytes:
return buf.getvalue()
def _make_financial_dat() -> bytes:
"""未压缩 .dat(服务器实际提供的形式)。"""
entry = struct.pack("<6sBL", b"600000", 1, 31)
header = struct.pack("<1hI1H3L", 0, 20260331, 1, 0, 8, 0)
return header + entry + struct.pack("<2f", 1.0, 2.0)
# --------------------------------------------------------------------------- #
# fixture
# --------------------------------------------------------------------------- #
@@ -281,8 +291,7 @@ async def td():
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())):
mock.patch("pytdxdata.pool.pool.schedule_probe", return_value=None):
t = TdxData(cache_dir=None, pool_min=1, pool_max=2)
_use("start")
await t.start()
@@ -485,6 +494,69 @@ async def test_parsed_files(td):
assert len(recs) == 1 and recs[0].report_date == 20260331
# --------------------------------------------------------------------------- #
# 六之二、BUG 回归(真实联网实测发现,见 tests 说明)
# --------------------------------------------------------------------------- #
async def test_financial_dat_fallback(td):
"""BUG-2 回归:索引写 ``.zip``,服务器只给未压缩 ``.dat`` 时必须能回退取到。
服务器对**不存在的**文件名不报错,而是回 0~1 字节空壳;旧实现会把空壳直接
丢给 ``zipfile`` → ``BadZipFile``。现在要求按候选名回退到 ``tdxfin/*.dat``。
"""
calls: list[str] = []
async def fake_get_file(name: str) -> bytes:
calls.append(name)
if name == "tdxfin/gpcw20260331.zip":
return b"" # 服务器没有 .zip
if name == "gpcw20260331.zip":
return b"\x00" # 裸名被路由到 MAC 通道 → 1 字节空壳
if name == "tdxfin/gpcw20260331.dat":
return _make_financial_dat()
return b""
with mock.patch.object(td, "get_file", new=fake_get_file):
recs = await td.get_financial_records_parsed("gpcw20260331.zip")
assert "tdxfin/gpcw20260331.dat" in calls, "必须回退尝试未压缩 .dat"
assert len(recs) == 1 and recs[0].report_date == 20260331
assert recs[0].code == "600000"
async def test_financial_records_alias_not_silent(td):
"""BUG-2 回归:废弃别名取不到有效财报数据时应返回 ``b""``,而非 0~1 字节空壳。"""
import warnings
async def empty_get_file(name: str) -> bytes:
return b"\x00"
with mock.patch.object(td, "get_file", new=empty_get_file), warnings.catch_warnings():
warnings.simplefilter("ignore", DeprecationWarning)
got = await td.get_financial_records("gpcw20260331.zip")
assert got == b""
async def test_sampling_derives_from_tick_chart(td):
"""BUG-1 回归:A股 ``sampling=True`` 必须由分时(0x122D)派生。
``MacChartSamplingCmd``(0x254D) 是 **EX 协议**命令,7709 主机对它一律不响应
(实测 3 台各 10s 超时,叠加连接池重试 ≈24s 才报错)。两条路径的 mock 数据刻意
不同,以便从结果区分实际走的是哪条命令。
"""
# A股:得到分时派生值(10.0/10.1/10.2),而非 0x254D 的 99.0/98.0
a_share = await td.get_minutes("sh600000", sampling=True)
a_share_hist = await td.get_minutes("sh600000", date=20260811, sampling=True)
assert [b.price for b in a_share] == [10.0, 10.1, 10.2]
assert [b.price for b in a_share_hist] == [10.0, 10.1, 10.2]
assert all(b.vol == 0.0 and b.avg_price == 0 for b in a_share), "采样点无量/均价"
assert [b.fields["i"] for b in a_share] == [0.0, 1.0, 2.0], "点位序号在 fields['i']"
# EX:仍走 0x254D
ex = await td.get_minutes("hk00700", sampling=True)
assert [b.price for b in ex] == [99.0, 98.0]
# --------------------------------------------------------------------------- #
# 七、废弃别名(33 个)
# --------------------------------------------------------------------------- #
@@ -544,7 +616,11 @@ async def test_aliases_files(td):
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"
with mock.patch.object(td, "get_file",
new=mock.AsyncMock(
return_value=_make_financial_dat())):
assert await td.get_financial_records(
"gpcw20260331.zip") == _make_financial_dat()
assert isinstance(await td.get_company_info_category(1, "600000"), list)
assert isinstance(await td.get_company_info_content(
1, "600000", "f.txt"), str)
@@ -579,7 +655,7 @@ async def test_aliases_goods(td):
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 await td.get_goods_chart_sampling(31, "00700") == [99.0, 98.0]
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)
+140 -2
View File
@@ -6,14 +6,19 @@ from __future__ import annotations
import io
import struct
import unittest.mock as mock
import zipfile
from unittest import mock
import pytest
from pytdxdata.api import TdxData
from pytdxdata.codec.block import infer_block_category, parse_block_dat
from pytdxdata.codec.financial import parse_financial_dat, parse_financial_file_list
from pytdxdata.codec.financial import (
extract_gpcw_dat,
looks_like_gpcw_dat,
parse_financial_dat,
parse_financial_file_list,
)
from pytdxdata.codec.industry import parse_tdxhy_cfg
from pytdxdata.models import FinancialFileInfo, FinancialRecord, IndustryInfo, TdxBlock
@@ -317,3 +322,136 @@ async def test_api_get_financial_records_parsed_no_date_in_name():
new=mock.AsyncMock(return_value=zip_bytes)):
recs = await td.get_financial_records_parsed("gpcw.zip")
assert recs[0].report_date == 20260331
# --------------------------------------------------------------------------- #
# looks_like_gpcw_dat / extract_gpcw_dat(BUG-2 修复的判据层)
# --------------------------------------------------------------------------- #
def test_looks_like_gpcw_dat_accepts_real_dat():
assert looks_like_gpcw_dat(_valid_two_record_dat()) is True
def test_looks_like_gpcw_dat_rejects_short_shell():
"""服务器对不存在的文件名回的空壳(0~1 字节)必须判否。"""
assert looks_like_gpcw_dat(b"") is False
assert looks_like_gpcw_dat(b"\x00") is False
assert looks_like_gpcw_dat(b"abcd") is False
def test_looks_like_gpcw_dat_rejects_zero_header():
"""长度够但 header 全零(max_count=0 / report_size=0)也要判否。"""
assert looks_like_gpcw_dat(b"\x00" * 64) is False
def test_looks_like_gpcw_dat_rejects_report_size_not_multiple_of_4():
data = _make_dat_raw([(b"600000", 1, 31)], struct.pack("<2f", 1.0, 2.0),
report_size=6)
assert looks_like_gpcw_dat(data) is False
def test_looks_like_gpcw_dat_rejects_truncated_index():
"""header 声称的条目数超出实际长度 -> 判否。"""
data = _make_dat_raw([(b"600000", 1, 31)], struct.pack("<2f", 1.0, 2.0),
max_count=100)
assert looks_like_gpcw_dat(data) is False
def test_extract_gpcw_dat_from_uncompressed():
dat = _valid_two_record_dat()
assert extract_gpcw_dat(dat) == dat
def test_extract_gpcw_dat_from_zip():
dat = _valid_two_record_dat()
assert extract_gpcw_dat(_make_financial_zip(dat)) == dat
def test_extract_gpcw_dat_empty_and_garbage():
assert extract_gpcw_dat(b"") == b""
assert extract_gpcw_dat(b"\x00") == b""
assert extract_gpcw_dat(b"not a financial file") == b""
def test_extract_gpcw_dat_zip_without_dat_member():
assert extract_gpcw_dat(_make_financial_zip(b"x", inner_name="readme.txt")) == b""
def test_extract_gpcw_dat_zip_with_invalid_inner_dat():
"""zip 里虽有 .dat,但内容不是有效财报数据 -> 空。"""
assert extract_gpcw_dat(_make_financial_zip(b"\x00" * 4)) == b""
def test_extract_gpcw_dat_broken_zip():
"""以 PK 开头但不是合法 zip -> 空,不抛异常。"""
assert extract_gpcw_dat(b"PK\x03\x04broken-not-a-zip") == b""
# --------------------------------------------------------------------------- #
# TdxData._fetch_financial_dat 候选回退(BUG-2 回归)
# --------------------------------------------------------------------------- #
@pytest.mark.asyncio
async def test_fetch_financial_dat_falls_back_to_uncompressed_dat():
"""索引名 ``gpcw*.zip`` 取不到时,必须回退到服务器实际的 ``tdxfin/*.dat``。"""
td = _new_tdxdata()
dat = _valid_two_record_dat()
seen: list[str] = []
async def fake(name: str) -> bytes:
seen.append(name)
if name == "tdxfin/gpcw20260331.dat":
return dat
if name == "gpcw20260331.zip":
return b"\x00" # 裸名 -> MAC 路由 -> 1 字节空壳
return b"" # 带前缀的 .zip 不存在
with mock.patch.object(td, "get_file", new=fake):
got = await td._fetch_financial_dat("gpcw20260331.zip")
assert got == dat
assert seen == ["tdxfin/gpcw20260331.zip", "tdxfin/gpcw20260331.dat"]
@pytest.mark.asyncio
async def test_fetch_financial_dat_prefers_declared_zip_when_present():
"""服务器若恢复提供 .zip,应优先用索引声明的那个名字。"""
td = _new_tdxdata()
dat = _valid_two_record_dat()
seen: list[str] = []
async def fake(name: str) -> bytes:
seen.append(name)
return _make_financial_zip(dat)
with mock.patch.object(td, "get_file", new=fake):
got = await td._fetch_financial_dat("tdxfin/gpcw20260331.zip")
assert got == dat
assert seen == ["tdxfin/gpcw20260331.zip"]
@pytest.mark.asyncio
async def test_fetch_financial_dat_skips_raising_candidate():
"""某个候选取回时抛异常,不应中断,继续试后面的候选。"""
td = _new_tdxdata()
dat = _valid_two_record_dat()
async def fake(name: str) -> bytes:
if name.endswith(".zip"):
raise ConnectionError("模拟网络错误")
return dat
with mock.patch.object(td, "get_file", new=fake):
assert await td._fetch_financial_dat("gpcw20260331.zip") == dat
@pytest.mark.asyncio
async def test_fetch_financial_dat_all_candidates_fail_returns_empty():
td = _new_tdxdata()
async def fake(name: str) -> bytes:
return b""
with mock.patch.object(td, "get_file", new=fake):
assert await td._fetch_financial_dat("gpcw20260331.zip") == b""
+365
View File
@@ -0,0 +1,365 @@
"""当日测速缓存单元测试(注入假探针与假日期,不连真实网络)
覆盖点:
- 当日首次启动测一次;当天已有缓存则**不刷新**(探针一次都不发起)
- 跨日 / 缓存损坏 / 版本不符 → 重新测速
- 结果按实测延迟升序被 config 采用
- **绝不改写包内 servers.json**,缓存落在用户级缓存目录
- 全部不可达 → 不写缓存(下次启动重试)
- 并发调用只真正测一次(单飞)
- 非法主机名(测试 mock 混入的 "s1" 等)被挡在测速之外
- 连接池 start() 不阻塞、close() 会取消后台测速
"""
from __future__ import annotations
import asyncio
import json
import time
from datetime import date, timedelta
from pathlib import Path
import pytest
from pytdxdata import config
from pytdxdata.pool.probe_cache import ProbeCache
TODAY = date.today().isoformat()
YESTERDAY = (date.today() - timedelta(days=1)).isoformat()
PROTOS = ("standard", "mac", "ex")
@pytest.fixture(autouse=True)
def isolated_cache(tmp_path, monkeypatch):
"""把用户级缓存目录指到临时目录,并复位所有相关环境变量。"""
monkeypatch.setenv("PYPYTDX_DATA_CACHE_DIR", str(tmp_path))
monkeypatch.delenv("PYPYTDX_DATA_DISABLE_PROBE", raising=False)
for var in ("PYPYTDX_DATA_STANDARD_HOSTS", "PYPYTDX_DATA_MAC_HOSTS",
"PYPYTDX_DATA_EX_HOSTS"):
monkeypatch.delenv(var, raising=False)
return tmp_path
def fake_probers(latencies: dict[str, dict[str, float | None]], calls: list):
"""构造假探针;latencies = {协议: {主机: 延迟或 None}}。"""
def _make(protocol: str):
async def _probe(host: str, timeout: float) -> float | None:
calls.append((protocol, host))
return latencies.get(protocol, {}).get(host)
return _probe
return {p: _make(p) for p in PROTOS}
def patch_candidates(monkeypatch, mapping: dict[str, list[str]]) -> None:
"""把"全量候选"换成受控清单,避免依赖真实服务器清单。"""
monkeypatch.setattr("pytdxdata.pool.probe_cache.all_probe_candidates",
lambda: mapping)
def write_cache(path: Path, day: str, results: dict, version: int = 1) -> None:
path.write_text(json.dumps({"version": version, "date": day, "results": results}),
encoding="utf-8")
# ---------- 是否该测速 ----------
def test_needs_probe_when_no_cache(tmp_path):
pc = ProbeCache(tmp_path / "c.json", today_fn=lambda: TODAY)
assert pc.needs_probe_today() is True
assert pc.read_cache() is None
def test_needs_probe_false_for_today_cache(tmp_path):
cache = tmp_path / "c.json"
write_cache(cache, TODAY, {"1.1.1.1": {"standard": 0.05}})
pc = ProbeCache(cache, today_fn=lambda: TODAY)
assert pc.needs_probe_today() is False
def test_stale_cache_needs_probe(tmp_path):
cache = tmp_path / "c.json"
write_cache(cache, YESTERDAY, {"1.1.1.1": {"standard": 0.05}})
pc = ProbeCache(cache, today_fn=lambda: TODAY)
assert pc.needs_probe_today() is True
def test_version_mismatch_needs_probe(tmp_path):
cache = tmp_path / "c.json"
write_cache(cache, TODAY, {"1.1.1.1": {"standard": 0.05}}, version=999)
pc = ProbeCache(cache, today_fn=lambda: TODAY)
assert pc.needs_probe_today() is True
@pytest.mark.parametrize("content", ["{not json", "[]", '{"version":1}', ""])
def test_broken_cache_is_ignored_not_crash(tmp_path, content):
cache = tmp_path / "c.json"
cache.write_text(content, encoding="utf-8")
pc = ProbeCache(cache, today_fn=lambda: TODAY)
assert pc.read_cache() is None
assert pc.needs_probe_today() is True
# ---------- 核心行为:当天已有缓存就不刷新 ----------
async def test_today_cache_is_not_refreshed(tmp_path, monkeypatch):
cache = tmp_path / "c.json"
write_cache(cache, TODAY, {"1.1.1.1": {"standard": 0.05}})
before = cache.read_text(encoding="utf-8")
calls: list = []
patch_candidates(monkeypatch, {"standard": ["1.1.1.1"], "mac": [], "ex": []})
pc = ProbeCache(cache, probers=fake_probers({}, calls), today_fn=lambda: TODAY)
await pc.ensure_probe()
assert calls == [] # 未发起任何测速
assert cache.read_text(encoding="utf-8") == before # 缓存内容原封不动
async def test_stale_cache_is_refreshed(tmp_path, monkeypatch):
cache = tmp_path / "c.json"
write_cache(cache, YESTERDAY, {"9.9.9.9": {"standard": 9.0}})
calls: list = []
patch_candidates(monkeypatch, {"standard": ["1.1.1.1"], "mac": [], "ex": []})
pc = ProbeCache(cache,
probers=fake_probers({"standard": {"1.1.1.1": 0.02}}, calls),
today_fn=lambda: TODAY)
await pc.ensure_probe()
assert calls == [("standard", "1.1.1.1")]
data = json.loads(cache.read_text(encoding="utf-8"))
assert data["date"] == TODAY and data["version"] == config.PROBE_CACHE_VERSION
assert data["results"] == {"1.1.1.1": {"standard": 0.02}}
assert data["hosts"]["standard"] == ["1.1.1.1"]
assert "9.9.9.9" not in data["results"] # 旧结果被整体替换,不残留
# ---------- 缓存写入 ----------
async def test_write_is_atomic_and_leaves_no_tmp(tmp_path, monkeypatch):
cache = tmp_path / "sub" / "c.json" # 目录不存在也要能建
patch_candidates(monkeypatch, {"standard": ["1.1.1.1"], "mac": [], "ex": []})
pc = ProbeCache(cache,
probers=fake_probers({"standard": {"1.1.1.1": 0.03}}, []),
today_fn=lambda: TODAY)
await pc.ensure_probe()
assert cache.exists()
assert list(cache.parent.glob("*.tmp*")) == []
assert json.loads(cache.read_text(encoding="utf-8"))["probed_at"]
async def test_all_unreachable_writes_nothing(tmp_path, monkeypatch):
cache = tmp_path / "c.json"
patch_candidates(monkeypatch, {"standard": ["1.1.1.1"], "mac": [], "ex": []})
pc = ProbeCache(cache, probers=fake_probers({}, []), today_fn=lambda: TODAY)
await pc.ensure_probe()
assert not cache.exists() # 不把"全挂"缓存一整天
assert pc.needs_probe_today() is True
async def test_never_touches_package_servers_json(tmp_path, monkeypatch):
"""最关键的一条:测速**绝不能**改写随包分发的 servers.json。"""
servers_json = config._SERVERS_FILE
before_bytes = servers_json.read_bytes()
before_mtime = servers_json.stat().st_mtime_ns
patch_candidates(monkeypatch, {"standard": ["1.1.1.1"], "mac": [], "ex": []})
pc = ProbeCache(probers=fake_probers({"standard": {"1.1.1.1": 0.04}}, []),
today_fn=lambda: TODAY)
await pc.ensure_probe()
assert servers_json.read_bytes() == before_bytes
assert servers_json.stat().st_mtime_ns == before_mtime
assert pc.cache_file() == tmp_path / "hosts-today.json" # 落在用户缓存目录
assert Path(config.probe_cache_file()).parent == tmp_path
async def test_results_are_recorded_per_protocol(tmp_path, monkeypatch):
cache = tmp_path / "c.json"
patch_candidates(monkeypatch, {
"standard": ["1.1.1.1", "2.2.2.2"],
"mac": ["1.1.1.1", "2.2.2.2"],
"ex": ["3.3.3.3"],
})
lats = {"standard": {"1.1.1.1": 0.30, "2.2.2.2": 0.10},
"mac": {"1.1.1.1": 0.20}, # 2.2.2.2 的 mac 故意不给 → 应记为 None
"ex": {"3.3.3.3": 0.05}}
pc = ProbeCache(cache, probers=fake_probers(lats, []), today_fn=lambda: TODAY)
await pc.ensure_probe()
data = json.loads(cache.read_text(encoding="utf-8"))
assert data["hosts"]["standard"] == ["2.2.2.2", "1.1.1.1"] # 按延迟升序
assert data["hosts"]["mac"] == ["1.1.1.1"] # 不可达的 2.2.2.2 被排除
assert data["hosts"]["ex"] == ["3.3.3.3"]
# 2.2.2.2 的 mac 探针返回 None,也要如实记录(便于事后诊断)
assert data["results"]["2.2.2.2"]["mac"] is None
# ---------- 单飞 / 开关 / 脏数据 ----------
async def test_concurrent_ensure_probe_runs_once(tmp_path, monkeypatch):
patch_candidates(monkeypatch, {"standard": ["1.1.1.1", "2.2.2.2"], "mac": [], "ex": []})
calls: list = []
pc = ProbeCache(tmp_path / "c.json",
probers=fake_probers({"standard": {"1.1.1.1": 0.01,
"2.2.2.2": 0.02}}, calls),
today_fn=lambda: TODAY)
await asyncio.gather(pc.ensure_probe(), pc.ensure_probe(), pc.ensure_probe())
assert sorted(calls) == [("standard", "1.1.1.1"), ("standard", "2.2.2.2")]
async def test_disabled_env_skips_everything(tmp_path, monkeypatch):
monkeypatch.setenv("PYPYTDX_DATA_DISABLE_PROBE", "1")
calls: list = []
patch_candidates(monkeypatch, {"standard": ["1.1.1.1"], "mac": [], "ex": []})
pc = ProbeCache(tmp_path / "c.json",
probers=fake_probers({"standard": {"1.1.1.1": 0.01}}, calls),
today_fn=lambda: TODAY)
assert pc.needs_probe_today() is False
await pc.ensure_probe()
assert calls == []
assert not (tmp_path / "c.json").exists()
async def test_illegal_hosts_are_filtered_out(tmp_path, monkeypatch):
"""测试 mock 常传入 "s1"/"m1" 这类伪主机名,必须挡在缓存之外。"""
patch_candidates(monkeypatch, {"standard": [], "mac": [], "ex": []})
calls: list = []
pc = ProbeCache(tmp_path / "c.json",
probers=fake_probers({"standard": {"1.1.1.1": 0.01}}, calls),
today_fn=lambda: TODAY)
await pc.ensure_probe(["s1", "m1", "1.1.1.1", ""])
assert calls == [("standard", "1.1.1.1")]
data = json.loads((tmp_path / "c.json").read_text(encoding="utf-8"))
assert "s1" not in data["results"] and "m1" not in data["results"]
async def test_reset_allows_recheck(tmp_path, monkeypatch):
patch_candidates(monkeypatch, {"standard": ["1.1.1.1"], "mac": [], "ex": []})
calls: list = []
pc = ProbeCache(tmp_path / "c.json",
probers=fake_probers({"standard": {"1.1.1.1": 0.01}}, calls),
today_fn=lambda: TODAY)
await pc.ensure_probe()
await pc.ensure_probe()
assert len(calls) == 1 # 第二次被单飞挡掉
pc.reset()
await pc.ensure_probe()
assert len(calls) == 1 # 重置后当天已有缓存,仍不重测
# ---------- config 侧:采用顺序与兜底 ----------
def test_config_getters_prefer_cache_and_order_by_latency(tmp_path, monkeypatch):
monkeypatch.setenv("PYPYTDX_DATA_CACHE_DIR", str(tmp_path))
(tmp_path / "hosts-today.json").write_text(json.dumps({
"version": config.PROBE_CACHE_VERSION, "date": TODAY,
"results": {
"3.3.3.3": {"standard": 0.9},
"1.1.1.1": {"standard": 0.05},
"2.2.2.2": {"standard": 0.4, "mac": 0.1},
"9.9.9.9": {"ex": 0.2},
},
}), encoding="utf-8")
assert config.get_standard_hosts() == ["1.1.1.1", "2.2.2.2", "3.3.3.3"]
assert config.get_mac_hosts() == ["2.2.2.2"]
assert config.get_ex_hosts() == ["9.9.9.9"]
def test_config_getters_fall_back_without_cache(tmp_path, monkeypatch):
monkeypatch.setenv("PYPYTDX_DATA_CACHE_DIR", str(tmp_path))
assert config.get_standard_hosts() == config._load_ok_hosts("standard", fast_only=True)
assert config.get_mac_hosts() == config._load_ok_hosts("mac", fast_only=True)
assert config.get_ex_hosts() == config._load_ok_hosts("ex")
def test_env_override_beats_cache(tmp_path, monkeypatch):
monkeypatch.setenv("PYPYTDX_DATA_CACHE_DIR", str(tmp_path))
(tmp_path / "hosts-today.json").write_text(json.dumps({
"version": config.PROBE_CACHE_VERSION, "date": TODAY,
"results": {"1.1.1.1": {"standard": 0.05}},
}), encoding="utf-8")
monkeypatch.setenv("PYPYTDX_DATA_STANDARD_HOSTS", "8.8.8.8")
assert config.get_standard_hosts() == ["8.8.8.8"]
def test_all_probe_candidates_covers_full_set_not_filtered():
cand = config.all_probe_candidates()
assert set(config.STANDARD_HOSTS) <= set(cand["standard"])
assert set(config.MAC_HOSTS) <= set(cand["mac"])
assert set(config.EX_HOSTS) <= set(cand["ex"])
assert "117.34.114.17" in cand["standard"] # 未申报 MAC 的节点也要被测到
assert "s1" not in cand["standard"] # 包内清单里的脏数据被挡
@pytest.mark.parametrize(("host", "expected"), [
("1.2.3.4", True),
("117.34.114.17", True),
("a.b", True),
("good-host.com", True),
("s1", False),
("m1", False),
("", False),
(" ", False),
("-bad.com", False),
("bad-.com", False),
("has space.com", False),
(123, False),
(None, False),
])
def test_is_valid_host(host, expected):
assert config.is_valid_host(host) is expected
# ---------- 连接池集成 ----------
async def test_pool_start_does_not_block_and_close_cancels_probe(monkeypatch):
from pytdxdata.pool import pool as pool_mod
cancel_seen = asyncio.Event()
created: list[asyncio.Task] = []
async def _hang(hosts=None):
try:
await asyncio.sleep(30) # 模拟耗时测速
except asyncio.CancelledError:
cancel_seen.set()
raise
def _fake_schedule(hosts=None):
task = asyncio.create_task(_hang())
created.append(task)
return task
monkeypatch.setattr(pool_mod, "schedule_probe", _fake_schedule)
p = pool_mod.DynamicPool([], min_size=1, max_size=1)
t0 = time.monotonic()
await p.start()
assert time.monotonic() - t0 < 1.0 # start() 不等测速
assert p._probe_task is created[0]
await asyncio.sleep(0) # 让测速任务真正跑起来再关闭
await p.close()
assert p._probe_task is None
assert created[0].cancelled()
assert cancel_seen.is_set()
async def test_pool_auto_probe_false_schedules_nothing(monkeypatch):
from pytdxdata.pool import pool as pool_mod
def _boom(hosts=None): # pragma: no cover - 不应被调用
raise AssertionError("auto_probe=False 时不应调度测速")
monkeypatch.setattr(pool_mod, "schedule_probe", _boom)
p = pool_mod.DynamicPool([], min_size=1, max_size=1, auto_probe=False)
await p.start()
assert p._probe_task is None
await p.close()
Generated
+1 -1
View File
@@ -535,7 +535,7 @@ wheels = [
[[package]]
name = "pytdxdata"
version = "0.6.0"
version = "0.6.1"
source = { editable = "." }
[package.optional-dependencies]