如何为Python整数位标志参数添加类型提示并实现IDE智能提示？

要让VS Code这类IDE在调用Thing.call()时弹出可选的FLAG值菜单，最实用的方案是用enum.IntEnum定义位标志——既能保留整数位运算特性，又能让IDE识别枚举成员并提供补全提示。

具体实现代码 #

from enum import IntEnum

class ThingFlags(IntEnum):
    FLAG_FOO = 1 << 0
    FLAG_BAR = 1 << 1
    FLAG_JOE = 1 << 2

class Thing:
    # 类型提示同时兼容枚举成员和位组合后的整数
    def call(self, flags: ThingFlags | int) -> None:
        # 可选：添加合法标志校验，拦截无效值
        valid_flags = ThingFlags.FLAG_FOO | ThingFlags.FLAG_BAR | ThingFlags.FLAG_JOE
        if (flags & valid_flags) != flags:
            raise ValueError("传入了无效的标志值")
        
        # 这里编写方法业务逻辑
        print(f"处理标志: {flags}")

效果说明 #

• 调用Thing().call()时，IDE会自动弹出ThingFlags的所有成员（FLAG_FOO、FLAG_BAR、FLAG_JOE）供选择。
• 支持传入多个标志的位组合（比如ThingFlags.FLAG_FOO | ThingFlags.FLAG_BAR），此时结果为整数类型，ThingFlags | int的类型提示能完美兼容这种场景。
• 相比枚举所有可能组合的方案，IntEnum扩展性极强——新增标志时只需在枚举类中添加一行定义，无需修改类型提示。

不推荐的Literal方案 #

如果硬要仿照字符串字面量的实现方式，只能手动列出所有单个及组合后的标志值，但这种写法扩展性极差，新增标志后需手动补充所有新组合，示例如下：

from typing import Literal

FLAG_FOO = 1 << 0
FLAG_BAR = 1 << 1
FLAG_JOE = 1 << 2

# 手动枚举所有合法的单个/组合值
ValidFlags = Literal[
    FLAG_FOO, FLAG_BAR, FLAG_JOE,
    FLAG_FOO | FLAG_BAR, FLAG_FOO | FLAG_JOE, FLAG_BAR | FLAG_JOE,
    FLAG_FOO | FLAG_BAR | FLAG_JOE
]

class Thing:
    def call(self, flags: ValidFlags) -> None:
        pass

该写法仅适合标志数量极少且永不改动的场景，一般不建议使用。

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