Python 3.5+Аннотации и typingпонятие

TYPE_CHECKING

импорт

Булева константа, True только при статическом анализе (mypy, pyright). Позволяет импортировать типы лишь для аннотаций, избегая циклических импортов в рантайме.

Синтаксис

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from module import SomeType

Раз импорт под if TYPE_CHECKING в рантайме не выполняется, имя из него не должно попадать в вычисляемый код — в значения по умолчанию, cast(), isinstance. В аннотациях с Python 3.14 его можно писать без кавычек: аннотации вычисляются лениво, и модуль загрузится без ошибки (до 3.14 нужны были кавычки или from __future__ import annotations, иначе NameError при загрузке). Побочный эффект остаётся: всё, что читает типы во время работы программы (typing.get_type_hints, __annotations__, dataclasses, валидаторы), не сможет разрешить такое имя и получит NameError.

Примеры

from typing import TYPE_CHECKING
print(TYPE_CHECKING)  # → False  (в рантайме)
if TYPE_CHECKING:
    from collections import OrderedDict

from typing import TYPE_CHECKING
def process(path: 'str') -> None:
    print(path)
process('test')  # → test
print(bool(TYPE_CHECKING))  # → False

См. также

Открыть в полном глоссарииdocs.python.orgСообщить о неточности