مدیریت بسته پایتون (python package management) با poetry

از ابزار Poetry برای مدیریت وابستگی (dependency) و بسته بندی (packaging) در پایتون استقاده میشه؛ کافیه بسته هایی رو که پروژه مون بهش وابسته ست رو تعیین کنیم تا برامون مدیریتشون (نصب/بروز رسانی) کنه و در نهایت با استفاده از محیط مجازی (virtual environment) پروژه (اسکریپت) مورد نظر رو اجرا کنه.

پروژه نمونه ای که قراره پیاده کنیم رو میتونین از مخزن اصلی گیت هاب ایرانی پای بردارید.

الزامات سیستم

در حال حاضر ابزار Poetry به پایتون 2.7 یا 3.5 به بالا نیاز داره و برای پلتفرم های پر استقاده (Windows، Linux و OSX) قابل استفاده ست.

نصب Poetry

  • نصب روی osx و linux (یا با استفاده از bash تو windows)
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
  • نصب روی windows با استفاده از powershell
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -

اسکریپت get-poetry.py که در دستورات بالا استفاده شده، تو نسخه 1.2 با install-poetry.py جایگزین میشه. از Poetry 1.1.7 به بعد، می تونید از این اسکریپت همینطور که توضیح داده شد استفاده کنید.

در نهایت با استفاده از دستور زیر میتونیم بررسی کنیم که Poetry درست نصب شده یا نه (ممکنه نصب شده باشه ولی مسیرش (path) به متغییر های محیطی (environment variables) اضافه نشده باشه).

poetry --version

به جز موارد گفته شده، امکان نصب Poetry از طریق سایر مدیر بسته ها مثل pip هم امکان پذیره (ولی پیشنهاد نمیشه).

برای مطالعه بیشتر در مورد شیوه های مختلف نصب و مراحلشون میتونید از مرجع اصلی استفاده کنید.

استفاده اولیه

برای معرفی کاربردهای اولیه، کتابخانه pendulum رو نصب می کنیم.

  • راه اندازی پروژه (ساخت پروژه جدید)

اول پروژه جدید با اسم poetry_demo میسازیم:

poetry new poetry_demo

با این کار پوشه poetry_demo با محتوای زیر ساخته میشه:

poetry_demo
├── pyproject.toml
├── README.rst
├── poetry_demo
│ └── __init__.py
└── tests
    ├── __init__.py
    └── test_poetry_demo.py

چون فعلا قصد تست نوشتن برای پروژه مون نداریم، میتونیم مسیر tests/ و محتویاتشو حذف کنیم. به فایل README.rst هم نیازی نداریم و حذفش میکنیم که در این صورت ساختار پروژه به صورت زیر میشه:

poetry_demo
├── pyproject.toml
└── poetry_demo
    └── __init__.py

فایلی که بیشتر از بقیه برامون اهمیت داره، pyproject.toml هستش. ابزار Poetry با استفاده از این فایل پروژه و بسته هاش رو مدیریت می کنه. محتویات این فایل به صورت زیر هستش:

[tool.poetry]
name = &quotpoetry_demo&quot
version = &quot0.1.0&quot
description = &quot&quot
authors = [&quotiranipy <info@iranipy.ir>&quot]

[tool.poetry.dependencies]
python = &quot*&quot

[tool.poetry.dev-dependencies]
pytest = &quot^3.4&quot

[build-system]
requires = [&quotpoetry-core>=1.0.0&quot]
build-backend = &quotpoetry.core.masonry.api&quot
  • راه اندازی پروژه (در صورتی که پروژه از قبل موجود باشه)

به جای ساخت پروژه جدید، از Poetry برای ایجاد فایل pyproject.toml مناسب پروژه مون به صورت تعاملی، میشه استفاده کرد. دستورش به این صورته: (دستور زیر باید تو دایرکتوری اصلی (root) پروژه اجرا بشه)

poetry init

تعیین وابستگی ها

اگر بخوایم وابستگی هایی رو به پروژه اضافه کنیم، دو راه وجود داره. اولین راه اینه که می تونیم تو قسمت tool.poetry.dependencies تو فایل pyproject.toml بنویسمشون:

[tool.poetry.dependencies]
python = &quot*&quot
pendulum = &quot^1.4&quot

فقط کافیه اسم و نسخه مورد نظر پکیج نوشته بشه. Poetry از این اطلاعات برای جستجوی مجموعه مناسب فایل ها در مخازن (repositories) که تو قسمت tool.poetry.repositories تعیین شده (به طور پیش فرض PyPI)، استفاده می کنه.

نسخه ای که به pendulum نسبت دادیم شامل هر نسخه بزرگتر یا مساوی 1.4.0 میشه. برای مطالعه بیشتر در مورد الگویی که تو این مثال برای تعیین نسخه استفاده شده، میتونید از مرجع اصلی استفاده کنید. به این الگو version constraints گفته میشه.

برای اعمال تغییرات و نصب وابستگی ها کافیه دستور زیر رو اجرا کنیم:

poetry install

راه دوم استفاده از دستور add به جای تغییر دستی فایل pyproject.toml هستش:

poetry add pendulum

با این دستور، Poetry به طور خودکار نسخه مناسب رو پیدا می کنه و بسته و وابستگی های فرعیش رو تو محیط مجازی ساخته شده برای این پروژه نصب می کنه و به فایل pyproject.toml هم بسته رو اضافه میکنه (همون کارایی که دستی انجام دادیم رو خودش انجام میده).

بعد از اجرای دستور poetry install یا poetry add برای اولین بار، فایلی به اسم poetry.lock ساخته میشه. تو این فایل تمام پکیج های مورد نیاز پروژه به همراه نسخه دقیقی که دانلود شده، نوشته میشه. کاربرد این فایل اینه که وابستگی های پروژه رو، رو پکیج های دانلود شده اصطلاحا قفل (lock) میکنه.

فایل poetry.lock باعث می شه هر کسی که پروژه رو راه اندازی می کنه، از نسخه های مشابه وابستگی هایی که شما استفاده می کنید، استفاده کنه. پس اگر از کنترل نسخه ای (version control) مثل git استفاده میکنید، پیشنهاد میشه این فایل رو هم کامیت (commit) کنید.

بعد از اعمال این تغییرات محتوای فایل pyproject.toml به صورت زیر میشه:

[tool.poetry]
name = &quotpoetry_demo&quot
version = &quot0.1.0&quot
description = &quot&quot
authors = [&quotiranipy <info@iranipy.ir>&quot]

[tool.poetry.dependencies]
python = &quot^3.8&quot
pendulum = &quot^2.1.2&quot

[tool.poetry.dev-dependencies] 
pytest = &quot^3.4&quot

[build-system]
requires = [&quotpoetry-core>=1.0.0&quot]
build-backend = &quotpoetry.core.masonry.api&quot

چون فعلا قصد تست نوشتن برای پروژه مون نداریم، به ماژول pytest نیاز نداریم. دو روش برای حذف کردنش وجود داره:

  • فایل pyproject.toml رو دستی تغییر بدیم و بعد از ذخیره تغییرات، دستور poetry install رو اجرا کنیم که در نهایت محتوای فایل pyproject.toml اینجوری میشه:
[tool.poetry]
name = &quotpoetry_demo&quot
version = &quot0.1.0&quot
description = &quot&quot
authors = [&quotiranipy <info@iranipy.ir>&quot]

[tool.poetry.dependencies]
python = &quot^3.8&quot
pendulum = &quot^2.1.2&quot

[build-system]
requires = [&quotpoetry-core>=1.0.0&quot]
build-backend = &quotpoetry.core.masonry.api&quot
  • روش دوم استفاده از دستور poetry remove هستش که علاوه بر حذف بسته مورد نظر از محیط مجازی ساخته شده برای این پروژه، خودش فایل pyproject.toml رو هم تغییر میده:
poetry remove pytest

ایجاد اسکریپت اصلی

اسکریپت مورد نظر رو با اسم main.py و تو پکیج poetry_demo/ با محتوای زیر می سازیم:

import pendulum

def main():
    now = pendulum.now(&quotEurope/Paris&quot)
    now.in_timezone(&quotAmerica/Toronto&quot)
    now.to_iso8601_string()
    print(now)

if __name__ == '__main__':
    main()

محتوای این فایل اسکریپت ساده ای هستش که نمونه کدی از کتابخونه pendulum رو اجرا می کنه.

بعد از ساخت اسکریپت main.py، ساختار پروژه اینجوری میشه:

poetry_demo 
├── pyproject.toml 
├── poetry.lock
└── poetry_demo     
   ├── __init__.py
   └── main.py

اجرای پروژه (اسکریپت)

برای اجرای اسکریپت main.py کافیه دستور زیر رو اجرا کنیم:

poetry run python poetry_demo/main.py

دستور بالا اسکریپت main.py که تو پکیج poetry_demo/ هستش رو تو محیط مجازی ساخته شده برای این پروژه اجرا می کنه.

قبل استفاده از دستور poetry run برای اطمینان از اینکه تغییرات فایل pyproject.toml اعمال شده، دستور poetry install رو اجرا کنید.

محیط مجازی (virtual environment)

ساده ترین راه برای فعال کردن محیط مجازی ساخت shell جدید با استفاده از دستور زیر هستش:

poetry shell

برای غیرفعال کردن محیط مجازی و خروج از این shell جدید دستور زیر رو اجرا می کنیم:

exit

برای غیرفعال کردن محیط مجازی بدون خروج از shell دستور زیر رو اجرا می کنیم:

deactivate

به این نکته هم توجه کنید که وقتی از دستور poetry run استفاده می کنیم، Poetry اسکریپت (پروژه) رو تو محیط مجازی ساخته شده برای اون پروژه اجرا می کنه. در نتیجه در اکثر اوقات به فعال کردن محیط مجازی به صورت دستی نیازی نیست.

تو این پست دیدیم که چجوری با استفاده از ابزار Poetry پروژه مون رو مدیریت کنیم. کلی کارمون رو راحت می کنه، مثل استفاده از محیط مجازی (virtual environment) که در حالت عادی برای خیلیامون راحت نیست.

امیدواریم از این پست استفاده کافی رو برده باشید. اگه شما هم مثل ما از خوندن مطالب پایتونی لذت میبرید، خوشحال میشیم ما رو تو شبکه های اجتماعی دنبال و در صورت داشتن انتقاد و پیشنهاد ما رو ازش مطلع کنید. لایک هم یادتون نره :)

حمایت از ما

با دنبال کردن ما در

یا کمک مالی به مبلغ دلخواه از طریق درگاه آیدی پی میتونید از ما حمایت کنید.

وب سایت (به زودی): iranipy.ir