Python中如何定义可被mypy等效识别的NoOp特殊形式类型

核心利用PEP 593引入的Annotated类型特性：类型检查器会完全忽略Annotated附带的元数据，仅按照第一个参数的类型做校验，同时运行时可以完整读取到注解上的元数据标记，实现标识层面的区分，完全满足需求。

from typing import Annotated, TypeVar, get_type_hints, get_origin, get_args

T = TypeVar("T")

# 私有标记类，仅用于运行时识别NoOp包裹的类型
class _NoOpMarker:
    pass

# 定义NoOp泛型注解
NoOp = Annotated[T, _NoOpMarker]


# 类型检查行为测试：和直接标注原生类型完全一致
def foo(bar: NoOp[int]) -> int:
    return bar + 1

foo(1)  # mypy校验通过，和标注bar: int的表现完全一致
foo("invalid")  # mypy会抛出和标注int时完全相同的类型错误

检测某个注解是NoOp包裹的类型还是原生类型时，给get_type_hints传入include_extras=True保留完整注解信息，再判断元数据中是否存在标记即可：

def is_noop_annotation(annotation: type) -> bool:
    """判断传入的类型注解是否为NoOp包裹的类型"""
    if get_origin(annotation) is not Annotated:
        return False
    # 检查注解元数据中是否包含NoOp标记
    return _NoOpMarker in get_args(annotation)[1:]


# 检测逻辑测试
def bar(a: int, b: NoOp[str]) -> None:
    pass

hints = get_type_hints(bar, include_extras=True)
print(is_noop_annotation(hints["a"]))  # 输出False，为原生int类型
print(is_noop_annotation(hints["b"]))  # 输出True，为NoOp包裹的str类型

• 不使用NewType的原因：NewType会创建独立的子类型，mypy会要求显式做类型转换才能传入原类型值，无法做到和原类型检查逻辑完全等效；且NewType本质是返回原值的函数，运行时识别逻辑可读性差。
• 普通类型别名NoOp[T] = T不可行：这种写法运行时会直接将NoOp[int]解析为原生int，无法做标识层面的区分。

• 读取类型注解做运行时判断时，必须给get_type_hints传入include_extras=True，否则Python会自动剥离Annotated的元数据，拿到的就是裸的原类型，无法识别NoOp标记。
• 该实现完全符合PEP标准，mypy、pyright等主流类型检查器都原生支持该行为，不需要额外插件。
• 如果使用Python 3.8及更早版本，需要从typing_extensions导入Annotated，其余逻辑完全一致。

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