استثناءات مخصصة

استثناءات مخصصة — Custom Exceptions

الاستثناءات المدمجة في Python مثل ValueError وTypeError ممتازة للأخطاء العامة. لكن تطبيقك يملك منطقاً خاصاً — يحتاج أخطاء خاصة به. هل بريد المستخدم غير صالح؟ هل كلمة المرور ضعيفة جداً؟ هل الحساب البنكي ليس لديه رصيد كافٍ؟

ValueError("رصيد غير كافٍ") ينقل المعلومة، لكنه يعني أن المستدعي لا يستطيع التمييز بين “رصيد غير كافٍ” و"اسم غير صالح" إلا بقراءة نص الرسالة — وهذا هشّ. الحل: استثناءات مخصصة تعطي لكل حالة خطأ في تطبيقك اسماً واضحاً ونوعاً قابلاً للمقارنة.

أبسط استثناء مخصص

الاستثناءات في Python مجرد كلاسات ترث من Exception. أبسط شكل:

class InsufficientFundsError(Exception):
    pass  # لا نحتاج تعريف أي شيء — No need to define anything

هذا كافٍ تماماً. يمكنك إطلاقه والتقاطه:

raise InsufficientFundsError("الرصيد غير كافٍ للإتمام العملية")

try:
    withdraw(account, 5000)
except InsufficientFundsError as e:
    print(f"فشل السحب: {e}")

ورث InsufficientFundsError من Exception يعني أنه يُلتقط أيضاً بـ except Exception — كل الاستثناءات المخصصة تنتمي لعائلة Exception.

استثناء مع سياق إضافي

الميزة الحقيقية للاستثناءات المخصصة هي أنها كلاسات كاملة — يمكنها حمل بيانات:

main.go

class InsufficientFundsError(Exception):
    # استثناء مع معلومات إضافية — Exception with extra context
    def __init__(self, balance, amount):
        self.balance = balance    # الرصيد الحالي — Current balance
        self.amount = amount      # المبلغ المطلوب — Requested amount
        self.shortfall = amount - balance  # النقص — Shortfall
        # رسالة وصفية — Descriptive message
        super().__init__(
            f"رصيد غير كافٍ: لديك {balance:.2f} ر.س وتريد سحب {amount:.2f} ر.س "
            f"(ينقصك {self.shortfall:.2f} ر.س)"
        )

def withdraw(balance, amount):
    # التحقق ثم السحب — Validate then withdraw
    if amount > balance:
        raise InsufficientFundsError(balance, amount)
    return balance - amount

# اختبار السحب الناجح — Test successful withdrawal
try:
    new_balance = withdraw(1000.0, 300.0)
    print(f"تم السحب. الرصيد الجديد: {new_balance:.2f} ر.س")
except InsufficientFundsError as e:
    print(f"فشل: {e}")
    print(f"  الرصيد: {e.balance:.2f}")
    print(f"  النقص: {e.shortfall:.2f}")

print()

# اختبار السحب الفاشل — Test failed withdrawal
try:
    new_balance = withdraw(500.0, 750.0)
except InsufficientFundsError as e:
    print(f"فشل: {e}")
    print(f"  الرصيد: {e.balance:.2f}")
    print(f"  النقص: {e.shortfall:.2f}")

Output:

لاحظ: المستدعي يمكنه الوصول لـ e.balance وe.shortfall مباشرة — يستطيع عرضها في واجهة المستخدم، تسجيلها في log، أو استخدامها لاتخاذ قرار. ValueError("رصيد غير كافٍ") لا يوفر هذا.

التسلسل الهرمي — Exception Hierarchy

عندما يكبر التطبيق، تحتاج تصنيف الأخطاء. المثال الكلاسيكي هو أخطاء التحقق من البيانات:

main.go

# تسلسل هرمي لأخطاء التحقق — Validation error hierarchy

class ValidationError(Exception):
    # الأب: أي خطأ تحقق — Base: any validation error
    def __init__(self, field, message):
        self.field = field          # اسم الحقل — Field name
        self.message = message      # وصف المشكلة — Problem description
        super().__init__(f"{field}: {message}")

class EmailError(ValidationError):
    # خطأ تحقق خاص بالبريد — Email-specific validation error
    def __init__(self, email, reason):
        self.email = email
        super().__init__("email", f"'{email}' غير صالح — {reason}")

class PasswordError(ValidationError):
    # خطأ تحقق خاص بكلمة المرور — Password-specific validation error
    def __init__(self, reason):
        super().__init__("password", reason)

def validate_email(email):
    # التحقق من البريد الإلكتروني — Validate email
    if "@" not in email:
        raise EmailError(email, "يجب أن يحتوي على @")
    if "." not in email.split("@")[-1]:
        raise EmailError(email, "النطاق غير صالح")

def validate_password(password):
    # التحقق من كلمة المرور — Validate password
    if len(password) < 8:
        raise PasswordError("يجب أن تكون 8 أحرف على الأقل")
    if not any(c.isdigit() for c in password):
        raise PasswordError("يجب أن تحتوي على رقم واحد على الأقل")

# التقاط محدد — Catch specific
try:
    validate_email("ahmed.example.com")
except EmailError as e:
    print(f"خطأ بريد: {e}")
    print(f"  الحقل: {e.field}")

print()

# التقاط عام — Catch general (يعمل لأن EmailError يرث ValidationError)
try:
    validate_password("qwerty")
except ValidationError as e:
    print(f"خطأ تحقق: {e}")
    print(f"  الحقل: {e.field}")
    print(f"  هل هو خطأ مرور؟ {isinstance(e, PasswordError)}")

Output:

التسلسل الهرمي يعطيك مرونة في الالتقاط: except EmailError يلتقط أخطاء البريد فقط، except ValidationError يلتقط كل أخطاء التحقق بغض النظر عن الحقل. المستدعي يختار مستوى التفصيل الذي يحتاجه.

متى تعرّف استثناء مخصصاً؟

لا تعرّف استثناءً مخصصاً لكل شيء — الاستثناءات المدمجة قوية وكافية في كثير من الحالات. عرّف استثناءً مخصصاً عندما:

المستدعي يحتاج التمييز برمجياً: إذا كان الكود الأعلى يريد فعل شيء مختلف بناءً على نوع الخطأ (مثل: عرض رسالة مختلفة، إعادة المحاولة، إرسال إشعار)
الخطأ يحمل بيانات إضافية: إذا كان الخطأ يحتاج حقل الاسم، القيمة المُرسلة، أو أي سياق آخر لا تحمله رسالة النص وحدها
المكتبة أو الوحدة تملك منطق خاص: وحدة payments يجب أن تُطلق PaymentError، وليس ValueError عاماً — المستدعي يعرف أن الخطأ من طبقة الدفع

لا تعرّف استثناءً مخصصاً إذا كانت استثناءات Python المدمجة تصف الحالة بدقة.

تسلسل الاستثناءات — raise from

أحياناً تلتقط استثناءً من مكتبة خارجية وتريد إطلاق استثناء خاص بتطبيقك — لكن مع الحفاظ على الاستثناء الأصلي للتصحيح (debugging):

main.go

class DatabaseError(Exception):
    # خطأ قاعدة بيانات — Database error
    pass

class UserNotFoundError(DatabaseError):
    # مستخدم غير موجود — User not found
    def __init__(self, user_id):
        self.user_id = user_id
        super().__init__(f"المستخدم {user_id} غير موجود")

def fetch_user_from_db(user_id):
    # محاكاة قاعدة بيانات — Simulate database
    users = {1: "أحمد", 2: "نورة"}
    if user_id not in users:
        raise KeyError(f"id={user_id}")
    return users[user_id]

def get_user(user_id):
    # تحويل خطأ المكتبة لخطأ تطبيقنا — Convert library error to our app error
    try:
        return fetch_user_from_db(user_id)
    except KeyError as original_error:
        # raise X from Y — يحفظ السياق الأصلي للتصحيح
        raise UserNotFoundError(user_id) from original_error

# اختبار — Test
try:
    user = get_user(99)
except UserNotFoundError as e:
    print(f"خطأ: {e}")
    print(f"  معرف المستخدم: {e.user_id}")
    # السبب الأصلي محفوظ في __cause__
    print(f"  السبب الأصلي: {e.__cause__}")

Output:

raise UserNotFoundError(user_id) from original_error يفعل شيئين:

يُطلق UserNotFoundError — الاستثناء الذي يفهمه تطبيقنا
يحفظ original_error في خاصية __cause__ — متاح للتصحيح

عندما يطبع Python الـ traceback، يظهر كلا الاستثناءين مع عبارة “The above exception was the direct cause of the following exception” — مما يجعل تتبع المشكلة سهلاً.

raise from None — إخفاء السبب الأصلي

أحياناً السبب الأصلي تفصيل داخلي لا تريد كشفه للخارج:

try:
    db.query(sql)
except sqlite3.Error as e:
    # إخفاء تفاصيل قاعدة البيانات الداخلية — Hide internal DB details
    raise DatabaseError("فشل استعلام قاعدة البيانات") from None

from None يقطع سلسلة الاستثناءات — لن يظهر الاستثناء الأصلي في traceback.

تحدي: استثناء مخصص بسياق

تحدي — Challenge

# عرّف GradeError مع سياق: الدرجة والنطاق المسموح
# Define GradeError with context: grade and allowed range

class GradeError(Exception):
    def __init__(self, grade, min_val, max_val):
        self.grade = grade        # الدرجة المُرسلة — Submitted grade
        self.min_val = min_val    # الحد الأدنى — Minimum allowed
        self.max_val = max_val    # الحد الأقصى — Maximum allowed
        super().__init__(
            f"الدرجة {grade} خارج النطاق ({min_val}-{max_val})"
        )

def set_grade(grade):
    # تحقق من الدرجة وأطلق GradeError إذا كانت خارج 0-100
    # Validate grade and raise GradeError if outside 0-100
    if grade < 0 or grade > 100:
        raise GradeError(grade, 0, 100)
    return grade

# اختبار الدرجة غير الصالحة — Test invalid grade
try:
    set_grade(150)
except GradeError as e:
    print(f"خطأ التقييم: {e}")
    print(f"الدرجة المُرسلة: {e.grade}")
    print(f"النطاق المسموح: {e.min_val} إلى {e.max_val}")

# اختبار الدرجة الصالحة — Test valid grade
try:
    grade = set_grade(85)
    print(f"تم قبول الدرجة: {grade}")
except GradeError as e:
    print(f"خطأ: {e}")

خلاصة

الاستثناءات المخصصة تحوّل رسائل الخطأ من نصوص مبهمة إلى أنواع قابلة للمقارنة تحمل سياقاً. عرّف استثناءً مخصصاً عندما يحتاج المستدعي التمييز أو عندما تحمل بيانات لا تحملها رسالة نصية وحدها. نظّمها في تسلسل هرمي عندما تتعدد الأنواع. استخدم raise X from Y للحفاظ على سلسلة الاستثناءات للتصحيح. في الدرس التالي ستطبق كل هذا في مختبر تحقق كامل من بيانات التسجيل.