fastapi_faults

fastapi-faults proporciona contratos de error tipados para FastAPI, conectando excepciones de Python con Problem Details de RFC 9457 y documentación de OpenAPI. Su idea central es que cada error de aplicación tiene una definición inmutable, utilizada consistentemente para el manejo de excepciones, respuestas application/problem+json y esquemas de OpenAPI generados. El proyecto tiene como objetivo evitar diccionarios de respuesta duplicados, registros globales del proceso y la divergencia entre los errores de los endpoints documentados y los reales. Los conceptos centrales son Fault y FaultRegistry. Un Fault mapea una excepción de dominio a campos como status, código estable, título, detalle, encabezados, ejemplos y esquemas. Una funcionalidad puede definir un FaultRegistry pequeño junto a su código, y la aplicación compone los registros explícitamente con FaultRegistry.merge. Las definiciones son inmutables, el orden de fusión es determinista y las clases de excepción, códigos, URIs de tipo o nombres de esquema conflictivos fallan durante la configuración. La opción type_base deriva una URI de tipo de problema estable de cada código de falla; en su lugar, un fault puede proporcionar un tipo explícito. La instalación falla cuando un fault de dominio no tiene ninguno de los dos, lo que evita que contratos incompletos lleguen a una aplicación en ejecución. Las rutas utilizan el APIRouter estándar de FastAPI, y registry.responses(...) genera los metadatos de respuesta para los faults declarados. La librería no hereda ni reemplaza APIRouter. Los faults declarados deben pertenecer al registro instalado en la aplicación. Los miembros de extensión de RFC 9457 pueden tiparse con modelos de Pydantic: un extensions_model valida campos de problema personalizados y un callable de extensions produce los valores, mientras que el esquema de problema generado describe esos miembros. La instalación de un registro puede normalizar los fallos del framework por defecto. La validación de solicitudes se convierte en una respuesta Problem Details 422 con errores estables y conscientes de la ubicación. HTTPException y los errores de enrutamiento reciben respuestas Problem Details correspondientes. La validación de respuestas y las excepciones inesperadas se convierten en respuestas seguras de error interno. Las opciones de instalación incluyen include_validation_error, include_http_exceptions e include_unhandled_error. Los ayudantes de prueba residen en tests/helpers.py del repositorio y no se distribuyen con la librería. Dentro de un checkout, pueden afirmar la divergencia entre el tiempo de ejecución y la documentación a través de funciones como assert_no_undeclared_faults, assert_openapi_contract y assert_problem. El monitor de faults no declarados debe activarse antes de la primera solicitud de la aplicación. Los requisitos son CPython 3.12, 3.13 o 3.14; FastAPI 0.115 o posterior inferior a 1.0; y Pydantic 2.9 o posterior inferior a 3.0. La instalación es a través de pip install fastapi_faults. El desarrollo utiliza uv sync --all-groups y las puertas de calidad ejecutan ruff format --check, ruff check, mypy, pytest y uv build. Hay ejemplos ejecutables en examples/minimal y examples/namespaced. El proyecto se publica bajo la Licencia MIT.