Об этом проекте

fastapi-faults предоставляет типизированные контракты ошибок для FastAPI, связывая исключения Python с Problem Details RFC 9457 и документацией OpenAPI. Основная идея заключается в том, что каждая ошибка приложения имеет одно неизменяемое определение, которое последовательно используется для обработки исключений, ответов application/problem+json и генерируемых схем OpenAPI. Проект стремится избежать дублирования словарей ответов, глобальных реестров процессов и расхождений между задокументированными и фактическими ошибками эндпоинтов. Основными концепциями являются Fault и FaultRegistry. Fault сопоставляет доменное исключение с такими полями, как статус, стабильный код, заголовок, детали, заголовки, примеры и схемы. Функция может определять небольшой FaultRegistry рядом со своим кодом, а приложение явно объединяет реестры с помощью FaultRegistry.merge. Определения неизменяемы, порядок слияния детерминирован, а конфликтующие классы исключений, коды, URI типов или имена схем вызывают ошибку при конфигурации. Опция type_base выводит стабильный URI типа проблемы из каждого кода ошибки; в противном случае Fault может предоставить явный тип. Установка завершается ошибкой, если доменный Fault не имеет ни того, ни другого, что предотвращает попадание неполных контрактов в работающее приложение. Маршруты используют стандартный APIRouter из FastAPI, а registry.responses(...) генерирует метаданные ответов для объявленных Fault. Библиотека не наследует и не заменяет APIRouter. Объявленные Fault должны принадлежать реестру, установленному в приложении. Расширения RFC 9457 могут быть типизированы с помощью моделей Pydantic: extensions_model валидирует пользовательские поля проблемы, а вызываемый объект extensions создает значения, при этом генерируемая схема проблемы описывает эти члены. Установка реестра может по умолчанию нормализовать сбои фреймворка. Валидация запросов становится ответом Problem Details 422 со стабильными ошибками, привязанными к местоположению. HTTPException и ошибки маршрутизации получают соответствующие ответы Problem Details. Валидация ответов и непредвиденные исключения становятся безопасными ответами о внутренней ошибке. Опции установки включают include_validation_error, include_http_exceptions и include_unhandled_error. Помощники для тестирования находятся в tests/helpers.py репозитория и не поставляются с библиотекой. В рамках копии репозитория они могут проверять расхождения между временем выполнения и документацией с помощью таких функций, как assert_no_undeclared_faults, assert_openapi_contract и assert_problem. Монитор необъявленных ошибок должен быть запущен до первого запроса к приложению. Требования: CPython 3.12, 3.13 или 3.14; FastAPI 0.115 или новее (до 1.0); Pydantic 2.9 или новее (до 3.0). Установка осуществляется через pip install fastapi_faults. Разработка использует uv sync --all-groups, а проверки качества выполняются с помощью ruff format --check, ruff check, mypy, pytest и uv build. Запускаемые примеры находятся в examples/minimal и examples/namespaced. Проект выпущен под лицензией MIT.