typing —— 对类型提示的支持

typing —— 对类型提示的支持

3.5 新版功能.

备注

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

本模块提供对类型提示的运行时支持。对于类型系统的原始说明，请参阅 PEP 484。一个更简明的介绍是 PEP 483。

下面的函数接收与返回的都是字符串，注解方式如下：

def greeting(name: str) -> str:
    return 'Hello ' + name

greeting 函数中，参数 name 的类型应是 str，返回类型是 str。子类型也可以作为参数。

新的功能频繁地被添加到 typing 模块中。typing_extensions 包提供了这些新功能对旧版本 Python 的向后移植。

要获取已弃用特性及其弃用时间线的概要，请参阅 Deprecation Timeline of Major Features。

参见

“类型系统备忘单”

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

mypy 文档的 “Type System Reference” 章节

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

“Static Typing with Python”

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

类型别名

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

type Vector = list[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

## passes type checking; a list of floats qualifies as a 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:
    ...

## The static type checker will treat the previous type signature as
## being exactly equivalent to this one.
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:
    ...

## passes type checking
user_a = get_user_name(UserId(42351))

## fails type checking; an int is not a UserId
user_b = get_user_name(-1)

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

## 'output' is of type 'int', not '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)

## Fails at runtime and does not pass type checking
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 类型的位置。这种方式适用于以最小运行时成本防止逻辑错误。

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:
    ...  # Body

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    ...  # Body

async def on_update(value: str) -> None:
    ...  # Body

callback: Callable[[str], Awaitable[None]] = on_update

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

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

def concat(x: str, y: str) -> str:
    return x + y

x: Callable[..., str]
x = str     # OK
x = concat  # Also OK

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)  # OK
batch_proc([], bad_cb)   # Error! Argument 2 has incompatible type because of
                         # different name and kind in the callback

以其他可调用对象为参数的可调用对象可以使用 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] indicates that all elements in the sequence
## must be instances of "Employee".
## Mapping[str, str] indicates that all keys and all values in the mapping
## must be strings.
def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

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

from collections.abc import Sequence

def first[T](l: Sequence[T]) -> T:  # Function is generic over the TypeVar "T"
    return l[0]

或直接使用 TypeVar 工厂：

from collections.abc import Sequence
from typing import TypeVar

U = TypeVar('U')                  # Declare type variable "U"

def second(l: Sequence[U]) -> U:  # Function is generic over the TypeVar "U"
    return l[1]

在 3.12 版更改: 对泛型的语法支持是在 Python 3.12 中新增的。

标注元组

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

from collections.abc import Mapping

## Type checker will infer that all elements in ``x`` are meant to be ints
x: list[int] = []

## Type checker error: ``list`` only accepts a single type argument:
y: list[int, str] = [1, 'foo']

## Type checker will infer that all keys in ``z`` are meant to be strings,
## and that all values in ``z`` are meant to be either strings or ints
z: Mapping[str, str | int] = {}

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

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

## OK: ``x`` is assigned to a tuple of length 1 where the sole element is an int
x: tuple[int] = (5,)

## OK: ``y`` is assigned to a tuple of length 2;
## element 1 is an int, element 2 is a str
y: tuple[int, str] = (5, "foo")

## Error: the type annotation indicates a tuple of length 1,
## but ``z`` has been assigned to a tuple of length 3
z: tuple[int] = (1, 2, 3)

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

x: tuple[int, ...] = (1, 2)
## These reassignments are OK: ``tuple[int, ...]`` indicates x can be of any length
x = (1, 2, 3)
x = ()
## This reassignment is an error: all elements in ``x`` must be ints
x = ("foo", "bar")

## ``y`` can only ever be assigned to an empty tuple
y: tuple[()] = ()

z: tuple = ("foo", "bar")
## These reassignments are OK: plain ``tuple`` is equivalent to ``tuple[Any, ...]``
z = (1, 2, 3)
z = ()

类对象的类型

用 C 注解的变量可以接受类型 C 的值。然而，用类型 type[C] （或者 typing.Type[C] ）注解的变量则可以接受本身是类的值——准确地说，是接受 C 的 类对象 。例如：

a = 3         # Has type ``int``
b = int       # Has type ``type[int]``
c = type(a)   # Also has type ``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)      # OK
make_new_user(ProUser)   # Also OK: ``type[ProUser]`` is a subtype of ``type[User]``
make_new_user(TeamUser)  # Still fine
make_new_user(User())    # Error: expected ``type[User]`` but got ``User``
make_new_user(int)       # Error: ``type[int]`` is not a subtype of ``type[User]``

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

def new_non_team_user(user_class: type[BasicUser | ProUser]): ...

new_non_team_user(BasicUser)  # OK
new_non_team_user(ProUser)    # OK
new_non_team_user(TeamUser)   # Error: ``type[TeamUser]`` is not a subtype
                              # of ``type[BasicUser | ProUser]``
new_non_team_user(User)       # Also an error

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

用户定义的泛型类型

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

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 使用单个类型变量 type variable <TypeVar>``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]):   # INVALID
    ...

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

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): # Same as Iterable[Any]
    ...

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

from collections.abc import Iterable

type Response[S] = Iterable[S] | int

## Return type here is same as 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: # Same as 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 is a TypeVar; P is a 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 = []          # OK
a = 2           # OK

s: str = ''
s = a           # OK

def foo(item: Any) -> int:
    # Passes type checking; 'item' could be any type,
    # and that type might have a 'bar' method
    item.bar()
    ...

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

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

def legacy_parser(text):
    ...
    return data

## A static type checker will treat the above
## as having the same signature as:
def legacy_parser(text: Any) -> Any:
    ...
    return data

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

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

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

def hash_a(item: object) -> int:
    # Fails type checking; an object does not have a 'magic' method.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Passes type checking
    item.magic()
    ...

## Passes type checking, since ints and strs are subclasses of object
hash_a(42)
hash_a("foo")

## Passes type checking, since Any is compatible with all types
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:  # Note: no base classes
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Passes type check

此外，结构子类型的优势在于，通过继承特殊类 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")    # OK, output has type 'str'
concat(b"foo", b"bar")  # OK, output has type 'bytes'
concat("foo", b"bar")   # Error, cannot mix str and bytes

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

## Invalid use of AnyStr:
## The type variable is used only once in the function signature,
## so cannot be "solved" by the type checker
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

## The better way of annotating this function:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"

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")  # OK
    run_query(literal_string)  # OK
    run_query("SELECT * FROM " + literal_string)  # OK
    run_query(arbitrary_string)  # type checker error
    run_query(  # type checker error
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

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

请参阅 PEP 675 了解详情。

3.11 新版功能.

typing.Never

底类型，一个没有成员的类型。

这可以用于定义一个永不应该被调用的函数，或一个永不返回的函数：

from typing import Never

def never_call_me(arg: Never) -> None:
    pass

def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # type checker error
    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

3.11 新版功能: 在更老的 Python 版本上，NoReturn 可被用于表达相同的概念。 Never 为了更显式地表达这个意图被加入。

typing.NoReturn

特殊类型，表示永不返回的函数。

例如：

from typing import NoReturn

def stop() -> NoReturn:
    raise RuntimeError('no way')

NoReturn 也可以用于底类型的定义，这是一种没有值的类型。自从 Python 3.11 开始，应该使用 Never 类型代替这个概念。类型检查器应该将这两种类型视为等价。

3.5.4 新版功能.

3.6.2 新版功能.

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())  # Revealed type is "Foo"
reveal_type(SubclassOfFoo().return_self())  # Revealed type is "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 would be an incorrect return annotation here,
    # as the object returned is always an instance of Eggs,
    # even in subclasses
    def returns_eggs(self) -> "Eggs":
        return Eggs()

更多细节请参见 PEP 673。

3.11 新版功能.

typing.TypeAlias

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

例如：

from typing import TypeAlias

Factors: TypeAlias = list[int]

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

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

## "Box" does not exist yet,
## so we have to use quotes for the forward reference on Python <3.12.
## Using ``TypeAlias`` tells the type checker that this is a type alias declaration,
## not a variable assignment to a string.
BoxOfStrings: TypeAlias = "Box[str]"

class Box(Generic[T]):
    @classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...

请参阅 PEP 613 了解详情。

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  # The constructor actually returns 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, ParamSpec, TypeVar

P = ParamSpec('P')
R = TypeVar('R')

## Use this lock to ensure that only one thread is executing a function
## at any time.
my_lock = Lock()

def with_lock(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)

## We don't need to pass in the lock ourselves thanks to the decorator.
sum_threadsafe([1.1, 2.2, 3.3])

3.10 新版功能.

参见

PEP 612 — 参数规范变量（引入 ParamSpec 和 Concatenate 的 PEP）
ParamSpec
标注可调用对象

typing.Literal

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

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

例如：

def validate_simple(data: Any) -> Literal[True]:  # always returns True
    ...

type Mode = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: Mode) -> str:
    ...

open_helper('/some/path', 'r')      # Passes type check
open_helper('/other/path', 'typo')  # Error in type checker

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

3.8 新版功能.

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

typing.ClassVar

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

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

class Starship:
    stats: ClassVar[dict[str, int]] = {} # class variable
    damage: int = 10                     # instance variable

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

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

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Error, setting class variable on instance
Starship.stats = {}     # This is OK

3.5.3 新版功能.

typing.Final

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

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

例如：

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # Error reported by type checker

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # Error reported by type checker

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

3.8 新版功能.

typing.Required

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

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

3.11 新版功能.

typing.NotRequired

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

详情参见 TypedDict 和 PEP 655。

3.11 新版功能.

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)]

## When used in a type annotation, a type checker will treat "V" the same as
## ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
type V = Vec[int]

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

type Variadic[*Ts] = Annotated[*Ts, Ann1]  # NOT valid

这等价于：

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')

参见

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

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

3.9 新版功能.

typing.TypeGuard

用于标记用户自定义类型防护函数的特殊类型构造。

TypeGuard can be used to annotate the return type of a user-defined type guard function. TypeGuard only accepts a single type argument. At runtime, functions marked this way should return a boolean.

PX旨在使 类型缩小 受益—这是静态类型检查器用来确定程序代码流中表达式的更精确类型的一种技术。通常，类型缩小是通过分析条件性代码流并将缩小的结果应用于一个代码块来完成的。这里的条件表达式有时被称为 “类型保护”:

def is_str(val: str | float):
    # "isinstance" type guard
    if isinstance(val, str):
        # Type of ``val`` is narrowed to ``str``
        ...
    else:
        # Else, type of ``val`` is narrowed to ``float``.
        ...

有时，使用一个用户定义的布尔函数作为类型保护会很方便。这样的函数应该使用 TypeGuard[...] 作为其返回类型，以提醒静态类型检查器注意这一意图。

对于一个给定的函数，使用 -> TypeGuard 告诉静态类型检查器:

返回值是一个布尔值。
如果返回值是 True，其参数的类型是 TypeGuard 里面的类型。

例如：

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):
        # Type of ``val`` is narrowed to ``list[str]``.
        print(" ".join(val))
    else:
        # Type of ``val`` remains as ``list[object]``.
        print("Not a list of strings!")

如果 is_str_list 是一个类或实例方法，那么 TypeGuard 中的类型映射到 cls 或 self 之后的第二个参数的类型。

简而言之，def foo(arg: TypeA) -> TypeGuard[TypeB]: ... 形式的意思是：如果 foo(arg) 返回 True，那么 arg 将把 TypeA 缩小为 TypeB。

备注

TypeB 无需为 TypeA 的缩小形式 — 它甚至可以是扩大形式。主要原因是允许像把 list[object] 缩小到 list[str] 这样的事情，即使后者不是前者的一个子类型，因为 list 是不变的。编写类型安全的类型防护的责任留给了用户。

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

3.10 新版功能.

typing.Unpack

Typing operator to conceptually mark an object as having been unpacked.

For example, using the unpack operator * on a type variable tuple is equivalent to using Unpack to mark the type variable tuple as having been unpacked:

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
## Effectively does:
tup: tuple[Unpack[Ts]]

In fact, Unpack can be used interchangeably with * in the context of typing.TypeVarTuple and builtins.tuple types. You might see Unpack being used explicitly in older versions of Python, where * couldn’t be used in certain places:

## In older versions of Python, TypeVarTuple and Unpack
## are located in the `typing_extensions` backports package.
from typing_extensions import TypeVarTuple, Unpack

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Syntax error on Python <= 3.10!
tup: tuple[Unpack[Ts]]  # Semantically equivalent, and backwards-compatible

Unpack can also be used along with typing.TypedDict for typing **kwargs in a function signature:

from typing import TypedDict, Unpack

class Movie(TypedDict):
    name: str
    year: int

## This function expects two keyword arguments - `name` of type `str`
## and `year` of type `int`.
def foo(**kwargs: Unpack[Movie]): ...

See PEP 692 for more details on using Unpack for **kwargs typing.

3.11 新版功能.

构造泛型类型与类型别名

The following classes should not be used directly as annotations. Their intended purpose is to be building blocks for creating generic types and type aliases.

These objects can be created through special syntax (type parameter lists and the type statement). For compatibility with Python 3.11 and earlier, they can also be created without the dedicated syntax, as documented below.

class typing.Generic

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

A generic type is typically declared by adding a list of type parameters after the class name:

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

Such a class implicitly inherits from Generic. The runtime semantics of this syntax are discussed in the Language Reference.

该类的用法如下：

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

Here the brackets after the function name indicate a generic function.

For backwards compatibility, generic classes can also be declared by explicitly inheriting from Generic. In this case, the type parameters must be declared separately:

KT = TypeVar('KT')
VT = TypeVar('VT')

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

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

类型变量。

The preferred way to construct a type variable is via the dedicated syntax for generic functions, generic classes, and generic type aliases:

class Sequence[T]:  # T is a TypeVar
    ...

This syntax can also be used to create bound and constrained type variables:

class StrSequence[S: str]:  # S is a TypeVar bound to str
    ...

class StrOrBytesSequence[A: (str, bytes)]:  # A is a TypeVar constrained to str or bytes
    ...

However, if desired, reusable type variables can also be constructed manually, like so:

T = TypeVar('T')  # Can be anything
S = TypeVar('S', bound=str)  # Can be any subtype of str
A = TypeVar('A', str, bytes)  # Must be exactly str or bytes

Type variables exist primarily for the benefit of static type checkers. They serve as the parameters for generic types as well as for generic function and type alias definitions. See Generic for more information on generic types. Generic functions work as follows:

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

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

The variance of type variables is inferred by type checkers when they are created through the type parameter syntax or when infer_variance=True is passed. Manually created type variables may be explicitly marked covariant or contravariant by passing covariant=True or contravariant=True. By default, manually created type variables are invariant. See PEP 484 and PEP 695 for more details.

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

x = print_capitalized('a string')
reveal_type(x)  # revealed type is str

class StringSubclass(str):
    pass

y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # revealed type is StringSubclass

z = print_capitalized(45)  # error: int is not a subtype of str

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

## Can be anything with an __abs__ method
def print_abs[T: SupportsAbs](arg: T) -> None:
    print("Absolute value:", abs(arg))

U = TypeVar('U', bound=str|bytes)  # Can be any subtype of the union str|bytes
V = TypeVar('V', bound=SupportsAbs)  # Can be anything with an __abs__ method

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

a = concatenate('one', 'two')
reveal_type(a)  # revealed type is str

b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # revealed type is str, despite StringSubclass being passed in

c = concatenate('one', b'two')  # error: type variable 'A' can be either str or bytes in a function call, but not both

At runtime, isinstance(x, T) will raise TypeError.

name

The name of the type variable.

covariant

Whether the type var has been explicitly marked as covariant.

contravariant

Whether the type var has been explicitly marked as contravariant.

infer_variance

Whether the type variable’s variance should be inferred by type checkers.

3.12 新版功能.

bound

The bound of the type variable, if any.

在 3.12 版更改: For type variables created through type parameter syntax, the bound is evaluated only when the attribute is accessed, not when the type variable is created (see 惰性求值).

constraints

A tuple containing the constraints of the type variable, if any.

在 3.12 版更改: For type variables created through type parameter syntax, the constraints are evaluated only when the attribute is accessed, not when the type variable is created (see 惰性求值).

在 3.12 版更改: Type variables can now be declared using the type parameter syntax introduced by PEP 695. The infer_variance parameter was added.

class typing.TypeVarTuple(name)

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

Type variable tuples can be declared in type parameter lists using a single asterisk (*) before the name:

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

Or by explicitly invoking the TypeVarTuple constructor:

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 is bound to int, Ts is bound to ()

Return value is (1,), which has type tuple[int]

move_first_element_to_last(tup=(1,))

T is bound to int, Ts is bound to (str,)

Return value is ('spam', 1), which has type tuple[str, int]

move_first_element_to_last(tup=(1, 'spam'))

T is bound to int, Ts is bound to (str, float)

Return value is ('spam', 3.0, 1), which has type tuple[str, float, int]

move_first_element_to_last(tup=(1, 'spam', 3.0))

This fails to type check (and fails at runtime)

because tuple[()] is not compatible with tuple[T, *Ts]

（本文超出站点单文档体积上限，已按小节截断）

typing —— 对类型提示的支持

typing —— 对类型提示的支持