6.2 · مشاكل متكررة (دليل)

المستوى 6 · في الممارسة

6.2مشاكل متكررة (دليل)

الهدف: امتلاك دليل « عرض ← أسباب ← إجراءات » للعوائق الشائعة في Python.
الوقت المقدّر: 12 دقيقة · إذا كان لديك 5 دقائق فقط: اقرأ «الأساسي في 30 ثانية» + المخطط.

الأساسي في 30 ثانية

  • المنعكس : عرض = أسباب محتملة = إجراء مستهدف — نشخص قبل لمس الشيفرة.
  • القراءة : التتبع (traceback) يُقرأ من الأسفل : السطر الأخير يسمي، والأعلى يحدد المكان.
  • العزل : كل فرق بين المحلي وCI يُعالج بـ venv ومتطلبات مثبتة ونسخ مواءمة.

خيط نبيل — الدليل الملصق بجانب الشاشة

نبيل يحتفظ بهذا الدليل بجانب شاشته. الحكم بعد سنة : ثلاثة أسطر خدمته أكثر — ‏venv غير مفعل وراء ModuleNotFoundError، وخلط الجدولة + المسافات، وCI حمراء بينما كان كل شيء أخضر محلياً. لكل منها، انتهى بتطبيق التسلسل (قراءة التتبع، والتحقق من السبب، والتصحيح) بدل التعديل عشوائياً.

عرض ملاحظ، وأسباب متحقق منها، وإجراءات بالترتيب : المنعكس يتم في ثلاثة أوقات.

التشخيص قبل إعادة التشغيل

معظم عوائق Python كلاسيكيات كبيرة : لكل عرض أسباب نمطية وإجراء مستهدف. الجدول أدناه يجمع الحالات الأكثر شيوعاً، من الاستيراد إلى النشر.

العَرَضالأسباب المحتملةالإجراءات
ModuleNotFoundErrorمفسر خاطئ، وvenv غير مفعل، وملف في مكان خاطئاختيار المفسر الصحيح، وتفعيل venv، والتحقق من المسار
IndentationError / TabErrorجدولة + مسافات مخلوطةالتحويل إلى 4 مسافات، وblack للتوحيد
NameErrorغلطة إملائية، ومتغير خارج النطاق، واستيراد منسيإعادة قراءة السطر الأخير، والتحقق من النطاق والاستيرادات
KeyError على قاموسمفتاح غائب، ووصول مباشر.get() مع قيمة افتراضية + التحقق من بيانات الإدخال
كان يعمل أمس (التبعيات)عام مخلوط، ونسخ منحرفة‏venv ‏+ متطلبات مثبتة، وإعادة بناء للإثبات
اختبارات حمراء بعد إعادة هيكلةسلوك متغير دون قصدقراءة الاختبار الخاطئ الوحيد، وتصحيح الشيفرة (لا الاختبار)، وإعادة التشغيل
واجهة لا تُبلغ في حاويةمضيف localhost بدل 0.0.0.0‏CMD مع --host 0.0.0.0، و-p للنشر
CI حمراء، والمحلي أخضرنسخ مختلفة، واختبار ناقص، وسر غائبمواءمة النسخ (المتطلبات)، وإعادة الإنتاج محلياً، والتحقق من الأسرار
سكربت بطيء على حجم كبيرحلقات Python بدل المتجه/المولدالتنميط (profiler)، والمتجهة (pandas/NumPy) أو yield
خطأ شائع في الفهم: « الدليل يعوض التشخيص ». خطأ. الجدول يعطي أسباباً محتملة، لا حكماً : اقرأ التتبع (السطر الأخير + الملف)، وتحقق، ثم طبق الإجراء المستهدف.
نص المخطط (SEO / قارئات الشاشة / الترجمة): منهج الدليل : 1) تسمية العرض الملاحظ (ModuleNotFoundError، وIndentationError، وNameError، وKeyError، والتبعيات، والاختبارات الحمراء، والحاوية، وCI، والبطء). 2) استبقاء الأسباب المحتملة للجدول دون استنتاج وحيد. 3) تطبيق الإجراءات بالترتيب (venv، و4 مسافات، والنطاق، و.get، وإعادة البناء، والاختبار الخاطئ، و0.0.0.0، والنسخ، والمتجهة). ‏4) قراءة التتبع من الأسفل والتوثيق (venv، وتلميحات، واختبارات). الدرس : عائق يعود يستدعي منهجاً، لا تعديلات عشوائية.

نص جاهز للقول — تشخيص دون لمس عشوائي (30 ثانية)

« عرضي : [ModuleNotFoundError ‏/ KeyError ‏/ CI حمراء / بطء]. أقرأ التتبع من الأسفل، وأحدد السبب المحتمل للدليل، وأطبق الإجراء المستهدف وأتحقق. »

نموذج نسخ ولصق — وصول آمن + خطأ دقيق

def taux_ville(ligne: dict) -> float:
    ville = ligne.get("ville", "inconnue")
    if ville == "inconnue":
        raise ValueError("clé 'ville' absente de la ligne")
    return float(ligne.get("taux", 0.0))

شركة صغيرة جداً / ميزانية صغيرة

لا جدول رسمي : عرض واحد، والسبب المحتمل للدليل، والإجراء والمسؤول مدون.

شركة صغيرة ومتوسطة في الجزائر

دمج الواقع المحلي في التشخيص : النسخ المثبتة، والحواسيب المشتركة، وذروات الاثنين المعروفة.

عن بعد / هجين

إضافة السجلات المكتوبة الفورية إلى الإجراءات : عن بعد، عرض غير مدون يشبه نظاماً يعمل.

بين الثقافات

توضيح الملاحظات كتابة : ما يبدو بديهياً (أي venv، وأي نسخة) ليس كذلك للجميع.

حذر: تذكير عام : عند سر مكشوف أو CI حمراء مرتبطة بالأسرار، أعد توليد المفتاح، وانقله إلى متغير بيئة خارج المستودع واعرض على المرجع المعين ؛ هذا الدليل لا يقدم رأياً قانونياً.

تحدي 48 ساعة — طبّق غداً

حدد عرضاً حالياً واحداً (استيراد، وKeyError، وCI حمراء)، وطبق سطر الدليل (تتبع مقروء + سبب متحقق منه + إجراء مستهدف).

قائمة الخروج من القسم
  • أعرف ربط العرض بأسبابه المحتملة.
  • أقرأ التتبع من الأسفل قبل التصحيح.
  • أعرف التوثيق بـ venv وتلميحات واختبارات.
تقييم ذاتي 1-5 : تشخيص قبل التعديل ؟تتبع مقروء بانتباه ؟
تحقّق من فهمك

سكربت نبيل يرفع KeyError على قاموس مبيعات. أي منعكس يطبق الدليل ؟

💡

نفس العائق الذي يعود دون توقف ليس عشر حوادث : إنه منهج يجب تصحيحه (venv، واختبارات، وتلميحات).