تعبئة بايثون الحديثة: الانتقال إلى pyproject.toml باستخدام Hatch و Build

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

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

لماذا الابتعاد عن setup.py؟

الحجة الرئيسية ضد setup.py هي طبيعته الأمرية (Imperative). فهي تتطلب تنفيذ الملف لقراءة بيانات التعريف، مما يقدم مخاطر مثل الآثار الجانبية أثناء الاستيراد ومشاكل في حل التبعيات. على النقيض من ذلك، فإن pyproject.toml هو ملف وصفي (Declarative). فهو يستخدم تنسيق TOML لفصل متطلبات البناء عن تبعيات وقت التشغيل بوضوح.

هذا الفصل حاسم لخلفيات البناء الحديثة. عند استخدام build لإنشاء توزيع المصدر (sdist) أو عجلة (wheel)، يكون البيئة معزولة. إذا كان ملف setup.py الخاص بك يعتمد على تثبيت تبعيات محددة للعمل، فقد يعطل عملية البناء في البيئات المعزولة. يضمن pyproject.toml أن نظام البناء نفسه مُعرّف صراحةً، مما يمنع "جحيم التبعيات" أثناء مرحلة التعبئة.

إعداد المشروع باستخدام Hatch

يُعد Hatch أداة حديثة جداً لتعبئة وإدارة مشاريع بايثون تتماشى تماماً مع المعايير الجديدة. فهي تبسط دورة الحياة بأكملها، من إدارة التبعيات إلى رفع إصدار البرنامج ونشره.

للبدء في الانتقال، تأكد من تثبيت Hatch في بيئتك:

pip install hatch

بمجرد التثبيت، يمكنك تهيئة مشروع. سواء كنت تبدأ من جديد أو تقوم بتحويل هيكل موجود، يمكن لـ Hatch إنشاء ملف pyproject.toml التأسيسي لك. يحتوي هذا الملف على قلب تكوينك الجديد، بما في ذلك بيانات التعريف ومتطلبات البناء وإعدادات الإضافات.

إليك مثال قوي لما يبدو عليه ملف pyproject.toml بعد الانتقال عند تكوينه مع Hatch:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "modern-pkg"
version = "0.1.0"
description = "A modern Python package using pyproject.toml"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
  {name = "Jane Doe", email = "jane@example.com"}
]
dependencies = [
  "requests>=2.28.0",
  "pydantic>=2.0.0"
]

[project.optional-dependencies]
dev = [
  "pytest>=7.0",
  "hatch"
]

[tool.hatch.build.targets.wheel]
packages = ["src/modern_pkg"]

[tool.hatch.build.targets.sdist]
include = ["src/modern_pkg", "tests"]

لاحظ الوضوح: جميع التبعيات مدرجة تحت قسم [project]، بينما توجد التكوينات الخاصة بالبناء تحت [tool.hatch]. لا يوجد أي كود أمرية يجب تحليله؛ إنه بيانات خالصة.

البناء باستخدام سلسلة الأدوات الحديثة

مع وجود ملف التكوين، أصبحت أوامر python setup.py sdist bdist_wheel القديمة عفا عليها الزمن. بدلاً من ذلك، نستخدم وحدة build التي تعمل كمحرك تنفيذ خلفي. ومع ذلك، فإن Hatch يبسط هذا أكثر.

لبناء حزمة التوزيع الخاصة بك، قم بتشغيل الأمر التالي في الجذر الرئيسي للمشروع:

hatch build

يؤدي هذا الأمر إلى تشغيل خلفية البناء (Hatchling في هذه الحالة) لإنشاء ملفات في مجلد dist/. هذه الملفات جاهزة الآن لرفعها إلى PyPI أو اختبارها محلياً.

إذا كنت تفضل الالتزام بوحدة build القياسية دون الميزات الإضافية لـ Hatch، فيمكنك استخدامها مباشرة:

python -m build

سيقوم هذا الأمر بقراءة ملف pyproject.toml الخاص بك، وتثبيت تبعيات البناء اللازمة من قسم build-system، وتوليد التوزيعات. النتيجة مطابقة لـ Hatch، مما يثبت توافقية البيئة.

استراتيجية الانتقال العملية

يتم الانتقال من مشروع قائم بشكل أفضل بشكل تدريجي. أولاً، قم بإنشاء ملف pyproject.toml الجديد عن طريق استخراج بياناتك التعريفية من setup.py. لا تحذف الملف القديم على الفور. بدلاً من ذلك، اختبر عملية البناء باستخدام hatch build أو python -m build للتأكد من أن العجلات المولدة تطابق توقعاتك القديمة.

تحقق من نجاح اختباراتك في الملفات المولدة. تأكد من تثبيت جميع التبعيات الاختيارية بشكل صحيح. بعد التحقق، يمكنك إزالة setup.py و setup.cfg (إذا تم استخدامها) بأمان لتنظيف مستودعك.

الخاتمة

الانتقال من setup.py إلى pyproject.toml هو أكثر من مجرد تغيير في النطق؛ إنه استثمار في الصحة والصيانة طويلة المدى لمشاريع بايثون الخاصة بك. من خلال الاستفادة من أدوات مثل Hatch وخلفية البناء القياسية، فإنك تتبنى سير عمل قوي، ومعياري، ومستعد للمستقبل.

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