fastapi_faults

fastapi-faults fournit des contrats d'erreur typés pour FastAPI, reliant les exceptions Python aux détails de problème RFC 9457 et à la documentation OpenAPI. Son idée centrale est que chaque erreur d'application possède une définition immuable, utilisée de manière cohérente pour la gestion des exceptions, les réponses application/problem+json et les schémas OpenAPI générés. Le projet vise à éviter la duplication des dictionnaires de réponses, les registres globaux au processus et le décalage entre les erreurs documentées et les erreurs réelles des points de terminaison. Les concepts fondamentaux sont Fault et FaultRegistry. Un Fault mappe une exception de domaine vers des champs tels que le statut, un code stable, le titre, le détail, les en-têtes, les exemples et les schémas. Une fonctionnalité peut définir un petit FaultRegistry à côté de son code, et l'application compose les registres explicitement avec FaultRegistry.merge. Les définitions sont immuables, l'ordre de fusion est déterministe, et les conflits de classes d'exception, de codes, d'URI de type ou de noms de schéma échouent lors de la configuration. L'option type_base dérive une URI de type de problème stable à partir de chaque code de faute ; une faute peut sinon fournir un type explicite. L'installation échoue lorsqu'une faute de domaine n'en possède aucun, ce qui empêche les contrats incomplets d'intégrer une application en cours d'exécution. Les routes utilisent l'APIRouter standard de FastAPI, et registry.responses(...) génère les métadonnées de réponses pour les fautes déclarées. La bibliothèque ne sous-classe ni ne remplace APIRouter. Les fautes déclarées doivent appartenir au registre installé sur l'application. Les membres d'extension RFC 9457 peuvent être typés avec des modèles Pydantic : un extensions_model valide les champs de problème personnalisés, et un appelable extensions produit les valeurs, le schéma de problème généré décrivant ces membres. L'installation d'un registre peut normaliser les échecs du framework par défaut. La validation des requêtes devient une réponse Problem Details 422 avec des erreurs stables et sensibles à l'emplacement. HTTPException et les erreurs de routage reçoivent des réponses Problem Details correspondantes. La validation des réponses et les exceptions inattendues deviennent des réponses d'erreur interne sécurisées. Les options d'installation incluent include_validation_error, include_http_exceptions et include_unhandled_error. Les aides au test se trouvent dans tests/helpers.py du dépôt et ne sont pas livrées avec la bibliothèque. Dans un checkout, elles peuvent affirmer le décalage entre le runtime et la documentation via des fonctions telles que assert_no_undeclared_faults, assert_openapi_contract et assert_problem. Le moniteur de fautes non déclarées doit être activé avant la première requête de l'application. Les prérequis sont CPython 3.12, 3.13 ou 3.14 ; FastAPI 0.115 ou plus récent (inférieur à 1.0) ; et Pydantic 2.9 ou plus récent (inférieur à 3.0). L'installation s'effectue via pip install fastapi_faults. Le développement utilise uv sync --all-groups et les portes de qualité exécutent ruff format --check, ruff check, mypy, pytest et uv build. Des exemples exécutables se trouvent dans examples/minimal et examples/namespaced. Le projet est publié sous licence MIT.