Правильная рантайм-проверка типов в Python с typeguard.check_type

Разбираем корректное использование typeguard.check_type в Python: рантайм-проверка типов без ложных предикатов, безопасная обёртка с перегрузками и ясные типы.

Когда вы пытаетесь совместить статическую типизацию с гарантиями на этапе выполнения, стандартный cast(type, obj) в Python упирается в жёсткое ограничение: он не выполняет проверок во время выполнения. Либо вы доверяете аннотации, либо нет. Если же нужно действительно валидировать значения на рантайме и при этом не раздражать статические анализаторы, стоит использовать typeguard.check_type — при условии, что вы применяете его правильно и оборачиваете в типобезопасную обёртку.

Проблема: хелпер выглядит верно, но ломается на рантайме и в типизации

Представьте небольшую утилиту, которая сверяет значение с подсказкой типа и возвращает его при совпадении. Идея — получить прямолинейный, однострочный поток, без россыпи проверок if. Наивная реализация может выглядеть так:

from types import GenericAlias, UnionType
from typing import Any, cast
from annotated_types import T
from typeguard import check_type
def enforce_kind(item, hint):  # noqa: ANN401 Эта функция должна принимать значение Any
    """Return the item if it matches the expected type, otherwise raise TypeError."""
    if check_type(item, hint):
        return cast("T", item)
    message = f"Type check failed: type({item}) is {type(item)}, expected {hint}"
    raise TypeError(message)

На первый взгляд выглядит неплохо, но внутри спрятана тонкая ошибка, к тому же типизаторам не хватает сведений о возвращаемом типе.

Почему это ломается: что на самом деле возвращает check_type

Ключевой момент — поведение typeguard.check_type. Эта функция не возвращает булево значение. При успешной проверке она возвращает исходный объект, а при неуспехе выбрасывает TypeError. Следовательно, любая проверка на истинность вокруг неё некорректна и «стрельнёт» на ложноподобных значениях. Например, False или пустой словарь пройдут проверку типов, но в условии if оценятся как ложь и ошибочно отправятся по ветке ошибки.

Отсюда естественным выглядит и более прямой стиль вызова: obj = check_type(obj, type). Такой паттерн одновременно выражает и проверку на этапе выполнения, и уточнение типа после вызова.

До и после: что происходит в месте вызова

Со вспомогательной функцией место вызова получается лаконичным. Но и без неё поток остаётся таким же линейным, если позволить check_type вернуть значение:

# С использованием вспомогательной функции
payload = enforce_kind(fetch_payload(), dict[str])
token = enforce_kind(payload.get("key"), AssuredKey)
print(token)
# Используем check_type напрямую
payload = check_type(fetch_payload(), dict[str])
token = check_type(payload.get("key"), AssuredKey)
print(token)

Оба варианта обходятся без разветвлений и делают движение значения прозрачным. Важно опираться на возвращаемое значение, а не воспринимать check_type как предикат.

Типизация хелпера с перегрузками

Правильную типизацию задаёт сигнатура самой check_type. Её перегрузки объясняют, когда возвращается уточнённый тип, а когда остаётся Any:

@overload
def check_type(
    value: object,
    expected_type: type[T],
    *,
    forward_ref_policy: ForwardRefPolicy = ...,
    typecheck_fail_callback: TypeCheckFailCallback | None = ...,
    collection_check_strategy: CollectionCheckStrategy = ...,
) -> T: ...
@overload
def check_type(
    value: object,
    expected_type: Any,
    *,
    forward_ref_policy: ForwardRefPolicy = ...,
    typecheck_fail_callback: TypeCheckFailCallback | None = ...,
    collection_check_strategy: CollectionCheckStrategy = ...,
) -> Any: ...

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

Решение: возвращайте проверенное значение и пропишите перегрузки

Надёжная реализация оставляет check_type единственным источником истины и, при желании, переформулирует текст ошибки. Дополнительно она задаёт перегрузки для распространённых форм ожидаемых типов:

from types import GenericAlias, UnionType
from typing import Any, overload
from annotated_types import T
from typeguard import check_type
@overload
def affirm_kind(obj: object, expected: type[T]) -> T: ...
@overload
def affirm_kind(obj: object, expected: GenericAlias) -> GenericAlias: ...
@overload
def affirm_kind(obj: object, expected: UnionType) -> UnionType: ...
def affirm_kind(obj, expected):
    """Validate and return the object when types match, else raise TypeError."""
    try:
        return check_type(obj, expected)
    except TypeError:
        detail = f"Type check failed: type({obj}) is {type(obj)}, expected {expected}"
        raise TypeError(detail)

Такая версия корректно обращается с ложноподобными значениями, возвращает тот же объект и предоставляет достаточно типовой информации для статического анализа.

Почему эта тонкость важна

Ошибочная трактовка приводит к целому классу багов, проявляющихся лишь на ложноподобных, но корректных значениях. Если использовать check_type как предикат, вы теряете её результат и смешиваете проверку типов с истинностью — а функция делает совсем другое. Возвращая значение, вы согласуете поведение на рантайме с тем, что имели в виду, и получаете более ясные пути исполнения. А благодаря перегрузкам типизаторы понимают сужение типов и меньше требуют лишних аннотаций.

Вывод

Если вам нужна проверка типов на этапе выполнения в Python, опирайтесь на контракт check_type: при успехе она возвращает входное значение, при неуспехе бросает TypeError. Стройте вспомогательную функцию так, чтобы она возвращала это значение, и пропишите перегрузки для нужных вам форм ожидаемых типов. В местах вызова отдавайте предпочтение прямым присваиваниям, а не булевым проверкам. Так вы сохраните корректную семантику выполнения, улучшите читаемость и дадите статическим анализаторам нужные подсказки без лишней «церемонии».