إتقان تغليف وتوزيع بايثون: من السكربتات المحلية إلى PyPI

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

في هذا الدليل، سنكشف الغموض عن مشهد تغليف بايثون الحديث. سننتقل بعيداً عن النموذج القديم والمفرط في التعقيد setup.py ونتبنى المعايير الأحدث والأكثر متانة التي توصي بها هيئة تغليف بايثون (PyPA).

التحول من Setuptools إلى PEP 517/518

تاريخياً، اعتمد تغليف بايثون بشكل كبير على setuptools وملف setup.py الطويل. وعلى الرغم من كونه فعالاً، إلا أن هذا النهج غالباً ما أدى إلى عمليات بناء هشة وتضخم في التكوين. انتقلت المجتمع منذ ذلك الحين نحو واجهات خلفية قياسية للبناء محددة في PEP 517 وPEP 518.

يقدم المعيار الجديد ملفين رئيسيين:

1. pyproject.toml: يعلن عن متطلبات البناء وبيانات تعريف المشروع.
2. واجهة خلفية للبناء (build backend): أداة مثل setuptools أو poetry أو flit التي تقوم بعملية البناء الفعلية.

تحديد بنية مشروعك

تُعد بنية المشروع النظيفة أساس الحافظة القابلة للصيانة. وعلى الرغم من وجود العديد من الاختلافات، إلا أن التخطيط الحديث الشائع يبدو كالتالي:

my_package/
├── pyproject.toml
├── README.md
├── LICENSE
└── src/
    └── my_package/
        ├── __init__.py
        ├── core.py
        └── utils.py

يُوصى بشدة باستخدام تخطيط src/. فهو يمنع الاستيراد العرضي للملفات المحلية أثناء الاختبار ويضمن أن الحزمة المثبتة هي دائماً ما يتم اختباره، وليس شفرة المصدر الموجودة في دليلك الحالي.

تكوين pyproject.toml

يُعد ملف pyproject.toml المصدر الوحيد الموثوق لبيانات تعريف مشروعك. فيما يلي مثال على التكوين باستخدام setuptools كواجهة خلفية للبناء، وهو المعيار الأكثر انتشاراً.

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-awesome-package"
version = "0.1.0"
description = "A sample Python package for demonstration."
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.8"
authors = [
  {name = "Jane Developer", email = "jane@example.com"},
]
dependencies = [
  "requests>=2.28.0",
  "click>=8.0.0",
]

[project.optional-dependencies]
dev = [
  "pytest>=7.0.0",
  "black>=22.0.0",
]

الميزات الرئيسية التي يجب ملاحظتها في هذا التكوين:

• بيانات تعريف ديناميكية: يمكنك أرقام الإصدارات في ملفات منفصلة لتجنب التحديثات اليدوية.
• التبعيات الاختيارية: يمكن للمستخدمين تثبيت أدوات التطوير عبر الأمر pip install my-package[dev].
• قيد إصدار بايثون: يضمن التعريف الصريح لـ requires-python إجراء فحوصات التوافق.

pip install build twine

python -m build

Creating sdist archive: dist/my_awesome_package-0.1.0.tar.gz
Creating  wheel archive: dist/my_awesome_package-0.1.0-py3-none-any.whl

twine upload --repository testpypi dist/*

pip install --index-url https://test.pypi.org/simple/ --no-deps my-awesome-package