Сообщить об ошибке.

Помощники самоанализа модуля typing в Python

В разделе рассмотрены функции, которые помогают провести самоанализ проведенной типизации исходного кода программистом.

Содержание:

typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False):

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

Часто это то же самое, что и obj.__annotations__. Кроме того, прямые ссылки, закодированные как строковые литералы, обрабатываются путем их оценки в глобальных и локальных пространствах имен. При необходимости для аннотаций функций и методов добавляется Optional[t], если задано значение по умолчанию, равное None. Для класса C вернет словарь, созданный путем объединения всех __annotations__ по C.__mro__ в обратном порядке.

Функция рекурсивно заменяет все Annotated[T, ...] на T, если для include_extras не установлено значение True (смотрите тип аннотации Annotated для получения дополнительной информации).

Например:

class Student(NamedTuple):
    name: Annotated[str, 'some marker']

get_type_hints(Student) == {'name': str}
get_type_hints(Student, include_extras=False) == {'name': str}
get_type_hints(Student, include_extras=True) == {
    'name': Annotated[str, 'some marker']
}

Изменено в Python 3.9: добавлен параметр include_extras

Изменено в версии 3.11: ранее для аннотаций функций и методов добавлялся Optional[t], если было установлено значение по умолчанию, равное None. Теперь аннотация возвращается без изменений.

typing.get_args(tp):
typing.get_origin(tp):

Функция typing.get_origin() обеспечивает базовый самоанализ для общих типов и специальных форм ввода.

Для типизирующего объекта формы X[Y, Z, ...] обе функции возвращают X и кортеж (Y, Z, ...). Если X является общим псевдонимом для встроенного класса или класса коллекций, то он нормализуется до исходного класса. Если X является Union или Literal, содержащимся в другом общем типе, то порядок (Y, Z, ...) может отличаться от порядка исходных аргументов [Y, Z, ...] из-за кэширования типов. Для неподдерживаемых объектов возвращает None и () соответственно.

Примеры:

assert get_origin(Dict[str, int]) is dict
assert get_args(Dict[int, str]) == (int, str)

assert get_origin(Union[int, str]) is Union
assert get_args(Union[int, str]) == (int, str)

Новое в Python 3.8.

typing.get_protocol_members(tp):

Добавлено в Python 3.13.

Функция typing.get_protocol_members() возвращает набор элементов, определенных в протоколе.

Вызывает исключение TypeError для аргументов, которые не являются протоколами.

from typing import Protocol, get_protocol_members

class P(Protocol):
    def a(self) -> str: ...
    b: int

>>> get_protocol_members(P) == frozenset({'a', 'b'})
# True

typing.is_protocol(tp):

Добавлено в Python 3.13.

Функция typing.is_protocol() определяет, является ли тип протоколом.

Пример:

class P(Protocol):
    def a(self) -> str: ...
    b: int

is_protocol(P)    # => True
is_protocol(int)  # => False

typing.is_typeddict(tp):

Добавлено в Python 3.10.

Функция typing.is_typeddict() определяет, является ли тип TypedDict.

Пример:

class Film(TypedDict):
    title: str
    year: int

assert is_typeddict(Film)
assert not is_typeddict(list | str)

# TypedDict is a factory for creating typed dicts,
# not a typed dict itself
assert not is_typeddict(TypedDict)

typing.ForwardRef:

Класс typing.ForwardRef используется для внутреннего представления типизации прямых ссылок на строки.

Например, List['SomeClass'] неявно преобразуется в List[ForwardRef('SomeClass')]. ForwardRef не должен создаваться пользователем, но может использоваться инструментами самоанализа.

Примечание. Общие типы PEP 585, такие как list['SomeClass'] не будут неявно преобразованы в list[ForwardRef('SomeClass')] и, следовательно, не будут автоматически разрешаться в list[SomeClass].

Изменено в Python 3.14: Теперь это псевдоним для annotationlib.ForwardRef. Несколько недокументированных поведений этого класса были изменены; например, после вычисления ForwardRef вычисленное значение больше не кэшируется.

typing.evaluate_forward_ref(forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=annotationlib.Format.VALUE):

Добавлено в Python 3.14.

Функция typing.evaluate_forward_ref() вычисляет annotationlib.ForwardRef как подсказку типа.

Это похоже на вызов annotationlib.ForwardRef.evaluate(), но в отличие от этого метода, evaluate_forward_ref() также рекурсивно вычисляет ссылки вперед, вложенные в подсказку типа.

from typing import evaluate_forward_ref
from annotationlib import ForwardRef

# Создание forward reference
forward_ref = ForwardRef('list[int]')

# Вычисление forward reference
result = evaluate_forward_ref(forward_ref)
print(result)  # list[int]

typing.NoDefault:

Добавлено в Python 3.13.

Дозорный объект typing.NoDefault, используемый для указания того, что параметр типа не имеет значения по умолчанию. Например:

>>> T = TypeVar("T")
>>> T.__default__ is typing.NoDefault
# True
>>> S = TypeVar("S", default=None)
>>> S.__default__ is None
# True

Константа модуля

typing.TYPE_CHECKING:

Специальная константа 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 от среды выполнения интерпретатора. Аннотации типов для локальных переменных не оцениваются, поэтому вторую аннотацию не нужно заключать в кавычки.

Примечание. Если аннотации импорта from __future__ используются в Python 3.7 или новее, аннотации не оцениваются во время определения функции, а хранятся в виде строк в __annotations__. Это делает ненужным использование кавычек вокруг аннотации.