如何为Python的Literal类型添加文档以在IDE提示中显示？

我们可以通过TypedDict轻松约束输入字典，还能为每个字典键添加文档注释，示例如下：

import typing

class MyType(typing.TypedDict):
    a: str
    """参数a的说明文档"""
    b: int
    """参数b的说明文档"""

def fun(x: MyType):
    ...

多数IDE会列出所有已声明的键，且键的文档注释会在提示框中显示。

但如果是字符串字面量的场景，比如下面的函数：

import typing

def fun(x: typing.Literal["a", "b", "c"]):
    ...

VS Code等IDE会提示可选的输入值"a"、"b"、"c"，但直接给这些字面量添加文档注释（类似TypedDict的方式）目前并不被Python类型提示规范和主流IDE支持，不过可以通过以下两种替代方案实现类似效果：

方案1：使用枚举（Enum）替代Literal #

通过enum.Enum定义带注释的选项，每个枚举成员可以添加文档字符串，IDE会识别并在提示时显示这些注释：

from enum import Enum
import typing

class Options(Enum):
    A = "a"
    """选项a：用于XXX场景"""
    B = "b"
    """选项b：用于YYY场景"""
    C = "c"
    """选项c：用于ZZZ场景"""

# 方式1：参数类型仍用Literal，指定枚举成员的value
def fun(x: typing.Literal[Options.A.value, Options.B.value, Options.C.value]):
    ...

# 方式2：直接将参数类型指定为枚举类型，调用时传入枚举成员
def fun_enum(x: Options):
    ...

# 调用示例
fun_enum(Options.A)

这种方案不仅能让IDE在提示枚举成员时显示对应注释，还能避免手动输入字符串时的拼写错误，体验更优。

方案2：类型别名+注释（限部分IDE支持） #

PyCharm、VS Code配合Pylance等IDE支持在类型别名的注释中说明每个Literal选项的含义：

import typing

# 定义类型别名，在注释中逐一说明选项含义
MyLiteral = typing.Literal["a", "b", "c"]
"""
- "a": 选项a的详细说明
- "b": 选项b的详细说明
- "c": 选项c的详细说明
"""

def fun(x: MyLiteral):
    ...

当鼠标悬停在MyLiteral类型上时，IDE会显示类型别名的注释，从而间接查看每个选项的文档说明。

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