بسته‌بندی مدرن پایتون: مهاجرت به pyproject.toml با Hatch و Build

اکوسیستم بسته‌بندی پایتون در سال‌های اخیر دگرگونی‌های عظیمی را تجربه کرده است. برای بیش از یک دهه، setup.py به عنوان استاندارد غیررسمی برای تعریف متادیتا و الزامات ساخت پروژه عمل می‌کرد. با این حال، حرکت به سمت پیکربندی اعلانی (declarative) از طریق pyproject.toml، بنیادین‌ترین تغییر را در نحوه تفکر ما درباره توزیع نرم‌افزار ایجاد کرده است. این گذار که توسط مرجع بسته‌بندی پایتون (PyPA) رهبری می‌شود، هدفش حذف ابهام، اعمال ثبات و امکان‌پذیر کردن تعامل بهتر بین ابزارهاست.

برای توسعه‌دهندگان متوسط تا پیشرفته، پایبندی به گردش‌کارهای قدیمی دیگر پایدار نیست. ابزارهایی مانند Hatch و Build در خط مقدم این حرکت قرار دارند و تجربه‌ای روان‌تر را ارائه می‌دهند که جایگزین اسکریپت‌های پیچیده خط فرمان و بک‌اند‌های ساخت سفارشی می‌شود. در این راهنما، انگیزه‌های پشت این مهاجرت، ساختار استاندارد جدید و یک نقشه راه عملی برای پیش بردن پروژه خود را بررسی خواهیم کرد.

چرا باید از setup.py فاصله گرفت؟

استدلال اصلی علیه setup.py ماهیت اعلانی (imperative) آن است. این فایل باید برای خواندن متادیتا اجرا شود که ریسک‌هایی مانند عوارض جانبی هنگام وارد کردن (import) و مشکلات حل وابستگی را به همراه دارد. در مقابل، pyproject.toml اعلانی است. این فایل از فرمت 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 آزمایش کنید تا اطمینان حاصل شود که فایل‌های wheel تولید شده با انتظارات قدیمی شما مطابقت دارند.

تست کنید که تست‌های شما در فایل‌های خروجی ساخته شده به درستی اجرا می‌شوند. بررسی کنید که تمام وابستگی‌های اختیاری به درستی نصب می‌شوند. پس از اعتبارسنجی، می‌توانید با اطمینان setup.py و setup.cfg (در صورت استفاده) را حذف کنید تا مخزن خود را پاکسازی کنید.

نتیجه‌گیری

مهاجرت از setup.py به pyproject.toml بیش از یک تغییر در نحو (syntax) است؛ این یک سرمایه‌گذاری در سلامت و قابلیت نگهداری بلندمدت پروژه‌های پایتون شماست. با بهره‌گیری از ابزارهایی مانند Hatch و بک‌اند ساخت استاندارد، شما گردش‌کاری را اتخاذ می‌کنید که مستحکم، استاندارد و آینده‌دار است.

برای توسعه‌دهندگانی که آماده مدرن‌سازی مجموعه ابزارهای خود هستند، منحنی یادگیری بسیار کم است، اما مزایا از نظر ثبات ابزارها و سازگاری با اکوسیستم قابل توجه است. با به‌روزرسانی پیکربندی پروژه بعدی خود از امروز شروع کنید و آینده بسته‌بندی پایتون را در آغوش بگیرید.