typing —— 对类型提示的支持

Added in version 3.5.

源代码： Lib/typing.py

备注

Python 运行时不强制要求函数与变量类型标注。 它们可被 类型检查器、IDE、语法检查器等第三方工具使用。

本模块提供了对类型提示的运行时支持。

考虑下面的函数:

def surface_area_of_cube(edge_length: float) -> str:
    return f"The surface area of the cube is {6 * edge_length ** 2}."

函数 surface_area_of_cube 接受一个预期为 float 实例的参数，如 type hint edge_length: float 所指明的。 该函数预期返回一个 str 实例，如 -> str 提示所指明的。

类型提示可以是简单的类比如 float 或 str，它们也可以更为复杂。 typing 模块提供了一套用于更高级类型提示的词汇。

新特性被频繁添加到 typing 模块中。 typing_extensions 包提供了这些新特性针对较旧版本 Python 的向下移植。

参见

“类型系统备忘单”

关于类型提示的概览（发布于 mypy 文档站点）

mypy 文档 的 “Type System Reference” 章节

Python 类型系统是通过 PEP 来标准化的，因此该参考应当广泛适用于大多数 Python 类型检查器。 （但某些部分仍然是 mypy 专属的。）

“Static Typing with Python”

由社区编写的不限定具体类型检查器的文档，详细讲解了类型系统特性，有用的类型相关工具以及类型的最佳实践。

有关 Python 类型系统的规范说明

Python 类型系统最新的规范说明可以在 “Specification for the Python type system” 查看。

类型别名

类型别名是使用 type 语句来定义的，它将创建一个 TypeAliasType 的实例。 在这个示例中，Vector 和 list[float] 将被静态类型检查器等同处理:

type Vector = list[float]
def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]
# 通过类型检查；浮点数列表是合格的 Vector。
new_vector = scale(2.0, [1.0, -4.2, 5.4])

类型别名适用于简化复杂的类型签名。例如：

from collections.abc import Sequence
type ConnectionOptions = dict[str, str]
type Address = tuple[str, int]
type Server = tuple[Address, ConnectionOptions]
def broadcast_message(message: str, servers: Sequence[Server]) -> None:
    ...
# 静态类型检查器会认为上面的类型签名
# 完全等价于下面这个写法。
def broadcast_message(
    message: str,
    servers: Sequence[tuple[tuple[str, int], dict[str, str]]]
) -> None:
    ...

type 语句是在 Python 3.12 中新增加的。 为了向下兼容，类型别名也可以通过简单的赋值来创建:

Vector = list[float]

或者用 TypeAlias 标记来显式说明这是一个类型别名，而非一般的变量赋值：

from typing import TypeAlias
Vector: TypeAlias = list[float]

NewType

用 NewType 助手创建与原类型不同的类型：

from typing import NewType
UserId = NewType('UserId', int)
some_id = UserId(524313)

静态类型检查器把新类型当作原始类型的子类，这种方式适用于捕捉逻辑错误：

def get_user_name(user_id: UserId) -> str:
    ...
# 通过类型检查
user_a = get_user_name(UserId(42351))
# 未通过类型检查；整数不能作为 UserId
user_b = get_user_name(-1)

UserId 类型的变量可执行所有 int 操作，但返回结果都是 int 类型。这种方式允许在预期 int 时传入 UserId，还能防止意外创建无效的 UserId：

# 'output' 的类型为 'int' 而非 'UserId'
output = UserId(23413) + UserId(54341)

注意，这些检查只由静态类型检查器强制执行。在运行时，语句 Derived = NewType('Derived', Base) 将产生一个 Derived 可调用对象，该对象立即返回你传递给它的任何参数。 这意味着语句 Derived(some_value) 不会创建一个新的类，也不会引入超出常规函数调用的很多开销。

更确切地说，在运行时，some_value is Derived(some_value) 表达式总为 True。

创建 Derived 的子类型是无效的:

from typing import NewType
UserId = NewType('UserId', int)
# 将在运行时失败且无法通过类型检查
class AdminUserId(UserId): pass

然而，我们可以在 “派生的” NewType 的基础上创建一个 NewType。

from typing import NewType
UserId = NewType('UserId', int)
ProUserId = NewType('ProUserId', UserId)

同时，ProUserId 的类型检查也可以按预期执行。

详见 PEP 484。

备注

请记住使用类型别名将声明两个类型是相互 等价 的。 使用 type Alias = Original 将使静态类型检查器在任何情况下都把 Alias 视为与 Original 完全等价。 这在你想要简化复杂的类型签名时会很有用处。

反之，NewType 声明把一种类型当作另一种类型的 子类型。Derived = NewType('Derived', Original) 时，静态类型检查器把 Derived 当作 Original 的 子类 ，即，Original 类型的值不能用在预期 Derived 类型的位置。这种方式适用于以最小运行时成本防止逻辑错误。

Added in version 3.5.2.

在 3.10 版本发生变更: NewType 现在是一个类而不是一个函数。 因此，当调用 NewType 而非常规函数时会有一些额外的运行时开销。

在 3.11 版本发生变更: 调用 NewType 的性能已恢复到 Python 3.9 时的水平。

标注可调用对象

函数 — 或是其他 callable 对象 — 可以使用 collections.abc.Callable 或已被弃用的 typing.Callable 来标注。 Callable[[int], str] 表示一个接受 int 类型的单个形参并返回一个 str 的函数。

例如:

from collections.abc import Callable, Awaitable
def feeder(get_next_item: Callable[[], str]) -> None:
    ...  # 函数体
def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    ...  # 函数体
async def on_update(value: str) -> None:
    ...  # 函数体
callback: Callable[[str], Awaitable[None]] = on_update

下标语法总是要刚好使用两个值：参数列表和返回类型。 参数列表必须是一个由类型组成的列表、ParamSpec、Concatenate 或省略号。 返回类型必须是单一类型。

如果将一个省略号字面值 ... 作为参数列表，则表示可以接受包含任意形参列表的可调用对象:

def concat(x: str, y: str) -> str:
    return x + y
x: Callable[..., str]
x = str     # 可以
x = concat  # 同样可以

Callable 无法表达复杂的签名如接受可变数量参数的函数，重载的函数，或具有仅限关键字形参的函数。 但是，这些签名可通过自定义具有 __call__() 方法的 Protocol 类来表达：

from collections.abc import Iterable
from typing import Protocol
class Combiner(Protocol):
    def __call__(self, *vals: bytes, maxlen: int | None = None) -> list[bytes]: ...
def batch_proc(data: Iterable[bytes], cb_results: Combiner) -> bytes:
    for item in data:
        ...
def good_cb(*vals: bytes, maxlen: int | None = None) -> list[bytes]:
    ...
def bad_cb(*vals: bytes, maxitems: int | None) -> list[bytes]:
    ...
batch_proc([], good_cb)  # 可以
batch_proc([], bad_cb)   # 错误！参数 2 的类型不兼容
                         # 因为在回调中有不同的名称和类别

以其他可调用对象为参数的可调用对象可以使用 ParamSpec 来表明其参数类型是相互依赖的。 此外，如果该可调用对象增加或删除了其他可调用对象的参数，可以使用 Concatenate 操作符。 它们分别采取 Callable[ParamSpecVariable, ReturnType] 和 Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType] 的形式。

在 3.10 版本发生变更: Callable 现在支持 ParamSpec 和 Concatenate。 详情见 PEP 612。

参见

ParamSpec 和 Concatenate 的文档提供了在 Callable 中使用的例子。

泛型（Generic）

由于无法以通用方式静态地推断容器中保存的对象的类型信息，标准库中的许多容器类都支持下标操作来以表示容器元素的预期类型。

from collections.abc import Mapping, Sequence
class Employee: ...
# Sequence[Employee] 表明该序列中的所有元素
# 都必须是 "Employee" 的实例。
# Mapping[str, str] 表明该映射中的所有键和所有值
# 都必须是字符串。
def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

泛型函数和类可以通过使用 类型形参语法 来实现参数化:

from collections.abc import Sequence
def first[T](l: Sequence[T]) -> T:  # 函数是 TypeVar "T" 泛型
    return l[0]

或直接使用 TypeVar 工厂：

from collections.abc import Sequence
from typing import TypeVar
U = TypeVar('U')                  # 声明类型变量 "U"
def second(l: Sequence[U]) -> U:  # 函数是 TypeVar "U" 泛型
    return l[1]

在 3.12 版本发生变更: 对泛型的语法支持是在 Python 3.12 中新增的。

标注元组

对于 Python 中的大多数容器，类型系统会假定容器中的所有元素都是相同类型的。 例如:

from collections.abc import Mapping
# 类型检查器将推断 ``x`` 中的所有元素均为整数
x: list[int] = []
# 类型检查器错误: ``list`` 只接受单个类型参数：
y: list[int, str] = [1, 'foo']
# 类型检查器将推断 ``z`` 中的所有键均为字符串，
# 并且 ``z`` 中的所有值均为字符串或整数
z: Mapping[str, str | int] = {}

list 只接受一个类型参数，因此类型检查器将在上述代码中对 y 赋值时报告错误。同样，Mapping 只接受两个类型参数：第一个给出键的类型，第二个则给出值的类型。

然而，与大多数其它 Python 容器不同的是，在常见的 Python 代码中，元组中元素的类型并不相同。因此，在 Python 的类型系统中，元组是特殊情况。tuple 可以接受 任意数量 的类型参数：

# 可以: ``x`` 被赋值为长度为 1 的元组，其中的唯一元素是个整数
x: tuple[int] = (5,)
# 可以: ``y`` 被赋值为长度为 2 的元素；
# 第 1 个元素是个整数，第 2 个元素是个字符串
y: tuple[int, str] = (5, "foo")
# 错误: 类型标注表明是长度为 1 的元组，
# 但 ``z`` 却被赋值为长度为 3 的元组
z: tuple[int] = (1, 2, 3)

要表示一个可以是 任意 长度的元组，并且其中的所有元素都是相同类型的 T，请使用 tuple[T, ...]。要表示空元组，请使用 tuple[()]。只使用 tuple 作为注解等效于使用``tuple[Any, …]``：

x: tuple[int, ...] = (1, 2)
# 这些赋值是可以的 OK: ``tuple[int, ...]`` 表明 x 可以为任意长度
x = (1, 2, 3)
x = ()
# 这个赋值是错误的: ``x`` 中的所有元素都必须为整数
x = ("foo", "bar")
# ``y`` 只能被赋值为一个空元组
y: tuple[()] = ()
z: tuple = ("foo", "bar")
# 这些重新赋值是可以的 OK: 简单的 ``tuple`` 等价于 ``tuple[Any, ...]``
z = (1, 2, 3)
z = ()

类对象的类型

带有 C 标注的变量可接受 C 类型的值。 反之，带有 type[C] (或已被弃用的 typing.Type[C]) 标注的变量则可接受本身是类的值 — 准确地说，它将接受 C 的 类对象。 例如:

a = 3         # 为 ``int`` 类型
b = int       # 为 ``type[int]`` 类型
c = type(a)   # 同样为 ``type[int]`` 类型

注意，type[C] 是协变的：

class User: ...
class ProUser(User): ...
class TeamUser(User): ...
def make_new_user(user_class: type[User]) -> User:
    # ...
    return user_class()
make_new_user(User)      # 可以
make_new_user(ProUser)   # 同样可以: ``type[ProUser]`` 是 ``type[User]`` 的子类型
make_new_user(TeamUser)  # 仍然可以
make_new_user(User())    # 错误: 预期为 ``type[User]`` 但得到 ``User``
make_new_user(int)       # 错误: ``type[int]`` 不是 ``type[User]`` 的子类型

type 的合法形参只有类, Any, 类型变量 以及前面这些类型的并集。 例如:

def new_non_team_user(user_class: type[BasicUser | ProUser]): ...
new_non_team_user(BasicUser)  # 可以
new_non_team_user(ProUser)    # 可以
new_non_team_user(TeamUser)   # 错误: ``type[TeamUser]`` 不是
                              # ``type[BasicUser | ProUser]`` 的子类型
new_non_team_user(User)       # 同样错误

type[Any] 等价于 type，它是 Python 的 元类层级结构 的根对象。

标注生成器和协程

生成器可以使用泛型类型 Generator[YieldType, SendType, ReturnType] 来标。 例如:

def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

请注意与标准库里的许多其他泛型类不同，Generator 的 SendType 采用逆变行为，而不是协变或不变行为。

SendType 和 ReturnType 形参默认为 None：

def infinite_stream(start: int) -> Generator[int]:
    while True:
        yield start
        start += 1

也可以显式设置这些类型：

def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1

仅产生值的简单生成器可以被标注为具有 Iterable[YieldType] 或 Iterator[YieldType] 类型的返回值:

def infinite_stream(start: int) -> Iterator[int]:
    while True:
        yield start
        start += 1

异步生成器的处理方式类似，但不要指望有 ReturnType 类型参数 (AsyncGenerator[YieldType, SendType])。 SendType 参数默认为 None，因此以下定义是等价的:

async def infinite_stream(start: int) -> AsyncGenerator[int]:
    while True:
        yield start
        start = await increment(start)
async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
    while True:
        yield start
        start = await increment(start)

与同步情况一样，AsyncIterable[YieldType] 和 AsyncIterator[YieldType] 也可用:

async def infinite_stream(start: int) -> AsyncIterator[int]:
    while True:
        yield start
        start = await increment(start)

协程可使用 [YieldType, SendType, ReturnType] 进行注释。 泛型参数对应于 Generator 的参数，例如:

from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # 在其他地方定义的协程
x = c.send('hi')                   # 推断 'x' 的类型为 list[str]
async def bar() -> None:
    y = await c                    # 推断 'y' 的类型为 int

用户定义的泛型类型

用户定义的类可以定义为泛型类。

from logging import Logger
class LoggedVar[T]:
    def __init__(self, value: T, name: str, logger: Logger) -> None:
        self.name = name
        self.logger = logger
        self.value = value
    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = new
    def get(self) -> T:
        self.log('Get ' + repr(self.value))
        return self.value
    def log(self, message: str) -> None:
        self.logger.info('%s: %s', self.name, message)

这种语法表示类 LoggedVar 是围绕单个 类型变量 T 实现参数化的。 这也使得 T 成为类体内部有效的类型。

泛型类隐式继承自 Generic。为了与 Python 3.11 及更低版本兼容，也允许显式地从 Generic 继承以表示泛型类：

from typing import TypeVar, Generic
T = TypeVar('T')
class LoggedVar(Generic[T]):
    ...

泛型类具有 __class_getitem__() 方法，这意味着泛型类可在运行时进行参数化（例如下面的 LoggedVar[int]）：

from collections.abc import Iterable
def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)

一个泛型可以有任何数量的类型变量。所有种类的 TypeVar 都可以作为泛型的参数:

from typing import TypeVar, Generic, Sequence
class WeirdTrio[T, B: Sequence[bytes], S: (int, str)]:
    ...
OldT = TypeVar('OldT', contravariant=True)
OldB = TypeVar('OldB', bound=Sequence[bytes], covariant=True)
OldS = TypeVar('OldS', int, str)
class OldWeirdTrio(Generic[OldT, OldB, OldS]):
    ...

Generic 类型变量的参数应各不相同。下列代码就是无效的：

from typing import TypeVar, Generic
...
class Pair[M, M]:  # SyntaxError
    ...
T = TypeVar('T')
class Pair(Generic[T, T]):   # 无效
    ...

泛型类也可以从其他类继承：

from collections.abc import Sized
class LinkedList[T](Sized):
    ...

从泛型类继承时，某些类型参数可被固定：

from collections.abc import Mapping
class MyDict[T](Mapping[str, T]):
    ...

在这个例子中，MyDict 就只有一个参数 T。

未指定泛型类的类型参数时，会假定每个位置的类型都为 Any。在下面的例子中，MyIterable 不是泛型，但却隐式继承了 Iterable[Any]：

from collections.abc import Iterable
class MyIterable(Iterable): # 与 Iterable[Any] 相同
    ...

用户定义的泛型类型别名也同样受到支持。例如：

from collections.abc import Iterable
type Response[S] = Iterable[S] | int
# 这里的返回类型与 Iterable[str] | int 相同
def response(query: str) -> Response[str]:
    ...
type Vec[T] = Iterable[tuple[T, T]]
def inproduct[T: (int, float, complex)](v: Vec[T]) -> T: # 与 Iterable[tuple[T, T]] 相同
    return sum(x*y for x, y in v)

出于向后兼容性的考虑，也允许使用简单的赋值来创建泛型类型别名：

from collections.abc import Iterable
from typing import TypeVar
S = TypeVar("S")
Response = Iterable[S] | int

在 3.7 版本发生变更: Generic 不再支持自定义元类。

在 3.12 版本发生变更: 3.12 版本新增了对泛型和类型别名的语法支持。在之前的版本中，泛型类必须显式继承自 Generic，或者在其基类之一中包含有类型变量。

用户定义的参数表达式的泛型也受到支持，可以采用 [**P] 形式的参数规格变量来表示。该行为与上面描述的类型变量一致，因为参数规格变量被 typing 模块视为专门的类型变量。这方面的一个例外是，类型的列表可用于替代 ParamSpec：

>>> class Z[T, **P]: ...  # T 为 TypeVar；P 为 ParamSpec
...
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]

带有 ParamSpec 的泛型类也可以使用从 Generic 显式继承的方式来创建。在这种情况下，不需要使用 **：

from typing import ParamSpec, Generic
P = ParamSpec('P')
class Z(Generic[P]):
    ...

TypeVar 与 ParamSpec 的另一个区别在于只有单个参数规格变量的泛型会接受形如 X[[Type1, Type2, ...]] 的参数列表，同时为了美观，也接受 X[Type1, Type2, ...] 这样的形式。 在内部，后者被转换为前者，所以下面的内容是等价的：

>>> class X[**P]: ...
...
>>> X[int, str]
__main__.X[[int, str]]
>>> X[[int, str]]
__main__.X[[int, str]]

请注意：在某些情况下，具有 ParamSpec 的泛型在替换后可能不具有正确的 __parameters__，因为参数规格主要用于静态类型检查。

在 3.10 版本发生变更: Generic 现在可以通过参数表达式进行参数化。参见 ParamSpec 和 PEP 612 以了解更多细节。

用户定义的泛型类可以将 ABC 作为基类而不会导致元类冲突。 参数化泛型的输出结果会被缓存，且 typing 模块中的大多数类型都是 hashable 并且支持相等性比较。

Any 类型

Any 是一种特殊的类型。静态类型检查器认为所有类型均与 Any 兼容，同样，Any 也与所有类型兼容。

也就是说，可对 Any 类型的值执行任何操作或方法调用，并赋值给任意变量：

from typing import Any
a: Any = None
a = []          # 可以
a = 2           # 可以
s: str = ''
s = a           # 可以
def foo(item: Any) -> int:
    # 通过类型检查；'item' 可以为任意类型，
    # 并且其类型会具有 'bar' 方法
    item.bar()
    ...

注意，Any 类型的值赋给更精确的类型时，不执行类型检查。例如，把 a 赋给 s，在运行时，即便 s 已声明为 str 类型，但接收 int 值时，静态类型检查器也不会报错。

此外，未指定返回值与参数类型的函数，都隐式地默认使用 Any：

def legacy_parser(text):
    ...
    return data
# 静态类型检查器将认为上面的函数
# 具有与下面的函数相同的签名：
def legacy_parser(text: Any) -> Any:
    ...
    return data

需要混用动态与静态类型代码时，此操作把 Any 当作 应急出口。

Any 和 object 的区别。与 Any 相似，所有类型都是 object 的子类型。然而，与 Any 不同，object 不可逆：object 不是 其它类型的子类型。

就是说，值的类型是 object 时，类型检查器几乎会拒绝所有对它的操作，并且，把它赋给更精确的类型变量（或返回值）属于类型错误。例如：

def hash_a(item: object) -> int:
    # 不能通过类型检查；对象没有 'magic' 方法。
    item.magic()
    ...
def hash_b(item: Any) -> int:
    # 通过类型检查
    item.magic()
    ...
# 通过类型检查，因为整数和字符串都是 object 的子类
hash_a(42)
hash_a("foo")
# 通过类型检查，因为 Any 可以兼容所有类型
hash_b(42)
hash_b("foo")

使用 object，说明值能以类型安全的方式转为任何类型。使用 Any，说明值是动态类型。

名义子类型 vs 结构子类型

最初 PEP 484 将 Python 静态类型系统定义为使用 名义子类型。这意味着当且仅当类 A 是 B 的子类时，才满足有类 B 预期时使用类 A 。

此项要求以前也适用于抽象基类，例如，Iterable 。这种方式的问题在于，定义类时必须显式说明，既不 Pythonic，也不是动态类型式 Python 代码的惯用写法。例如，下列代码就遵从了 PEP 484 的规范：

from collections.abc import Sized, Iterable, Iterator
class Bucket(Sized, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

PEP 544 允许用户在类定义时不显式说明基类，从而解决了这一问题，静态类型检查器隐式认为 Bucket 既是 Sized 的子类型，又是 Iterable[int] 的子类型。这就是 结构子类型 （又称为静态鸭子类型）：

from collections.abc import Iterator, Iterable
class Bucket:  # 注意：没有基类
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...
def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # 通过类型检查

此外，结构子类型的优势在于，通过继承特殊类 Protocol ，用户可以定义新的自定义协议（见下文中的例子）。

模块内容

typing 模块定义了下列类、函数和装饰器。

特殊类型原语

特殊类型

这些类型可用于在注解中表示类型，但不支持下标用法（[]）。

typing.Any

特殊类型，表示没有约束的类型。

• 所有类型都与 Any 兼容。

• Any 与所有类型都兼容。

在 3.11 版本发生变更: Any 现在可以用作基类。这有助于避免类型检查器在高度动态或可通过鸭子类型使用的类上报错。

typing.AnyStr

受约束的类型变量。

定义：

AnyStr = TypeVar('AnyStr', str, bytes)

AnyStr 用于可接受 str 或 bytes 参数但不允许两者混用的函数。

例如：

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b
concat("foo", "bar")    # 可以，输出为 'str' 类型
concat(b"foo", b"bar")  # 可以，输出为 'bytes' 类型
concat("foo", b"bar")   # 错误，不可混用 str 和 bytes

请注意：尽管名为 AnyStr，但它与 Any 类型毫无关系，也不是指“任何字符串”。而且，AnyStr 更是和 str | bytes 彼此互不相同，各有各的使用场景：

# AnyStr 的无效使用:
# 类型变量在函数签名中仅使用一次，
# 因此无法通过类型检查器“解决”
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"
# 注释此函数的更好方法:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"

Deprecated since version 3.13, will be removed in version 3.18: 已被弃用而应改用新的 类型形参语法。 使用 class A[T: (str, bytes)]: ... 而不是导入 AnyStr。 详情参见 PEP 695。

在 Python 3.16 中，AnyStr 将从 typing.__all__ 中被移除，在运行时当它被访问或从 typing 导入时将发出弃用警告。 在 Python 3.18 中 AnyStr 将从 typing 中被移除。

typing.LiteralString

只包括字符串字面值的的特殊类型。

任何字符串字面值或其他 LiteralString 都与 LiteralString 兼容。但 str 类型的对象不与其兼容。组合 LiteralString 类型的对象产生的字符串也被认为是 LiteralString。

示例:

def run_query(sql: LiteralString) -> None:
    ...
def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
    run_query("SELECT * FROM students")  # 可以
    run_query(literal_string)  # 可以
    run_query("SELECT * FROM " + literal_string)  # 可以
    run_query(arbitrary_string)  # 类型检查器错误
    run_query(  # 类型检查器错误
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

LiteralString 对于会因用户可输入任意字符串而导致问题的敏感 API 很有用。例如，上述两处导致类型检查器报错的代码可能容易被 SQL 注入攻击。

请参阅 PEP 675 了解详情。

Added in version 3.11.

typing.Never

typing.NoReturn

Never 和 NoReturn 代表 底类型，一种没有成员的类型。

它们可被用于指明一个函数绝不会返回，例如 sys.exit():

from typing import Never  # 或 NoReturn
def stop() -> Never:
    raise RuntimeError('no way')

或者用于定义一个绝不应被调用的函数，因为不存在有效的参数，例如 assert_never():

from typing import Never  # 或 NoReturn
def never_call_me(arg: Never) -> None:
    pass
def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # 类型检查器错误
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _:
            never_call_me(arg)  # OK, arg is of type Never (or NoReturn)

Never 和 NoReturn 在类型系统中具有相同的含义并且静态类型检查器会以相同的方式对待这两者。

Added in version 3.6.2: 增加了 NoReturn。

Added in version 3.11: 增加了 Never。

typing.Self

特殊类型，表示当前闭包内的类。

例如：

from typing import Self, reveal_type
class Foo:
    def return_self(self) -> Self:
        ...
        return self
class SubclassOfFoo(Foo): pass
reveal_type(Foo().return_self())  # 揭示的类型为 "Foo"
reveal_type(SubclassOfFoo().return_self())  # 揭示的类型为 "SubclassOfFoo"

此注解在语法上等价于以下代码，但形式更为简洁：

from typing import TypeVar
Self = TypeVar("Self", bound="Foo")
class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self

通常来说，如果某些内容返回 self，如上面的示例所示，您应该使用 Self 作为返回值注解。如果 Foo.return_self 被注解为返回 "Foo"，那么类型检查器将推断从 SubclassOfFoo.return_self 返回的对象是 Foo 类型，而不是 SubclassOfFoo。

其它常见用例包括：

• 被用作替代构造器的 classmethod，它将返回 cls 形参的实例。

• 标注一个返回自身的 __enter__() 方法。

如果不能保证在子类中方法会返回子类的实例（而非父类的实例），则不应使用 Self 作为返回值注解：

class Eggs:
    # 在这里 self 是一个不正确的返回注释,
    # 因为返回的对象始终是 Eggs 的一个实例,
    # 即使在子类中
    def returns_eggs(self) -> "Eggs":
        return Eggs()

更多细节请参见 PEP 673。

Added in version 3.11.

typing.TypeAlias

特殊注解，用于显式声明 类型别名.

例如：

from typing import TypeAlias
Factors: TypeAlias = list[int]

在较早的 Python 版本上，TypeAlias 对注解使用前向引用的别名时特别有用，因为类型检查器可能很难将这些别名与正常的变量赋值区分开来：

from typing import Generic, TypeAlias, TypeVar
T = TypeVar("T")
# "Box" 还不存在,
# 因此我们必须在 Python <3.12 版本中使用引号进行前向引用。
# 使用 ``TypeAlias`` 告诉类型检查器这是一个类型别名声明，
# 而不是对字符串的变量赋值。
BoxOfStrings: TypeAlias = "Box[str]"
class Box(Generic[T]):
    @classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...

请参阅 PEP 613 了解详情。

Added in version 3.10.

自 3.12 版本弃用: TypeAlias 被弃用，请使用 type 语句，后者创建 TypeAliasType 的实例，并且天然支持正向引用。请注意，虽然 TypeAlias 和 TypeAliasType 具有相似的用途和名称，但它们是不同的，后者并不是前者的类型。目前还没有移除 TypeAlias 的计划，但鼓励用户迁移到 type 语句。

特殊形式

这些内容在注解中可以视为类型，且都支持下标用法（[]），但每个都有唯一的语法。

typing.Union

联合类型； Union[X, Y] 等价于 X | Y ，意味着满足 X 或 Y 之一。

要定义一个联合类型，可以使用类似 Union[int, str] 或简写 int | str。建议使用这种简写。细节:

• 参数必须是某种类型，且至少有一个。

• 联合类型之联合类型会被展平，例如：

  Union[Union[int, str], float] == Union[int, str, float]

• 单参数之联合类型就是该参数自身，例如：

  Union[int] == int  # 该构造器确实返回 int

• 冗余的参数会被跳过，例如：

  Union[int, str, int] == Union[int, str] == int | str

• 比较联合类型，不涉及参数顺序，例如：

  Union[int, str] == Union[str, int]

• 不可创建 Union 的子类或实例。

• 没有 Union[X][Y] 这种写法。

在 3.7 版本发生变更: 在运行时，不要移除联合类型中的显式子类。

在 3.10 版本发生变更: 联合类型现在可以写成 X | Y。 参见 联合类型表达式。

typing.Optional

Optional[X] 等价于 X | None （或 Union[X, None] ） 。

注意，可选类型与含默认值的可选参数不同。含默认值的可选参数不需要在类型注解上添加 Optional 限定符，因为它仅是可选的。例如：

def foo(arg: int = 0) -> None:
    ...

另一方面，显式应用 None 值时，不管该参数是否可选， Optional 都适用。例如：

def foo(arg: Optional[int] = None) -> None:
    ...

在 3.10 版本发生变更: 可选参数现在可以写成 X | None。 参见 联合类型表达式。

typing.Concatenate

特殊形式，用于注解高阶函数。

Concatenate 可用于与 Callable 和 ParamSpec 连用来注解高阶可调用对象，该可象可以添加、移除或转换另一个可调用对象的形参。 使用形式为 Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]。 Concatenate 目前仅可用作传给 Callable 的第一个参数。传给 Concatenate 的最后一个形参必须是 ParamSpec 或省略号（ ... ）。

例如，为了注释一个装饰器 with_lock，它为被装饰的函数提供了 threading.Lock，Concatenate 可以用来表示 with_lock 期望一个可调用对象，该对象接收一个 Lock 作为第一个参数，并返回一个具有不同类型签名的可调用对象。 在这种情况下，ParamSpec 表示返回的可调用对象的参数类型取决于被传入的可调用程序的参数类型:

from collections.abc import Callable
from threading import Lock
from typing import Concatenate
# 使用此锁来确保在任何时候只有一个线程正在执行某个函数。
my_lock = Lock()
def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''A type-safe decorator which provides a lock.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # Provide the lock as the first argument.
        return f(my_lock, *args, **kwargs)
    return inner
@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''Add a list of numbers together in a thread-safe manner.'''
    with lock:
        return sum(numbers)
# 由于装饰器的存在，我们不需要自己传递锁。
sum_threadsafe([1.1, 2.2, 3.3])

Added in version 3.10.

参见

• PEP 612 — 参数规范变量（引入 ParamSpec 和 Concatenate 的 PEP）

• ParamSpec

• 标注可调用对象

typing.Literal

特殊类型注解形式，用于定义“字面值类型”。

Literal 可以用来向类型检查器说明被注解的对象具有与所提供的字面量之一相同的值。

例如：

def validate_simple(data: Any) -> Literal[True]:  # 总是返回 True
    ...
type Mode = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: Mode) -> str:
    ...
open_helper('/some/path', 'r')      # 通过类型检查
open_helper('/other/path', 'typo')  # 类型检查错误

Literal[...] 不能创建子类。在运行时，任意值均可作为 Literal[...] 的类型参数，但类型检查器可以对此加以限制。字面量类型详见 PEP 586 。

Added in version 3.8.

在 3.9.1 版本发生变更: Literal 现在能去除形参的重复。 Literal 对象的相等性比较不再依赖顺序。 现在如果有某个参数不为 hashable，Literal 对象在相等性比较期间将引发 TypeError。

typing.ClassVar

特殊类型注解构造，用于标注类变量。

如 PEP 526 所述，打包在 ClassVar 内的变量注解是指，给定属性应当用作类变量，而不应设置在类实例上。用法如下：

class Starship:
    stats: ClassVar[dict[str, int]] = {} # 类变量
    damage: int = 10                     # 实例变量

ClassVar 仅接受类型，也不能使用下标。

ClassVar 本身不是类，不应用于 isinstance() 或 issubclass()。ClassVar 不改变 Python 运行时行为，但可以用于第三方类型检查器。例如，类型检查器会认为以下代码有错：

enterprise_d = Starship(3000)
enterprise_d.stats = {} # 错误，在实例上设置类变量
Starship.stats = {}     # 这是可以的

Added in version 3.5.3.

在 3.13 版本发生变更: 现在 ClassVar 可以被嵌套在 Final 中，反之亦然。

typing.Final

特殊类型注解构造，用于向类型检查器表示最终名称。

不能在任何作用域中重新分配最终名称。类作用域中声明的最终名称不能在子类中重写。

例如：

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # 类型检查器将报告错误
class Connection:
    TIMEOUT: Final[int] = 10
class FastConnector(Connection):
    TIMEOUT = 1  # 类型检查器将报告错误

这些属性没有运行时检查。详见 PEP 591。

Added in version 3.8.

在 3.13 版本发生变更: 现在 Final 可以被嵌套在 ClassVar 中，反之亦然。

typing.Required

特殊类型注解构造，用于标记 TypedDict 键为必填项。

这主要用于 total=False 的 TypedDict。有关更多详细信息，请参阅 TypedDict 和 PEP 655 。

Added in version 3.11.

typing.NotRequired

特殊类型注解构造，用于标记 TypedDict 键为可能不存在的键。

详情参见 TypedDict 和 PEP 655。

Added in version 3.11.

typing.ReadOnly

一个特殊的类型标注构造，用于将 TypedDict 的项标记为只读。

例如：

class Movie(TypedDict):
   title: ReadOnly[str]
   year: int
def mutate_movie(m: Movie) -> None:
   m["year"] = 1999  # allowed
   m["title"] = "The Matrix"  # 类型检查错误

这个属性没有运行时检查。

详见 TypedDict 和 PEP 705。

Added in version 3.13.

typing.Annotated

特殊类型注解形式，用于向注解添加特定于上下文的元数据。

使用注解 Annotated[T, x] 将元数据 x 添加到给定类型 T 。使用 Annotated 添加的元数据可以被静态分析工具使用，也可以在运行时使用。在运行时使用的情况下，元数据存储在 __metadata__ 属性中。

如果库或工具遇到注解 Annotated[T, x] ，并且没有针对这一元数据的特殊处理逻辑，则应该忽略该元数据，简单地将注解视为 T 。因此， Annotated 对于希望将注解用于 Python 的静态类型注解系统之外的目的的代码很有用。

使用 Annotated[T, x] 作为注解仍然允许对 T 进行静态类型检查，因为类型检查器将简单地忽略元数据 x 。因此，Annotated 不同于 @no_type_check 装饰器，后者虽然也可以用于在类型注解系统范围之外添加注解，但是会完全禁用对函数或类的类型检查。

具体解释元数据的方式由遇到 Annotated 注解的工具或库来负责。遇到 Annotated 类型的工具或库可以扫描元数据的各个元素以确定其是否有意处理（比如使用 isinstance() ）。

• Annotated[<type>, <metadata>]

以下示例演示在进行区间范围分析时使用 Annotated 将元数据添加到类型注解的方法：

@dataclass
class ValueRange:
    lo: int
    hi: int
T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

语法细节：

• Annotated 的第一个参数必须是有效的类型。

• 可提供多个元数据的元素（ Annotated 支持可变参数）：

  @dataclass
  class ctype:
      kind: str
  Annotated[int, ValueRange(3, 10), ctype("char")]

  由处理注解的工具决定是否允许向一个注解中添加多个元数据元素，以及如何合并这些注解。

• Annotated 至少要有两个参数（ Annotated[int] 是无效的）

• 元数据元素的顺序会被保留，且影响等价检查：

  assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
      int, ctype("char"), ValueRange(3, 10)
  ]

• 嵌套的 Annotated 类型会被展平。元数据元素从最内层的注解开始依次展开：

  assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
      int, ValueRange(3, 10), ctype("char")
  ]

• 元数据中的重复元素不会被移除：

  assert Annotated[int, ValueRange(3, 10)] != Annotated[
      int, ValueRange(3, 10), ValueRange(3, 10)
  ]

• Annotated 可以与嵌套别名和泛型别名一起使用：

  @dataclass
  class MaxLen:
      value: int
  type Vec[T] = Annotated[list[tuple[T, T]], MaxLen(10)]
  # 当在类型注释中使用时，类型检查器会将“V”视为
  # ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
  type V = Vec[int]

• Annotated 不能与已解包的 TypeVarTuple 一起使用:

  type Variadic[*Ts] = Annotated[*Ts, Ann1]  # 不可用

  这等价于：

  Annotated[T1, T2, T3, ..., Ann1]

  其中 T1 、 T2 等都是 TypeVars 。这种写法无效：应当只有一个类型被传递给 Annotated。

• 默认情况下， get_type_hints() 会去除注解中的元数据。传入 include_extras=True 可以保留元数据：

  >>> from typing import Annotated, get_type_hints
  >>> def func(x: Annotated[int, "metadata"]) -> None: pass
  ...
  >>> get_type_hints(func)
  {'x': <class 'int'>, 'return': <class 'NoneType'>}
  >>> get_type_hints(func, include_extras=True)
  {'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

• 在运行时，与特定 Annotated 类型相关联的元数据可通过 __metadata__ 属性来获取：

  >>> from typing import Annotated
  >>> X = Annotated[int, "very", "important", "metadata"]
  >>> X
  typing.Annotated[int, 'very', 'important', 'metadata']
  >>> X.__metadata__
  ('very', 'important', 'metadata')

• 在运行时 ，如果要检索由 Annotated 封装的原始类型，请使用 __origin__ 属性：

  >>> from typing import Annotated, get_origin
  >>> Password = Annotated[str, "secret"]
  >>> Password.__origin__
  <class 'str'>

  请注意使用 get_origin() 将返回 Annotated 本身：

  >>> get_origin(Password)
  typing.Annotated

参见

• PEP 593 - 灵活的函数与变量标注

  该 PEP 将 Annotated 引入到标准库中。

Added in version 3.9.

typing.TypeIs

特殊类型注解构造，用于标记用户定义的谓词函数。

TypeIs 能用来注解用户定义的谓词函数的返回值类型。TypeIs 接受单个类型参数。如此标注的函数在运行时应当有至少一个位置参数，并且返回一个布尔值。

TypeIs 旨在方便 类型收窄 — 一个被静态类型检查器使用，用来更精准地决定程序代码流中表达式类型的技巧。通常类型收窄通过分析有条件的代码流并对代码块执行类型收窄实现。此处的条件表达式有时也被称为“类型谓词”。

def is_str(val: str | float):
    # "isinstance" 类型谓词
    if isinstance(val, str):
        #  ``val`` 的类型缩小为 ``str``
        ...
    else:
        # 否则， ``val`` 的类型缩小为 ``float``。
        ...

使用一个用户定义的布尔函数作为类型谓词有时很方便。这样的函数应当将 TypeIs[...] 或 TypeGuard 作为它的返回类型，以向静态类型检查器传达这个意图。TypeIs 的行为通常比 TypeGuard 更直观，但在函数的输入与输出类型不兼容 (例如从 list[object] 到 list[int]) 或函数不会对所有收窄后类型的实例返回 True 时不能使用。

使用 -> TypeIs[NarrowedType] 告诉静态类型检查器对于给定的函数：

1. 返回一个布尔值。

2. 如果返回值是 True，那么其参数的类型收窄到参数本身类型与 NarrowedType 的并。

3. 如果返回值是 False，那么其参数的类型收窄到排除 NarrowedType。

例如：

from typing import assert_type, final, TypeIs
class Parent: pass
class Child(Parent): pass
@final
class Unrelated: pass
def is_parent(val: object) -> TypeIs[Parent]:
    return isinstance(val, Parent)
def run(arg: Child | Unrelated):
    if is_parent(arg):
        # ``arg`` 的类型缩小为 ``Parent`` 和 ```Child`` 的交集，
        # 相当于 ``Child``.
        assert_type(arg, Child)
    else:
        # ``arg`` 的类型缩小为 ``Parent`` 除外，所以仅剩 ``Unrelated``。
        assert_type(arg, Unrelated)

TypeIs 内的类型必须与函数参数类型契合，否则静态类型检查器会引发错误。编写不正确的 TypeIs 可能导致类型系统中出现不健全行为，以类型安全的方式编写这些函数是用户的责任。

如果 TypeIs 函数是一个类或实例方法，那么 TypeIs 中的类型将映射到（在 cls 或 self 之后）第二个形参的类型。

简单来说，def foo(arg: TypeA) -> TypeIs[TypeB]: ... 意味着如果 foo(arg) 返回 True，那么 arg 就是 TypeB 的实例，如果返回 False，它就不是 TypeB.的实例。

TypeIs 同样可作用于类型变量，详见 PEP 742 (使用 TypeIs 收窄类型) 。

Added in version 3.13.

typing.TypeGuard

特殊类型注解构造，用于标记用户定义的谓词函数。

类型谓词函数是由用户定义的函数，它的返回值指示参数是否为某个特定类型的实例。TypeGuard 和 TypeIs 用法相近，但是对类型检查行为有不同的影响（如下）。

-> TypeGuard 告诉静态类型检查器，某函数：

1. 返回一个布尔值。

2. 如果返回值是 True，那么其参数的类型是 TypeGuard 内的类型。

TypeGuard 也适用于类型变量。 详情参见 PEP 647。

例如：

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''Determines whether all objects in the list are strings'''
    return all(isinstance(x, str) for x in val)
def func1(val: list[object]):
    if is_str_list(val):
        # ``val`` 的类型缩小为 ``list[str]``.
        print(" ".join(val))
    else:
        # ``val`` 的类型仍为 ``list[object]``.
        print("Not a list of strings!")

TypeIs 和 TypeGuard 有以下不同：

• TypeIs 要求收窄的类型是输入类型的子类型，但 TypeGuard 不要求。这主要是为了允许将 list[object] 缩小为 list[str]，即使后者不是前者的子类型，因为 list 是不变的。

• 当 TypeGuard 函数返回 True 时，类型检查器会将变量的类型精确地收窄到 TypeGuard 类型。当 TypeIs 函数返回 True 时，类型检查程序可以结合先前已知的变量类型和 TypeIs 类型推断出更精确的类型。（从技术上讲，这叫做交类型。）

• 当 TypeGuard 函数返回 False 时，类型检查器不会收窄变量的类型范围。当 TypeIs 函数返回 False 时，类型检查器可以收窄变量的类型范围至排除 TypeIs 类型。

Added in version 3.10.

typing.Unpack

在概念上将对象标记为已解包的类型运算符。

例如，在一个 类型变量元组 上使用解包运算符 * 就等价于使用 Unpack 来将该类型变量元组标记为已被解包:

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# 实际所做的：
tup: tuple[Unpack[Ts]]

实际上，Unpack 在 typing.TypeVarTuple 和 builtins.tuple 类型的上下文中可以和 * 互换使用。 你可能会看到 Unpack 在较旧版本的 Python 中被显式地使用，这时 * 在特定场合则是无法使用的:

# 在旧版本的 Python 中，TypeVarTuple 和 Unpack 位于
# `typing_extensions` 反向移植包中。
from typing_extensions import TypeVarTuple, Unpack
Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Python <= 3.10 时的语法错误！
tup: tuple[Unpack[Ts]]  # 语义等效且向后兼容

Unpack 也可以与 typing.TypedDict 一起使用以便在函数签名中对 **kwargs 进行类型标注:

from typing import TypedDict, Unpack
class Movie(TypedDict):
    name: str
    year: int
# 此函数需要两个关键字参数 -
# 类型为 `str` 的 `name` 和类型为 `int` 的 `year`。
def foo(**kwargs: Unpack[Movie]): ...

请参阅 PEP 692 了解将 Unpack 用于 **kwargs 类型标注的更多细节。

Added in version 3.11.

构造泛型类型与类型别名

下列类不应被直接用作标注。 它们的设计目标是作为创建泛型类型和类型别名的构件。

这些对象可通过特殊语法 (类型形参列表 和 type 语句) 来创建。 为了与 Python 3.11 及更早版本的兼容性，它们也可不用专门的语法来创建，如下文所述。

class typing.Generic

用于泛型类型的抽象基类。

泛型类型通常是通过在类名后添加一个类型形参列表来声明的:

class Mapping[KT, VT]:
    def __getitem__(self, key: KT) -> VT:
        ...
        # 其他

这样的类将隐式地继承自 Generic。 对于该语法的运行语义的讨论参见 语言参考。

该类的用法如下：

def lookup_name[X, Y](mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default

此处函数名之后的圆括号是表示 泛型函数。

为了保持向下兼容性，泛型类也可通过显式地继承自 Generic 来声明。 在此情况下，类型形参必须单独声明:

KT = TypeVar('KT')
VT = TypeVar('VT')
class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # 其他

class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)

类型变量。

构造类型变量的推荐方式是使用针对 泛型函数, 泛型类 和 泛型类型别名 的专门语法:

class Sequence[T]:  # T 是一个 TypeVar
    ...

此语法也可被用于创建绑定和带约束的类型变量:

class StrSequence[S: str]:  # S 是一个绑定到 str 的 TypeVar
    ...
class StrOrBytesSequence[A: (str, bytes)]:  # A 是一个 TypeVar constrained to str or bytes
    ...

不过，如有需要，也可通过手动方式来构造可重用的类型变量，就像这样:

T = TypeVar('T')  # 可以是任意类型
S = TypeVar('S', bound=str)  # 可以是任意 str 的子类型
A = TypeVar('A', str, bytes)  # 必须是 str 或 bytes

类型变量的主要用处是为静态类型检查器提供支持。 它们可作为泛型类型以及泛型函数和类型别名定义的形参。 请参阅 Generic 了解有关泛型类型的更多信息。 泛型函数的作用方式如下:

def repeat[T](x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n
def print_capitalized[S: str](x: S) -> S:
    """Print x capitalized, and return x."""
    print(x.capitalize())
    return x
def concatenate[A: (str, bytes)](x: A, y: A) -> A:
    """Add two strings or bytes objects together."""
    return x + y

请注意，类型变量可以是 被绑定的 ， 被约束的 ，或者两者都不是，但不能既是被绑定的 又是 被约束的。

类型变量的种类是在其通过 类型形参语法 创建时或是在传入 infer_variance=True 时由类型检查器推断得到的。 手动创建的类型变量可通过传入 covariant=True 或 contravariant=True 被显式地标记为协变或逆变。 在默认情况下，手动创建的类型变量为不变。 请参阅 PEP 484 和 PEP 695 了解更多细节。

绑定类型变量和约束类型变量在几个重要方面具有不同的主义。 使用 绑定 类型变量意味着 TypeVar 将尽可能使用最为专属的类型来解析:

x = print_capitalized('a string')
reveal_type(x)  # 显示的类型是 str
class StringSubclass(str):
    pass
y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # 显示的类型是 StringSubclass
z = print_capitalized(45)  # 错误：int 不是 str 的子类型

类型变量可以被绑定到具体类型、抽象类型（ ABC 或 protocol ），甚至是类型的联合:

# 可以是任何具有 __abs__ 方法的内容
def print_abs[T: SupportsAbs](arg: T) -> None:
    print("Absolute value:", abs(arg))
U = TypeVar('U', bound=str|bytes)  # 可以是联合 str|bytes 的任何子类型
V = TypeVar('V', bound=SupportsAbs)  # 可以是任何具有 __abs__ 方法的内容

但是，如果使用 约束 类型变量，则意味着 TypeVar 只能被解析为恰好是给定的约束之一:

a = concatenate('one', 'two')
reveal_type(a)  # 揭示的类型为 str
b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # 揭示的类型为 str，虽然传入的是 StringSubclass
c = concatenate('one', b'two')  # 错误：在一个函数调用中类型变量 'A' 可以为 str 或 bytes，但不可同时使用

在运行时，isinstance(x, T) 将引发 TypeError。

• __name__

  类型变量的名称。

• __covariant__

  类型变量是否已被显式地标记为 covariant。

• __contravariant__

  类型变量是否已被显式地标记为 contravariant。

• __infer_variance__

  类型变量的种类是否应由类型检查器来推断。

  Added in version 3.12.

• __bound__

  类型变量的绑定，如果有的话。

  在 3.12 版本发生变更: 对于通过 类型形参语法 创建的类型变量，只有在属性被访问的时候才会对绑定求值，而不是在类型变量被创建的时候 (参见 惰性求值)。

• __constraints__

  一个包含对类型变量的约束的元组，如果有的话。A tuple containing the constraints of the type variable, if any.

  在 3.12 版本发生变更: 对于通过 类型形参语法 创建的类型变量，只有在属性被访问的时候才会对约束求值，而不是在类型变量被创建的时候 (参见 惰性求值)。

• __default__

  类型变量的默认值，如果没有默认值，则为 typing.NoDefault。

  Added in version 3.13.

• has_default()

  返回类型变量是否有默认值。它等价于检查 __default__ 是否为 typing.NoDefault 单例，但它不要求对 惰性求值 的默认值求值。

  Added in version 3.13.

在 3.12 版本发生变更: 类型变量现在可以通过使用 PEP 695 引入的 类型形参 语法来声明。 增加了 infer_variance 形参。

在 3.13 版本发生变更: 增加了对默认值的支持。

class typing.TypeVarTuple(name, *, default=typing.NoDefault)

类型变量元组。 一种启用了 variadic 泛型的专属 类型变量 形式。

类型变量元组可以通过在 类型形参列表 中使用名称前的单个星号 (*) 来声明:

def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

或者通过显式地发起调用 TypeVarTuple 构造器:

T = TypeVar("T")
Ts = TypeVarTuple("Ts")
def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

一个普通类型变量将启用单个类型的形参化。 作为对比，一个类型变量元组通过将 任意 数量的类型变量封包在一个元组中来允许 任意 数量类型的形参化。 例如:

# T 绑定到 int，Ts 绑定到 ()
# 返回值为 (1,)，其类型为 tuple[int]
move_first_element_to_last(tup=(1,))
# T 绑定到 int，Ts 绑定到 (str,)
# 返回值为 ('spam', 1)，其类型为 tuple[str, int]
move_first_element_to_last(tup=(1, 'spam'))
# T 绑定到 int，Ts 绑定到 (str, float)
# 返回值为 ('spam', 3.0, 1)，其类型为 tuple[str, float, int]
move_first_element_to_last(tup=(1, 'spam', 3.0))
# 这不能通过类型检查（并会在运行时执行失败）
# 因为 tuple[()] 与 tuple[T, *Ts] 不兼容
# （至少需要有一个元素）
move_first_element_to_last(tup=())

请注意解包运算符 * 在 tuple[T, *Ts] 中的使用。 在概念上，你可以将 Ts 当作一个由类型变量组成的元组 (T1, T2, ...)。 那么 tuple[T, *Ts] 就将变为 tuple[T, *(T1, T2, ...)]，这等价于 tuple[T, T1, T2, ...]。 （请注意在旧版本 Python 中，你可能会看到改用 Unpack 的写法，如 Unpack[Ts]。）

类型变量元组 总是 要被解包。 这有助于区分类型变量元组和普通类型变量:

x: Ts          # 不可用
x: tuple[Ts]   # 不可用
x: tuple[*Ts]  # 正确的做法

类型变量元组可被用在与普通类型变量相同的上下文中。 例如，在类定义、参数和返回类型中:

class Array[*Shape]:
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Array[*Shape]": ...
    def get_shape(self) -> tuple[*Shape]: ...

类型变量元组可以很好地与普通类型变量结合在一起：

class Array[DType, *Shape]:  # 这样可以
    pass
class Array2[*Shape, DType]:  # 这样也可以
    pass
class Height: ...
class Width: ...
float_array_1d: Array[float, Height] = Array()     # 完全可以
int_array_2d: Array[int, Height, Width] = Array()  # 是的，同样可以

但是，请注意在一个类型参数或类型形参列表中最多只能有一个类型变量元组:

x: tuple[*Ts, *Ts]            # 不可用
class Array[*Shape, *Shape]:  # 不可用
    pass

最后，一个已解包的类型变量元组可以被用作 *args 的类型标注:

def call_soon[*Ts](
    callback: Callable[[*Ts], None],
    *args: *Ts
) -> None:
    ...
    callback(*args)

相比非解包的 *args 标注 —— 例如 *args: int，它将指明 所有 参数均为 int —— *args: *Ts 启用了对 *args 中 单个 参数的类型的引用。 在此，这允许我们确保传入 call_soon 的 *args 的类型与 callback 的（位置）参数的类型相匹配。

关于类型变量元组的更多细节，请参见 PEP 646。

• __name__

  类型变量元组的名称。

• __default__

  类型变量元组的默认值，如果没有默认值，则为 typing.NoDefault。

  Added in version 3.13.

• has_default()

  返回类型变量元组是否有默认值。它等价于检查 __default__ 是否为 typing.NoDefault 单例，但它不要求对 惰性求值 的默认值求值。

  Added in version 3.13.

Added in version 3.11.

在 3.12 版本发生变更: 类型变量元组现在可以使用 PEP 695 所引入的 类型形参 语法来声明。

在 3.13 版本发生变更: 增加了对默认值的支持。

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False, default=typing.NoDefault)

形参专属变量。 类型变量 的一个专用版本。

In 类型形参列表，形参规格可以使用两个星号 (**) 来声明:

type IntFunc[**P] = Callable[P, int]

为了保持与 Python 3.11 及更早版本的兼容性，ParamSpec 对象也可以这样创建:

P = ParamSpec('P')

参数规范变量的存在主要是为了使静态类型检查器受益。 它们被用来将一个可调用对象的参数类型转发给另一个可调用对象的参数类型——这种模式通常出现在高阶函数和装饰器中。 它们只有在 Concatenate 中使用时才有效，或者作为 Callable 的第一个参数，或者作为用户定义的泛型的参数。 参见 Generic 以了解更多关于泛型的信息。

例如，为了给一个函数添加基本的日志记录，我们可以创建一个装饰器 add_logging 来记录函数调用。 参数规范变量告诉类型检查器，传入装饰器的可调用对象和由其返回的新可调用对象有相互依赖的类型参数:

from collections.abc import Callable
import logging
def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
    '''A type-safe decorator to add logging to a function.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner
@add_logging
def add_two(x: float, y: float) -> float:
    '''Add two numbers together.'''
    return x + y

如果没有 ParamSpec，以前注释这个的最简单的方法是使用一个 TypeVar 与绑定 Callable[..., Any]。

1. 类型检查器不能对 inner 函数进行类型检查，因为 *args 和 **kwargs 的类型必须是 Any。

2. cast() 在返回 inner 函数时，可能需要在 add_logging 装饰器的主体中进行，或者必须告诉静态类型检查器忽略 return inner。

• args

• kwargs

  由于 ParamSpec 同时捕获了位置参数和关键字参数，P.args 和 P.kwargs 可以用来将 ParamSpec 分割成其组成部分。 P.args 代表给定调用中的位置参数的元组，只能用于注释 *args。 P.kwargs 代表给定调用中的关键字参数到其值的映射，只能用于注释 **kwargs。在运行时，P.args 和 P.kwargs 分别是 ParamSpecArgs 和 ParamSpecKwargs 的实例。

• __name__

  形参规格的名称。

• __default__

  形参规格的默认值，如果没有默认值，则为 typing.NoDefault。

  Added in version 3.13.

• has_default()

  返回形参规格是否有默认值。它等价于检查 __default__ 是否为 typing.NoDefault 单例，但它不要求对 惰性求值 的默认值求值。

  Added in version 3.13.

用 covariant=True 或 contravariant=True 创建的参数规范变量可以用来声明协变或逆变泛型类型。 参数 bound 也被接受，类似于 TypeVar。 然而这些关键字的实际语义还有待决定。

Added in version 3.10.

在 3.12 版本发生变更: 形参说明现在可以使用 PEP 695 所引入的 类型形参 语法来声明。

在 3.13 版本发生变更: 增加了对默认值的支持。

备注

只有在全局范围内定义的参数规范变量可以被 pickle。

参见

• PEP 612 — 参数规范变量（引入 ParamSpec 和 Concatenate 的 PEP）

• Concatenate

• 标注可调用对象

typing.ParamSpecArgs

typing.ParamSpecKwargs

ParamSpec`的参数和关键字参数属性。``ParamSpec` 的 P.args 属性是 ParamSpecArgs 的一个实例，P.kwargs 是 ParamSpecKwargs 的一个实例。 它们的目的是用于运行时内部检查的，对静态类型检查器没有特殊意义。

在这些对象中的任何一个上调用 get_origin() 将返回原始的 ParamSpec:

>>> from typing import ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) is P
True
>>> get_origin(P.kwargs) is P
True

Added in version 3.10.

class typing.TypeAliasType(name, value, *, type_params=())

通过 type 语句创建的类型别名的类型。

示例:

>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>

Added in version 3.12.

• __name__

  类型别名的名称：

  >>> type Alias = int
  >>> Alias.__name__
  'Alias'

• __module__

  类型别名定义所在的模块名称:

  >>> type Alias = int
  >>> Alias.__module__
  '__main__'

• __type_params__

  类型别名的类型形参，或者如果别名不属于泛型则为一个空元组:

  >>> type ListOrSet[T] = list[T] | set[T]
  >>> ListOrSet.__type_params__
  (T,)
  >>> type NotGeneric = int
  >>> NotGeneric.__type_params__
  ()

• __value__

  类型别名的值。 它将被 惰性求值，因此别名定义中使用的名称将直到 __value__ 属性被访问时才会被解析:

  >>> type Mutually = Recursive
  >>> type Recursive = Mutually
  >>> Mutually
  Mutually
  >>> Recursive
  Recursive
  >>> Mutually.__value__
  Recursive
  >>> Recursive.__value__
  Mutually

其他特殊指令

这些函数和类不应被直接用作标注。 它们的设计目标是作为创建和声明类型的构件。

class typing.NamedTuple

collections.namedtuple() 的类型版本。

用法：

class Employee(NamedTuple):
    name: str
    id: int

这相当于：

Employee = collections.namedtuple('Employee', ['name', 'id'])

为字段提供默认值，要在类体内赋值：

class Employee(NamedTuple):
    name: str
    id: int = 3
employee = Employee('Guido')
assert employee.id == 3

带默认值的字段必须在不带默认值的字段后面。

由此产生的类有一个额外的属性 __annotations__ ，给出一个 dict ，将字段名映射到字段类型。（字段名在 _fields 属性中，默认值在 _field_defaults 属性中，这两者都是 namedtuple() API 的一部分。）

NamedTuple 子类也支持文档字符串与方法：

class Employee(NamedTuple):
    """代表一位雇员。"""
    name: str
    id: int = 3
    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

NamedTuple 子类也可以为泛型：

class Group[T](NamedTuple):
    key: T
    group: list[T]