26.1. typing – Поддержка подсказок типов¶typing – Support for type hints

26.1.1. Псевдонимы типов¶Type aliases

Псевдоним типа определяется присваиванием типа псевдониму. В этом примере Vector и List[float] будут рассматриваться как взаимозаменяемые синонимы:

from typing import List
Vector = List[float]

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

# Проходит проверку типов; список чисел с плавающей запятой считается Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

Псевдонимы типов полезны для упрощения сложных сигнатур типов. Например:

from 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:
    ...

# Статическая проверка типов будет считать предыдущую сигнатуру типа как
# полностью эквивалентную этой.
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:
    ...

# Проходит проверку типов.
user_a = get_user_name(UserId(42351))

# Не проходит проверку типов; int не является UserId.
user_b = get_user_name(-1)

Можно по-прежнему выполнять все операции int над переменной типа UserId, но результат всегда будет типа int. Это позволяет передавать UserId везде, где может ожидаться int, но предотвращает случайное создание UserId недопустимым способом:

# 'output' имеет тип 'int', а не '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)

# Завершается ошибкой во время выполнения и не проходит проверку типов.
class AdminUserId(UserId): pass

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

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

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

Подробнее см. PEP 484.

26.1.3. Callable¶

Фреймворки, ожидающие функции обратного вызова с определённой сигнатурой, могут быть аннотированы с помощью Callable[[Arg1Type, Arg2Type], ReturnType].

Например:

from typing import Callable

def feeder(get_next_item: Callable[[], str]) -> None:
    # Тело

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    # Тело

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

26.1.4. Дженерики¶Generics

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

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')      # Объявить переменную типа

def first(l: Sequence[T]) -> T:   # Обобщённая функция
    return l[0]

26.1.5. Пользовательские обобщённые типы¶User-defined generic types

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

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]):   # НЕДОПУСТИМО
    ...

Можно использовать множественное наследование с 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): # То же, что и Iterable[Any].

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

from typing import TypeVar, Iterable, Tuple, Union
S = TypeVar('S')
Response = Union[Iterable[S], int]

# Тип возврата здесь такой же, как 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: # То же, что Iterable[Tuple[T, T]]
    return sum(x*y for x, y in v)

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

26.1.6. Тип Any¶The Any type

Особым видом типа является Any. Статический проверяющий типов будет считать каждый тип совместимым с Any, а Any – совместимым с каждым типом.

Это означает, что над значением типа Any можно выполнять любые операции или вызовы методов и присваивать его любой переменной:

from typing import Any

a = None    # type: Any
a = []      # ОК
a = 2       # ОК

s = ''      # type: str
s = a       # ОК

def foo(item: Any) -> int:
    # Проходит проверку типов; 'item' может быть любого типа,
    # и этот тип может иметь метод 'bar'
    item.bar()
    ...

Обратите внимание, что никакая проверка типов не выполняется при присваивании значения типа Any более точному типу. Например, статический проверяющий типы не сообщил об ошибке при присваивании a переменной s, хотя s был объявлен как тип str и получает значение int во время выполнения!

Кроме того, все функции без указания типа возврата или типов параметров по умолчанию неявно используют Any:

def legacy_parser(text):
    ...
    return data

# Статический проверщик типов будет рассматривать вышеприведенное
# как имеющее ту же сигнатуру, что и:
def legacy_parser(text: Any) -> Any:
    ...
    return data

Такое поведение позволяет использовать Any в качестве запасного выхода, когда нужно смешивать динамически и статически типизированный код.

Сравните поведение Any с поведением object. Как и Any, каждый тип является подтипом object. Однако, в отличие от Any, обратное неверно: object не является подтипом любого другого типа.

Это означает, что когда тип значения – object, проверяющий типы будет отклонять почти все операции над ним, а присваивание его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например:

def hash_a(item: object) -> int:
    # Завершается ошибкой; у объекта нет метода 'magic'.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Проходит проверку типов.
    item.magic()
    ...

# Проходит проверку типов, так как int и str являются подклассами object.
hash_a(42)
hash_a("foo")

# Проходит проверку типов, так как Any совместим со всеми типами.
hash_b(42)
hash_b("foo")

Используйте object, чтобы указать, что значение может быть любого типа в типобезопасной манере. Используйте Any, чтобы указать, что значение динамически типизировано.

26.1.7. Классы, функции и декораторы¶Classes, functions, and decorators

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

class typing.TypeVar¶

Переменная типа.

Использование:

T = TypeVar('T')  # Может быть чем угодно
A = TypeVar('A', str, bytes)  # Должно быть str или bytes

Переменные типа существуют в первую очередь для статических анализаторов типов. Они служат параметрами для обобщённых типов, а также для определений обобщённых функций. См. класс Generic для получения дополнительной информации об обобщённых типах. Обобщённые функции работают следующим образом:

def repeat(x: T, n: int) -> Sequence[T]:
    """Возвращает список, содержащий n ссылок на x."""
    return [x]*n

def longest(x: A, y: A) -> A:
    """Возвращает самую длинную из двух строк."""
    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:
        ...
        # И т.д.

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

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         # Имеет тип 'int'
b = int       # Имеет тип 'Type[int]'
c = type(a)   # Также имеет тип 'Type[int]'

Обратите внимание, что Type[C] ковариантен:

class User: ...
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...

# Принимает 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.

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

Обобщённая версия 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.6.1.

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

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

class typing.AsyncIterator(AsyncIterable[T_co])¶

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

class typing.ContextManager(Generic[T_co])¶

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

Новое в версии 3.6.

class typing.AsyncContextManager(Generic[T_co])¶

ABC с асинхронными абстрактными методами __aenter__() и __aexit__().

Новое в версии 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.

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

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

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

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

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

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

Новое в версии 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.5.4.

class typing.Text¶

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

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

Типизированная версия 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 также могут иметь докстринги и методы:

class Employee(NamedTuple):
    """Представляет сотрудника."""
    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: Добавлена поддержка значений по умолчанию, методов и строк документации.

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__ по C.__mro__ в обратном порядке.

@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.Any¶

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

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

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

typing.NoReturn¶

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

from typing import NoReturn

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

Новое в версии 3.6.5.

typing.Union¶

Тип объединения; Union[X, Y] означает либо X, либо Y.

Чтобы определить объединение, используйте, например, Union[int, str]. Подробности:

• Аргументы должны быть типами, и их должно быть как минимум один.

• Объединения объединений разворачиваются, например:

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

• Объединения из одного аргумента исчезают, например:

  Union[int] == int  # Конструктор на самом деле возвращает int
  

• Повторяющиеся аргументы пропускаются, например:

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

• При сравнении объединений порядок аргументов игнорируется, например:

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

• Когда присутствуют класс и его подкласс, последний пропускается, например:

  Union[int, object] == object
  

• Нельзя создавать подкласс или экземпляр объединения.

• Нельзя записать Union[X][Y].

• Можно использовать Optional[X] как сокращение для Union[X, None].

typing.Optional¶

Тип 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[T1, T2] – это кортеж из двух элементов, соответствующих переменным типа T1 и T2. Tuple[int, float, str] – это кортеж из int, float и строки.

Чтобы задать кортеж переменной длины из однотипных элементов, используйте литеральное многоточие, например Tuple[int, ...]. Простой Tuple эквивалентен Tuple[Any, ...], а тот, в свою очередь, tuple.

typing.Callable¶

Тип 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]] = {} # переменная класса
    damage: int = 10                     # переменная экземпляра

ClassVar принимает только типы и не может быть дополнительно индексирован.

ClassVar сам по себе не является классом и не должен использоваться с isinstance() или issubclass(). ClassVar не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный:

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Ошибка: установка переменной класса на экземпляре
Starship.stats = {}     # Это корректно.

Новое в версии 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")  # Ок, результат имеет тип 'unicode'
concat(b"foo", b"bar")  # Ок, результат имеет тип 'bytes'
concat(u"foo", b"bar")  # Ошибка, нельзя смешивать unicode и 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()

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

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