如何在Python类型检查中指定排除特定字面量的字符串类型？

需求背景 #

需要实现与Union[X, Y]反向的类型约束：类型必须是X但绝不能是Y，具体分两种场景：

1. 任意X类型，但排除X的特定子类Y；
2. 任意基础类型，但排除该类型的某个特定字面量（比如排除字符串中的"id"）。

以用户给出的Attribute类为例：当name为"id"时，required必须为True且null必须为False；当name为其他字符串时，这两个参数为可选。希望在静态类型检查阶段就拦截Attribute("id", False, False)这类无效组合。

解决方案 #

场景1：排除特定字面量 #

利用Not类型（Python 3.11+内置到typing模块，低版本需安装typing-extensions库）配合函数重载，即可实现字面量的排除约束，同时绑定参数组合规则：

from typing import overload, Literal
# Python <3.11 需从typing_extensions导入Not
from typing import Not

class Attribute:
    @overload
    def __init__(
        self,
        name: Literal["id"],
        required: Literal[True] = ...,
        null: Literal[False] = ...,
    ) -> None:
        pass

    @overload
    def __init__(
        self,
        name: Not[Literal["id"]],
        required: bool = ...,
        null: bool = ...,
    ) -> None:
        pass

    def __init__(
        self,
        name: str,
        required: bool = False,
        null: bool = False,
    ) -> None:
        # 运行时兜底检查（可选）
        if name == "id":
            if not required or null:
                raise ValueError("id属性必须满足required=True且null=False")
        # 初始化逻辑

主流类型检查器（mypy、pyright）会识别这种重载规则：

• 当传入name="id"时，强制要求required=True、null=False；
• 当传入其他字符串时，required和null可自由设置为布尔值。

场景2：排除特定子类 #

通过自定义Protocol来定义类型约束，让类型检查器验证目标类型是否不属于指定子类：

from typing import Protocol, TypeVar
from typing_extensions import runtime_checkable

# 定义泛型类型变量
BaseType = TypeVar("BaseType")
ExcludedSubtype = TypeVar("ExcludedSubtype", bound=BaseType)

@runtime_checkable
class NotSubclassOf(Protocol[BaseType, ExcludedSubtype]):
    @classmethod
    def __subclasscheck__(cls, other: type) -> bool:
        return issubclass(other, BaseType) and not issubclass(other, ExcludedSubtype)

# 示例用法
class Base:
    pass

class ForbiddenSub(Base):
    pass

def process_obj(obj: NotSubclassOf[Base, ForbiddenSub]) -> None:
    pass

process_obj(Base())      # 类型检查通过
process_obj(ForbiddenSub())  # 类型检查报错，符合预期

@runtime_checkable装饰器可选，添加后可以在运行时也执行该约束检查。

总结 #

• 排除字面量：用Not[Literal[...]]配合重载，简单直接，支持静态检查拦截非法参数组合；
• 排除子类：用自定义Protocol实现类型校验逻辑，兼容主流类型检查器；
• 无需额外复杂工具，依赖Python标准库或轻量扩展库即可实现需求。

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