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

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

Исходный код: Lib/typing.py

Этот модуль поддерживает подсказки типов, как указано в PEP 484. Основная поддержка состоит из типов Any, Union, Tuple, Callable, TypeVar и Generic. Полную спецификацию см. в PEP 484. Упрощённое введение в подсказки типов см. в PEP 483.

Функция ниже принимает и возвращает строку и анотирована следующим образом:

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

В функции greeting, аргумент name ожидается типа str, а тип возвращаемого значения str. Подтипы принимаются в качестве аргументов.

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

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)

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

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

Обратите внимание, что эти проверки выполняются только статическим анализатором типов. Во время выполнения оператор Derived = NewType('Derived', Base) создаст функцию, которая немедленно возвращает переданный ей параметр. Это означает, что выражение Derived(some_value) не создаёт новый класс и не вносит дополнительной нагрузки, помимо вызова обычной функции.

Более точно, выражение some_value is Derived(some_value) всегда истинно во время выполнения.

Это также означает, что невозможно создать подтип Derived, поскольку это функция тождества во время выполнения, а не фактический тип. Аналогично, невозможно создать другой NewType() на основе типа Derived.

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 для получения дополнительной информации.

Примечание

Вспомните, что использование псевдонима типа объявляет два типа как равнозначные. Выполнив Alias = Original, вы заставите статический анализатора типов рассматривать Alias как точно эквивалентный Original во всех случаях. Это полезно, когда необходимо упростить сложные сигнатуры типов.

В отличие от этого, NewType объявляет один тип как подтип другого. Выполнив Derived = NewType('Derived', Original), вы заставите статический анализатора типов рассматривать Derived как подкласс Original, что означает, что значение типа Original не может использоваться там, где ожидается значение типа Derived. Это полезно для предотвращения логических ошибок с минимальными затратами во время выполнения.

3. 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].

4. Обобщённые типы

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

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]

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. Обобщённый класс может быть абстрактным, включая абстрактные методы или свойства, а обобщённые классы также могут иметь абстрактные базовые классы без конфликта метаклассов. Обобщённые метаклассы не поддерживаются. Результат параметризации обобщённых типов кэшируется, и большинство типов в модуле typing хэшируются и сравниваются на равенство.

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

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.

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

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

Type[Any] эквивалентно 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: 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.AbstractSet(Sized, Iterable[T_co], Container[T_co]): Обобщённая версия collections.abc.Set.

class typing.MutableSet(AbstractSet[T]): Обобщённая версия collections.abc.MutableSet.

class typing.Mapping(Sized, Iterable[KT], Container[KT], Generic[VT_co]): Обобщённая версия collections.abc.Mapping.

class typing.MutableMapping(Mapping[KT, VT]): Обобщённая версия collections.abc.MutableMapping.

class typing.Sequence(Sized, Iterable[T_co], Container[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.

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

Обратите внимание, что в отличие от многих других обобщённых типов в модуле 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'

class typing.io

Пространство имён для типов потоков ввода-вывода.

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

class typing.re

Пространство имён для типов совпадений с регулярными выражениями.

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

typing.NamedTuple(typename, fields)

Наименованный кортеж с типизацией.

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

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

Эквивалентно:

Employee = collections.namedtuple('Employee', ['name', 'id'])

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

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

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

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

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

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

typing.Optional

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

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

Обратите внимание, что это не то же самое, что необязательный аргумент, у которого есть значение по умолчанию. Необязательный аргумент с значением по умолчанию не обязательно должен использовать квалификатор Optional в своей аннотации типа (хотя он неявно выводится, если значение по умолчанию равно None). Обязательный аргумент всё ещё может иметь тип Optional, если явно разрешено значение None.

typing.Tuple

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

Пример: 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 = {}  # type: ClassVar[Dict[str, int]] # class variable
    damage = 10 # type: int                      # 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 от интерпретатора во время выполнения. Аннотации типа для локальных переменных не оцениваются, поэтому вторая аннотация не должна быть заключена в кавычки.