26.1. typing
—支持类型提示¶
3.5 新版功能.
源代码: Lib/typing.py
此模块支持由 PEP 484 和 PEP 526 指定的类型提示。最基本的支持包括类型 Any
,Union
,Tuple
,Callable
,TypeVar
和 Generic
。有关完整规格,请参阅 PEP 484。有关类型提示的简化介绍,请参阅 PEP 483。
下面的函数接受并返回一个字符串,并注释如下:
def greeting(name: str) -> str:
return 'Hello ' + name
在函数 greeting
中,参数 name
预期为 str
类型,返回类型为 str
。接受子类型作为参数。
26.1.1. 类型别名¶
通过将类型分配给别名来定义类型别名。在本示例中,Vector
和 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, List
ConnectionOptions = Dict[str, str]
Address = Tuple[str, int]
Server = Tuple[Address, ConnectionOptions]
def broadcast_message(message: str, servers: List[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: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:
...
注意,None
作为类型提示是一种特殊情况,并由 type(None)
替代。
26.1.2. NewType¶
使用 NewType()
辅助函数创建不同类型:
from typing import NewType
UserId = NewType('UserId', int)
some_id = UserId(524313)
静态类型检查器将把新类型视为原始类型的子类。这有助于捕获逻辑错误:
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)
您仍然可以对类型为 UserId
的变量执行所有 int
操作,但结果将始终为类型 int
。这允许您传递 UserId
在任何地方可能期望 int
,但将阻止您以无效方式意外创建 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)
在运行时总是为真。
这也意味着不可能创建 Derived
的子类型,因为它是运行时的标识函数,而不是实际类型。类似地,不可能基于 Derived
类型创建另一 NewType()
:
from typing import NewType
UserId = NewType('UserId', int)
# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass
# Also does not typecheck
ProUserId = NewType('ProUserId', UserId)
有关详细信息,请参阅 PEP 484。
注解
回想一下,类型别名的使用声明两种类型是彼此的 equivalent。在所有情况下,执行 Alias = Original
将使静态类型检查器将 Alias
视为 完全等同 到 Original
。当您想要简化复杂类型签名时,这是有用的。
相比之下,NewType
声明一种类型是另一种的 subtype。执行 Derived = NewType('Derived', Original)
将使静态类型检查器将 Derived
视为 Original
的 subclass,这意味着类型 Original
的值不能在期望类型 Derived
的值的地方使用。当您希望以最小的运行时成本防止逻辑错误时,这是有用的。
26.1.3. 可叫¶
期望特定签名的回调函数的框架可能使用 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
可以通过用类型hint:Callable[..., ReturnType]
中的参数列表替换文本省略号来声明可调用的返回类型,而不指定调用签名。
26.1.4. 泛型¶
由于不能以通用方式静态推断容器中保存的对象的类型信息,因此已经扩展了抽象基类以支持预订来表示容器元素的预期类型。
from typing import Mapping, Sequence
def notify_by_email(employees: Sequence[Employee],
overrides: Mapping[str, str]) -> None: ...
通过使用在名为 TypeVar
的打字中可用的新工厂,可以对通用参数进行参数化。
from typing import Sequence, TypeVar
T = TypeVar('T') # Declare type variable
def first(l: Sequence[T]) -> T: # Generic function
return l[0]
26.1.5. 用户定义的泛型类型¶
用户定义的类可以定义为通用类。
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]
作为基类定义 LoggedVar
类采用单个类型参数 T
。这也使 T
有效作为类体中的类型。
Generic
基类使用定义 __getitem__()
的元类,以便 LoggedVar[t]
作为类型有效:
from typing import Iterable
def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
for var in vars:
var.set(0)
通用类型可以具有任意数量的类型变量,并且类型变量可以被约束:
from typing import TypeVar, Generic
...
T = TypeVar('T')
S = TypeVar('S', int, str)
class StrangePair(Generic[T, S]):
...
Generic
的每个类型变量参数必须是不同的。因此这是无效的:
from typing import TypeVar, Generic
...
T = TypeVar('T')
class Pair(Generic[T, T]): # INVALID
...
您可以使用 Generic
的多重继承:
from typing import TypeVar, Generic, Sized
T = TypeVar('T')
class LinkedList(Sized, Generic[T]):
...
当从泛型类继承时,一些类型变量可以被修复:
from typing import TypeVar, Mapping
T = TypeVar('T')
class MyDict(Mapping[str, T]):
...
在这种情况下,MyDict
具有单个参数 T
。
使用不指定类型参数的泛型类为每个位置假定 Any
。在以下示例中,MyIterable
不是通用的,而是隐式地继承自 Iterable[Any]
:
from typing import Iterable
class MyIterable(Iterable): # Same as Iterable[Any]
还支持用户定义的通用类型别名。例子:
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)
Generic
使用的元类是 abc.ABCMeta
的子类。通用类可以是通过包括抽象方法或属性的ABC,并且通用类也可以具有ABC作为基类而没有元类冲突。不支持通用元类。参数化泛型的结果被缓存,并且在类型模块中的大多数类型是可哈希的并且可比较的相等。
26.1.6. Any
类型¶
一种特殊类型的是 Any
。静态类型检查器将把每种类型视为与 Any
和 Any
兼容,以与每种类型兼容。
这意味着可以对 Any
上的类型的值执行任何操作或方法调用,并将其分配给任何变量:
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()
...
请注意,在将 Any
类型的值指定为更精确的类型时,不会执行类型检查。例如,即使 s
被声明为 str
类型并且在运行时接收到 int
值,静态类型检查器在将 a
分配给 s
时没有报告错误!
此外,所有没有返回类型或参数类型的函数将默认使用 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
是 not 每个其他类型的子类型。
这意味着当值的类型是 object
时,类型检查器将拒绝几乎所有操作,并将其分配给更专门类型的变量(或使用它作为返回值)是类型错误。例如:
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")
26.1.7. 类,函数和装饰器¶
模块定义了以下类,函数和装饰器:
-
class
typing.
TypeVar
¶ 类型变量。
用法:
T = TypeVar('T') # Can be anything A = TypeVar('A', str, bytes) # Must be str or bytes
类型变量主要用于静态类型检查器的好处。它们用作泛型类型以及通用函数定义的参数。有关泛型类型的更多信息,请参阅类Generic。通用函数的工作方式如下:
def repeat(x: T, n: int) -> Sequence[T]: """Return a list containing n references to x.""" return [x]*n def longest(x: A, y: A) -> A: """Return the longest of two strings.""" return x if len(x) >= len(y) else y
后一个例子的签名基本上是
(str, str) -> str
和(bytes, bytes) -> bytes
的重载。还要注意,如果参数是str
的一些子类的实例,返回类型仍然是纯str
。在运行时,
isinstance(x, T)
将提高TypeError
。一般来说,isinstance()
和issubclass()
不应与类型一起使用。类型变量可以通过传递
covariant=True
或contravariant=True
来标记协变或逆变。有关详细信息,请参阅 PEP 484。默认类型变量是不变的。或者,类型变量可以使用bound=<type>
指定上限。这意味着,对类型变量替换(显式或隐式)的实际类型必须是边界类型的子类,请参阅 PEP 484。
-
class
typing.
Generic
¶ 泛型类型的抽象基类。
通常类型通常通过从具有一个或多个类型变量的该类的实例化继承来声明。例如,通用映射类型可以定义为:
class Mapping(Generic[KT, VT]): def __getitem__(self, key: KT) -> VT: ... # Etc.
这个类可以如下使用:
X = TypeVar('X') Y = TypeVar('Y') def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y: try: return mapping[key] except KeyError: return default
-
class
typing.
Type
(Generic[CT_co])¶ 用
C
注释的变量可以接受类型C
的值。相反,用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 BasicUser(User): ... class ProUser(User): ... class TeamUser(User): ... # Accepts User, BasicUser, ProUser, TeamUser, ... def make_new_user(user_class: Type[User]) -> User: # ... return user_class()
Type[C]
是协变的这一事实意味着C
的所有子类应该实现与C
相同的构造符签名和类方法签名。类型检查器应标记违反此情况,但也应允许在指定基类中与构造函数调用匹配的子类中构造函数调用。如何处理此特定情况需要类型检查器可能会在 PEP 484 的未来修订版本中更改。def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...
Type[Any]
等价于Type
,Type
又等同于type
,它是Python的元类层次结构的根。
-
class
typing.
Iterable
(Generic[T_co])¶ collections.abc.Iterable
的通用版本。
-
class
typing.
Iterator
(Iterable[T_co])¶ collections.abc.Iterator
的通用版本。
-
class
typing.
Reversible
(Iterable[T_co])¶ collections.abc.Reversible
的通用版本。
-
class
typing.
SupportsInt
¶ 一个ABC与一个抽象方法
__int__
。
-
class
typing.
SupportsFloat
¶ 一个ABC与一个抽象方法
__float__
。
-
class
typing.
SupportsAbs
¶ 具有一个抽象方法
__abs__
的ABC,其返回类型是协变的。
-
class
typing.
SupportsRound
¶ 具有一个抽象方法
__round__
的ABC,其返回类型是协变的。
-
class
typing.
Container
(Generic[T_co])¶ collections.abc.Container
的通用版本。
-
class
typing.
Hashable
¶
-
class
typing.
Sized
¶
-
class
typing.
Collection
(Sized, Iterable[T_co], Container[T_co])¶ collections.abc.Collection
的通用版本3.6 新版功能.
-
class
typing.
AbstractSet
(Sized, Collection[T_co])¶ collections.abc.Set
的通用版本。
-
class
typing.
MutableSet
(AbstractSet[T])¶ collections.abc.MutableSet
的通用版本。
-
class
typing.
Mapping
(Sized, Collection[KT], Generic[VT_co])¶ collections.abc.Mapping
的通用版本。
-
class
typing.
MutableMapping
(Mapping[KT, VT])¶
-
class
typing.
Sequence
(Reversible[T_co], Collection[T_co])¶ collections.abc.Sequence
的通用版本。
-
class
typing.
MutableSequence
(Sequence[T])¶
-
class
typing.
ByteString
(Sequence[int])¶ collections.abc.ByteString
的通用版本。此类型表示类型
bytes
,bytearray
和memoryview
。作为此类型的简写,
bytes
可用于注释上述任何类型的参数。
-
class
typing.
List
(list, MutableSequence[T])¶ list
的通用版本。用于注释返回类型。要注释参数,最好使用抽象集合类型,例如Mapping
,Sequence
或AbstractSet
。这种类型可以如下使用:
T = TypeVar('T', int, float) def vec2(x: T, y: T) -> List[T]: return [x, y] def keep_positives(vector: Sequence[T]) -> List[T]: return [item for item in vector if item > 0]
-
class
typing.
Set
(set, MutableSet[T])¶ builtins.set
的通用版本。
-
class
typing.
FrozenSet
(frozenset, AbstractSet[T_co])¶ builtins.frozenset
的通用版本。
-
class
typing.
MappingView
(Sized, Iterable[T_co])¶ collections.abc.MappingView
的通用版本。
-
class
typing.
KeysView
(MappingView[KT_co], AbstractSet[KT_co])¶ collections.abc.KeysView
的通用版本。
-
class
typing.
ItemsView
(MappingView, Generic[KT_co, VT_co])¶ collections.abc.ItemsView
的通用版本。
-
class
typing.
ValuesView
(MappingView[VT_co])¶ collections.abc.ValuesView
的通用版本。
-
class
typing.
Awaitable
(Generic[T_co])¶ collections.abc.Awaitable
的通用版本。
-
class
typing.
Coroutine
(Awaitable[V_co], Generic[T_co T_contra, V_co])¶ collections.abc.Coroutine
的通用版本。类型变量的方差和顺序对应于例如Generator
的方差和顺序:from typing import List, Coroutine c = None # type: Coroutine[List[str], str, int] ... x = c.send('hi') # type: List[str] async def bar() -> None: x = await c # type: int
-
class
typing.
AsyncIterable
(Generic[T_co])¶
-
class
typing.
AsyncIterator
(AsyncIterable[T_co])¶
-
class
typing.
ContextManager
(Generic[T_co])¶ contextlib.AbstractContextManager
的通用版本。3.6 新版功能.
-
class
typing.
Dict
(dict, MutableMapping[KT, VT])¶ dict
的通用版本。这种类型的用法如下:def get_position_in_index(word_list: Dict[str, int], word: str) -> int: return word_list[word]
-
class
typing.
DefaultDict
(collections.defaultdict, MutableMapping[KT, VT])¶ collections.defaultdict
的通用版本
-
class
typing.
Generator
(Iterator[T_co], Generic[T_co, T_contra, V_co])¶ 生成器可以由通用类型
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, 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
-
class
typing.
Text
¶ Text
是str
的别名。它提供为Python 2代码提供一个向前兼容的路径:在Python 2中,Text
是unicode
的别名。使用
Text
来指示值必须以与Python 2和Python 3兼容的方式包含unicode字符串:def add_unicode_checkmark(text: Text) -> Text: return text + u' \u2713'
-
class
typing.
io
¶ I/O流类型的包装器命名空间。
这定义了通用类型
IO[AnyStr]
,并且分别针对IO[str]
和IO[bytes]
别名TextIO
和BinaryIO
。这些表示由open()
返回的I/O流的类型。
-
class
typing.
re
¶ 正则表达式匹配类型的Wrapper命名空间。
这定义了对应于来自
re.compile()
和re.match()
的返回类型的类型别名Pattern
和Match
。这些类型(和相应的功能)在AnyStr
中是通用的,并且可以通过写入Pattern[str]
,Pattern[bytes]
,Match[str]
或Match[bytes]
来具体化。
-
class
typing.
NamedTuple
¶ namedtuple的类型化版本。
用法:
class Employee(NamedTuple): name: str id: int
这相当于:
Employee = collections.namedtuple('Employee', ['name', 'id'])
结果类有一个额外的属性:
_field_types
,给出一个dict将字段名称映射到类型。 (字段名称在_fields
属性中,它是namedtuple API的一部分。)向后兼容使用:
Employee = NamedTuple('Employee', [('name', str), ('id', int)])
在 3.6 版更改: 添加了对 PEP 526 变量注释语法的支持。
-
typing.
NewType
(typ)¶ 一个辅助函数,用于向类型检查器指示不同类型,请参阅 NewType。在运行时它返回一个返回其参数的函数。用法:
UserId = NewType('UserId', int) first_user = UserId(1)
-
typing.
cast
(typ, val)¶ 将值转换为类型。
这将返回不变的值。对于类型检查器,这表示返回值具有指定的类型,但在运行时我们有意不检查任何东西(我们希望这是尽可能快的)。
-
typing.
get_type_hints
(obj[, globals[, locals]])¶ 返回一个包含函数,方法,模块或类对象的类型提示的字典。
这通常与
obj.__annotations__
相同。此外,编码为字符串字面量的前向引用通过在globals
和locals
命名空间中评估它们来处理。如果必要,如果设置了等于None
的默认值,则为函数和方法注释添加Optional[t]
。对于类C
,返回通过沿着C.__mro__
以相反顺序合并所有__annotations__
构造的字典。
-
@
typing.
overload
¶ @overload
装饰器允许描述支持参数类型的多个不同组合的函数和方法。一系列@overload
装饰的定义后面必须紧跟一个非@overload
装饰的定义(对于相同的功能/方法)。@overload
修饰的定义仅仅对类型检查器有利,因为它们将被非@overload
修饰的定义覆盖,而后者在运行时使用,但是应该被类型检查器忽略。在运行时,直接调用@overload
装饰函数将提高NotImplementedError
。提供更精确类型的重载示例可以使用联合或类型变量表示:@overload def process(response: None) -> None: ... @overload def process(response: int) -> Tuple[int, str]: ... @overload def process(response: bytes) -> str: ... def process(response): <actual implementation>
有关详细信息和与其他类型语义的比较,请参阅 PEP 484。
-
@
typing.
no_type_check
(arg)¶ 装饰器指示注释不是类型提示。
参数必须是类或函数;如果它是一个类,它将递归应用于该类中定义的所有方法(但不适用于在其超类或子类中定义的方法)。
这会改变函数的位置。
-
@
typing.
no_type_check_decorator
(decorator)¶ 装饰师给另一个装饰师
no_type_check()
效果。这将装饰器包装在
no_type_check()
中的装饰函数。
-
typing.
Union
¶ 联合型;
Union[X, Y]
是指X或Y.要定义联合,请使用
Union[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]
当比较联合时,参数顺序被忽略,例如。:
Union[int, str] == Union[str, int]
当一个类及其子类存在时,前者被跳过,例如。:
Union[int, object] == object
您不能子类化或实例化union。
你不能写
Union[X][Y]
。您可以使用
Optional[X]
作为Union[X, None]
的缩写。
-
typing.
Optional
¶ 可选类型。
Optional[X]
等价于Union[X, None]
。请注意,这不是一个可选参数的概念,它是一个具有默认值的参数。具有默认值的可选参数不需要在其类型注释上使用
Optional
限定符(虽然如果默认值为None
,则推断)。如果允许None
的显式值,则强制参数可以仍然具有Optional
类型。
-
typing.
Tuple
¶ 元组类型;
Tuple[X, Y]
是具有类型X的第一项和类型Y的第二项的两个项目的元组的类型。示例:
Tuple[T1, T2]
是对应于类型变量T1和T2的两个元素的元组。Tuple[int, float, str]
是一个int,一个float和一个字符串的元组。要指定同构类型的可变长度元组,请使用文字省略号,例如。
Tuple[int, ...]
。普通的Tuple
相当于Tuple[Any, ...]
,进而相当于tuple
。
-
typing.
Callable
¶ 可叫类型;
Callable[[int], str]
是(int) - > str的函数。订阅语法必须始终使用两个值:参数列表和返回类型。参数列表必须是类型列表或省略号;返回类型必须是单个类型。
没有用于指示可选或关键字参数的语法;这样的函数类型很少用作回调类型。
Callable[..., ReturnType]
(文本省略号)可以用于键入提示,可调用任何数量的参数并返回ReturnType
。平原Callable
等价于Callable[..., Any]
,反过来等同于collections.abc.Callable
。
-
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.
AnyStr
¶ AnyStr
是定义为AnyStr = TypeVar('AnyStr', str, bytes)
的类型变量。它意味着用于可以接受任何种类的字符串而不允许不同种类的字符串混合的函数。例如:
def concat(a: AnyStr, b: AnyStr) -> AnyStr: return a + b concat(u"foo", u"bar") # Ok, output has type 'unicode' concat(b"foo", b"bar") # Ok, output has type 'bytes' concat(u"foo", b"bar") # Error, cannot mix unicode and bytes
-
typing.
TYPE_CHECKING
¶ 由第三方静态类型检查器假定为
True
的特殊常量。它在运行时是False
。用法:if TYPE_CHECKING: import expensive_mod def fun(): local_var: expensive_mod.some_type = other_fun()