`typing` — 支持类型提示 ¶

3.5 版新增。

注意

Python 运行时不强迫函数和变量类型注解。可以使用它们通过第 3 方工具，譬如：类型检查器、IDE、linter 等。

此模块提供运行时支持为类型提示作为指定通过 PEP 484 , PEP 526 , PEP 544 , PEP 586 , PEP 589 ，和 PEP 591 。最基础支持包含类型 Any , Union , Tuple , Callable , TypeVar ，和 Generic 。对于完整规范，请参阅 PEP 484 。对于类型提示的简化介绍，见 PEP 483 .

以下函数接受并返回字符串，注解如下：

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

在函数 greeting ，自变量 name 期望为类型 str 和返回类型 str 。子类型被接受作为自变量。

类型别名 ¶

类型别名是通过对类型赋值别名来定义的。在此范例中， Vector and List[float] 将被视为可互换的同义词：

from typing import List
Vector = List[float]
def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]
# typechecks; a list of floats qualifies as a Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

类型别名很有用为简化复杂类型签名。例如：

from typing import Dict, Tuple, Sequence
ConnectionOptions = Dict[str, str]
Address = Tuple[str, int]
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:
    ...

注意， None 作为类型提示是特殊情况且替换通过 type(None) .

NewType ¶

使用 NewType() 帮手函数以创建截然不同的类型：

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

The static type checker will treat the new type as if it were a subclass of the original type. This is useful in helping catch logical errors:

def get_user_name(user_id: UserId) -> str:
    ...
# typechecks
user_a = get_user_name(UserId(42351))
# does not typecheck; an int is not a UserId
user_b = get_user_name(-1)

可以仍然履行所有 int operations on a variable of type UserId , but the result will always be of type int . This lets you pass in a UserId wherever an int might be expected, but will prevent you from accidentally creating a UserId in an invalid way:

# 'output' is of type 'int', not 'UserId'
output = UserId(23413) + UserId(54341)

Note that these checks are enforced only by the static type checker. At runtime, the statement Derived = NewType('Derived', Base) will make Derived a function that immediately returns whatever parameter you pass it. That means the expression Derived(some_value) does not create a new class or introduce any overhead beyond that of a regular function call.

More precisely, the expression some_value is Derived(some_value) is always true at runtime.

This also means that it is not possible to create a subtype of Derived since it is an identity function at runtime, not an actual type:

from typing import NewType
UserId = NewType('UserId', int)
# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass

However, it is possible to create a NewType() based on a ‘derived’ NewType :

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

and typechecking for ProUserId will work as expected.

见 PEP 484 了解更多细节。

注意

Recall that the use of a type alias declares two types to be equivalent to one another. Doing Alias = Original will make the static type checker treat Alias as being exactly equivalent to Original in all cases. This is useful when you want to simplify complex type signatures.

In contrast, NewType declares one type to be a subtype of another. Doing Derived = NewType('Derived', Original) will make the static type checker treat Derived 作为 subclass of Original , which means a value of type Original cannot be used in places where a value of type Derived is expected. This is useful when you want to prevent logic errors with minimal runtime cost.

3.5.2 版新增。

可调用 ¶

Frameworks expecting callback functions of specific signatures might be type hinted using Callable[[Arg1Type, Arg2Type], ReturnType] .

例如：

from typing import Callable
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

It is possible to declare the return type of a callable without specifying the call signature by substituting a literal ellipsis for the list of arguments in the type hint: Callable[..., ReturnType] .

一般 ¶

Since type information about objects kept in containers cannot be statically inferred in a generic way, abstract base classes have been extended to support subscription to denote expected types for container elements.

from typing import Mapping, Sequence
def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

Generics can be parameterized by using a new factory available in typing called TypeVar .

from typing import Sequence, TypeVar
T = TypeVar('T')      # Declare type variable
def first(l: Sequence[T]) -> T:   # Generic function
    return l[0]

用户定义一般类型 ¶

A user-defined class can be defined as a generic class.

from typing import TypeVar, Generic
from logging import Logger
T = TypeVar('T')
class LoggedVar(Generic[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)

Generic[T] as a base class defines that the class LoggedVar takes a single type parameter T . This also makes T valid as a type within the class body.

The Generic base class defines __class_getitem__() so that LoggedVar[t] is valid as a type:

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

A generic type can have any number of type variables, and type variables may be constrained:

from typing import TypeVar, Generic
...
T = TypeVar('T')
S = TypeVar('S', int, str)
class StrangePair(Generic[T, S]):
    ...

Each type variable argument to Generic must be distinct. This is thus invalid:

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

You can use multiple inheritance with Generic :

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

When inheriting from generic classes, some type variables could be fixed:

from typing import TypeVar, Mapping
T = TypeVar('T')
class MyDict(Mapping[str, T]):
    ...

在此情况下 MyDict 拥有单参数， T .

Using a generic class without specifying type parameters assumes Any for each position. In the following example, MyIterable is not generic but implicitly inherits from Iterable[Any] :

from typing import Iterable
class MyIterable(Iterable): # Same as Iterable[Any]

User defined generic type aliases are also supported. Examples:

from typing import TypeVar, Iterable, Tuple, Union
S = TypeVar('S')
Response = Union[Iterable[S], int]
# Return type here is same as Union[Iterable[str], int]
def response(query: str) -> Response[str]:
    ...
T = TypeVar('T', int, float, complex)
Vec = Iterable[Tuple[T, T]]
def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]]
    return sum(x*y for x, y in v)

3.7 版改变： Generic 不再拥有自定义元类。

A user-defined generic class can have ABCs as base classes without a metaclass conflict. Generic metaclasses are not supported. The outcome of parameterizing generics is cached, and most types in the typing module are hashable and comparable for equality.

The `Any` type ¶

A special kind of type is Any . A static type checker will treat every type as being compatible with Any and Any as being compatible with every type.

This means that it is possible to perform any operation or method call on a value of type Any and assign it to any variable:

from typing import Any
a = None    # type: Any
a = []      # OK
a = 2       # OK
s = ''      # type: str
s = a       # OK
def foo(item: Any) -> int:
    # Typechecks; 'item' could be any type,
    # and that type might have a 'bar' method
    item.bar()
    ...

Notice that no typechecking is performed when assigning a value of type Any to a more precise type. For example, the static type checker did not report an error when assigning a to s even though s was declared to be of type str and receives an int value at runtime!

Furthermore, all functions without a return type or parameter types will implicitly default to using 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

This behavior allows Any to be used as an escape hatch when you need to mix dynamically and statically typed code.

Contrast the behavior of Any with the behavior of object . Similar to Any , every type is a subtype of object . However, unlike Any , the reverse is not true: object is not a subtype of every other type.

That means when the type of a value is object , a type checker will reject almost all operations on it, and assigning it to a variable (or using it as a return value) of a more specialized type is a type error. For example:

def hash_a(item: object) -> int:
    # Fails; an object does not have a 'magic' method.
    item.magic()
    ...
def hash_b(item: Any) -> int:
    # Typechecks
    item.magic()
    ...
# Typechecks, since ints and strs are subclasses of object
hash_a(42)
hash_a("foo")
# Typechecks, since Any is compatible with all types
hash_b(42)
hash_b("foo")

使用 object to indicate that a value could be any type in a typesafe manner. Use Any to indicate that a value is dynamically typed.

名义 vs 结构子类型 ¶

Initially PEP 484 defined Python static type system as using nominal subtyping . This means that a class A is allowed where a class B is expected if and only if A 是子类化的 B .

This requirement previously also applied to abstract base classes, such as Iterable . The problem with this approach is that a class had to be explicitly marked to support them, which is unpythonic and unlike what one would normally do in idiomatic dynamically typed Python code. For example, this conforms to PEP 484 :

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

PEP 544 allows to solve this problem by allowing users to write the above code without explicit base classes in the class definition, allowing Bucket to be implicitly considered a subtype of both Sized and Iterable[int] by static type checkers. This is known as structural subtyping (or static duck-typing):

from typing 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

Moreover, by subclassing a special class Protocol , a user can define new custom protocols to fully enjoy structural subtyping (see examples below).

Classes, functions, and decorators ¶

The module defines the following classes, functions and decorators:

class typing. TypeVar ¶

class typing. 一般 ¶

class typing. 类型 ( Generic[CT_co] ) ¶

The fact that Type[C] is covariant implies that all subclasses of C should implement the same constructor signature and class method signatures as C . The type checker should flag violations of this, but should also allow constructor calls in subclasses that match the constructor calls in the indicated base class. How the type checker is required to handle this particular case may change in future revisions of PEP 484 .

The only legal parameters for Type are classes, Any , 类型变量 , and unions of any of these types. For example:

def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...

Type[Any] 相当于 Type which in turn is equivalent to type , which is the root of Python’s metaclass hierarchy.

3.5.2 版新增。

class typing. Iterable ( Generic[T_co] ) ¶

class typing. 迭代器 ( Iterable[T_co] ) ¶

class typing. Reversible ( Iterable[T_co] ) ¶

class typing. SupportsInt ¶

class typing. SupportsFloat ¶

class typing. SupportsComplex ¶

class typing. SupportsBytes ¶

class typing. SupportsIndex ¶

class typing. SupportsAbs ¶

class typing. SupportsRound ¶

class typing. Container ( Generic[T_co] ) ¶

class typing. Hashable ¶

class typing. Sized ¶

class typing. Collection ( Sized, Iterable[T_co], Container[T_co] ) ¶

class typing. AbstractSet ( Sized, Collection[T_co] ) ¶

class typing. MutableSet ( AbstractSet[T] ) ¶

class typing. 映射 ( Sized, Collection[KT], Generic[VT_co] ) ¶

class typing. MutableMapping ( Mapping[KT, VT] ) ¶

class typing. Sequence ( Reversible[T_co], Collection[T_co] ) ¶

class typing. MutableSequence ( Sequence[T] ) ¶

class typing. ByteString ( Sequence[int] ) ¶

class typing. Deque ( deque, MutableSequence[T] ) ¶

class typing. List ( list, MutableSequence[T] ) ¶

class typing. Set ( set, MutableSet[T] ) ¶

class typing. FrozenSet ( frozenset, AbstractSet[T_co] ) ¶

class typing. MappingView ( Sized, Iterable[T_co] ) ¶

class typing. KeysView ( MappingView[KT_co], AbstractSet[KT_co] ) ¶

class typing. ItemsView ( MappingView, Generic[KT_co, VT_co] ) ¶

class typing. ValuesView ( MappingView[VT_co] ) ¶

class typing. Awaitable ( Generic[T_co] ) ¶

class typing. Coroutine ( Awaitable[V_co], Generic[T_co, T_contra, V_co] ) ¶

class typing. AsyncIterable ( Generic[T_co] ) ¶

class typing. AsyncIterator ( AsyncIterable[T_co] ) ¶

class typing. ContextManager ( Generic[T_co] ) ¶

class typing. AsyncContextManager ( Generic[T_co] ) ¶

class typing. Dict ( dict, MutableMapping[KT, VT] ) ¶

class typing. DefaultDict ( collections.defaultdict, MutableMapping[KT, VT] ) ¶

class typing. OrderedDict ( collections.OrderedDict, MutableMapping[KT, VT] ) ¶

class typing. Counter ( collections.Counter, Dict[T, int] ) ¶

class typing. ChainMap ( collections.ChainMap, MutableMapping[KT, VT] ) ¶

class typing. 生成器 ( Iterator[T_co], Generic[T_co, T_contra, V_co] ) ¶

class typing. AsyncGenerator ( AsyncIterator[T_co], Generic[T_co, T_contra] ) ¶

class typing. 文本 ¶

class typing. IO ¶
class typing. TextIO ¶
class typing. BinaryIO ¶

class typing. 模式 ¶
class typing. Match ¶

class typing. NamedTuple ¶

class typing. TypedDict ( dict ) ¶

The type info for introspection can be accessed via Point2D.__annotations__ and Point2D.__total__ . To allow using this feature with older versions of Python that do not support PEP 526 , TypedDict supports two additional equivalent syntactic forms:

Point2D = TypedDict('Point2D', x=int, y=int, label=str)
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})

By default, all keys must be present in a TypedDict. It is possible to override this by specifying totality. Usage:

class point2D(TypedDict, total=False):
    x: int
    y: int

This means that a point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body be required.

见 PEP 589 for more examples and detailed rules of using TypedDict .

3.8 版新增。

class typing. ForwardRef ¶

typing. NewType ( name , tp ) ¶

3.5.2 版新增。

typing. cast ( typ , val ) ¶

typing. get_type_hints ( obj [ , globals [ , locals ] ] ) ¶

typing. get_origin ( tp ) ¶

typing. get_args ( tp ) ¶

3.8 版新增。

@ typing. overload ¶

见 PEP 484 for details and comparison with other typing semantics.

@ typing. final ¶

There is no runtime checking of these properties. See PEP 591 了解更多细节。

3.8 版新增。

@ typing. no_type_check ¶

@ typing. no_type_check_decorator ¶

@ typing. type_check_only ¶

Note that returning instances of private classes is not recommended. It is usually preferable to make such classes public.

@ typing. runtime_checkable ¶

Warning: this will check only the presence of the required methods, not their type signatures!

3.8 版新增。

typing. 任何 ¶

typing. NoReturn ¶

3.5.4 版新增。

3.6.2 版新增。

typing. Union ¶

typing. 可选 ¶

On the other hand, if an explicit value of None is allowed, the use of Optional is appropriate, whether the argument is optional or not. For example:

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

typing. Tuple ¶

typing. 可调用 ¶

typing. Literal ¶

Literal[...] cannot be subclassed. At runtime, an arbitrary value is allowed as type argument to Literal[...] , but type checkers may impose restrictions. See PEP 586 for more details about literal types.

3.8 版新增。

typing. ClassVar ¶

ClassVar accepts only types and cannot be further subscribed.

ClassVar is not a class itself, and should not be used with isinstance() or issubclass() . ClassVar does not change Python runtime behavior, but it can be used by third-party type checkers. For example, a type checker might flag the following code as an error:

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

3.5.3 版新增。

typing. Final ¶

There is no runtime checking of these properties. See PEP 591 了解更多细节。

3.8 版新增。

typing. AnyStr ¶

typing. TYPE_CHECKING ¶

Note that the first type annotation must be enclosed in quotes, making it a “forward reference”, to hide the expensive_mod reference from the interpreter runtime. Type annotations for local variables are not evaluated, so the second annotation does not need to be enclosed in quotes.

3.5.2 版新增。

`typing` — 支持类型提示 ¶

类型别名 ¶

NewType ¶

可调用 ¶

一般 ¶

用户定义一般类型 ¶

The `Any` type ¶

名义 vs 结构子类型 ¶

Classes, functions, and decorators ¶

内容表

上一话题

下一话题

本页

快速搜索

typing — 支持类型提示 ¶

类型别名 ¶

NewType ¶

可调用 ¶

一般 ¶

用户定义一般类型 ¶

The Any type ¶

名义 vs 结构子类型 ¶

Classes, functions, and decorators ¶

内容表

上一话题

下一话题

本页

快速搜索

`typing` — 支持类型提示 ¶

The `Any` type ¶