Типы дают наибольшую пользу в местах, где в программу поступают данные с неизвестной структурой. HTTP-запросы, webhook-сообщения, переменные окружения и ответы моделей нельзя считать корректными только потому, что рядом написана аннотация типа.
Разбирайте данные до передачи внутрь
Считайте внешние данные значением типа object (или используйте Any, только
если другого выхода нет), проверьте их один раз и преобразуйте в небольшую
внутреннюю структуру. После этого бизнес-логика может работать со значениями,
инварианты которых уже проверены.
def parse_limit(value: object) -> int:
if isinstance(value, bool) or not isinstance(value, int):
raise ValueError("limit must be an integer")
if value < 1:
raise ValueError("limit must be positive")
return value
Явная проверка на bool важна: в Python bool является подклассом int.
Проверка на границе — подходящее место, чтобы однозначно обработать такие
особенности языка.
Пусть внутренние модели остаются простыми
После разбора данных используйте обычные dataclass или чётко определённые модели вместо повторяющегося доступа к словарям. Это улучшает автодополнение, рефакторинг и статический анализ, сохраняя понятное поведение во время выполнения.
Проверьте один раз — затем полагайтесь на контракт
Если проверять данные по всему коду, сложно понять, какие инварианты уже выполняются. Узкий парсер на каждой внешней границе даёт остальной системе единый контракт, которому можно доверять.