ty 对 Pythonwith语句的类型推断上下文管理器协议、异常抑制语义与诊断规则【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文以 crates/ty_python_semantic/resources/mdtest/with/sync.md 这份 mdtest 规格文档为主体系统讲解仓库中 tyRust 编写的高性能 Python 类型检查器如何对同步with语句进行类型推断包括as目标变量的类型推导、上下文管理器__exit__返回值与异常抑制的关系、联合类型/重载方法下的边界行为以及invalid-context-manager诊断的判定逻辑。读完本文你将理解 ty 类型推断引擎处理with语句的完整规则并能用仓库中的 mdtest 用例验证自己的类型标注是否会被正确分析。一、测试载体mdtest 规格文档本文依托的文档是 ty 语义层测试体系的一部分。crates/ty_python_semantic/resources/mdtest/目录下存放着一组以 Markdown 书写的可执行规格每个代码块会被抽取为独立文件交由 ty 推断# revealed:注释断言某个名字的推断类型# error:注释断言某个位置必须产生指定诊断码。配套的异步with规格位于 crates/ty_python_semantic/resources/mdtest/with/async.md本文聚焦同步版本。测试框架本身实现于 crates/mdtest/src/lib.rs关键控制方式设置环境变量MDTEST_TEST_FILTER测试名后执行cargo test -p ty_python_semantic --test mdtest可只运行指定用例设置MDTEST_UPDATE_SNAPSHOTS1可自动更新快照部分用例通过!-- snapshot-diagnostics --与# snapshot标记输出完整诊断快照存放于 crates/ty_python_semantic/resources/mdtest/snapshots/。二、基本规则目标变量类型来自__enter__的返回值with语句中as目标变量的类型等于上下文管理器__enter__方法的返回类型class Target: ... class Manager: def __enter__(self) - Target: return Target() def __exit__(self, exc_type, exc_value, traceback): ... with Manager() as f: reveal_type(f) # revealed: Target该行为在源码中由 crates/ty_python_semantic/src/types/context_manager.rs 的try_enter_with_mode实现它同步调用__enter__与__exit____exit__以(None, None, None)作为参数对应正常退出路径并返回__enter__的返回类型绑定到目标变量。with语句的推断入口是 crates/ty_python_semantic/src/types/infer/builder.rs 中的infer_with_statement。三、异常抑制上下文管理器contextlib.suppress的绑定语义当上下文管理器在赋值过程中抑制了异常时with语句之后的绑定可见性遵循一组精确规则这也是本文档篇幅最大的部分。3.1 之前的绑定在抑制后仍然可见from contextlib import suppress def may_raise() - str: raise ValueError result None with suppress(ValueError): result may_raise() reveal_type(result) # revealed: None | strsuppress(ValueError)的__exit__返回True说明它可以抑制异常。因此result may_raise()存在两条路径要么成功赋值为str要么在赋值前抛异常被抑制、result保持之前的None。推断结果是并集None | str。3.2 新名字在异常中断赋值后可能未定义with suppress(ValueError): value may_raise() # error: [possibly-unresolved-reference] reveal_type(value) # revealed: str如果value在此之前从未绑定那么异常路径下它始终未定义因此引用它是可疑的触发possibly-unresolved-reference诊断而在成功路径上它的类型是str。3.3 被del删除的绑定不会被恢复deleted 1 with suppress(ValueError): del deleted may_raise() deleted # error: [unresolved-reference]del deleted已经执行即使后续异常被抑制之前的绑定也已被删除引用它是确定的错误unresolved-reference而非可能未定义。3.4 不会抛异常的赋值不受抑制影响with suppress(ValueError): safe_value 1 reveal_type(safe_value) # revealed: Literal[1]safe_value 1不可能抛出ValueError因此抑制机制完全不参与类型被精确推断为Literal[1]。3.5 解包__enter__结果也可能抛异常解包unpacking在上下文管理器进入之后进行同样可能抛异常class EmptyIterableManager: def __enter__(self) - list[int]: return [] def __exit__(self, exc_type, exc_value, traceback) - bool: return True value before with EmptyIterableManager() as (value, missing): pass reveal_type(value) # revealed: Literal[before] | int # error: [possibly-unresolved-reference] reveal_type(missing) # revealed: int(value, missing)解包一个空列表时抛出ValueError迭代器耗尽被__exit__返回True抑制。于是value保持旧的before或得到intmissing从未被赋值引用触发possibly-unresolved-reference。3.6 靠前的管理器可以抑制靠后管理器的进入失败多个上下文管理器从左到右进入如果前面的管理器抑制了后面管理器__enter__抛出的异常后面管理器的目标可能从未被赋值from contextlib import suppress class EnterFails: def __enter__(self) - str: raise ValueError def __exit__(self, exc_type, exc_value, traceback) - None: ... with suppress(ValueError), EnterFails() as target: pass # error: [possibly-unresolved-reference] reveal_type(target) # revealed: str四、循环与控制流break、continue与嵌套管理器上下文管理器无法抑制break或continue但它可以抑制下一个管理器进入时抛出的异常因此循环体内break/continue之后的赋值只是可能被到达。4.1 多个管理器中的循环退出from contextlib import nullcontext, suppress for _ in [1]: with suppress(ValueError), nullcontext(): break after_break 1 after_break # error: [possibly-unresolved-reference]break本身无法被抑制所以after_break 1可能从未执行。continue同理for _ in [1]: with suppress(ValueError), nullcontext(): continue after_continue 1 after_continue # error: [possibly-unresolved-reference]异常在break之前被抑制同样会让后续赋值成为可能未到达for _ in [1]: with suppress(ValueError): int(invalid) break after_exception 1 after_exception # error: [possibly-unresolved-reference]4.2 嵌套上下文管理器嵌套写法与并列写法行为一致外层管理器可以抑制内层管理器进入时的异常但两者都无法抑制break/continuefrom contextlib import nullcontext, suppress for _ in [1]: with suppress(ValueError): with nullcontext(): break after_break 1 after_break # error: [possibly-unresolved-reference]for _ in [1]: with suppress(ValueError): with nullcontext(): continue after_continue 1 after_continue # error: [possibly-unresolved-reference]4.3return与抑制的交互return语句本身无法被抑制from contextlib import suppress def bare_return() - int: with suppress(ValueError): return 1但如果异常发生在求值 return 表达式期间它会被抑制函数继续执行并以隐式None结束从而触发invalid-return-typedef may_raise() - int: raise ValueError # error: [invalid-return-type] Function can implicitly return None, which is not assignable to return type int def interrupted_return() - int: with suppress(ValueError): return may_raise()4.4except、finally与抑制的优先级一个裸except:会先于外围上下文管理器捕获异常因此函数不会走到隐式None返回from contextlib import suppress def caught_before_suppression() - int: with suppress(ValueError): try: raise ValueError except: return 1finally中的return会在异常到达外层管理器之前将其替换掉from contextlib import suppress def always_returns() - int: with suppress(ValueError): try: raise ValueError finally: return 1finally中的赋值则在外层管理器抑制异常之前完成因此抑制后仍然可见from contextlib import suppress def cleanup_before_suppression() - None: result None with suppress(ValueError): try: raise ValueError finally: result cleaned reveal_type(result) # revealed: Literal[cleaned]4.5 急切求值表达式列表推导体是急切求值的其内部异常可以被上下文管理器抑制进而使后续return 1无法执行函数隐式返回Nonefrom contextlib import suppress def may_raise() - int: raise ValueError # error: [invalid-return-type] Function can implicitly return None, which is not assignable to return type int def eager_comprehension() - int: with suppress(ValueError): [may_raise() for _ in [0]] return 1ty 同样将生成器表达式视为假定急切求值异常同样可以被抑制# error: [invalid-return-type] Function can implicitly return None, which is not assignable to return type int def eager_generator() - int: with suppress(ValueError): (may_raise() for _ in [0]) return 1五、__exit__返回类型与异常抑制判定能否抑制异常完全取决于__exit__的声明返回类型而非运行时的真值。这一点由 crates/ty_python_semantic/src/types/context_manager.rs 中的can_suppress_exceptions实现仅当某个签名返回类型等价于bool或Literal[True]时才判定为可抑制。5.1 可抑制bool与Literal[True]from typing import Any, Literal class Manager: def __enter__(self) - None: ... class ReturnsBool(Manager): def __exit__(self, exc_type, exc_value, traceback) - bool: return True def may_raise() - str: raise ValueError bool_result None with ReturnsBool(): bool_result may_raise() reveal_type(bool_result) # revealed: None | strclass ReturnsTrue(Manager): def __exit__(self, exc_type, exc_value, traceback) - Literal[True]: return True true_result None with ReturnsTrue(): true_result may_raise() reveal_type(true_result) # revealed: None | str5.2 不可抑制Literal[False]与Noneclass ReturnsFalse(Manager): def __exit__(self, exc_type, exc_value, traceback) - Literal[False]: return False false_result None with ReturnsFalse(): false_result may_raise() reveal_type(false_result) # revealed: strclass ReturnsNone(Manager): def __exit__(self, exc_type, exc_value, traceback) - None: ... none_result None with ReturnsNone(): none_result may_raise() reveal_type(none_result) # revealed: str5.3 关键约定bool | None与Any视为不可抑制typing 规范将bool | None归类为不可抑制——尽管运行时真值可以抑制异常但大量普通管理器习惯标注为bool | None若按可能为真处理会把异常路径错误地保留下来。ty 特意在源码注释中说明这与运行时真值语义有意不同是为了兼容常见的非抑制管理器标注。class ReturnsOptionalBool(Manager): def __exit__(self, exc_type, exc_value, traceback) - bool | None: return None optional_result None with ReturnsOptionalBool(): optional_result may_raise() reveal_type(optional_result) # revealed: strLiteral[True] | None同样被视为不可抑制class ReturnsOptionalTrue(Manager): def __exit__(self, exc_type, exc_value, traceback) - Literal[True] | None: return True optional_true_result None with ReturnsOptionalTrue(): optional_true_result may_raise() reveal_type(optional_true_result) # revealed: strLiteral[False] | None也如此class ReturnsOptionalFalse(Manager): def __exit__(self, exc_type, exc_value, traceback) - Literal[False] | None: return False optional_false_result None with ReturnsOptionalFalse(): optional_false_result may_raise() reveal_type(optional_false_result) # revealed: strAny同样不表示可抑制class ReturnsAny(Manager): def __exit__(self, exc_type, exc_value, traceback) - Any: return False any_result None with ReturnsAny(): any_result may_raise() reveal_type(any_result) # revealed: str判定速查表__exit__返回类型是否可抑制异常示例结果bool是None \| strLiteral[True]是None \| strLiteral[False]否strNone否strbool \| None否规范约定strLiteral[True] \| None否规范约定strAny否str六、联合类型与类型别名的上下文管理器6.1 联合中任一成员可抑制则整体可抑制如果一个联合类型中的任一成员可以抑制异常即使另一个成员不能整个联合也视为可抑制[environment] python-version 3.12class Manager: def __enter__(self) - None: ... class Suppresses(Manager): def __exit__(self, exc_type, exc_value, traceback) - bool: return True class Propagates(Manager): def __exit__(self, exc_type, exc_value, traceback) - bool | None: return None def may_raise() - str: raise ValueError def possibly_suppressing(manager: Suppresses | Propagates) - None: result None with manager: result may_raise() reveal_type(result) # revealed: None | str这对应can_suppress_exceptions中对联合类型的处理对每个成员分别判定只要有一个成员可抑制即返回true且该判定结果按类型做 salsa 缓存源码注释明确说明合并不同成员/重载的返回类型会把可抑制与不可抑制的bool与bool | None混在一起导致误判因此必须逐成员分类。6.2 PEP 695 别名不改变行为type Managers Suppresses | Propagates def preserved_binding(manager: Managers) - None: result None with manager: result may_raise() reveal_type(result) # revealed: None | str被抑制的异常同样可能让新绑定保持未定义def missing_binding(manager: Managers) - None: with manager: result may_raise() # error: [possibly-unresolved-reference] reveal_type(result) # revealed: str6.3 联合上下文管理器的__enter__返回类型并集class Manager1: def __enter__(self) - str: return foo def __exit__(self, exc_type, exc_value, traceback): ... class Manager2: def __enter__(self) - int: return 42 def __exit__(self, exc_type, exc_value, traceback): ... def _(context_expr: Manager1 | Manager2): with context_expr as f: reveal_type(f) # revealed: str | int6.4 三种类型别名形式等价TypeAlias、PEP 695type语句与typing_extensions.TypeAliasType三种别名形式在with推断上行为一致[environment] python-version 3.12from typing import Self, TypeAlias from typing_extensions import TypeAliasType class A: def __enter__(self) - Self: return self def __exit__(self, exc_type, exc_value, traceback) - None: ... class B: def __enter__(self) - Self: return self def __exit__(self, exc_type, exc_value, traceback) - None: ... UnionAB1: TypeAlias A | B type UnionAB2 A | B UnionAB3 TypeAliasType(UnionAB3, A | B) def f1(x: UnionAB1) - None: with x as y: reveal_type(y) # revealed: A | B def f2(x: UnionAB2) - None: with x as y: reveal_type(y) # revealed: A | B def f3(x: UnionAB3) - None: with x as y: reveal_type(y) # revealed: A | B七、非抑制管理器保留类型窄化非抑制管理器不会改变异常传播后的窄化narrowing结果class Manager: def __enter__(self) - None: ... def __exit__(self, exc_type, exc_value, traceback) - None: ... def propagating_exception(value: int | str) - None: if isinstance(value, int): with Manager(): raise ValueError reveal_type(value) # revealed: str在可能抛异常的操作之后建立的窄化同样被保留def narrowing_after_possible_exception(value: int | str) - None: with Manager(): int(invalid) if isinstance(value, int): raise ValueError reveal_type(value) # revealed: str当另一条异常路径在非抑制管理器中引入新绑定时类型守卫TypeGuard在一侧的窄化仍被保留from typing import TypeGuard class Base: ... def is_string(value: Base) - TypeGuard[str]: return isinstance(value, str) def make_integer() - int: return 1 def type_guard_across_exception_handler() - None: value Base() try: if not is_string(value): return except Exception: with Manager(): value make_integer() reveal_type(value) # revealed: str | int普通isinstance窄化遵循同样规则被排除的None不会在合并异常处理器赋值时重新出现def isinstance_across_exception_handler(source: str | None) - None: value source try: if not isinstance(value, str): return except Exception: with Manager(): value make_integer() reveal_type(value) # revealed: str | int八、重载的__exit__方法重载是否可抑制异常取决于异常发生时命中的重载而非代码块正常退出时命中的重载。正常退出时 Python 调用__exit__(None, None, None)。仅正常退出返回True的管理器不能抑制异常from typing import Literal, overload from typing_extensions import Never class Manager: def __enter__(self) - None: ... def may_raise() - str: raise ValueError class NormalOnly(Manager): overload def __exit__(self, exc_type: None, exc_value: None, traceback: None) - Literal[True]: ... overload def __exit__(self, exc_type: type[BaseException], exc_value: BaseException, traceback: object) - Literal[False]: ... def __exit__(self, exc_type, exc_value, traceback) - bool: return exc_type is None normal_value None with NormalOnly(): normal_value may_raise() reveal_type(normal_value) # revealed: str若异常重载的任一异常参数是不可满足类型Never该重载不可能被命中也不能抑制异常class ImpossibleExceptionalExit(Manager): overload def __exit__(self, exc_type: Never, exc_value: BaseException, traceback: object) - Literal[True]: ... overload def __exit__(self, exc_type: type[BaseException], exc_value: Never, traceback: object) - Literal[True]: ... overload def __exit__( self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: object | None ) - Literal[False]: ... def __exit__(self, exc_type, exc_value, traceback) - bool: return False impossible_exception_value None with ImpossibleExceptionalExit(): impossible_exception_value may_raise() reveal_type(impossible_exception_value) # revealed: str一个异常重载可以抑制异常即使另一个异常重载不能class SuppressesValueError(Manager): overload def __exit__(self, exc_type: type[ValueError], exc_value: ValueError, traceback: object) - Literal[True]: ... overload def __exit__(self, exc_type: type[TypeError], exc_value: TypeError, traceback: object) - None: ... overload def __exit__(self, exc_type: None, exc_value: None, traceback: None) - None: ... def __exit__(self, exc_type, exc_value, traceback) - Literal[True] | None: return True if exc_type is ValueError else None mixed_exceptional_value None with SuppressesValueError(): mixed_exceptional_value may_raise() reveal_type(mixed_exceptional_value) # revealed: None | str源码实现can_suppress_exceptions中对每个重载签名先检查其前两个位置参数的类型是否与type[BaseException]/BaseException实例不相交disjoint若不相交则说明该签名描述的不是异常退出路径直接跳过不参与抑制判定。九、invalid-context-manager诊断协议校验当上下文表达式不是合法上下文管理器时ty 报告invalid-context-manager诊断默认级别Error声明于 crates/ty_python_semantic/src/types/diagnostic.rs。诊断消息由ContextManagerError::report_diagnostic生成能够区分缺失方法方法可能缺失实现不正确三类成因。9.1 缺失__enter__或__exit__class Manager: ... # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not implement __enter__ and __exit__ with Manager(): passclass Manager: def __exit__(self, exc_tpe, exc_value, traceback): ... # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not implement __enter__ with Manager(): passclass Manager: def __enter__(self): ... # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not implement __exit__ with Manager(): pass9.2 非可调用非函数的 dunder 属性class Manager: __enter__: int 42 def __exit__(self, exc_tpe, exc_value, traceback): ... # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not correctly implement __enter__ with Manager(): passfrom typing_extensions import Self class Manager: def __enter__(self) - Self: return self __exit__: int 32 # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not correctly implement __exit__ with Manager(): pass9.3 无效的__enter__签名class Manager: def __enter__() - str: return foo def __exit__(self, exc_type, exc_value, traceback): ... context_expr Manager() # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not correctly implement __enter__ with context_expr as f: reveal_type(f) # revealed: str9.4 联合类型中存在可能缺失方法的成员当联合类型中某成员不是上下文管理器时诊断会使用possibly missing措辞且as目标类型只取能提供__enter__的那部分class Manager1: def __enter__(self) - str: return foo def __exit__(self, exc_type, exc_value, traceback): ... class NotAContextManager: ... def _(context_expr: Manager1 | NotAContextManager): # error: [invalid-context-manager] Object of type Manager1 | NotAContextManager cannot be used with with because the methods __enter__ and __exit__ are possibly missing with context_expr as f: reveal_type(f) # revealed: str多个成员同时缺失包括部分实现时同理class GoodManager: def __enter__(self) - str: return foo def __exit__(self, exc_type, exc_value, traceback): ... class MissingExitManager: def __enter__(self) - str: return bar class NotAContextManager: ... def _(context_expr: GoodManager | MissingExitManager | NotAContextManager): # error: [invalid-context-manager] Object of type GoodManager | MissingExitManager | NotAContextManager cannot be used with with because the methods __enter__ and __exit__ are possibly missing with context_expr as f: reveal_type(f) # revealed: str9.5 全部实现但实现不正确的联合若联合的每个成员都实现了协议但至少一个实现不正确如非可调用__exit__诊断应反映实现不正确而不是可能缺失class GoodManager: def __enter__(self) - str: return foo def __exit__(self, exc_type, exc_value, traceback): ... class BadManager: def __enter__(self) - str: return bar # __exit__ is present but not callable __exit__: int 32 def _(context_expr: GoodManager | BadManager): # error: [invalid-context-manager] Object of type GoodManager | BadManager cannot be used with with because it does not correctly implement __exit__ with context_expr as f: reveal_type(f) # revealed: str9.6 条件定义导致的可能缺失方法def _(flag: bool): class Manager: if flag: def __enter__(self) - str: return abcd def __exit__(self, *args): ... # error: [invalid-context-manager] Object of type Manager cannot be used with with because the method __enter__ may be missing with Manager() as f: reveal_type(f) # revealed: str十、误用同步with于异步上下文管理器若对仅实现__aenter__/__aexit__的类型使用同步withty 会提示用户可能想用async withclass Manager: async def __aenter__(self): ... async def __aexit__(self, *args): ... # snapshot: invalid-context-manager with Manager(): pass对应快照完整呈现诊断与提示信息error[invalid-context-manager]: Object of type Manager cannot be used with with because it does not implement __enter__ and __exit__ -- src/mdtest_snippet.py:6:6 | 6 | with Manager(): | ^^^^^^^^^ info: Objects of type Manager can be used as async context managers info: Consider using async with here该提示逻辑位于ContextManagerError::report_diagnostic当同步模式失败但反向检查__aenter__/__aexit__可调用时附加info级别的建议。异步方法签名不正确或参数个数不符时同样给出该提示class Manager: async def __aenter__(self): ... async def __aexit__(self, typ: str, exc, traceback): ... # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not implement __enter__ and __exit__ with Manager(): passclass Manager: async def __aenter__(self, wrong_extra_arg): ... async def __aexit__(self, typ, exc, traceback, wrong_extra_arg): ... # error: [invalid-context-manager] Object of type Manager cannot be used with with because it does not implement __enter__ and __exit__ with Manager(): pass十一、从源码理解推断链路将以上规则串联起来ty 对with语句的处理链路如下infer_with_statement 遍历每个with项有as目标时通过infer_target调用__enter__对应try_enter_with_mode无目标时单独调用infer_context_expression做协议校验。try_enter_with_mode同时以(None, None, None)试调__exit__任何失败都会被包装为ContextManagerErrorEnter、Exit、EnterAndExit、NotAwaitable四种变体。绑定合并阶段调用can_suppress_exceptions判定异常路径是否保留旧绑定或制造未定义引用该函数对联合类型逐成员判定、对重载逐签名判定结果按(program, manager, is_async)缓存。ContextManagerError::report_diagnostic生成invalid-context-manager诊断并根据失败原因自动选择不实现 / 可能缺失 / 未正确实现措辞必要时附加async with建议。十二、如何运行与验证这些规格不是静态文档而是可执行的测试。在仓库根目录运行cargo test -p ty_python_semantic --test mdtest即可把crates/ty_python_semantic/resources/mdtest/下的所有 Markdown 规格当作测试执行。只运行with相关用例MDTEST_TEST_FILTERWith statements cargo test -p ty_python_semantic --test mdtest需要更新快照例如诊断文案变更后时MDTEST_UPDATE_SNAPSHOTS1 cargo test -p ty_python_semantic --test mdtest失败时 CLI 会打印断言差异并给出可复现的单测命令在 CI 中可通过MDTEST_GITHUB_ANNOTATIONS_FORMAT切换为 GitHub Actions 注解格式。相关诊断码的完整文档另见 crates/ty/docs/rules.mdinvalid-context-manager、invalid-return-type、possibly-unresolved-reference等条目可作为阅读本文时的规则手册。结语with语句看似简单其类型推断却横跨协议校验、异常流分析、联合类型与重载解析多个层面。本文档通过十余组可执行用例把__exit__返回类型决定异常抑制这一核心语义落实到可验证的边界行为上bool与Literal[True]可抑制None、Literal[False]、bool | None、Any不可抑制联合类型只要有一个成员可抑制即可抑制重载按异常路径而非正常路径判定。理解这些规则不仅能预测 ty 对with代码的诊断结果也为编写类型安全的自定义上下文管理器提供了明确依据。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考