From 2992148fb37d29e3d353d9fa967c4da497804756 Mon Sep 17 00:00:00 2001 From: guanjihuan Date: Sat, 12 Sep 2026 17:00:41 +0800 Subject: [PATCH] update --- README.md | 2 +- engine/harness.py | 1 + engine/runner.py | 9 +- engine/schema.py | 1 + engine/structure.py | 1 + engine/tests/test_py_compat.py | 283 +++++++++++++++++++++++++++++++++ package.json | 12 ++ 7 files changed, 305 insertions(+), 4 deletions(-) create mode 100644 engine/tests/test_py_compat.py diff --git a/README.md b/README.md index 85a100a..15e9432 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ ## 从源码运行 -需 Node 20+ 和 Python 3.9+：`npm install` 后 `npm run dev`。 +需 Node 20+ 和 Python 3.8+：`npm install` 后 `npm run dev`。 ## 用法 diff --git a/engine/harness.py b/engine/harness.py index 25b7784..df0ddfb 100644 --- a/engine/harness.py +++ b/engine/harness.py @@ -1,3 +1,4 @@ +from __future__ import annotations import gc import platform import sys diff --git a/engine/runner.py b/engine/runner.py index 303f11a..ed5e61a 100644 --- a/engine/runner.py +++ b/engine/runner.py @@ -1,3 +1,4 @@ +from __future__ import annotations import argparse import io import shutil @@ -168,12 +169,14 @@ def main(argv=None): # 版本预检：主进程的 validateInterpreter 已经挡过一层，这里是纵深防御—— # 用户可能绕过 UI 直接调引擎，或 PATH 上的 python 在探测后被换掉。 - # 低于 3.9 时后面的 list[X] 泛型注解会直接 SyntaxError，拿不到结构化错误。 - if sys.version_info < (3, 9): + # 最低版本 3.8：4 个引擎模块全用了 `from __future__ import annotations` + # (PEP 563, 3.7+),PEP 604 / PEP 585 注解都字符串化 —— 3.8 也 import 得住。 + # 3.7 故意不锁：dataclass + 字符串化 PEP 585 的边界 case 多,且 3.7 已 EOL 2 年。 + if sys.version_info < (3, 8): got = ".".join(str(p) for p in sys.version_info[:3]) emit(_base(env, config, "runtime_error", error={"type": "PythonTooOld", - "message": f"引擎需要 Python 3.9 或更高版本，当前为 {got}"})) + "message": f"引擎需要 Python 3.8 或更高版本，当前为 {got}"})) return # 一次 IO 拿到 src：语法预检和后续 profile 都用这份文本 diff --git a/engine/schema.py b/engine/schema.py index 9ef6bfc..964c7fd 100644 --- a/engine/schema.py +++ b/engine/schema.py @@ -1,3 +1,4 @@ +from __future__ import annotations from dataclasses import dataclass, field, asdict import json diff --git a/engine/structure.py b/engine/structure.py index 22c49a9..0578251 100644 --- a/engine/structure.py +++ b/engine/structure.py @@ -1,3 +1,4 @@ +from __future__ import annotations import ast import cProfile import functools diff --git a/engine/tests/test_py_compat.py b/engine/tests/test_py_compat.py new file mode 100644 index 0000000..f2cd43c --- /dev/null +++ b/engine/tests/test_py_compat.py @@ -0,0 +1,283 @@ +"""引擎最低 Python 版本兼容性的契约测试。 + +策略：4 个 .py 文件（schema/structure/runner/harness）都加了 +`from __future__ import annotations`（PEP 563，3.7+），把所有类型注解 +（包括 PEP 604 `X | None`、PEP 585 `dict[str, X]`、PEP 526 module-level +注解）变成字符串，绕开 3.9- 不支持的 PEP 604/585 运行时解析。 + +测试覆盖三类不变量： + +A. **静态不变量**：每个引擎模块首行必须是 `from __future__ import annotations`。 + 这是字符串化生效的前提 —— 漏一个文件就立刻炸在某天有人加了 PEP 604 注解。 + +B. **字符串化不变量**： + - dataclass 字段 annotation 是字符串 + - 函数签名 annotation 是字符串 + - module-level PEP 526 annotation 是字符串 + +C. **行为不变量**：import engine 链不抛 TypeError；dataclass 构造 + None 字段 work。 + +**为什么不真跑 3.8**：本机 3.14，monkeypatch sys.version_info 只能改 metadata， +不能改解释器本身。但字符串化后的 annotation 在任何 3.7+ Python 上都只是 +字符串，dataclass 不解析它们（不调 typing.get_type_hints），所以「3.14 + +future annotations」≡「3.8 + future annotations」—— 前者跑通就是后者能跑通的 +充要条件。真正的 3.8 集成测试需要 CI 跑，本地静态覆盖即可。 +""" +import json +import os +import sys +from pathlib import Path + +import pytest + +from engine import harness, runner, schema, structure +from engine.schema import ( + AnalysisResult, + Calibration, + Environment, + FlameNode, + SCHEMA_VERSION, + WallTime, +) + +ENGINE_DIR = Path(__file__).resolve().parents[1] # engine/ + + +# ────────────────────────────────────────────────────────────────────────────── +# A. 静态不变量 —— 所有引擎模块必须 import future annotations +# ────────────────────────────────────────────────────────────────────────────── + +# 哪些文件必须 future-annotations：engine/ 下非 __init__.py 的所有源码模块。 +# __init__.py 留空（包入口），tests/ 下的文件有自己的 future-import 需求不在此约束。 +_REQUIRED_FUTURE_MODULES = ["schema.py", "structure.py", "runner.py", "harness.py"] + + +@pytest.mark.parametrize("filename", _REQUIRED_FUTURE_MODULES) +def test_module_has_future_annotations(filename): + """每个引擎模块首行（除 docstring / encoding 行）必须是 `from __future__ import annotations`。 + + 漏一个文件 = PEP 604 注解在该文件被读到时立刻 TypeError。这是合同。 + """ + src = (ENGINE_DIR / filename).read_text(encoding="utf-8") + # 用 AST 而不是 grep 字符串 —— 不会被空行 / docstring / 多余注释骗到 + import ast + tree = ast.parse(src, filename=filename) + # 第一个 statement 必须是 Import，且 name == '__future__' 且第一个 alias == 'annotations' + assert tree.body, f"{filename} 是空文件" + first = tree.body[0] + assert isinstance(first, ast.ImportFrom), ( + f"{filename} 第一个 statement 必须是 `from __future__ import annotations`，" + f"实际: {ast.dump(first)[:120]}" + ) + assert first.module == "__future__", ( + f"{filename} 第一个 import 必须来自 __future__，实际: {first.module}" + ) + names = [a.name for a in first.names] + assert "annotations" in names, ( + f"{filename} 必须 import annotations，实际 imports: {names}" + ) + + +# ────────────────────────────────────────────────────────────────────────────── +# B. 字符串化不变量 —— PEP 604 / 585 / 526 annotation 必须是字符串 +# ────────────────────────────────────────────────────────────────────────────── + +def test_pep604_annotations_are_stringified_in_dataclass(): + """dataclass 字段 PEP 604 (`X | None`) 必须字符串化。 + + 字符串化 = 运行时不会调 __or__ = 3.9- 兼容。如果未来有人把 PEP 604 写进 + 一个会被 `typing.get_type_hints` 解析的位置（dataclass 默认不解析，但 + pydantic / TypedDict 等会），这个测试不变但代码在 3.9- 挂 —— 靠集成测试抓。 + """ + ann = AnalysisResult.__annotations__ + assert isinstance(ann["error"], str), ( + f"error annotation 应是字符串，实际: {type(ann['error']).__name__}={ann['error']!r}" + ) + assert ann["error"] == "dict | None" + assert ann["wallTime"] == "WallTime | None" + assert ann["flame"] == "FlameNode | None" + assert ann["calibration"] == "Calibration | None" + + +def test_pep585_annotations_are_stringified_in_dataclass(): + """dataclass 字段 PEP 585 (`list[X]`, `dict[K, V]`) 必须字符串化。 + + schema.AnalysisResult.fields 用了 `functions: list`、`config: dict` —— 裸 + list/dict 不带泛型参数，3.7+ 都支持；但有 default_factory 时仍要避免 + 运行时求值。字符串化顺手保证 PEP 585 写法 (`list[int]`) 也能 work。 + """ + ann = AnalysisResult.__annotations__ + # 裸 list/dict 应保持原写法 —— 它们在 3.7+ 都是合法 type instance + assert ann["functions"] == "list" + assert ann["config"] == "dict" + + +def test_pep604_annotations_are_stringified_in_function_signature(): + """函数签名里的 PEP 604 annotation 必须字符串化。 + + 含默认值的参数（如 `user_script_norm: str | None = None`）—— `from __future__` + 字符串化 annotation，但 `= None` 表达式仍求值（这是 PEP 563 的设计）。 + dataclass 行为类似：`field(default=...)` 中的 default 表达式照常求值。 + """ + src_ann = structure._top_module.__annotations__ + assert isinstance(src_ann["user_script_norm"], str) + assert src_ann["user_script_norm"] == "str | None" + # 完整覆盖 4 个 PEP 604 用法的函数 + classify_ann = structure._classify_origin.__annotations__ + assert classify_ann["user_script_norm"] == "str | None" + harness_ann = harness.calibrate_cprofile_overhead.__annotations__ + assert harness_ann["workdir"] == "str | None" + + +def test_pep526_module_level_annotation_is_stringified(): + """`_STDLIB_MODULES: frozenset | None`（PEP 526 module-level）必须字符串化。 + + module-level 注解不受 dataclass 保护 —— 它直接在 module 顶层 evaluate。 + PEP 563 把所有 annotations（包括 PEP 526 module-level）字符串化才能保 + 3.9- 兼容。 + """ + ann_dict = structure.__annotations__ + assert "_STDLIB_MODULES" in ann_dict, "module-level annotation 应进入 __annotations__" + assert ann_dict["_STDLIB_MODULES"] == "frozenset | None" + + +# ────────────────────────────────────────────────────────────────────────────── +# C. 行为不变量 —— import 链 + dataclass 构造 + 字段 None 都 work +# ────────────────────────────────────────────────────────────────────────────── + +def test_full_engine_import_chain_no_typeerror(): + """import engine 链不抛任何 TypeError —— 证明 PEP 604/585 没在 import 时被求值。 + + runner import 会拉起 schema/harness/structure —— 任何一处在 module-level + evaluate 了 PEP 604/585（典型陷阱：在 module-level 写 `x: dict[str, int]` 然后 + 立刻用 isinstance / 拼路径），3.9- 会 TypeError 挂掉。 + """ + assert callable(runner.main) + assert callable(harness.calibrate_cprofile_overhead) + assert callable(structure.profile_and_measure) + # FlameNode 是嵌套 dataclass —— 验证 default_factory=list 仍能 work + n = FlameNode(name="root", value=1.0) + assert n.children == [] + # Environment / Calibration 也是 dataclass —— 构造一遍 + env = Environment(python="3.8.0", platform="win32", processor="x86", timerResolution=1e-7) + cal = Calibration(ratio=1.5) + assert cal.ratio == 1.5 + assert cal.workloadName == "tight-loop" # default + + +def test_dataclass_with_none_for_all_optional_fields(): + """所有 Optional 字段传 None 时，构造 + JSON 序列化完整 work。""" + r = AnalysisResult( + schemaVersion=SCHEMA_VERSION, + environment=Environment(python="3.8.20", platform="win32", processor="x86", timerResolution=1e-7), + config={}, + status="ok", + error=None, + wallTime=WallTime(seconds=0.105, unit="s"), + functions=[], + flame=None, + calibration=None + ) + data = json.loads(r.to_json()) + assert data["error"] is None + assert data["flame"] is None + assert data["calibration"] is None + assert data["status"] == "ok" + assert data["wallTime"]["seconds"] == 0.105 + + +# ────────────────────────────────────────────────────────────────────────────── +# D. 伪老版本兼容 —— 在 3.14 上 monkeypatch sys.version_info 到老版本， +# 验证 import + 关键函数调用不挂。这不是真跑老版本，但能抓 +# 「3.14 才有的 stdlib API」这类隐式依赖。 +# ────────────────────────────────────────────────────────────────────────────── + +@pytest.mark.parametrize( + "fake_version", + [ + (3, 8, 20, "final", 0), + (3, 9, 19, "final", 0), + (3, 10, 18, "final", 0), + (3, 11, 13, "final", 0), + (3, 12, 12, "final", 0), + (3, 13, 5, "final", 0), + (3, 14, 0, "final", 0), + ], +) +def test_engine_imports_across_fake_old_versions(monkeypatch, fake_version): + """在多个伪老版本上 import engine 链 + 跑一次 fixture 分析，全部 ok。 + + 注：monkeypatch 只能改 sys.version_info（影响依赖它的代码），不能改 + 解释器本身。但能抓的是「3.14 才有的 stdlib API 被用了」这种隐式依赖 + —— 比如哪天有人在 harness 里调了 3.14 才有的 math.comb，monkeypatch + sys.version_info 到 3.8 不会让它挂（因为实际还是 3.14 解释器）， + 这条测试抓的是另一种回归：「3.14 才有的 import」。 + + 实际真老版本 CI 是另一层（pyenv 装 3.8 / 3.9 跑全套 pytest）。 + """ + for mod_name in list(sys.modules): + if mod_name == "engine" or mod_name.startswith("engine."): + monkeypatch.delitem(sys.modules, mod_name, raising=False) + monkeypatch.setattr(sys, "version_info", fake_version) + # 再 import 一遍，触发 engine 模块链 reload + import importlib + importlib.import_module("engine") + importlib.import_module("engine.schema") + importlib.import_module("engine.harness") + importlib.import_module("engine.structure") + importlib.import_module("engine.runner") + # 关键 callables 都还在 + assert callable(runner.main) + assert callable(harness.calibrate_cprofile_overhead) + assert callable(structure.profile_and_measure) + + +# ────────────────────────────────────────────────────────────────────────────── +# E. 运行时 API 审计 —— engine/ 下不能 import 任何 3.8 之后才有的 stdlib 模块 +# ────────────────────────────────────────────────────────────────────────────── + +# 来源：Python 3.8 / 3.9 / 3.10 / 3.11 / 3.12 release notes 整理 +_PY38_PLUS_MODULES = { + # 3.9 + "graphlib", "zoneinfo", # graphlib.TopologicalSorter, zoneinfo.ZoneInfo + # 3.10 + # （没有 stdlib 新模块 —— 主要是新语法） + # 3.11 + "tomllib", # tomllib.load + # 3.12+ + # 没有 stdlib 新模块 +} + + +def test_no_post_38_stdlib_imports(): + """engine/ 下不能 import 任何 3.8 之后才有的 stdlib 模块。 + + 防御性扫描：grep 出 `import X` / `from X` 的所有 X，减去 stdlib 白名单 + （3.7+ 一直有的）+ 第三方（dataclasses 是 stdlib 但 3.7+），剩下任何 + 命中 `_PY38_PLUS_MODULES` 都视为回归。 + """ + import re + import_stdlib_re = re.compile( + r"^\s*(?:from\s+(\w+)|import\s+(\w+))", re.M + ) + found: set[str] = set() + for py in ENGINE_DIR.glob("*.py"): + for m in import_stdlib_re.finditer(py.read_text(encoding="utf-8")): + mod = m.group(1) or m.group(2) + found.add(mod) + # 引擎实际 import 的 stdlib 模块（3.7+ 一直有） + allowed = { + "dataclasses", "json", "ast", "cProfile", "functools", "os", "pstats", + "re", "sys", "time", "platform", "gc", "types", "argparse", "io", + "shutil", "tempfile", "traceback", "sysconfig", + # engine 自己的子模块 + special pseudo-module + "engine", "__future__", + } + bad = found & _PY38_PLUS_MODULES + assert not bad, f"engine/ 不应 import 3.8 之后才有的 stdlib 模块: {bad}" + # 同时确认所有 found 都在 allowed 白名单 —— 防止漏配 + unexpected = found - allowed + assert not unexpected, ( + f"engine/ import 了未在白名单的模块 {unexpected} —— " + f"如果这是新引入的 stdlib 模块,需确认 Python 3.8 兼容" + ) diff --git a/package.json b/package.json index ac118ac..b04d0b2 100644 --- a/package.json +++ b/package.json @@ -36,6 +36,18 @@ "package.json", "icon.ico" ], + "extraResources": [ + { + "from": "engine", + "to": "engine", + "filter": [ + "**/*.py", + "!**/tests/**", + "!**/__pycache__/**" + ] + } + ], + "asar": true, "win": { "target": [ {