typing — Поддержка подсказок типов

Исходный код: 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. Подтипы принимаются в качестве аргументов.

Псевдонимы типов

Псевдоним типа определяется присваиванием типа псевдониму. В этом примере 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, 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)

Статический анализатор типов будет обрабатывать новый тип так, как будто он является подклассом исходного типа. Это полезно для выявления логических ошибок:

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 операции над переменной типа UserId, но результат всегда будет типа 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, поскольку это функция тождества во время выполнения, а не фактический тип:

from typing import NewType

UserId = NewType('UserId', int)

# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass

Однако, возможно создать NewType() на основе «производного» NewType:

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

и проверка типов для ProUserId будет работать как ожидается.

См. PEP 484 для получения более подробной информации.

Callable

Фреймворки, ожидающие функции обратного вызова со специфическими сигнатурами, могут иметь подсказки типов с использованием 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

Возможна декларация типа возвращаемого значения функции обратного вызова без указания сигнатуры вызова, заменив список аргументов в подсказке типа на литеранный многоточие: Callable[..., ReturnType].

Обобщения

Поскольку информацию о типах объектов, хранящихся в контейнерах, нельзя статически вывести обобщенным способом, базовые классы абстрактных типов были расширены для поддержки подписки, чтобы указать ожидаемые типы для элементов контейнера.

from typing import Mapping, Sequence

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

Обобщения могут быть параметризованы с использованием новой фабрики, доступной в typing, под названием TypeVar.

from typing import Sequence, TypeVar

T = TypeVar('T')      # Declare type variable

def first(l: Sequence[T]) -> T:   # Generic function
    return l[0]

Пользовательские обобщенные типы

Пользовательский класс может быть определён как обобщённый класс.

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 определяет __class_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)

Пользовательский обобщенный класс может иметь ABC в качестве базовых классов без конфликтов метакласса. Обобщенные метаклассы не поддерживаются. Результат параметризации обобщений кэшируется, и большинство типов в модуле typing хэшируются и сравниваются на равенство.

Тип 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 более точному типу. Например, статический анализатор типов не выдал ошибку при присваивании 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, проверка типов отклонит практически все операции над ним, а присвоение его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например:

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, чтобы указать, что значение может быть любого типа безопасным для типизированных данных способом. Используйте Any, чтобы указать, что значение имеет динамический тип.

Классы, функции и декораторы

Модуль определяет следующие классы, функции и декораторы:

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.

Единственными допустимыми параметрами для Type являются классы, Any, переменные типа и объединения любых из этих типов. Например:

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

Type[Any] эквивалентно Type, что в свою очередь эквивалентно type, что является корнем иерархии метаклассов Python.

Новая версия с 3.5.2.

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.SupportsComplex

ABC с одним абстрактным методом __complex__.

class typing.SupportsBytes

ABC с одним абстрактным методом __bytes__.

class typing.SupportsAbs

ABC с одним абстрактным методом __abs__ который ковариантен по своему типу возвращаемого значения.

class typing.SupportsRound

ABC с одним абстрактным методом __round__ который ковариантен по своему типу возвращаемого значения.

class typing.Container(Generic[T_co])

Обобщенная версия collections.abc.Container.

class typing.Hashable

Псевдоним для collections.abc.Hashable

class typing.Sized

Псевдоним для collections.abc.Sized

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

Обобщенная версия collections.abc.Collection

Новая версия с 3.6.0.

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. Этот тип может быть использован следующим образом:

def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
    return word_list[word]

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

Обобщенная версия collections.abc.MutableMapping.

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

Обобщенная версия collections.abc.Sequence.

class typing.MutableSequence(Sequence[T])

Обобщенная версия collections.abc.MutableSequence.

class typing.ByteString(Sequence[int])

Обобщенная версия collections.abc.ByteString.

Этот тип представляет типы bytes, bytearray и memoryview.

В качестве сокращения для этого типа, bytes можно использовать для аннотирования аргументов любого из упомянутых выше типов.

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

Обобщенная версия collections.deque.

Новая версия с 3.5.4.

Новая версия с 3.6.1.

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

Обобщенная версия list. Полезно для аннотирования типов возвращаемых значений. Для аннотирования аргументов предпочтительно использовать абстрактный тип коллекции, такой как Sequence или Iterable.

Этот тип может быть использован следующим образом:

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. Полезно для аннотации типов возвращаемых значений. Для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как AbstractSet.

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.

Добавлено в версии 3.5.2.

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

Добавлено в версии 3.5.3.

class typing.AsyncIterable(Generic[T_co])

Обобщенная версия collections.abc.AsyncIterable.

Добавлено в версии 3.5.2.

class typing.AsyncIterator(AsyncIterable[T_co])

Обобщенная версия collections.abc.AsyncIterator.

Добавлено в версии 3.5.2.

class typing.ContextManager(Generic[T_co])

Обобщенная версия contextlib.AbstractContextManager.

Добавлено в версии 3.5.4.

Добавлено в версии 3.6.0.

class typing.AsyncContextManager(Generic[T_co])

Обобщенная версия contextlib.AbstractAsyncContextManager.

Добавлено в версии 3.5.4.

Добавлено в версии 3.6.2.

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

Обобщенная версия dict. Полезно для аннотации типов возвращаемых значений. Для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как Mapping.

Этот тип можно использовать следующим образом:

def count_words(text: str) -> Dict[str, int]:
    ...

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

Обобщенная версия collections.defaultdict.

Добавлено в версии 3.5.2.

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

Обобщенная версия collections.OrderedDict.

Добавлено в версии 3.7.2.

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

Обобщенная версия collections.Counter.

Добавлено в версии 3.5.4.

Добавлено в версии 3.6.1.

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

Обобщенная версия collections.ChainMap.

Добавлено в версии 3.5.4.

Добавлено в версии 3.6.1.

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'

Обратите внимание, что в отличие от многих других обобщений в модуле typing, SendType Generator ведет себя контравариантно, а не ковариантно или инвариантно.

Если ваш генератор будет только генерировать значения, установите 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.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])

Асинхронный генератор можно аннотировать обобщенным типом AsyncGenerator[YieldType, SendType]. Например:

async def echo_round() -> AsyncGenerator[int, float]:
    sent = yield 0
    while sent >= 0.0:
        rounded = await round(sent)
        sent = yield rounded

В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа ReturnType отсутствует. Как и в случае с Generator, SendType ведет себя контравариантно.

Если ваш генератор будет только генерировать значения, установите SendType в None.

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)

Добавлено в версии 3.6.1.

class typing.Text

Text — псевдоним для str. Он предоставляется для обеспечения обратной совместимости с кодом Python 2: в Python 2 Text — псевдоним для unicode.

Используйте Text для указания того, что значение должно содержать строку Юникод, совместимую как с Python 2, так и с Python 3.

def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'

Добавлено в версии 3.5.2.

class typing.IO

class typing.TextIO

class typing.BinaryIO

Обобщенный тип IO[AnyStr] и его подклассы TextIO(IO[str]) и BinaryIO(IO[bytes]) представляют типы потоков ввода-вывода, например, возвращаемые функцией open().

class typing.Pattern

class typing.Match

Эти псевдонимы типов соответствуют типам возвращаемых значений re.compile() и re.match(). Эти типы (и соответствующие функции) обобщены в AnyStr и могут быть конкретизированы путем записи Pattern[str], Pattern[bytes], Match[str], или Match[bytes].

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

Поля с значением по умолчанию должны следовать за полями без значения по умолчанию.

Полученный класс имеет два дополнительных атрибута: _field_types, отображающий имена полей на типы, и _field_defaults, отображающий имена полей на значения по умолчанию. (Имена полей находятся в атрибуте _fields, который является частью API namedtuple.)

Классы, производные от NamedTuple, также могут иметь документацию и методы:

class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

Обратная совместимость:

Employee = NamedTuple('Employee', [('name', str), ('id', int)])

Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотаций переменных PEP 526.

Изменено в версии 3.6.1: Добавлена поддержка значений по умолчанию, методов и документации.

class typing.ForwardRef

Класс, используемый для внутреннего представления типов строковых ссылок вперёд. Например, List["SomeClass"] неявно преобразуется в List[ForwardRef("SomeClass")]. Пользователь не должен создавать экземпляры этого класса, но он может использоваться средствами интроспекции.

typing.NewType(typ)

Вспомогательная функция для указания различных типов для средства проверки типов, см. NewType. Во время выполнения она возвращает функцию, которая возвращает свой аргумент. Пример использования:

UserId = NewType('UserId', int)
first_user = UserId(1)

Добавлена в версии 3.5.2.

typing.cast(typ, val)

Приведение значения к типу.

Это возвращает значение без изменений. Для средства проверки типов это сигнализирует, что возвращаемое значение имеет указанный тип, но во время выполнения мы намеренно ничего не проверяем (мы хотим, чтобы это было максимально быстро).

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

Возвращает словарь, содержащий подсказки типов для функции, метода, модуля или объекта класса.

Это часто совпадает с obj.__annotations__. Кроме того, ссылки вперёд, закодированные как строковые литералы, обрабатываются путём их вычисления в пространствах имён globals и locals. При необходимости, Optional[t] добавляется для аннотаций функций и методов, если значение по умолчанию равно None. Для класса C, возвращается словарь, составленный путём объединения всех __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

Декоратор, указывающий, что аннотации не являются подсказками типов.

Он работает как декоратор для классов или функций декоратор. Применительно к классу, он рекурсивно применяется ко всем методам, определённым в этом классе (но не к методам, определённым в его родительских или дочерних классах).

Данный декоратор изменяет функцию(и) на месте.

@typing.no_type_check_decorator

Декоратор, позволяющий другому декоратору получить эффект no_type_check().

Он оборачивает декоратор чем-то, что оборачивает декорированную функцию в no_type_check().

@typing.type_check_only

Декоратор, помечающий класс или функцию как недоступную во время выполнения.

Этот декоратор сам по себе недоступен во время выполнения. Он в основном предназначен для маркирования классов, определённых в файлах заглушек типов, если реализация возвращает экземпляр приватного класса:

@type_check_only
class Response:  # private or not available at runtime
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...

Обратите внимание, что возвращение экземпляров приватных классов не рекомендуется. Обычно предпочтительнее сделать такие классы общедоступными.

typing.Any

Специальный тип, указывающий на не ограниченный тип.

• Каждый тип совместим с Any.
• Any совместим с каждым типом.

typing.NoReturn

Специальный тип, указывающий, что функция никогда не возвращает значение. Например:

from typing import NoReturn

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

Добавлена в версии 3.5.4.

Добавлена в версии 3.6.2.

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[X][Y].
• Вы можете использовать Optional[X] как сокращение для Union[X, None].

Изменено в версии 3.7: Не удалять явные подклассы из объединений во время выполнения.

typing.Optional

Необязательный тип.

Optional[X] эквивалентно Union[X, None].

Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Для необязательного аргумента по умолчанию не требуется квалификатор Optional в аннотации типа, просто потому, что он необязательный. Например:

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

С другой стороны, если разрешено явное значение None , использование Optional уместно, независимо от того, является ли аргумент необязательным или нет. Например:

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

typing.Tuple

Тип кортежа; Tuple[X, Y] - это тип кортежа из двух элементов, первый из которых имеет тип X, а второй - Y. Тип пустого кортежа можно записать как Tuple[()].

Пример: Tuple[T1, T2] - это кортеж из двух элементов, соответствующих переменным типов T1 и T2. Tuple[int, float, str] - это кортеж из целого числа, числа с плавающей запятой и строки.

Для указания кортежа переменной длины однородного типа используйте литерал эллипсиса, например 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(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()

Обратите внимание, что первая аннотация типа должна быть заключена в кавычки, превращая её в «ссылку вперёд», чтобы скрыть ссылку expensive_mod от интерпретатора во время выполнения. Аннотации типов для локальных переменных не вычисляются, поэтому второй аннотации не нужно заключать в кавычки.

Добавлена в версии 3.5.2.