如何为Python 3.12中用type定义的类型别名添加文档？

对于Python 3.12新增的type类型别名语句，你之前的写法无法关联文档字符串，是因为单独的文档字符串不会自动绑定到前面的别名，而放在=后会打破语法规则。下面是两种可行的正确方式：

方法一：用Annotated + Doc（推荐，IDE友好） #

Python 3.12引入了typing.Doc，配合Annotated可以给类型别名添加标准的文档注解，主流IDE（如PyCharm、VS Code）会识别并展示这些文档：

from typing import Annotated, Doc

type Number = Annotated[int | float, Doc("Represents a scalar number that is either an integer or float")]

方法二：直接设置别名的__doc__属性 #

type语句定义的别名本质是模块级的对象，你可以直接给它赋值__doc__属性来添加文档，这种方式简单直接，运行时也能访问到文档内容：

type Number = int | float
Number.__doc__ = "Represents a scalar number that is either an integer or float"

为什么之前的写法无效？ #

• 你在type语句后单独写的文档字符串，只是一个独立的表达式，执行后会被直接丢弃，不会绑定到Number别名上。
• 把文档字符串放在=之后的写法违反Python语法，因为=右侧必须是合法的类型表达式，不能直接插入字符串。

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