برای سالها، توسعهدهندگان پایتون به اکوسیستمی پراکنده از ابزارهای بستهبندی تکیه داشتند که اغلب بین 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) و چرخدنده است. sdist شامل تمام فایلهای منبع است و به کاربران اجازه میدهد بسته را از منبع در سیستمهای خود بسازند، در حالی که چرخدنده یک قالب سریع و قابل نصب را برای اکثر کاربران فراهم میکند.
آپلود به PyPI
با آماده بودن آثار شما، مرحله نهایی توزیع است. ویژگی انتشار مورد اعتماد که در نسخه 4.0+ twine معرفی شد، فرآیند آپلود را با حذف نیاز به توکنهای API با عمر طولانی ساده میکند. در عوض، از OIDC (اتصال OpenID) برای احراز هویت استفاده میکند که امنتر و راحتتر برای خطوط لوله 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، ابزارهای ساخت مدرن و روشهای توزیع امن، توسعهدهندگان میتوانند بر روی نوشتن کد تمرکز کنند تا عیبیابی مسائل نصب. پذیرش این شیوههای مدرن اطمینان حاصل میکند که مشارکتهای شما در اکوسیستم پایتون برای سالهای آینده قابل دسترسی، قابل اعتماد و قابل نگهداری باشد.