لسنوات طويلة، اعتمد مطورو بايثون على نظام بيئي مجزأ لأدوات التعبئة، حيث كانوا يوازنون بين setup.py وsetup.cfg وخلفيات بناء مختلفة. أدى هذا الافتقار إلى التوحيد القياسي إلى الارتباك وتراكم الديون التقنية. ومع ذلك، مع اعتماد PEP 517 وPEP 518، استقر المشهد. اليوم، تُعرّف تعبئة بايثون بواسطة ملف pyproject.toml، وهو تنسيق توحيد قياسي يبسط كل من البناء وتوزيع الحزم.
يستكشف هذا الدليل أفضل الممارسات الحديثة لإنشاء واختبار وتوزيع حزم بايثون، ويستهدف المطورين الذين يرغبون في ضمان أن تكون مكتباتهم قوية وقابلة للتكرار وسهلة التثبيت من قبل المجتمع.
التكوين الأساسي: pyproject.toml
يعمل سير عمل تعبئة بايثون الحديث بالكامل حول ملف pyproject.toml. يحل هذا المصدر الوحيد للحقيقة محل الحاجة إلى ملفات تكوين متعددة. فهو يحدد نظام البناء وبيانات تعريف المشروع، مما يضمن أن أي أداة تتبع PEP 517 يمكنها بناء مشروعك بشكل متسق.
يبدو ملف pyproject.toml النموذجي لمشروع حديث كالتالي:
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "my-awesome-library"
version = "0.1.0"
description = "A sample library demonstrating modern Python packaging"
readme = "README.md"
license = {text = "MIT"}
authors = [
{name = "Jane Doe", email = "jane@example.com"}
]
requires-python = ">=3.8"
dependencies = [
"requests>=2.28.0",
"click>=8.0"
]
[project.optional-dependencies]
dev = [
"pytest>=7.0",
"black"
]
[project.urls]
Homepage = "https://github.com/janedoe/my-awesome-library"
Documentation = "https://my-awesome-library.readthedocs.io"لاحظ استخدام البيانات التعريفية الثابتة في قسم [project]. على عكس البيانات التعريفية الديناميكية في setup.py، تسمح البيانات التعريفية الثابتة بتحليل أسرع من قبل أدوات مثل PyPI وتضمن إمكانية التكرار عبر بيئات مختلفة. يتم تحديد الإصدارات الخاصة بالتبعيات بدقة لتجنب التغييرات التي قد تكسر المكتبات الأصلية.
بناء وتوزيع العناصر
بمجرد إعداد التكوين الخاص بك، تكون الخطوة التالية هي إنشاء عناصر التوزيع. تحولت المعايير الصناعية من توزيعات المصدر (.tar.gz) والعجلات القديمة (.egg) إلى العجلات الحديثة (.whl). تتضمن العجلات الحديثة ثنائيات جاهزة مسبقاً وبيانات تعريفية، مما يسرع بشكل كبير أوقات التثبيت للمستخدمين النهائيين.
لبناء مشروعك، استخدم حزمة build، وهي الأداة الموصى بها لإنشاء توزيعات المصدر والعجلات. أولاً، قم بتثبيت أداة البناء:
python -m pip install buildثم، قم بتشغيل أمر البناء:
python -m buildينشئ هذا الأمر مجلداً dist/ يحتوي على كل من توزيع المصدر (sdist) والعجلة. يتضمن توزيع المصدر جميع ملفات المصدر ويسمح للمستخدمين ببناء الحزمة من المصدر على أنظمتهم، بينما توفر العجلة تنسيقاً سريعاً وقابلاً للتثبيت لمعظم المستخدمين.
رفع إلى PyPI
مع جاهزية عناصر التوزيع الخاصة بك، تكون الخطوة النهائية هي التوزيع. تبسط ميزة النشر الموثوق التي تم تقديمها في twine الإصدار 4.0+ عملية الرفع من خلال إزالة الحاجة إلى رموز واجهة برمجة التطبيقات طويلة الأمد. بدلاً من ذلك، يستخدم OIDC (ربط الهوية المفتوح) للمصادقة، وهو أكثر أماناً وملاءمة لخطوط أنابيب CI/CD.
قم بتثبيت twine:
python -m pip install twineارفع توزيعاتك:
python -m twine upload dist/*اختبر دائماً رفعك على TestPyPI أولاً للقبض على الأخطاء قبل الوصول إلى المستودع الرئيسي. يمكنك القيام بذلك عن طريق تحديد العلم --repository testpypi وتكوين ملف .pypirc الخاص بك أو استخدام متغيرات البيئة للبيانات الاعتماد.
أفضل الممارسات للصيانة طويلة الأمد
التعبئة ليست مهمة لمرة واحدة. للحفاظ على مشروع صحي، فكر في الممارسات التالية:
- إدارة الإصدارات: استخدم الإصدار الدلالي (SemVer) للإشارة إلى التغييرات التي تكسر التوافق.
- تثبيت التبعيات: ثبت التبعيات في ملف
pyproject.tomlالخاص بك لضمان بناء متسق، ولكن استخدم نطاقات مرنة (على سبيل المثال،>=2.0) للسماح بتصحيحات الأمان. - تكامل CI/CD: أتمتة الاختبار والنشر باستخدام GitHub Actions أو GitLab CI لضمان اختبار كل إصدار عبر إصدارات بايثون متعددة.
- التوثيق: حافظ على تحديث ملف
README.mdوالتوثيق الخاص بك، حيث أن هذه هي الأشياء الأولى التي يراها المستخدمون على PyPI.
الخاتمة
نضجت تعبئة بايثون لتصبح عملية قوية وموحدة. من خلال الاستفادة من pyproject.toml وأدوات البناء الحديثة وطرق التوزيع الآمنة، يمكن للمطورين التركيز على كتابة الكود بدلاً من استكشاف أخطاء التثبيت وإصلاحها. يضمن تبني هذه الممارسات الحديثة أن تكون مساهماتك في النظام البيئي لبايثون متاحة وموثوقة وقابلة للصيانة لسنوات قادمة.