Ruff 仓库 ty 类型检查器 no-matching-overload 规则解析提前捕获不匹配任何重载的函数调用【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruffno-matching-overload是 Ruff 仓库内 Rust 类型检查器 ty 提供的一条默认以error级别启用的诊断规则当代码调用一个带有overload装饰器的重载函数而实参无法与任何一条重载签名匹配时ty 会在此处报出该错误。它是把调用时参数不合法、运行时会抛TypeError这类缺陷从运行时提前到静态检查阶段的核心手段。读完本文你将掌握该规则的完整语义、源码层的判定流程、真实触发场景以及对应的消除方法。规则概述与基本信息该规则的定义位于 crates/ty_python_semantic/src/types/diagnostic.rs#L876-L883通过declare_lint!宏声明其规则文档正是通过include_str!从本文所依据的 no-matching-overload.md 直接嵌入文档与代码同步维护declare_lint! { #[doc include_str!(../../resources/lint_docs/no-matching-overload.md)] pub(crate) static NO_MATCHING_OVERLOAD { summary: detects calls that do not match any overload, status: LintStatus::stable(0.0.1-alpha.1), default_level: Level::Error, } }由此可确认该规则的三个关键属性summarydetects calls that do not match any overload检测不匹配任何重载的函数调用默认级别error。在聚合的规则参考文档 crates/ty/docs/rules.md#L4190 中同样标注了Default level: error状态自版本0.0.1-alpha.1起标记为稳定stable说明该诊断在类型检查器早期就已作为稳定能力提供。该规则要解决的问题Why is this bad规则文档的 Why is this bad 一节给出的解释非常直接Failing to provide the correct arguments to one of the overloads will raise aTypeErrorat runtime.即如果调用方没有为任一重载提供正确的参数组合程序运行到该调用点时就会抛出TypeError。类型检查器的作用就是在静态阶段拦截这种必然出错的调用而no-matching-overload正是针对重载函数这种签名由多个候选共同描述的特殊场景。最小可复现示例规则文档以及 crates/ty/docs/rules.md 中的规则条目给出如下示例from typing import overload overload def func(x: int): ... overload def func(x: bool): ... def func(x: int | bool): ... func(string) # error: [no-matching-overload]这里的func声明了两条重载只接受int或只接受bool实现函数签名则是两者并集int | bool。向func传入string既不匹配int也不匹配bool因此 ty 报告no-matching-overload。注意重载的匹配发生在逐个重载签名之上仅被实现签名接受是不够的——string恰好连实现签名int | bool也不满足是一个双重不匹配的典型反例。触发判定与源码实现诊断从何而来仅仅实现签名覆盖不足并不是no-matching-overload的唯一来源。从源码看重载调用的绑定与诊断决策是一个多阶段流水线位于 crates/ty_python_semantic/src/types/call/bind.rs 中元数arity预筛先检查实参数量能否满足某个重载的参数个数要求含*args展开等情况唯一类型匹配直达如果经过元数筛选后只有一个重载通过或在多个候选里恰好一个在类型层面匹配bind.rs#L4692-L4734ty 不会抛出笼统的no-matching-overload而是直接在该重载签名上报告更精确的参数诊断如参数类型错误、缺失参数等帮助定位到具体哪一条签名、哪一个参数出了问题无一匹配才报此规则当没有任何重载通过类型检查时才会走到 bind.rs#L4736-L4737在整段实参范围all_arguments_range(node)上报NO_MATCHING_OVERLOAD。报告时使用的诊断文本模板如下format_args!( No overload{} matches arguments, callable_description .map(|description| format!( of {description})) .unwrap_or_default() )即默认文本为No overload matches arguments当能推断出被调用对象的描述时会带上对象名例如在 mdtest 中固化下来的完整文案# error: [no-matching-overload] No overload of function f matches arguments reveal_type(f(a, b)) # revealed: Unknown这段来自 crates/ty_python_semantic/resources/mdtest/call/overloads.md 的测试还揭示了另一个细节触发该规则时调用表达式的推断类型为Unknown。也就是说重载全部落空之后ty 无法给出任何有意义的返回类型直接退化为未知类型——这会影响后续在该结果之上的一切类型操作因此这类错误应当尽早消除。此外当候选重载数量过多、诊断中列出的签名列表被截断时诊断还会附带说明被省略的重载数量详见下一节的测试场景。真实触发场景集锦来自 mdtest 行为测试ty 为该规则维护了一份相当全面的行为测试文档 crates/ty_python_semantic/resources/mdtest/diagnostics/no_matching_overload.md其中每一段# error: [no-matching-overload]注释都会被测试运行器断言为真实诊断并同步固化为snapshots目录下的快照文件例如no_matching_overload…_-_A_method_call_with_u…_(31cb5f881221158e).snap。以下场景均可在该文档中找到完整代码。场景一最简单的不匹配调用from typing import overload overload def f(x: int) - int: ... overload def f(x: str) - str: ... def f(x: int | str) - int | str: return x f(bfoo) # error: [no-matching-overload]bfoo是bytes类型既不匹配int也不匹配str于是即便实现签名写得再宽泛只要传入类型不在任一重载的接受集合内就会被拦截。场景二候选重载极多时的截断与提示no_matching_overload.md中专门构造了包含数十条foo(a, b, c)重载覆盖int/str/float/list[...]/bool的多种三元组合的函数再用foo(Foo(), Foo())调用它。文档注释明确说明当重载数量过多诊断会截断候选签名列表并额外输出一条消息说明省略了多少条重载避免诊断信息爆炸。这解释了该诊断在面对超大重载集合时仍保持可读性的工程取舍。同时文档还指出一个实现细节测试特意不用内置pow其重载签名相当复杂作为示例因为 ty 当时尚未支持其全部重载类型签名且Todo类型的处理在debug_assertions开关下会因编译配置不同而影响快照输出。这是诊断正确性依赖类型系统对重载签名支持完整度的直接注脚。场景三方法调用同样会被拦截from typing import overload class Foo: overload def bar(self, x: int) - int: ... overload def bar(self, x: str) - str: ... def bar(self, x: int | str) - int | str: return x foo Foo() foo.bar(bwat) # error: [no-matching-overload]no-matching-overload不只作用于模块级函数对类方法同样生效实例方法经过绑定把self计入参数之后仍然要逐一与重载签名比对。场景四大量参数的函数诊断可读性测试还覆盖了拥有 16 个命名参数lion、turtle、tortoise、goat……的两条全量重载用f(bfoo)触发错误。这类场景验证的是诊断在签名极长时的输出组织避免把几屏的签名堆到报错里。场景五对__get__的显式调用from typing import overload overload def f(x: int) - int: ... overload def f(x: str) - str: ... overload def f(x: bytes) - bytes: ... def f(x: int | str | bytes) - int | str | bytes: return x f.__get__() # error: [no-matching-overload]这是一个相当刁钻的用例f.__get__()触发的是描述符协议用于绑定__get__的重载是独立于f自身重载声明合成的。而测试文档断言即便如此诊断依然要展示出f的全部重载声明。它验证了诊断在合成绑定重载与源码重载两套签名并存时的行为正确性。场景六类构造器调用已知局限type() # error: [no-matching-overload]type本身是重载的内置可调用对象type()不带任何参数不符合其任何合法重载。不过 mdtest 中特别标注了一个 TODO截至 2025-05-15此时生成的诊断还不够理想——不会展示未匹配的重载列表。这说明构造器/内置可调用对象这一路径上的诊断质量仍在完善中属于已知限制而非最终形态。相邻场景联合类型展开与部分匹配的关系no-matching-overload还会出现在联合类型实参的部分匹配场景。例如 calls/overloads.md 的 Expanding second argument 一节# This also tests that partial matching works correctly as the argument type expansion results # in matching the first and second overloads, but not the third one. reveal_type(f(a, bc)) # revealed: B | C # error: [no-matching-overload] No overload of function f matches arguments reveal_type(f(a, cd)) # revealed: Unknown这里演示了 ty 的重载求解策略当实参是联合类型时ty 会尝试按成员展开实参逐一匹配重载argument type expansion只要某个分支能命中合法重载就继续推断所以f(a, bc)正常返回B | C而当展开后任何分支都无法命中任何重载f(a, cd)就落入no-matching-overload且结果类型为Unknown。对bool、tuple、type、枚举乃至 PEP 695 泛型等特殊类型的展开规则在该测试文件的同名小节中均有大量reveal_type断言可供查阅。这类机制保证了规则不会因为实参是复杂联合类型而漏报或误报。如何消除该错误综合规则文档与上述行为测试消除no-matching-overload的途径非常明确传参要落在重载签名集合内。写调用前先想清楚实参类型会被哪条重载接受上例func(string)之所以报错是因为int/bool都不接受str。让实现函数的签名与重载声明的并集保持一致。规则文档示例中实现签名写作def func(x: int | bool)即实现签名恰好是各重载参数类型的并集保持这种重载声明覆盖实现、实参覆盖重载的线性关系可以避免把不匹配推迟到运行时。善用reveal_type校验实参类型。mdtest 中大量使用reveal_type(...) # revealed: ...来观测推断结果在报错时结果类型为Unknown可以先确认自己传入的表达式推断出的到底是什么类型再决定是修正实参还是修正重载声明。注意联合实参的展开语义。不要以为实现函数接受A | B传A | C就没问题——重载逐条匹配的是每个展开后的成员任一成员命中不了任一重载即报错。测试与回归保障该规则的正确性由两层测试共同保障行为级 mdtest上文引用的 diagnostics/no_matching_overload.md 与 call/overloads.md 属于 ty 的 markdown 驱动测试由仓库内mdtest运行器执行代码中的# error: [no-matching-overload]注释即断言快照snapshot级断言上述每个报错场景都会生成对应的.snap文件保存在 crates/ty_python_semantic/resources/mdtest/snapshots/ 下快照完整记录了诊断文本、标注位置等信息防止输出格式在迭代中悄然漂移。小结no-matching-overload是 ty 类型检查器在重载函数这一 Python 动态特性上的静态安全网它以error级默认开启把调用不匹配任何overload签名、运行必然抛TypeError的缺陷消灭在编译期。理解它需要同时掌握三层内容规则语义做什么、为何是错、判定流程元数预筛 → 唯一匹配直达细粒度诊断 → 全落空才报本规则、以及边界行为联合实参展开、海量重载截断、方法/描述符/构造器路径。如果你想进一步深入可继续阅读规则文档 crates/ty_python_semantic/resources/lint_docs/no-matching-overload.md、规则注册表 crates/ty/docs/rules.md 与绑定求解器源码 crates/ty_python_semantic/src/types/call/bind.rs并结合上文的 mdtest 用例亲手构造参数组合来验证你的理解。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ruff 仓库 ty 类型检查器 no-matching-overload 规则解析提前捕获不匹配任何重载的函数调用【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruffno-matching-overload是 Ruff 仓库内 Rust 类型检查器 ty 提供的一条默认以error级别启用的诊断规则当代码调用一个带有overload装饰器的重载函数而实参无法与任何一条重载签名匹配时ty 会在此处报出该错误。它是把调用时参数不合法、运行时会抛TypeError这类缺陷从运行时提前到静态检查阶段的核心手段。读完本文你将掌握该规则的完整语义、源码层的判定流程、真实触发场景以及对应的消除方法。规则概述与基本信息该规则的定义位于 crates/ty_python_semantic/src/types/diagnostic.rs#L876-L883通过declare_lint!宏声明其规则文档正是通过include_str!从本文所依据的 no-matching-overload.md 直接嵌入文档与代码同步维护declare_lint! { #[doc include_str!(../../resources/lint_docs/no-matching-overload.md)] pub(crate) static NO_MATCHING_OVERLOAD { summary: detects calls that do not match any overload, status: LintStatus::stable(0.0.1-alpha.1), default_level: Level::Error, } }由此可确认该规则的三个关键属性summarydetects calls that do not match any overload检测不匹配任何重载的函数调用默认级别error。在聚合的规则参考文档 crates/ty/docs/rules.md#L4190 中同样标注了Default level: error状态自版本0.0.1-alpha.1起标记为稳定stable说明该诊断在类型检查器早期就已作为稳定能力提供。该规则要解决的问题Why is this bad规则文档的 Why is this bad 一节给出的解释非常直接Failing to provide the correct arguments to one of the overloads will raise aTypeErrorat runtime.即如果调用方没有为任一重载提供正确的参数组合程序运行到该调用点时就会抛出TypeError。类型检查器的作用就是在静态阶段拦截这种必然出错的调用而no-matching-overload正是针对重载函数这种签名由多个候选共同描述的特殊场景。最小可复现示例规则文档以及 crates/ty/docs/rules.md 中的规则条目给出如下示例from typing import overload overload def func(x: int): ... overload def func(x: bool): ... def func(x: int | bool): ... func(string) # error: [no-matching-overload]这里的func声明了两条重载只接受int或只接受bool实现函数签名则是两者并集int | bool。向func传入string既不匹配int也不匹配bool因此 ty 报告no-matching-overload。注意重载的匹配发生在逐个重载签名之上仅被实现签名接受是不够的——string恰好连实现签名int | bool也不满足是一个双重不匹配的典型反例。触发判定与源码实现诊断从何而来仅仅实现签名覆盖不足并不是no-matching-overload的唯一来源。从源码看重载调用的绑定与诊断决策是一个多阶段流水线位于 crates/ty_python_semantic/src/types/call/bind.rs 中元数arity预筛先检查实参数量能否满足某个重载的参数个数要求含*args展开等情况唯一类型匹配直达如果经过元数筛选后只有一个重载通过或在多个候选里恰好一个在类型层面匹配bind.rs#L4692-L4734ty 不会抛出笼统的no-matching-overload而是直接在该重载签名上报告更精确的参数诊断如参数类型错误、缺失参数等帮助定位到具体哪一条签名、哪一个参数出了问题无一匹配才报此规则当没有任何重载通过类型检查时才会走到 bind.rs#L4736-L4737在整段实参范围all_arguments_range(node)上报NO_MATCHING_OVERLOAD。报告时使用的诊断文本模板如下format_args!( No overload{} matches arguments, callable_description .map(|description| format!( of {description})) .unwrap_or_default() )即默认文本为No overload matches arguments当能推断出被调用对象的描述时会带上对象名例如在 mdtest 中固化下来的完整文案# error: [no-matching-overload] No overload of function f matches arguments reveal_type(f(a, b)) # revealed: Unknown这段来自 crates/ty_python_semantic/resources/mdtest/call/overloads.md 的测试还揭示了另一个细节触发该规则时调用表达式的推断类型为Unknown。也就是说重载全部落空之后ty 无法给出任何有意义的返回类型直接退化为未知类型——这会影响后续在该结果之上的一切类型操作因此这类错误应当尽早消除。此外当候选重载数量过多、诊断中列出的签名列表被截断时诊断还会附带说明被省略的重载数量详见下一节的测试场景。真实触发场景集锦来自 mdtest 行为测试ty 为该规则维护了一份相当全面的行为测试文档 crates/ty_python_semantic/resources/mdtest/diagnostics/no_matching_overload.md其中每一段# error: [no-matching-overload]注释都会被测试运行器断言为真实诊断并同步固化为snapshots目录下的快照文件例如no_matching_overload…_-_A_method_call_with_u…_(31cb5f881221158e).snap。以下场景均可在该文档中找到完整代码。场景一最简单的不匹配调用from typing import overload overload def f(x: int) - int: ... overload def f(x: str) - str: ... def f(x: int | str) - int | str: return x f(bfoo) # error: [no-matching-overload]bfoo是bytes类型既不匹配int也不匹配str于是即便实现签名写得再宽泛只要传入类型不在任一重载的接受集合内就会被拦截。场景二候选重载极多时的截断与提示no_matching_overload.md中专门构造了包含数十条foo(a, b, c)重载覆盖int/str/float/list[...]/bool的多种三元组合的函数再用foo(Foo(), Foo())调用它。文档注释明确说明当重载数量过多诊断会截断候选签名列表并额外输出一条消息说明省略了多少条重载避免诊断信息爆炸。这解释了该诊断在面对超大重载集合时仍保持可读性的工程取舍。同时文档还指出一个实现细节测试特意不用内置pow其重载签名相当复杂作为示例因为 ty 当时尚未支持其全部重载类型签名且Todo类型的处理在debug_assertions开关下会因编译配置不同而影响快照输出。这是诊断正确性依赖类型系统对重载签名支持完整度的直接注脚。场景三方法调用同样会被拦截from typing import overload class Foo: overload def bar(self, x: int) - int: ... overload def bar(self, x: str) - str: ... def bar(self, x: int | str) - int | str: return x foo Foo() foo.bar(bwat) # error: [no-matching-overload]no-matching-overload不只作用于模块级函数对类方法同样生效实例方法经过绑定把self计入参数之后仍然要逐一与重载签名比对。场景四大量参数的函数诊断可读性测试还覆盖了拥有 16 个命名参数lion、turtle、tortoise、goat……的两条全量重载用f(bfoo)触发错误。这类场景验证的是诊断在签名极长时的输出组织避免把几屏的签名堆到报错里。场景五对__get__的显式调用from typing import overload overload def f(x: int) - int: ... overload def f(x: str) - str: ... overload def f(x: bytes) - bytes: ... def f(x: int | str | bytes) - int | str | bytes: return x f.__get__() # error: [no-matching-overload]这是一个相当刁钻的用例f.__get__()触发的是描述符协议用于绑定__get__的重载是独立于f自身重载声明合成的。而测试文档断言即便如此诊断依然要展示出f的全部重载声明。它验证了诊断在合成绑定重载与源码重载两套签名并存时的行为正确性。场景六类构造器调用已知局限type() # error: [no-matching-overload]type本身是重载的内置可调用对象type()不带任何参数不符合其任何合法重载。不过 mdtest 中特别标注了一个 TODO截至 2025-05-15此时生成的诊断还不够理想——不会展示未匹配的重载列表。这说明构造器/内置可调用对象这一路径上的诊断质量仍在完善中属于已知限制而非最终形态。相邻场景联合类型展开与部分匹配的关系no-matching-overload还会出现在联合类型实参的部分匹配场景。例如 calls/overloads.md 的 Expanding second argument 一节# This also tests that partial matching works correctly as the argument type expansion results # in matching the first and second overloads, but not the third one. reveal_type(f(a, bc)) # revealed: B | C # error: [no-matching-overload] No overload of function f matches arguments reveal_type(f(a, cd)) # revealed: Unknown这里演示了 ty 的重载求解策略当实参是联合类型时ty 会尝试按成员展开实参逐一匹配重载argument type expansion只要某个分支能命中合法重载就继续推断所以f(a, bc)正常返回B | C而当展开后任何分支都无法命中任何重载f(a, cd)就落入no-matching-overload且结果类型为Unknown。对bool、tuple、type、枚举乃至 PEP 695 泛型等特殊类型的展开规则在该测试文件的同名小节中均有大量reveal_type断言可供查阅。这类机制保证了规则不会因为实参是复杂联合类型而漏报或误报。如何消除该错误综合规则文档与上述行为测试消除no-matching-overload的途径非常明确传参要落在重载签名集合内。写调用前先想清楚实参类型会被哪条重载接受上例func(string)之所以报错是因为int/bool都不接受str。让实现函数的签名与重载声明的并集保持一致。规则文档示例中实现签名写作def func(x: int | bool)即实现签名恰好是各重载参数类型的并集保持这种重载声明覆盖实现、实参覆盖重载的线性关系可以避免把不匹配推迟到运行时。善用reveal_type校验实参类型。mdtest 中大量使用reveal_type(...) # revealed: ...来观测推断结果在报错时结果类型为Unknown可以先确认自己传入的表达式推断出的到底是什么类型再决定是修正实参还是修正重载声明。注意联合实参的展开语义。不要以为实现函数接受A | B传A | C就没问题——重载逐条匹配的是每个展开后的成员任一成员命中不了任一重载即报错。测试与回归保障该规则的正确性由两层测试共同保障行为级 mdtest上文引用的 diagnostics/no_matching_overload.md 与 call/overloads.md 属于 ty 的 markdown 驱动测试由仓库内mdtest运行器执行代码中的# error: [no-matching-overload]注释即断言快照snapshot级断言上述每个报错场景都会生成对应的.snap文件保存在 crates/ty_python_semantic/resources/mdtest/snapshots/ 下快照完整记录了诊断文本、标注位置等信息防止输出格式在迭代中悄然漂移。小结no-matching-overload是 ty 类型检查器在重载函数这一 Python 动态特性上的静态安全网它以error级默认开启把调用不匹配任何overload签名、运行必然抛TypeError的缺陷消灭在编译期。理解它需要同时掌握三层内容规则语义做什么、为何是错、判定流程元数预筛 → 唯一匹配直达细粒度诊断 → 全落空才报本规则、以及边界行为联合实参展开、海量重载截断、方法/描述符/构造器路径。如果你想进一步深入可继续阅读规则文档 crates/ty_python_semantic/resources/lint_docs/no-matching-overload.md、规则注册表 crates/ty/docs/rules.md 与绑定求解器源码 crates/ty_python_semantic/src/types/call/bind.rs并结合上文的 mdtest 用例亲手构造参数组合来验证你的理解。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
