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を用いて明示的にレジストリを合成します。定義は不変であり、マージ順序は決定論的です。例外クラス、コード、type URI、またはスキーマ名が衝突した場合は、設定時に失敗します。type_baseオプションは各フォルトコードから安定したproblem type URIを導出しますが、フォルトが明示的なtypeを提供することも可能です。ドメインフォルトにそのどちらもない場合、インストールは失敗し、不完全なコントラクトが実行中のアプリケーションに混入するのを防ぎます。 ルートにはFastAPI標準のAPIRouterを使用し、registry.responses(...)が宣言されたフォルトのレスポンスメタデータを生成します。このライブラリはAPIRouterをサブクラス化したり置換したりしません。宣言されたフォルトは、アプリケーションにインストールされたレジストリに属している必要があります。RFC 9457の拡張メンバーはPydanticモデルで型定義でき、extensions_modelがカスタムプロブレムフィールドを検証し、extensionsコールバックが値を生成します。生成されるプロブレムスキーマにはこれらのメンバーが記述されます。 レジストリをインストールすると、デフォルトでフレームワークの失敗を正規化できます。リクエスト検証は、安定した場所を特定可能なエラーを含む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などの関数を通じて、ランタイムとドキュメントの乖離をアサートできます。未宣言フォルトモニターは、アプリケーションの最初のリクエスト前に開始する必要があります。 要件は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ライセンスの下でリリースされています。