عن المشروع

توفر fastapi-faults عقود أخطاء محددة النوع لـ FastAPI، حيث تربط استثناءات Python بتفاصيل المشكلات RFC 9457 وتوثيق OpenAPI. الفكرة الأساسية هي أن كل خطأ في التطبيق له تعريف واحد غير قابل للتغيير، يُستخدم باستمرار لمعالجة الاستثناءات، واستجابات application/problem+json، ومخططات OpenAPI المُنشأة. يهدف المشروع إلى تجنب تكرار قواميس الاستجابة، والسجلات العالمية على مستوى العملية، والانحراف بين أخطاء النقاط النهائية الموثقة والفعلية. المفاهيم الأساسية هي Fault و FaultRegistry. يقوم Fault بربط استثناء النطاق بحقول مثل الحالة (status)، والرمز المستقر (stable code)، والعنوان، والتفاصيل، والرؤوس، والأمثلة، والمخططات. يمكن للميزة تعريف FaultRegistry صغير بجانب الكود الخاص بها، ويقوم التطبيق بدمج السجلات صراحةً باستخدام FaultRegistry.merge. التعريفات غير قابلة للتغيير، وترتيب الدمج حتمي، وتفشل التكوينات في حالة وجود تعارض في فئات الاستثناءات أو الرموز أو معرفات النوع (type URIs) أو أسماء المخططات. يشتق خيار type_base معرف نوع مشكلة مستقر من رمز كل خطأ؛ أو يمكن للخطأ تقديم نوع صريح. يفشل التثبيت عندما لا يمتلك خطأ النطاق أيًا منهما، مما يمنع العقود غير المكتملة من الوصول إلى التطبيق المشغل. تستخدم المسارات APIRouter القياسي الخاص بـ FastAPI، ويقوم registry.responses(...) بتوليد بيانات وصف الاستجابات للأخطاء المعلنة. لا تقوم المكتبة بإنشاء فئة فرعية من APIRouter أو استبداله. يجب أن تنتمي الأخطاء المعلنة إلى السجل المثبت في التطبيق. يمكن تحديد نوع أعضاء تمديد RFC 9457 باستخدام نماذج Pydantic: حيث يقوم extensions_model بالتحقق من حقول المشكلة المخصصة، ويقوم extensions القابل للاستدعاء بإنتاج القيم، مع وصف مخطط المشكلة المُنشأ لتلك الأعضاء. يمكن لتثبيت السجل توحيد إخفاقات الإطار البرمجي بشكل افتراضي. تصبح عملية التحقق من الطلب استجابة Problem Details برمز 422 مع أخطاء مستقرة ومحددة الموقع. وتتلقى 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.