لاختبار حزمة wheel التي أنشأها مشروعك بالفعل، قم بإنشاء بيئة افتراضية جديدة على macOS، وثبّت ملف wheel من dist/، وتحقق من صحة بياناتها الوصفية وسلوك الاستيراد الخاص بها. قم بتشغيل الأوامر أدناه من دليل مشروعك في Terminal. يختبر هذا التثبيت لإصدار Python وبنية معمارية Mac التي استخدمتها؛ وهو لا يثبت التوافق مع كل إصدار Python أو Mac مدعوم.

1. بناء حزمة wheel من مشروعك

استخدم مفسر Python الذي ترغب في اختباره. في نظام macOS، يُعد python3 أمرًا شائعًا لـ Python 3؛ وإذا كنت تستخدم مدير إصدارات، فحدد المفسر المطلوب أولاً. من الدليل الذي يحتوي على pyproject.toml، قم ببناء حزمة wheel باستخدام أداة build التابعة لـ Python Packaging Authority: يوثق قسم Packaging Python Projects خطوة البناء هذه ودليل dist/ الناتج عنها.

python3 -m pip install --upgrade build
python3 -m build --wheel

ينشئ أمر البناء ملف .whl في dist/. يتيح البناء من جذر المشروع استخدام الحزمة الناتجة لاختبار التثبيت أدناه. تعد حزمة wheel هي التوزيع المبني الذي تريد اختباره؛ حيث إن تثبيت دليل المشروع أو استخدام الوضع القابل للتحرير (editable mode) سيختبر مسار تثبيت مختلفًا. راجع The Packaging Flow لمعرفة الفرق بين شجرة المصدر، وحزم البناء الناتجة، والتثبيت.

2. إنشاء بيئة افتراضية جديدة

أنشئ البيئة في دليل المشروع، ولكن احتفظ بمخرجات البناء منفصلة عنها. إذا كان المجلد .venv-wheel-test موجودًا بالفعل وتريد تشغيلًا نظيفًا، فاحذفه أولاً؛ يحذف هذا الأمر ذلك الدليل المحدد ومحتوياته نهائيًا، لذا تأكد من صحة المسار قبل تشغيله.

rm -rf .venv-wheel-test
python3 -m venv .venv-wheel-test
source .venv-wheel-test/bin/activate
python -m pip --version

يجب أن يحتوي مسار pip الظاهر في النتيجة على .venv-wheel-test. تنشئ أداة venv في Python بيئة معزولة بناءً على المفسر المستخدم لإنشائها، مع حزمها المثبتة الخاصة بها؛ ويدعم غلاف zsh الافتراضي في macOS Terminal أمر التنشيط source الموضح هنا. توضح وثائق venv في Python كلاً من العزل والتنشيط. لتجنب الاعتماد على التنشيط أو على أي أمر python موجود في مسار shell الخاص بك، استخدم .venv-wheel-test/bin/python بدلاً من python في الأوامر المتبقية.

3. تثبيت ملف wheel وليس دليل المصدر

اعرض ملفات wheel حتى تتمكن من تحديد الملف الدقيق المطلوب اختباره:

ls dist/*.whl

انسخ اسم الملف المطلوب من المخرجات وضعه في الأمر أدناه. احتفظ بعلامات التنصيص، واستبدل اسم الملف النموذجي بالاسم الفعلي. اسم الملف الموضح الذي يحتوي على شرطات هو للتوضيح فقط؛ حيث تتضمن أسماء ملفات wheel اسم التوزيع، والإصدار، وعلامات التوافق، لذا سيختلف اسم ملفك.

python -m pip install "dist/my_package-1.2.3-py3-none-any.whl"

يقوم هذا بتثبيت حزمة wheel المحلية وحل التبعيات المعلنة لها من فهرس الحزم المكوَّن إذا لزم الأمر. وهو لا يقوم بتثبيت دليل المصدر الخاص بك. يدعم pip تثبيت أرشيفات التوزيع المحلية مباشرةً، كما هو موضح في Install packages in a virtual environment using pip and venv. إذا كان يجب إجراء الاختبار بدون اتصال بالشبكة، فاجعل تبعيات ملف wheel متاحة محليًا أيضًا؛ وإلا فقد يفشل حل التبعيات. إذا استخدمت --no-deps، سيتخطى pip تثبيت التبعيات، وبالتالي قد تفشل عمليات الاستيراد التي تتطلب تلك الحزم حتى لو تم تثبيت حزمة wheel نفسها بنجاح.

4. التحقق من التثبيت وسلوك الاستيراد

تحقق من البيانات الوصفية للتوزيع المثبت وما إذا كانت التبعيات المعلنة متسقة:

python -m pip show my-package
python -m pip check

استخدم اسم التوزيع الموضح في اسم ملف wheel أو البيانات الوصفية للمشروع مع pip show؛ فقد يختلف عن اسم الاستيراد في Python. ثم اختبر الاستيراد باستخدام اسم الوحدة النمطية (module) المذكور في وثائق حزمتك. على سبيل المثال، إذا كانت الوحدة هي my_package، فقم بتشغيل:

python -c 'import my_package; print(my_package.__file__)'

الاستيراد الناجح الذي يشير مسار ملفه إلى داخل .venv-wheel-test يعد دليلاً على أنه يتم استيراد الحزمة المثبتة من بيئة الاختبار. لا يختبر الاستيراد بمفرده كل دالة أو نقطة دخول: شغّل اختبارات مشروعك ذات الصلة ضد هذه البيئة إذا كنت بحاجة إلى تغطية سلوكية كاملة.

عندما يفشل تثبيت حزمة wheel

يشير الخطأ المتعلق بعدم توافق حزمة wheel عادةً إلى أن علامات التوافق الخاصة بها لا تتطابق مع إصدار Python النشط، أو macOS، أو معمارية وحدة المعالجة المركزية (CPU). الحزم التي تحتوي على ملحقات مجمّعة (compiled extensions) قد تكون مخصصة لمنصة معينة؛ بينما يمكن استخدام حزمة wheel المكتوبة بلغة Python الصرفة على نطاق أوسع. توضح مواصفات علامات توافق المنصة كيفية استخدام أدوات التثبيت لهذه العلامات. قم ببناء أو الحصول على حزمة wheel متوافقة للمفسر وبنية Mac المعمارية التي تنوي دعمها، ثم كرر الاختبار في بيئة تم إنشاؤها حديثًا.

إذا نجح التثبيت ولكن فشل الاستيراد، فتحقق من صحة اسم الاستيراد ومن أن التبعيات المطلوبة لوقت التشغيل معلنة من قِبل المشروع. إذا تم تثبيت حزمة wheel ولكنها حذفت وحدة نمطية أو ملف بيانات، فافحص محتويات ملف wheel وصحح تكوين تحزيم المشروع قبل إعادة البناء. تساعد البيئة النظيفة في كشف التبعيات غير المعلنة والملفات المحزومة المفقودة والتي قد تكون محجوبة بواسطة حزم أو ملفات مصدر موجودة في بيئة المطور.

يؤكد التثبيت الناجح وفحص التبعيات والاستيراد المستهدف جوانب مفيدة من سلوك حزمة wheel على هذا الجهاز بنظام Mac وإصدار Python هذا. وهي لا تتحقق من الأنظمة الأساسية الأخرى أو إصدارات Python الأخرى؛ اختبر تلك المنصات بشكل منفصل باستخدام مفسرات مطابقة وبنيات wheel متوافقة.

المصادر