mypy对@overload重载构造函数做穷尽模式匹配时的类型校验报错问题

• mypy的@overload仅对外部调用场景做类型约束，不会在类内部的__init__实现逻辑中，自动反向推导所有overload声明的合法参数组合、帮你做分支穷尽校验。
• 你在类内部拿到的参数，永远来自不带overload的实际实现签名，也就是三个参数都是可空的自由组合类型。
• 之前的写法把所有非法参数组合堆到最后一个else里统一处理，本质上是希望mypy能自动识别所有遗漏的非法路径，但mypy只会严格按照你写的判断条件推导类型，不会主动参考overload的声明。这就导致走完两个合法分支后，else路径依然存在多种实实在在的可空类型组合，根本不是"穷尽后剩下的不可能值"，自然会触发传入类型和NoReturn不匹配的报错。

核心是利用mypy的类型收窄机制，顺着判断条件一步步排除所有合法参数分支，让所有走到assert_never的路径，都被mypy推导为不存在合法值的状态：

• 调整分支判断顺序，优先处理bv参数的合法场景：只要bv不为None，先校验类型合法性，匹配成功就直接处理逻辑并return，避免类型污染后续分支。
• 处理完bv分支后，mypy可以自动推导bv此时的类型一定是None，接下来只需要判断剩下的"size+content"组合的合法性：必须两个参数同时存在才是合法场景，缺任意一个就是非法组合，直接传入assert_never拦截。
• 对收窄后的合法类型，加一层运行时断言做双重保险，既可以拦截运行时的脏数据，也能帮mypy进一步确认类型范围。

from typing import overload, NoReturn, Optional, Union

def assert_never(value: NoReturn) -> NoReturn:
    assert False, f'Unhandled value: {value} ({type(value).__name__})'

class BitVector(): ...

class MyClass:

    @overload
    def __init__(self, *, size: int, content: bytes): ...
    @overload
    def __init__(self, *, size: int, content: int): ...
    @overload
    def __init__(self, *, bv: BitVector): ...

    def __init__(self, bv: Optional[BitVector]=None, size: Optional[int]=None, content: Optional[Union[bytes,int]]=None):
        # 分支1：直接传入BitVector实例的合法场景
        if bv is not None:
            if not isinstance(bv, BitVector):
                assert_never(bv)
            # 执行BitVector实例对应的处理逻辑
            ...
            return
        
        # 走到此处时，mypy已自动推导bv的类型为None
        # 剩余合法场景必须同时传入size和content
        if size is None or content is None:
            assert_never((size, content))
        
        # 走到此处时，mypy已自动推导size为int、content为bytes/int
        # 运行时断言做兜底校验
        assert isinstance(size, int)
        assert isinstance(content, (bytes, int))
        # 执行size+content参数对应的处理逻辑
        ...

按上述逻辑写完后，所有调用assert_never的位置，mypy都会推导出传入值的类型是理论上不存在的（即匹配NoReturn的要求），不会再抛出之前的类型不匹配报错；同时所有合法分支的类型范围，也和@overload声明的参数组合完全对齐，既满足外部调用的类型约束，也实现了内部逻辑的穷尽校验。

内容的提问来源于stack exchange，提问作者Pamplemousse