如何用类型标注表示enum.IntFlag或其任意组合？

给定如下enum.IntFlag类：

class Flag(enum.IntFlag):
    FOO = 1
    BAR = 2
    QUX = 4

能否定义一种类型，用于表示“Flag实例或Flag的任意组合”？例如定义如下函数：

def func(accepts: CombinationOf[Flag]):
    ...

使得以下调用均合法：

func(Flag.FOO)
func(Flag.FOO | Flag.BAR)

而如下调用不合法：

func(8)

首先要明确：Flag的按位或操作（如Flag.FOO | Flag.BAR）返回的仍然是Flag类的实例，所以从类型层面看，直接用Flag作为参数类型就能接受单个实例或任意组合。但这种方式无法阻止传入Flag(8)这类包含未定义位的实例，或者直接传入整数8。以下是几种更严格的实现方式：

方法一：枚举所有合法组合（静态类型检查） #

通过Literal列出所有单个枚举值及合法组合，再定义类型别名：

from enum import IntFlag
from typing import Literal, TypeAlias

class Flag(IntFlag):
    FOO = 1
    BAR = 2
    QUX = 4

# 定义所有合法的Flag组合
FlagCombination: TypeAlias = Literal[
    Flag.FOO,
    Flag.BAR,
    Flag.QUX,
    Flag.FOO | Flag.BAR,
    Flag.FOO | Flag.QUX,
    Flag.BAR | Flag.QUX,
    Flag.FOO | Flag.BAR | Flag.QUX,
]

def func(accepts: FlagCombination):
    pass

# 合法调用
func(Flag.FOO)
func(Flag.FOO | Flag.BAR)

# 不合法调用（mypy等类型检查工具会报错）
func(Flag(8))
func(8)

缺点：当枚举值较多时，组合数量会指数级增长，维护成本高。

方法二：类型守卫+运行时检查 #

定义类型守卫函数，配合运行时校验，既满足静态类型检查，又能拦截非法值：

from enum import IntFlag
from typing import TypeGuard, TypeVar

T = TypeVar('T', bound=IntFlag)

def is_valid_combination(flag: T | int, flag_type: type[T]) -> TypeGuard[T]:
    # 校验传入值的所有位都属于该IntFlag定义的枚举值
    return (flag & ~sum(flag_type)) == 0

class Flag(IntFlag):
    FOO = 1
    BAR = 2
    QUX = 4

# 定义类型别名，对应合法的Flag组合
CombinationOfFlag = Flag

def func(accepts: CombinationOfFlag):
    if not is_valid_combination(accepts, Flag):
        raise ValueError("仅允许使用Flag中定义的枚举值组合")

# 合法调用
func(Flag.FOO)
func(Flag.FOO | Flag.BAR)

# 不合法调用：直接传8会触发mypy类型报错；传Flag(8)会触发运行时异常
func(8)
func(Flag(8))

优点：无需枚举所有组合，同时兼顾静态类型检查和运行时校验，适合大多数场景。

方法三：自定义类型检查插件（进阶） #

如果需要更严格的静态校验，可以编写mypy等类型检查工具的插件，自定义规则验证IntFlag组合仅使用已定义的枚举值。这种方式适合大型项目，实现复杂度较高。

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