مقایسه‌ای عمیق بین setup.py و pyproject.toml برای مدیریت بسته‌های پایتون، پوشش‌دهنده بهترین روش‌ها، استراتژی‌های مهاجرت و ابزارهای مدرن.
ساختار بسته پایتون: Setup.py در مقابل Pyproject.toml - یک راهنمای جامع
سال‌ها، فایل setup.py سنگ بنای مدیریت بسته‌های پایتون بود. با این حال، چشم‌انداز تکامل یافته است و pyproject.toml به عنوان یک جایگزین مدرن ظهور کرده است. این راهنمای جامع تفاوت‌های بین این دو رویکرد را بررسی می‌کند و به شما کمک می‌کند تا درک کنید کدام یک برای پروژه شما مناسب است و چگونه به طور موثر بسته‌های پایتون خود را مدیریت کنید.
درک مبانی
بسته پایتون چیست؟
بسته پایتون راهی برای سازماندهی و توزیع کد پایتون شما است. این امکان را به شما می‌دهد تا ماژول‌های مرتبط را در یک سلسله مراتب دایرکتوری گروه‌بندی کنید، و کد شما را ماژولارتر، قابل استفاده مجدد و قابل نگهداری می‌کند. بسته‌ها برای به اشتراک گذاشتن کد خود با دیگران و برای مدیریت وابستگی‌ها در پروژه‌های خود ضروری هستند.
نقش فراداده بسته
فراداده بسته اطلاعات ضروری درباره بسته شما ارائه می‌دهد، مانند نام، نسخه، نویسنده، وابستگی‌ها و نقاط ورودی آن. این فراداده توسط مدیران بسته مانند pip برای نصب، ارتقاء و مدیریت بسته‌های شما استفاده می‌شود. از لحاظ تاریخی، setup.py روش اصلی برای تعریف این فراداده بود.
Setup.py: رویکرد سنتی
Setup.py چیست؟
setup.py یک اسکریپت پایتون است که از کتابخانه setuptools برای تعریف ساختار و فراداده بسته شما استفاده می‌کند. این یک فایل با اجرای پویا است، به این معنی که کد پایتون را برای پیکربندی بسته اجرا می‌کند.
اجزای اصلی Setup.py
یک فایل معمولی setup.py شامل اجزای زیر است:
- نام بسته: نام بسته شما (به عنوان مثال،
my_package). - نسخه: شماره نسخه بسته شما (به عنوان مثال،
1.0.0). - اطلاعات نویسنده و نگهدارنده: جزئیات مربوط به نویسنده و نگهدارنده بسته.
- وابستگی‌ها: لیستی از سایر بسته‌هایی که بسته شما به آنها وابسته است (به عنوان مثال،
requests >= 2.20.0). - نقاط ورودی: تعاریف برای اسکریپت‌های خط فرمان یا سایر نقاط ورودی به بسته شما.
- داده‌های بسته: فایل‌های غیر کد (به عنوان مثال، فایل‌های پیکربندی، فایل‌های داده) که باید در بسته گنجانده شوند.
مثال Setup.py
```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='A simple Python package', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```مزایای Setup.py
- آشنایی: این رویکرد سنتی و شناخته شده است، بنابراین بسیاری از توسعه دهندگان از قبل با آن آشنا هستند.
- انعطاف‌پذیری: از آنجا که یک اسکریپت پایتون است، درجه بالایی از انعطاف‌پذیری را ارائه می‌دهد. شما می‌توانید منطق پیچیده‌ای را انجام دهید و فرآیند ساخت را مطابق با نیاز خود سفارشی کنید.
- قابلیت توسعه: Setuptools مجموعه غنی از ویژگی‌ها را ارائه می‌دهد و می‌توان آن را با دستورات و افزونه‌های سفارشی گسترش داد.
معایب Setup.py
- اجرای پویا: ماهیت پویای
setup.pyمی‌تواند یک خطر امنیتی باشد، زیرا کد دلخواه را در طول فرآیند ساخت اجرا می‌کند. - وابستگی‌های ضمنی:
setup.pyاغلب به وابستگی‌های ضمنی، مانند خود setuptools، متکی است، که می‌تواند منجر به ناسازگاری‌ها و خطاها شود. - پیچیدگی: برای پروژه‌های پیچیده،
setup.pyمی‌تواند بزرگ و نگهداری آن دشوار شود. - پیکربندی اعلانی محدود: بیشتر فراداده بسته به جای اعلامی، به صورت امری تعریف می‌شود، و استدلال درباره آن را دشوارتر می‌کند.
Pyproject.toml: جایگزین مدرن
Pyproject.toml چیست؟
pyproject.toml یک فایل پیکربندی است که از فرمت TOML (زبان واضح و حداقلی تام) برای تعریف سیستم ساخت و فراداده بسته شما استفاده می‌کند. این یک رویکرد اعلانی است، به این معنی که شما مشخص می‌کنید که می‌خواهید به چه چیزی برسید، نه اینکه چگونه به آن برسید.
بخش‌های اصلی Pyproject.toml
یک فایل معمولیpyproject.toml شامل بخش‌های زیر است:
[build-system]: سیستم ساخت مورد استفاده را تعریف می‌کند (به عنوان مثال،setuptools،poetry،flit).[project]: حاوی فراداده درباره پروژه است، مانند نام، نسخه، توضیحات، نویسندگان و وابستگی‌های آن.[tool.poetry]یا[tool.flit]: بخش‌هایی برای پیکربندی‌های خاص ابزار (به عنوان مثال، Poetry، Flit).
مثال Pyproject.toml (با Setuptools)
```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```مثال Pyproject.toml (با Poetry)
```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = ["John Doeمزایای Pyproject.toml
- پیکربندی اعلانی:
pyproject.tomlیک روش اعلانی برای تعریف فراداده بسته شما ارائه می‌دهد، و درک و نگهداری آن را آسان‌تر می‌کند. - سیستم ساخت استاندارد: سیستم ساخت مورد استفاده را مشخص می‌کند، و ساخت‌های سازگار را در محیط‌های مختلف تضمین می‌کند.
- مدیریت وابستگی بهبود یافته: ابزارهایی مانند Poetry و Pipenv به طور یکپارچه با
pyproject.tomlادغام می‌شوند تا ویژگی‌های مدیریت وابستگی قوی را ارائه دهند. - کاهش خطرات امنیتی: از آنجا که یک فایل پیکربندی ایستا است، خطرات امنیتی مرتبط با اجرای پویای کد در طول فرآیند ساخت را از بین می‌برد.
- ادغام با ابزارهای مدرن:
pyproject.tomlاستاندارد برای ابزارهای بسته‌بندی پایتون مدرن مانند Poetry، Pipenv و Flit است.
معایب Pyproject.toml
- منحنی یادگیری: توسعه دهندگان ممکن است نیاز به یادگیری یک نحو جدید (TOML) و یک روش جدید تفکر در مورد مدیریت بسته داشته باشند.
- انعطاف‌پذیری محدود: ممکن است برای فرآیندهای ساخت بسیار سفارشی که نیاز به منطق پیچیده دارند، مناسب نباشد.
- وابستگی به ابزار: شما باید یک سیستم ساخت خاص (به عنوان مثال، Setuptools، Poetry، Flit) را انتخاب کنید و نحوه استفاده از آن را یاد بگیرید.
مقایسه Setup.py و Pyproject.toml
در اینجا جدولی وجود دارد که تفاوت‌های اصلی بین setup.py و pyproject.toml را خلاصه می‌کند:
| ویژگی | Setup.py | Pyproject.toml |
|---|---|---|
| سبک پیکربندی | امری (کد پایتون) | اعلانی (TOML) |
| سیستم ساخت | ضمنی (Setuptools) | صریح (مشخص شده در [build-system]) |
| امنیت | به طور بالقوه کمتر امن (اجرای پویا) | امن‌تر (پیکربندی ایستا) |
| مدیریت وابستگی | پایه (install_requires) |
پیشرفته (ادغام با Poetry، Pipenv) |
| ابزارها | سنتی (Setuptools) | مدرن (Poetry، Pipenv، Flit) |
| انعطاف‌پذیری | بالا | متوسط |
| پیچیدگی | می‌تواند برای پروژه‌های پیچیده بالا باشد | به طور کلی پایین‌تر |
استراتژی‌های مهاجرت: از Setup.py به Pyproject.toml
مهاجرت از setup.py به pyproject.toml می‌تواند دلهره‌آور به نظر برسد، اما یک سرمایه‌گذاری ارزشمند برای قابلیت نگهداری و سازگاری طولانی‌مدت است. در اینجا چند استراتژی وجود دارد که می‌توانید از آنها استفاده کنید:
1. با یک Pyproject.toml حداقلی شروع کنید
یک فایل pyproject.toml اساسی ایجاد کنید که سیستم ساخت را مشخص می‌کند و سپس به تدریج فراداده را از setup.py به pyproject.toml منتقل کنید.
2. از Setuptools با Pyproject.toml استفاده کنید
به استفاده از Setuptools به عنوان سیستم ساخت خود ادامه دهید، اما فراداده پروژه را در pyproject.toml تعریف کنید. این به شما امکان می‌دهد از مزایای pyproject.toml بهره ببرید در حالی که هنوز از یک ابزار آشنا استفاده می‌کنید.
3. به یک ابزار مدرن مانند Poetry مهاجرت کنید
به مهاجرت به یک ابزار مدرن مانند Poetry یا Pipenv فکر کنید. این ابزارها ویژگی‌های جامع مدیریت وابستگی را ارائه می‌دهند و به طور یکپارچه با pyproject.toml ادغام می‌شوند.
مثال: مهاجرت به Poetry
- نصب Poetry:
pip install poetry - مقداردهی اولیه Poetry در پروژه خود:
poetry init(این شما را در ایجاد یک فایلpyproject.tomlراهنمایی می‌کند) - اضافه کردن وابستگی‌های خود:
poetry add requests(یا هر وابستگی دیگر) - ساخت بسته خود:
poetry build
4. از ابزارهایی برای مهاجرت خودکار استفاده کنید
برخی از ابزارها می‌توانند به خودکارسازی فرآیند مهاجرت کمک کنند. به عنوان مثال، می‌توانید از ابزارها برای تبدیل فایل setup.py خود به یک فایل pyproject.toml استفاده کنید.
بهترین روش‌ها برای مدیریت بسته‌های پایتون
1. از یک محیط مجازی استفاده کنید
همیشه از یک محیط مجازی برای جدا کردن وابستگی‌های پروژه خود از نصب پایتون در سطح سیستم استفاده کنید. این از تضادها جلوگیری می‌کند و اطمینان می‌دهد که پروژه شما وابستگی‌های صحیح را دارد.
مثال با استفاده از venv:
مثال با استفاده از conda:
2. وابستگی‌ها را به طور دقیق مشخص کنید
از محدودیت‌های نسخه برای مشخص کردن نسخه‌های سازگار وابستگی‌های خود استفاده کنید. این از رفتار غیرمنتظره ناشی از به روز رسانی‌های کتابخانه ناسازگار جلوگیری می‌کند. از ابزارهایی مانند pip-tools برای مدیریت وابستگی‌های خود استفاده کنید.
مثال مشخصات وابستگی:
``` requests >= 2.20.0, < 3.0.0 ```3. از یک سیستم ساخت سازگار استفاده کنید
یک سیستم ساخت (به عنوان مثال، Setuptools، Poetry، Flit) را انتخاب کنید و به آن پایبند باشید. این ساخت‌های سازگار را در محیط‌های مختلف تضمین می‌کند و فرآیند بسته‌بندی را ساده می‌کند.
4. بسته خود را مستند کنید
مستندات واضح و مختصر برای بسته خود بنویسید. این به کاربران کمک می‌کند تا نحوه استفاده از بسته شما را درک کنند و مشارکت دیگران در پروژه شما را آسان‌تر می‌کند. از ابزارهایی مانند Sphinx برای تولید مستندات از کد خود استفاده کنید.
5. از ادغام مداوم (CI) استفاده کنید
یک سیستم CI (به عنوان مثال، GitHub Actions، Travis CI، GitLab CI) راه‌اندازی کنید تا هر زمان که تغییری در کد شما ایجاد می‌شود، بسته شما را به طور خودکار بسازد، آزمایش کند و مستقر کند. این کمک می‌کند تا اطمینان حاصل شود که بسته شما همیشه در یک حالت کاری است.
مثال پیکربندی GitHub Actions:
```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```6. بسته خود را در PyPI منتشر کنید
بسته خود را با انتشار آن در فهرست بسته‌های پایتون (PyPI) با جهان به اشتراک بگذارید. این کار نصب و استفاده از بسته شما را برای دیگران آسان می‌کند.
مراحل انتشار در PyPI:
- یک حساب کاربری در PyPI و TestPyPI ثبت کنید.
twineرا نصب کنید:pip install twine.- بسته خود را بسازید:
poetry buildیاpython setup.py sdist bdist_wheel. - بسته خود را در TestPyPI بارگذاری کنید:
twine upload --repository testpypi dist/*. - بسته خود را در PyPI بارگذاری کنید:
twine upload dist/*.
مثال‌های دنیای واقعی
بیایید نگاهی بیندازیم به اینکه چگونه برخی از پروژه‌های محبوب پایتون از pyproject.toml استفاده می‌کنند:
- Poetry: از
pyproject.tomlبرای مدیریت بسته خود استفاده می‌کند. - Black: فرمت‌کننده کد سازش‌ناپذیر نیز از
pyproject.tomlاستفاده می‌کند. - FastAPI: یک چارچوب وب مدرن، سریع (با عملکرد بالا) برای ساخت APIها با پایتون نیز از آن استفاده می‌کند.
نتیجه‌گیری
pyproject.toml نشان دهنده استاندارد مدرن برای مدیریت بسته‌های پایتون است، که یک روش اعلانی و ایمن برای تعریف فراداده بسته شما و مدیریت وابستگی‌ها ارائه می‌دهد. در حالی که setup.py به خوبی به ما خدمت کرده است، مهاجرت به pyproject.toml یک سرمایه‌گذاری ارزشمند برای قابلیت نگهداری، سازگاری و ادغام طولانی‌مدت با ابزارهای مدرن است. با اتخاذ بهترین روش‌ها و استفاده از ابزارهای مناسب، می‌توانید گردش کار بسته‌بندی پایتون خود را ساده کنید و بسته‌های با کیفیت و قابل استفاده مجدد ایجاد کنید.