إذا استورد بايثون ملفاً من مشروعك بدلاً من الحزمة التي قمت بتثبيتها، فحدد أولاً الملف الذي يقوم بايثون بتحميله. على macOS، تحقق من المفسر النشط، ومسار الوحدة المستوردة، وأي ملفات أو مجلدات في المشروع تحمل الاسم نفسه. أعد تسمية الملف المحلي المتعارض، وأزل التخزين المؤقت للـ bytecode القديم إذا لزم الأمر، وشغّل المشروع باستخدام بيئة بايثون المقصودة.

1. تحقق من إصدار بايثون والوحدة قيد الاستخدام

في Terminal، انتقل إلى مجلد المشروع واطلب من بايثون الإبلاغ عن مصدر الوحدة. استبدل requests باسم الاستيراد الذي يواجه المشكلة؛ على سبيل المثال، الحزمة المثبتة باسم Pillow يتم استيرادها باسم PIL.

cd "/path/to/your/project"
command -v python3
python3 -c 'import sys, importlib.util; name = "requests"; print("Python:", sys.executable); print("Module:", importlib.util.find_spec(name))'

النتيجة التي تحتوي على origin ضمن دليل مشروعك، مثل .../requests.py، تشير إلى ملف محلي يحجب الحزمة الأصلية (shadowing). يضع بايثون دليل البرنامج النصي أو دليل العمل الحالي في بداية مسار البحث الخاص به، لذا يمكن لوحدة محلية تحمل الاسم نفسه أن تحظى بالأسبقية على الحزمة المثبتة. وثائق مسار بحث الوحدات في بايثون

إذا أبلغ الأمر عن None، فهذا يعني أن المفسر لا يمكنه العثور على الوحدة بهذا الاسم. وإذا أظهر موقعاً في site-packages، فقد يكون التعارض في مكان آخر: قد يقوم تطبيقك بتشغيل مفسر مختلف، أو قد يختلف اسم الاستيراد عن اسم تثبيت الحزمة، أو قد ينشأ الخطأ داخل إحدى تبعيات الحزمة.

2. ابحث عن التعارض المحلي وأعد تسميته

ابحث في المشروع عن ملف يحمل اسم الاستيراد، مثل requests.py، أو دليل يحمل هذا الاسم. تحقق أيضاً من أسماء المكتبات القياسية الشائعة مثل email.py أو json.py أو typing.py. أعد تسمية الملف أو الدليل إلى اسم مخصص للمشروع، ثم حدّث أي عمليات استيراد كانت تشير إلى تلك الوحدة المحلية. تجنب مجرد إعادة تسميته إلى اسم حزمة شائعة أخرى أو مكتبة قياسية.

إذا كان الملف المتعارض عبارة عن وحدة مقصودة في المشروع، فاحتفظ به ولكن امنحه اسماً مميزاً واستورده من خلال بنية حزم مشروعك. إن وجود ملف مشروع يصادف أنه يشارك حزمة تابعة لجهة خارجية في اسمها من شأنه أن يتسبب على الأرجح في عمليات استيراد جزئية مربكة أو أخطاء تتعلق بفقدان السمات (missing attributes).

بعد إعادة التسمية، احذف فقط دليل __pycache__ المطابق إذا بقي موجوداً بجوار الملف القديم. يتحقق بايثون عادةً من أوقات تعديل ملفات المصدر ويقوم بتحديث التخزين المؤقت للـ bytecode تلقائياً؛ وحذف التخزين المؤقت المطابق هو مجرد خطوة تنظيف، وليس بديلاً عن حل تعارض الأسماء. وثائق الوحدات والـ bytecode في بايثون

3. تأكد من أن الحزمة تنتمي إلى نسخة بايثون التي تقوم بتشغيلها

في نظام macOS، من الشائع وجود أكثر من تثبيت لبايثون أو بيئة مشروع. الملف التنفيذي المعروض كـ sys.executable هو المفسر الكامن وراء الأمر الذي قمت بتشغيله للتو. ثبّت الحزم عبر هذا المفسر حتى لا يشير pip وبايثون دون قصد إلى بيئات مختلفة:

python3 -m pip show requests
python3 -m pip install requests

استخدم اسم توزيع الحزمة مع pip show واسم الاستيراد الخاص بها مع بايثون. قد يختلف الاسمان؛ على سبيل المثال، يتم استيراد Pillow عادةً باسم PIL. وتعني نتيجة "package not found" من pip show أن هذا التوزيع غير مثبت للمفسر المستخدم بواسطة هذا الأمر.

لإنشاء بيئة مخصصة للمشروع، أنشئ بيئة افتراضية وفعّلها من دليل المشروع، ثم ثبّت التبعية هناك:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -c 'import requests; print(requests.__file__)'

مع تفعيل البيئة، يجب أن يشير python إلى المفسر الخاص بها. يطبع الأمر الأخير مسار الملف الفعلي الذي تم تحميله؛ تأكد من أنه يقع أسفل .venv بدلاً من المستوى الأعلى لمشروعك. تعمل البيئات الافتراضية على عزل حزم المشروع عن البيئات الأخرى ويتم إنشاؤها باستخدام python -m venv. وثائق venv في بايثون

4. تحقق من تجاوزات المسار وأعد التشغيل بطريقة نظيفة

إذا كانت الوحدة لا تزال تشير إلى موقع غير متوقع، فافحص مسار بحث بايثون وأي تجاوز عبر PYTHONPATH:

python -c 'import os, sys; print("PYTHONPATH:", os.environ.get("PYTHONPATH")); print("sys.path:"); print("\n".join(sys.path))'

تتم تهيئة sys.path باستخدام PYTHONPATH والإعدادات الافتراضية التي تعتمد على التثبيت؛ وفي الاستدعاءات الشائعة، يسبق بايثون ذلك أيضاً بإضافة دليل البرنامج النصي أو دليل العمل الحالي. أزل إعداد PYTHONPATH غير المقصود من واجهة الأوامر (shell) الحالية باستخدام unset PYTHONPATH، ثم أعد تشغيل الفحص التشخيصي. بالنسبة للإعدادات الدائمة، افحص ملف بدء تشغيل واجهة الأوامر الذي تم تعيينه فيه وأزل أو صحح أمر التصدير (export) هذا. وثائق sys.path في بايثون

أعد تشغيل عملية بايثون بعد إعادة تسمية الملفات أو تغيير البيئات: إذ يمكن للمفسر الذي يعمل بالفعل أن يحتفظ بالوحدات التي استوردها في الذاكرة. ثم كرر فحص المصدر وشغّل الأمر أو التطبيق بنفس الطريقة التي تتبعها عادةً. وإذا كان المصدر صحيحاً ولكن الاستيراد لا يزال يفشل، فاقرأ التتبع الكامل للخطأ (traceback)؛ فقد يحدد ذلك تبعية مفقودة أو خطأ حدث أثناء تحميل الحزمة، بدلاً من وجود تعارض في الأسماء.

المصادر