From 95e936f1b333c0ced7b82b188ed24ae4a3e33c7f Mon Sep 17 00:00:00 2001 From: jxxghp Date: Fri, 16 Oct 2026 10:51:22 +0800 Subject: [PATCH] refactor(types): govern reflection helpers without changing runtime signatures --- app/foundation/reflection.py | 30 ++++++++++++------- docs/code-quality.md | 2 +- docs/refactor/optimization-checklist.md | 4 +-- mypy.ini | 1 + .../fixtures/architecture/mypy-baseline.json | 11 ------- tests/test_reflection_signature_contract.py | 18 +++++++++++ 6 files changed, 41 insertions(+), 25 deletions(-) create mode 100644 tests/test_reflection_signature_contract.py diff --git a/app/foundation/reflection.py b/app/foundation/reflection.py index 27dc7b051..b706a4433 100644 --- a/app/foundation/reflection.py +++ b/app/foundation/reflection.py @@ -8,11 +8,19 @@ import threading import tokenize import weakref from pathlib import Path -from types import CodeType, FunctionType -from typing import Any, Callable, List, Optional, get_type_hints +from types import CodeType, FunctionType, ModuleType +from typing import TYPE_CHECKING, Any, Callable, List, Optional, get_type_hints FilterFuncType = Callable[[str, Any], bool] +# 静态分析覆盖实际接收的可调用对象；运行时保留原注解供签名自省使用。 +if TYPE_CHECKING: + _ArgumentCallable = Callable[..., object] + _SignatureCallable = Callable[..., object] +else: + _ArgumentCallable = Callable + _SignatureCallable = FunctionType + # check_method 结果缓存：弱引用代码对象，模块或插件卸载后自动清理 _implemented_cache: "weakref.WeakKeyDictionary[CodeType, bool]" = weakref.WeakKeyDictionary() @@ -60,7 +68,7 @@ class ModuleHelper: filter_func: FilterFuncType = _default_filter, ) -> List[Any]: """加载包的一级模块，并返回通过过滤器的去重类对象。""" - submodules: list = [] + submodules: list[type[object]] = [] loaded_modules = set() packages = importlib.import_module(package_path) for _, package_name, _ in pkgutil.iter_modules(packages.__path__): @@ -92,7 +100,7 @@ class ModuleHelper: submodules = [] packages = importlib.import_module(package_path) - def reload_module_objects(target_module): + def reload_module_objects(target_module: ModuleType) -> list[type[object]]: """重载一个模块并返回过滤后的类对象。""" importlib.reload(target_module) return [ @@ -103,7 +111,7 @@ class ModuleHelper: and filter_func(name, obj) ] - def reload_sub_modules(parent_module, parent_module_name): + def reload_sub_modules(parent_module: ModuleType, parent_module_name: str) -> None: """重载父包下能够成功导入的所有子模块。""" for _, sub_module_name, _ in pkgutil.walk_packages( parent_module.__path__, @@ -147,7 +155,7 @@ class ObjectUtils: """提供对象类型、函数实现和签名检查能力。""" @staticmethod - def is_obj(obj: Any): + def is_obj(obj: Any) -> bool: """判断值是否属于可展开的复合对象。""" if isinstance(obj, list) \ or isinstance(obj, dict) \ @@ -162,7 +170,7 @@ class ObjectUtils: return True @staticmethod - def is_objstr(obj: Any): + def is_objstr(obj: Any) -> bool: """判断字符串是否以常见复合对象字面量开头。""" if not isinstance(obj, str): return False @@ -171,7 +179,7 @@ class ObjectUtils: or str(obj).startswith("(") @staticmethod - def arguments(func: Callable) -> int: + def arguments(func: _ArgumentCallable) -> int: """ 返回函数的参数个数 """ @@ -212,7 +220,7 @@ class ObjectUtils: return not all(_is_placeholder_stmt(stmt) for stmt in node.body) except Exception: # 源代码分析失败时，进行字节码分析 - code_obj = func.__code__ # type: ignore[attr-defined] + code_obj = func.__code__ instructions = list(dis.get_instructions(code_obj)) # 检查是否为仅返回None的简单结构 if len(instructions) == 2: @@ -221,7 +229,7 @@ class ObjectUtils: second.opname == 'RETURN_VALUE'): # 验证加载的常量是否为None const_index = first.arg - if (const_index < len(code_obj.co_consts) and + if (const_index is not None and const_index < len(code_obj.co_consts) and code_obj.co_consts[const_index] is None): # 未实现的空函数 return False @@ -229,7 +237,7 @@ class ObjectUtils: return True @staticmethod - def check_signature(func: FunctionType, *args) -> bool: + def check_signature(func: _SignatureCallable, *args: object) -> bool: """ 检查输出与函数的参数类型是否一致 """ diff --git a/docs/code-quality.md b/docs/code-quality.md index 1246d1314..255ebf8b7 100644 --- a/docs/code-quality.md +++ b/docs/code-quality.md @@ -75,7 +75,7 @@ uv run --locked --no-sync python scripts/architecture/complexity.py 回调和返回值类型；全仓错误计数为零并不保证单独纳入 strict frontier 后也为零。 2026-10-16 开始逐文件清理类型债务，`app/domain/title.py` 通过局部可空类型声明保留 -既有搜索解析行为，并纳入严格清单；当前清单共 51 个文件（50 个生产文件和 1 个脚本）。 +既有搜索解析行为，并纳入严格清单；当前清单共 52 个文件（51 个生产文件和 1 个脚本）。 每个治理提交只修改一个生产文件及其必要测试、门禁配置、真实下降基线和指标文档。 验收同时检查完整严格清单与全宿主 Linux 分析，避免 `follow_imports = skip` 隐藏依赖 签名冲突；不通过忽略诊断或放宽类型合同接受回退。最新文件清单以 `mypy.ini` 为准， diff --git a/docs/refactor/optimization-checklist.md b/docs/refactor/optimization-checklist.md index 9b4af74f6..479f5ce60 100644 --- a/docs/refactor/optimization-checklist.md +++ b/docs/refactor/optimization-checklist.md @@ -106,9 +106,9 @@ ARCH-201 至 ARCH-204 均达到实现、验证、提交、推送和远端门禁 | Model/Oper 事务债务 | 0 | 自建 Session、自动事务装饰器、直接 commit/rollback 等基线均为零 | | Module Contract | 215 specs / 211 methods / 263 calls | 动态方法名为 0；分类事实富化通过显式合同进入插件调度，旧 YAML 分类方法已移除；download 新增 custom_words 可选参数，旧 provider 签名通过显式合同兼容 | | Event Contract | 53 | 均已有 payload model，但当前全部是 diagnostic enforcement | -| Python 源码量 | 371,931 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 | +| Python 源码量 | 371,939 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 | | 长方法 | 309 个超过 80 行 | 本次 AST 扫描排除 `app/plugins/**`；61 个超过 150 行，17 个超过 250 行；新增函数仍受 C901/嵌套深度门禁约束 | -| 全量 mypy 历史债务 | 9,114 / 502 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项，逐文件逐错误码无增长 | +| 全量 mypy 历史债务 | 9,101 / 500 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项，逐文件逐错误码无增长 | | Ruff 历史诊断 | 100 | 低水位门禁通过，但规则集只覆盖 `E4/E7/E9/F/I` | | 覆盖率固定基线 | Application 80.00%，Domain 80.00% | Chain、Runtime、Agent、Adapter、Startup 未进入包级覆盖率门禁 | diff --git a/mypy.ini b/mypy.ini index 08c116e7f..cf48be956 100644 --- a/mypy.ini +++ b/mypy.ini @@ -14,6 +14,7 @@ files = app/domain/tokens.py, app/domain/meta/infopath.py, app/foundation/url.py, + app/foundation/reflection.py, app/adapters/network/cloudflare.py, app/adapters/web/correlation.py, app/agent/contracts.py, diff --git a/tests/fixtures/architecture/mypy-baseline.json b/tests/fixtures/architecture/mypy-baseline.json index 8d34b6853..31b704181 100644 --- a/tests/fixtures/architecture/mypy-baseline.json +++ b/tests/fixtures/architecture/mypy-baseline.json @@ -1295,14 +1295,6 @@ "app/foundation/environment.py": { "no-any-return": 1 }, - "app/foundation/reflection.py": { - "index": 1, - "no-untyped-call": 2, - "no-untyped-def": 5, - "operator": 1, - "type-arg": 2, - "unused-ignore": 1 - }, "app/foundation/singleton.py": { "arg-type": 2, "misc": 2, @@ -2458,9 +2450,6 @@ "union-attr": 1, "var-annotated": 1 }, - "app/runtime/extensions/module/dispatcher.py": { - "arg-type": 1 - }, "app/runtime/extensions/module/manager.py": { "attr-defined": 1, "type-arg": 4 diff --git a/tests/test_reflection_signature_contract.py b/tests/test_reflection_signature_contract.py new file mode 100644 index 000000000..dd37753b5 --- /dev/null +++ b/tests/test_reflection_signature_contract.py @@ -0,0 +1,18 @@ +"""反射工具公开注解参与运行时签名校验的兼容性回归。""" + +import pytest + +from app.foundation.reflection import ObjectUtils + + +@pytest.mark.parametrize("value, expected", [(lambda: None, True), (len, True), (1, False)]) +def test_argument_counter_preserves_runtime_callable_check(value, expected): + """参数计数器补齐静态类型后，仍能作为签名校验的目标函数。""" + assert ObjectUtils.check_signature(ObjectUtils.arguments, value) is expected + + +def test_signature_checker_preserves_function_annotation(): + """签名校验器仍保留函数对象注解，同时继续支持检查内建可调用对象。""" + assert ObjectUtils.check_signature(ObjectUtils.check_signature, lambda: None, 1) + assert not ObjectUtils.check_signature(ObjectUtils.check_signature, len, 1) + assert ObjectUtils.check_signature(len, [])