fastapi_faults

fastapi-faults는 Python 예외를 RFC 9457 Problem Details 및 OpenAPI 문서와 연결하여 FastAPI를 위한 타입 지정 오류 계약을 제공합니다. 핵심 아이디어는 모든 애플리케이션 오류가 하나의 불변 정의를 가지며, 이를 예외 처리, application/problem+json 응답 및 생성된 OpenAPI 스키마에 일관되게 사용하는 것입니다. 이 프로젝트는 중복된 응답 딕셔너리, 프로세스 전역 레지스트리, 그리고 문서화된 오류와 실제 엔드포인트 오류 간의 괴리를 방지하는 것을 목표로 합니다. 핵심 개념은 Fault와 FaultRegistry입니다. Fault는 도메인 예외를 상태(status), 안정적인 코드(stable code), 제목(title), 세부 내용(detail), 헤더(headers), 예시(examples) 및 스키마(schemas)와 같은 필드에 매핑합니다. 각 기능은 코드 옆에 작은 FaultRegistry를 정의할 수 있으며, 애플리케이션은 FaultRegistry.merge를 통해 레지스트리를 명시적으로 구성합니다. 정의는 불변이며, 병합 순서는 결정론적입니다. 충돌하는 예외 클래스, 코드, 타입 URI 또는 스키마 이름이 있을 경우 설정 중에 실패합니다. type_base 옵션은 각 fault 코드로부터 안정적인 problem type URI를 도출하며, fault가 명시적인 타입을 제공할 수도 있습니다. 도메인 fault에 둘 다 없는 경우 설치가 실패하여 불완전한 계약이 실행 중인 애플리케이션에 포함되지 않도록 합니다. 라우트는 FastAPI의 표준 APIRouter를 사용하며, registry.responses(...)는 선언된 fault에 대한 응답 메타데이터를 생성합니다. 이 라이브러리는 APIRouter를 서브클래싱하거나 대체하지 않습니다. 선언된 fault는 애플리케이션에 설치된 레지스트리에 속해야 합니다. RFC 9457 확장 멤버는 Pydantic 모델로 타입을 지정할 수 있습니다. extensions_model은 사용자 정의 problem 필드를 검증하고, extensions 호출 가능 객체는 값을 생성하며, 생성된 problem 스키마가 해당 멤버들을 설명합니다. 레지스트리를 설치하면 기본적으로 프레임워크 실패를 정규화할 수 있습니다. 요청 검증은 안정적이고 위치 인지적인 오류를 포함한 422 Problem Details 응답이 됩니다. HTTPException 및 라우팅 오류는 그에 맞는 Problem Details 응답을 받습니다. 응답 검증 및 예상치 못한 예외는 안전한 내부 오류 응답이 됩니다. 설치 옵션에는 include_validation_error, include_http_exceptions, include_unhandled_error가 포함됩니다. 테스트 헬퍼는 저장소의 tests/helpers.py에 있으며 라이브러리와 함께 배포되지 않습니다. 체크아웃 내에서 assert_no_undeclared_faults, assert_openapi_contract, assert_problem과 같은 함수를 통해 런타임과 문서 간의 괴리를 확인(assert)할 수 있습니다. undeclared-fault 모니터는 애플리케이션의 첫 번째 요청 전에 진입해야 합니다. 요구 사항은 CPython 3.12, 3.13 또는 3.14, 1.0 미만의 FastAPI 0.115 이상, 3.0 미만의 Pydantic 2.9 이상입니다. 설치는 pip install fastapi_faults를 통해 이루어집니다. 개발에는 uv sync --all-groups를 사용하며, 품질 게이트는 ruff format --check, ruff check, mypy, pytest 및 uv build를 실행합니다. 실행 가능한 예제는 examples/minimal 및 examples/namespaced에 있습니다. 이 프로젝트는 MIT 라이선스로 배포됩니다.