الشعر بالبايثون: بيئة بايثون حديثة وفعالة لإدارة البيئة والتبعيات

الدروس التعليمية
Python

تعتمد بيئة Python تقليديًا على أدوات مثل pip و virtualenv لإدارة التبعيات وبيئات المشروع. على الرغم من أن هذه الأدوات خدمتنا بشكل جيد، إلا أنها غالبًا ما تؤدي إلى تضارب التبعيات وإدارة البيئة اليدوية وإعدادات المشروع غير المتناسقة عبر الفرق.

تحل Python Poetry هذه التحديات من خلال توفير أداة حديثة وموحدة لإدارة التبعيات والبيئات. تتعامل مع كل شيء بدءًا من البيئات الافتراضية إلى نشر الحزم، كل ذلك بينما تضمن بناءًا قابلاً لإعادة الإنتاج من خلال قرارات ذكية بشأن التبعيات.

سيقدم لك هذا الدليل كيفية استخدام Poetry لتبسيط سير عمل تطوير Python الخاص بك وتجنب الصداع الشائع المتعلق بالتبعيات.

Python Poetry مقابل PIP

تؤدي Poetry و pip وظائف مختلفة في نظام Python. بينما pip هو في المقام الأول أداة تثبيت حزم, فإن Poetry هو أداة إدارة تبعيات ومشاريع كاملة. فيما يلي الفروقات الرئيسية:

1. حلول التبعيات

  • Pip: حلاً بسيطاً وخطياً لحل التبعيات يمكن أن يؤدي إلى تضاربات
  • الشعر: مُحلل تبعيات متقدم يمنع الصراعات قبل التثبيت

2. إدارة البيئة الافتراضية

  • Pip: يتطلب أدوات منفصلة (virtualenv، venv) وتفعيل يدوي
  • الشعر: ينشئ ويدير بيئات افتراضية تلقائيًا لكل مشروع

3. تكوين المشروع

  • Pip: يستخدم requirements.txt للتبعيات، setup.py لبيانات المشروع
  • الشعر: ملف pyproject.toml واحد لجميع الاحتياجات التكوينية

4. ملفات القفل

  • Pip: لا يدعم ملف القفل المدمج
  • Poetry: يولد poetry.lock لبناء متكرر عبر البيئات

5. نشر الحزم

  • Pip: يتطلب أدوات إضافية (twine، setuptools) للنشر
  • Poetry: أوامر مدمجة لبناء ونشر الحزم

عندما تستخدم Poetry بدلاً من pip

اختر Poetry عندما:

  • تعمل على مشاريع فريق تحتاج إلى بيئات يمكن تكرارها
  • تقوم ببناء حزم ستتم نشرها على PyPI
  • تدير شجرة تبعية معقدة مع احتمالية حدوث تضاربات
  • تحتاج إلى إدارة البيئة الافتراضية تلقائيًا
  • ترغب في أداة واحدة لسير العمل التطويري بأكمله

تواصل استخدام pip عندما:

  • العمل على سكربتات بسيطة بأدنى تبعيات
  • تعلم لغة Python للمرة الأولى
  • بحاجة لتثبيت حزمة واحدة بسرعة
  • العمل في بيئات حيث لا يمكن تثبيت Poetry
  • صيانة المشاريع القديمة التي تم تهيئتها بالفعل باستخدام pip

القاعدة العامة هي: استخدم Poetry لأي مشروع سيتم مشاركته، نشره، أو صيانته على المدى الطويل. استخدم pip للتجارب السريعة أو تمارين التعلم.

مع ذلك، دعنا ننتقل مباشرة إلى استخدام “Poetry”.

إعداد “Poetry” في Python

سوف تتفاعل بشكل أساسي مع “Poetry” كأداة سطر أوامر (CLI)، لذا من السليم تثبيتها على نطاق النظام على جهازك. تغطي هذه الجزء الخطوة الأولى الحاسمة وكيفية ضبط بعض التكوينات الافتراضية لـ “Poetry” استنادًا إلى احتياجاتك.

تثبيت “Poetry”

يمكنك تثبيت “Poetry” باستخدام نص تثبيت رسمي، الذي يمكن تنزيله وتشغيله بأمر واحد.

بالنسبة لنظام macOS و Linux و WSL2:

$ curl -sSL https://install.python-poetry.org | sudo python3 -

بالنسبة لـ Windows Powershell (تشغيل بامتيازات المسؤول):

$ (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

إذا كنت تستخدم نظام Windows وقمت بتثبيت Python من متجر Microsoft (لسبب غريب ما)، فقم بتبديل py بـ python في الأمر أعلاه.

بعد انتهاء نص التثبيت، يُطبع رسالة تطلب منك إضافة Poetry إلى PATH الخاص بك حتى يكون أمر poetry متوفرًا في كل مكان.

بالنسبة لنظام macOS، Linux، و WSL2، قم بإضافة السطر التالي إلى سكريبت الخاص بالشيل مثل .bashrc أو .zshrc:

$ export PATH="/Users/bexgboost/.local/bin:$PATH"

بالنسبة لنظام Windows، يمكنك اتباع تعليمات الإخراج.

بعد ذلك، قم بالتحقق من تثبيتك عن طريق تشغيل poetry --version.

تكوين Poetry

معظم تكوينات Poetry تتعلق بكيفية إنشاء البيئات الافتراضية وكيفية تثبيت الحزم. يمكنك طباعة قائمة (تقريبية) كاملة لتكوينات Poetry باستخدام:

$ poetry config --list

سيكون الإخراج مشابهًا تمامًا للمثال أدناه:

cache-dir = "/Users/bexgboost/Library/Caches/pypoetry"
experimental.system-git-client = false
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
keyring.enabled = true
solver.lazy-wheel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # /Users/bexgboost/Library/Caches/pypoetry/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"
warnings.export = true

في السطر الأول، نرى مسارًا إلى ذاكرة التخزين المؤقت للشعر. يُستخدم بشكل رئيسي لتخزين توزيعات الحزم المُنزّلة والبيئات الافتراضية. يتم تخزين أي بيئات افتراضية تقوم بإنشائها هنا افتراضيًا. إذا كنت ترغب في تغيير ذلك، يمكنك تشغيل الأمر التالي:

$ poetry config virtualenvs.path path/to/new/virtualenv/dir

تكوين آخر مهم هو عدد النوى المستخدمة أثناء التثبيت. بشكل افتراضي، يتم تعيينها على أربعة، ولكن يمكننا جعلها أسرع عن طريق استغلال جميع نوى وحدة المعالجة المركزية. أولاً، اعرف عدد النوى في جهازك من خلال تشغيل os.cpu_count() في مُفسّر Python. ثم، قم بتعيين الناتج:

$ poetry config installer.max-workers = 10

إحدى الإعدادات الاختيارية هي ما إذا كنت ترغب في إنشاء بيئات افتراضية في دليل العمل الخاص بك أو في ذاكرة التخزين المؤقت. يتم التحكم في ذلك عبر virtualenvs.in-project الخيار. إذا قمت بتعيينه على True، .venv سيتم دائمًا إنشاء دليل في دليل العمل الخاص بك:

$ poetry config virtualenvs.in-project true

إنشاء مشروع جديد باستخدام Poetry

لنقم بالتعمق في الخطوات الرئيسية لإنشاء مشروع جديد بـ Poetry وفهم ملف تكوينه الأساسي.

تهيئة مشروع جديد بـ Poetry

يبدأ استخدام الشعر عادةً بإنشاء مشروع جديد باستخدام poetry new الأمر:

$ poetry new explore-poetry
$ cd explore-poetry

ينشئ الأمر مجلدًا explore-poetry يحتوي مسبقًا على الملفات والمجلدات التالية:

explore-poetry
├── pyproject.toml
├── README.md
├── explore-poetry
│   └── __init__.py
└── tests
   └── __init__.py

تتبع هذه الهيكلة المجلدات ممارسات Python الأفضل:

  • pyproject.toml: الملف الرئيسي لتكوين المشروع الذي يحدد بيانات المشروع والاعتماديات
  • README.md: ملف وثائقي يشرح المشروع
  • explore-poetry/: مجلد شفرة المصدر الذي يحتوي على شفرة الحزمة الرئيسية، مع __init__.py لجعلها حزمة
  • tests/: الدليل لملفات الاختبار، مع __init__.py لجعله حزمة (قابلة للاستيراد)

فهم ملف pyproject.toml

هنا، يتطلب ملف pyproject.toml انتباهًا دقيقًا حيث أنه الوحيد غير الفارغ الذي تُنشأه شعرية:

[tool.poetry]
name = "explore-poetry"
version = "0.1.0"
description = ""
authors = ["BexTuychiev <[email protected]>"]
readme = "README.md"
[tool.poetry.dependencies]
python = "^3.8"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

هذا الملف ينظم مشروعك وتبعياته. يستخدم لغة توم الواضحة والحد الأدنى، التي تم الاتفاق عليها كلغة تكوين قياسية لحزم Python في PEP 518.

تنقسم pyproject.toml الملفات إلى أقسام تُسمى tables باستخدام الأقواس مثل tool.poetry أو build-system. تستخدم Poetry هذه الجداول لإدارة التبعيات، ومتطلبات بناء المشروع، أو أداء مهام أخرى.

أثناء تشغيل أوامر الشعر المحددة في الأقسام القادمة، سيتم تحديث ملف pyproject.toml تلقائيًا.

العمل مع البيئات الافتراضية في الشعر

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

إنشاء وتنشيط بيئة افتراضية

عندما تقوم بتثبيت برنامج Poetry لأول مرة، فإنه لا يحتوي على بيئات مدمجة، كما يظهر من خلال عدم وجود أي مخرجات عند تشغيل poetry env list:

$ poetry env list  # لا توجد مخرجات

ولكن بمجرد بدء إضافة التبعيات (سنتعرف على ذلك لاحقًا) باستخدام بويتري add package-name، يقوم بإنشاء بيئة تلقائيًا في دليل الذاكرة المؤقتة للمشروع. على سبيل المثال، دعنا نحاول إضافة requests كتبعية:

$ poetry add requests

يجب أن تتلقى مخرجات مماثلة لما يلي:

Creating virtualenv explore-poetry--I9GJYUn-py3.8 in /Users/bexgboost/Library/Caches/pypoetry/virtualenvs
Using version ^2.32.3 for requests
Updating dependencies
Resolving dependencies... (2.5s)
Package operations: 5 installs, 0 updates, 0 removals
 - Installing certifi (2024.8.30)
 - Installing charset-normalizer (3.4.0)
 - Installing idna (3.10)
 - Installing urllib3 (2.2.3)
 - Installing requests (2.32.3)
Writing lock file

السطر الأول يشير إلى أن الشعر قام بإنشاء البيئة في ذاكرة التخزين المؤقت. الأسطر التالية تُبلغ أن الاعتماديات لـrequests تم حلها بنجاح، وتم إنشاء ملف قفل (سنتحدث عن ذلك لاحقًا).

انتبه إلى اسم البيئة: explore-poetry--I9GJYUn-py3.8. يتضمن الاسم اسم دليل المشروع، تليها معرف فريد ثم إصدار Python الذي تستخدمه البيئة.

في المرة القادمة التي تضيف فيها تبعية، سيقوم Poetry تلقائيًا باستخدام هذا البيئة لتثبيت الحزم:

$ poetry add beautifulsoup4
Using version ^4.12.3 for beautifulsoup4
Updating dependencies
Resolving dependencies... (1.1s)
Package operations: 2 installs, 0 updates, 0 removals
 - Installing soupsieve (2.6)
 - Installing beautifulsoup4 (4.12.3)
Writing lock file

عند استخدامك لـ Poetry، لن يظهر في الطرفية أي بيئة افتراضية لـ Poetry نشطة. لرؤية هذه المعلومات، تحتاج إلى تشغيل poetry env list:

$ poetry env list
explore-poetry--I9GJYUn-py3.8 (Activated)

للتفاعل مع بيئة Poetry النشطة، يمكنك تشغيل poetry shell:

$ poetry shell

الأمر يفتح جلسة جديدة للشل داخل الجلسة الحالية، ويمكنك تنفيذ أوامر مثل python أو pytest.

على سبيل المثال، لتنفيذ نصوص Python:

$ poetry shell
$ python script.py

لتشغيل أطر تطوير مثل Streamlit:

# داخل الشل
$ streamlit run app.py

بعد ذلك، يمكنك الخروج من الشل عن طريق استدعاء exit.

بالإضافة إلى ذلك، يمكنك تشغيل الأوامر في شل Poetry دون الدخول إليه بواسطة poetry run:

$ poetry run python script.py
$ poetry run streamlit run app.py

تكوين إصدار Python

عند تشغيل poetry add أو poetry install, تستخدم Poetry تلقائيًا الإصدار الخاص بـ Python المحدد في ملف pyproject.toml. لتحديد إصدار Python مختلف، يمكنك تشغيل الأمر env use:

$ poetry env use python3.11

يرجى ملاحظة أنه يجب تثبيت Python 3.11 على نطاق النظام على جهازك لتعمل الأمر.

تحقق من أن Poetry يستخدم البيئة بإصدار Python الجديد:

$ poetry env list
explore-poetry--I9GJYUn-py3.11 (Activated)
explore-poetry--I9GJYUn-py3.8

لاحظ كيف تُرتبط البيئة الجديدة تلقائيًا بمشروعنا (تكون الهويات متطابقة). بمجرد تكوين إصدار Python الخاص بك، يمكنك حذف البيئات ذات الإصدارات الأخرى لتحرير مساحة القرص:

$ poetry env remove python3.8

عند حذف بيئة، يجب عليك تحديد إصدار Python فقط. يمكنك أيضًا حذف جميع البيئات والبدء من جديد:

$ poetry env remove --all

يرجى ملاحظة أن العلامة --all تزيل جميع البيئات المرتبطة بالمشروع الحالي، وليس البيئات التابعة لمشاريع أخرى.

إذا كنت تعمل على مشاريع فريقية، فمن الأفضل غالبًا الاحتفاظ بالبيئة الافتراضية في دليل المشروع:

$ poetry config virtualenvs.in-project true

لن يكون لهذا الأمر أي تأثير إذا كان لديك بالفعل بيئة للمشروع في الذاكرة المؤقتة. لإنشاء بيئة محلية، قم بإزالة جميع البيئات الحالية من الذاكرة المؤقتة أولاً.

تنشئ هذا.venv مجلدًا في دليل العمل الخاص بك، الذي يجب عليك إضافته إلى ملف .gitignore.

إدارة التبعيات باستخدام Poetry

إدارة التبعيات هي الميزة التي تبرز في Poetry. إنه يوفر ميزات شاملة لتحديد وتثبيت وإدارة التبعيات بحيث لا تواجه أبدًا صراعات تبعيات مروعة.

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

إضافة تبعيات في Poetry

عند استخدام بويتري، ستستخدم poetry add package-name الأمر لتثبيت الحزم من PyPI بدلاً من pip install. ولهذا بعض الفوائد:

  1. يضيف الحزمة تلقائيًا إلى pyproject.toml بالقيد الصحيح للإصدار
  2. يحدث ملف القفل لضمان بناء قابل لإعادة الإنتاج
  3. يحل الاعتماديات لتجنب التضاربات
  4. يثبت الحزمة وجميع الاعتماديات الخاصة بها في البيئة الافتراضية

على سبيل المثال، دعنا نضيف أولاً Numpy كاعتمادية:

$ poetry add numpy

في الحال، يجب عليك أن تتلقى صراع تحديد الاعتماديات يقول أن إصدار Numpy الذي يتم تثبيته ليس متوافقًا مع إصدار Python الخاص بك. السبب هو أننا عندما قمنا بالتبديل إلى بيئة Python 3.11، لم نقم بتحديث الملف pyproject.toml حتى الآن، يبدو كالتالي:

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.32.3"
beautifulsoup4 = "^4.12.3"

يتم استخدام رمز الرف ^ للإشارة إلى أن مشروعنا explore-poetry متوافق مع أي إصدار من Python حتى Python 4 ولكن نطاق إصدار Numpy يدعم فقط إصدارات Python بين 3.8 و 3.12، وهو نطاق أضيق. ينتج خطأ التعارض من هذه الحقيقة.

لحل الخطأ، يجب عليك تحديث نطاق إصدار Python إلى ما يلي:

python = ">=3.8, <3.12"

بمجرد أن تقوم بهذا التغيير، poetry add numpy يجب أن يعمل الأمر كما هو متوقع.

لقد لاحظت للتو واحدة من أفضل ميزات Poetry — التقاط تعارض الإصدارات قبل تثبيت أي حزم بدلاً من إبلاغك عن عدم التوافق بعد ذلك، مثل pip.

الصيغة لتحديد إصدارات التبعيات

تستخدم الشعرة بناء جملة قوي لتحديد مجموعة واسعة من الإصدارات للتزامن الأفضل بين التبعيات. فيما يلي الرموز الأكثر استخدامًا:

  1. رمز السهم المقلوب (^): يسمح بالتحديثات التصحيحية والفرعية ولكن لا يسمح بالتحديثات الرئيسية. مثال: ^1.2.3 يسمح بالتحديثات من 1.2.3 إلى 1.9.9 ولكن لا يسمح بـ 2.0.0.
  2. رمز الموجة (~): يسمح فقط بالتحديثات التصحيحية. مثال: ~1.2.3 يسمح بالتحديثات من 1.2.3 إلى 1.2.9 ولكن لا يسمح بـ 1.3.0.
  3. الإصدار الدقيق: يحدد رقم الإصدار الدقيق. مثال: 1.2.3 يسمح فقط بالإصدار 1.2.3
  4. أكبر من (>): يسمح بأي إصدار أعلى من المحدد. مثال: >1.2.3 يسمح 1.2.4، 1.3.0، 2.0.0، إلخ.
  5. أقل من (<): يسمح بأي إصدار أقل من المحدد. مثال: <2.0.0 يسمح بأي شيء أقل من 2.0.0.
  6. أكبر من أو يساوي (>=): يسمح بالإصدار المحدد وما فوق. مثال: >=1.2.3 يسمح بـ 1.2.3 وأي إصدار أعلى.
  7. أقل من أو يساوي (<=): يسمح بالإصدار المحدد والأصدقاء. مثال: <=2.0.0 يسمح بالإصدار 2.0.0 وأي إصدار أقل منه.
  8. نطاق الإصدار: يجمع بين القيود بفواصل. مثال: >=1.2.3,<2.0.0 يسمح بالإصدارات من 1.2.3 إلى 1.9.9
  9. Wildcard (*): تطابق أي إصدار. مثال: 1.2.* يطابق أي إصدار يبدأ بـ 1.2

بالطبع، يمكنك الجمع بين هذه الاستراتيجيات وتناسب احتياجاتك.

إنشاء مجموعات الاعتماد في Poetry

في المشاريع المعقدة التي تتضمن العديد من المكونات المتحركة، غالباً ما تتعامل مع فئات مختلفة من الاعتماديات.

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

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

$ poetry add --group ui streamlit plotly dash
$ poetry add --group dev black flake8 isort mypy pylint

تقوم الأوامر أعلاه بإنشاء مجموعتين من التبعيات، ui و dev (إذا لم تكن موجودة بالفعل)، واثنين من الجداول الفرعية في pyproject.toml:

[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.32.3"
beautifulsoup4 = "^4.12.3"
numpy = "^2.1.3"
[tool.poetry.group.ui.dependencies]
streamlit = "^1.39.0"
plotly = "^5.24.1"
dash = "^2.18.2"
[tool.poetry.group.dev.dependencies]
black = "^24.10.0"
flake8 = "^7.1.1"
isort = "^5.13.2"
mypy = "^1.13.0"
pylint = "^3.3.1"

على الرغم من أن مجموعات الاعتماد مفصولة، إلا أنها ما زالت تُحل بالنسبة لبعضها البعض. وبمعنى آخر، إذا كان هناك dev اعتماد متضارب مع حزمة في ui، فلن يقوم برنامج Poetry بتشغيل التثبيت.

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

[tool.poetry.group.ui]
optional = true
[tool.poetry.group.ui.dependencies]
streamlit = "^1.39.0"
plotly = "^5.24.1"
dash = "^2.18.2"

يتم ذلك عن طريق تعيين optional إلى true قبل إعلان تبعيات المجموعة.

إعادة إنشاء مشروع الشعر مع ملف poetry.lock

إذا قام شخص ما بنسخ مستودع GitHub الخاص بك الذي يحتوي على مشروع Poetry، فيمكنه إعادة إنشاء نسخة مثالية من البيئة الافتراضية لمشروعك من خلال تشغيل أمر واحد: poetry install.

الأمر install يستخدم الملف poetry.lock الشامل أكثر. على عكس pyproject.toml, يقوم الملف المقفل بسرد:

  • الإصدارات الدقيقة للتبعيات الرئيسية المدرجة في pyproject.toml
  • الإصدارات الدقيقة لتبعيات التبعيات الرئيسية (التبعيات المعتمدة)

على سبيل المثال، requests تعتمد على urllib3، certifi، charset-normalizer و idna. بدون ملف قفل، قد تؤدي هذه التبعيات الفرعية إلى إصدارات مختلفة على آلات مختلفة.

يضمن ملف القفل أن يحصل كل فرد في فريقك على نفس إصدارات التبعيات، مما يمنع مشكلة “يعمل على جهازي”.

الفرق بين الأمرين poetry add و poetry install

سنشرح الفرق بين add و install أوامر Poetry مع حالة استخدام.

لنقل أنك تعمل على مشروع للكشف عن الاحتيال. تقوم بإضافة التبعيات الأولية الخاصة بك:

$ poetry add pandas scikit-learn

يتم إضافة الحزم إلى الملفات القفل وpyproject.toml .ثم، يقوم زميلك بنسخ المستودع:

$ git clone fraud-detection-repo-link
$ cd fraud-detection
$ poetry install

يقومون بتشغيل install الأمر لتثبيت كل ما هو مدرج في ملف القفل.

في وقت لاحق، تحتاج إلى إضافة حزمة جديدة:

$ poetry add xgboost

يقوم زميلك بجلب التغييرات:

$ git pull
$ poetry install

يقومون بتشغيل install الأمر لتثبيت الحزمة الجديدة. لذا،

  • استخدم poetry add عند إضافة تبعيات جديدة
  • استخدم poetry install عندما تحتاج إلى إعداد مشروع قائم
  • قم دائمًا بعمل commit لـ pyproject.toml و poetry.lock إلى التحكم في الإصدارات

تثبيت مجموعات الاعتماد باستخدام أمر poetry install

في وقت سابق، تعلمنا كيفية تجميع التبعيات في Poetry. عندما تقوم بتشغيل poetry install، فإنه يقوم بتثبيت جميع المجموعات غير الاختيارية بشكل افتراضي، وهو ما قد لا يكون ما تريده في جميع الحالات.

على سبيل المثال، قد تقوم باستنساخ مستودع فقط للعمل على الوثائق. أو تريد العمل على الكود الرئيسي للمستودع، باستثناء الجوانب المتعلقة بالوثائق والاختبار. إن install أمر مرن بما يكفي لتغطية جميع هذه الحالات:

استبعاد مجموعات معينة:

$ poetry install --without ui,dev

تثبيت مجموعات اختيارية أيضًا:

# تثبيت مجموعة الوثائق الاختيارية
$ poetry install --with docs

تثبيت مجموعات محددة فقط:

$ poetry install --only ui

تثبيت متطلبات تشغيل المشروع فقط (التبعيات المذكورة خارج المجموعات، المضافة باستخدام poetry add package الأوامر):

$ poetry install --only main

إزالة التبعيات في Poetry

حذف الاعتماد بسيط باستخدام remove الأمر:

$ poetry remove requests

هذا يزيل requests من الاعتمادات الأساسية للمشروع. لإزالة حزمة من اعتماد المجموعة، يمكنك استخدام --group العلامة مرة أخرى:

$ poetry remove streamlit --group ui

الأمر remove يُلغي الحزمة بشكل نظيف، مع جميع التبعيات الشجرية لها.

نشر مشروع باستخدام Poetry إلى PyPI

إذا كان مشروعك جاهزًا للتوزيع، فإن نشره على PyPI (Python Package Index) يسمح للمطورين الآخرين بتثبيت واستخدام كودك بسهولة من خلال pip. يُسهل Poetry هذه العملية تمامًا بخطوتين فقط:

$ poetry build  # بناء التوزيعات
$ poetry publish  # نشر إلى PyPI

ومع ذلك، قبل أن تقوم بتشغيل هذه الأوامر، يجب عليك إعداد بيانات اعتماد PyPI الخاصة بك بشكل صحيح. أولاً، أنشئ حساباتك على:

  1. PyPI
  2. TestPyPI

قم بتكوين Poetry باستخدام بيانات اعتمادك:

$ poetry config pypi-token.pypi your-pypi-token
$ poetry config pypi-token.testpypi your-test-pypi-token

الآن، اختبر حزمةك أولاً:

# قم بتكوين مستودع TestPyPI
$ poetry config repositories.testpypi https://test.pypi.org/legacy/
# نشر إلى TestPyPI
$ poetry build
$ poetry publish -r testpypi

بعد نشرها على TestPyPI ، يمكنك محاولة تثبيت الحزمة الخاصة بك للتحقق من أن كل شيء يعمل بشكل جيد:

$ pip install --index-url https://test.pypi.org/simple/ your-package-name

إذا كان كل شيء على ما يرام، يمكنك نشرها على PyPI نفسها:

$ poetry publish

أفضل الممارسات عند العمل مع Poetry

هناك العديد من الأمور التي يجب توخي الحذر بها وأفضل الممارسات عند استخدام Poetry، وبالطبع، لا يمكننا ذكرها جميعًا في مقال واحد. ولكن هنا بعض الممارسات الشائعة التي يمكنك تطبيقها على الفور:

  1. استخدم دائمًا بيئات افتراضية – ينشئ Poetry تلك البيئات تلقائيًا لكل مشروع
  2. احتفظ بملف pyproject.toml تحت نظام التحكم في الإصدار ولكن استبعد poetry.lock للمكتبات
  3. قم بتضمين poetry.lock في نظام التحكم في الإصدار للتطبيقات لضمان بناء قابل للتكرار
  4. استخدم الترقيم الدلالي لإصدارات الحزمة الخاصة بك (رئيسي.ثانوي.تصحيح). يمكنك استخدام poetry version patch/minor/major الأوامر لزيادة إصدارات الحزمة بواحد. على سبيل المثال، poetry version major يغير 0.2.0 إلى 1.0.0 في ملفك pyproject.toml .
  5. حدد قيود إصدار الاعتمادات بعناية لتجنب التضاربات
  6. قم بتحديث الاعتماديات بانتظام باستخدام poetry update ولكن قم بإجراء اختبار شامل بعد التحديثات
  7. استخدم poetry add --group devللاعتماديات التطويرية للحفاظ على فصلها
  8. وثّق أغراض جميع التبعيات في pyproject.toml باستخدام تعليقات
  9. تشغيل poetry check قبل التزامات للتحقق من صحة pyproject.toml الصيغة. يمكنك أيضًا التفكير في خطوط تعليق ما قبل التزام.
  10. استخدم poetry export لإنشاء requirements.txt عند الحاجة لاستخدامها في أدوات أخرى.
  11. حافظ على تبسيط التبعيات الإنتاجية – قم بنقل الميزات الاختيارية إلى اضافات
  12. قم بفحص تثبيت الحزمة الخاصة بك في بيئة نظيفة قبل النشر
  13. استخدم TestPyPI قبل نشره في مستودع PyPI الرئيسي
  14. حافظ على CHANGELOG.md واضح لتتبع تغييرات الإصدار
  15. استخدم poetry run لتنفيذ السكريبت لضمان استخدام البيئة بشكل صحيح

الخاتمة والخطوات القادمة

قد غيّرت الشعرية إدارة تبعيات Python من خلال توفير حلاً قويًا وبديهيًا لتحديات إدارة الحزم الشائعة. تتميز بميزاتها القوية لحل التبعيات وإدارة البيئة الافتراضية ونشر المشروع، مما يجعلها أداة لا غنى عنها لتطوير Python الحديث.

لمواصلة رحلتك في تطوير Python، انظر إلى استكشاف هذه المسارات التعليمية الشاملة:

تذكر أن إدارة التبعيات بشكل فعال هي جانب واحد فقط من تطوير بايثون المهني. مع استمرارك في النمو كمطور، ستساعدك أدوات مثل Poetry في بناء مشاريع بايثون أكثر قابلية للصيانة وموثوقية.

Source:
https://www.datacamp.com/tutorial/python-poetry