fastapi_faults

O fastapi-faults fornece contratos de erro tipados para FastAPI, conectando exceções Python a Problem Details do RFC 9457 e documentação OpenAPI. Sua ideia central é que cada erro de aplicação possui uma definição imutável, usada consistentemente para tratamento de exceções, respostas application/problem+json e esquemas OpenAPI gerados. O projeto visa evitar dicionários de respostas duplicados, registros globais de processo e divergências entre os erros de endpoint documentados e reais. Os conceitos centrais são Fault e FaultRegistry. Um Fault mapeia uma exceção de domínio para campos como status, código estável, título, detalhe, cabeçalhos, exemplos e esquemas. Uma funcionalidade pode definir um pequeno FaultRegistry ao lado de seu código, e a aplicação compõe os registros explicitamente com FaultRegistry.merge. As definições são imutáveis, a ordem de mesclagem é determinística e classes de exceção, códigos, URIs de tipo ou nomes de esquema conflitantes falham durante a configuração. A opção type_base deriva uma URI de tipo de problema estável de cada código de falha; alternativamente, um fault pode fornecer um tipo explícito. A instalação falha quando um fault de domínio não possui nenhum dos dois, o que impede que contratos incompletos cheguem a uma aplicação em execução. As rotas utilizam o APIRouter padrão do FastAPI, e registry.responses(...) gera os metadados de respostas para os faults declarados. A biblioteca não herda nem substitui o APIRouter. Os faults declarados devem pertencer ao registro instalado na aplicação. Membros de extensão do RFC 9457 podem ser tipados com modelos Pydantic: um extensions_model valida campos de problema personalizados e um chamável extensions produz os valores, com o esquema de problema gerado descrevendo esses membros. A instalação de um registro pode normalizar falhas do framework por padrão. A validação de requisições torna-se uma resposta Problem Details 422 com erros estáveis e conscientes da localização. HTTPException e erros de roteamento recebem respostas Problem Details correspondentes. A validação de resposta e exceções inesperadas tornam-se respostas de erro interno seguras. As opções de instalação incluem include_validation_error, include_http_exceptions e include_unhandled_error. Auxiliares de teste residem em tests/helpers.py no repositório e não são distribuídos com a biblioteca. Dentro de um checkout, eles podem afirmar a divergência entre tempo de execução e documentação através de funções como assert_no_undeclared_faults, assert_openapi_contract e assert_problem. O monitor de faults não declarados deve ser ativado antes da primeira requisição da aplicação. Os requisitos são CPython 3.12, 3.13 ou 3.14; FastAPI 0.115 ou superior abaixo de 1.0; e Pydantic 2.9 ou superior abaixo de 3.0. A instalação é via pip install fastapi_faults. O desenvolvimento utiliza uv sync --all-groups e os portões de qualidade executam ruff format --check, ruff check, mypy, pytest e uv build. Exemplos executáveis estão em examples/minimal e examples/namespaced. O projeto é lançado sob a Licença MIT.