أفضل ممارسات Python uv: قائمة تحقق الاستقرار والتعاون

في الممارسة العملية، البيئات تميل إلى الكسر ليس لأن "uv ليس قوياً بما يكفي"، بل بسبب العملية والعادات. يمكن استخدام قائمة التحقق هذه كإرشادات يومية — كل مخاطرة يُتجنَّبها هي مرة أخرى تغادر العمل في وقتها.

الممارسات الموصى بها

1) التزم دائماً بـ uv.lock

lockfile هو أساس قابلية التكرار. عدم الالتزام به يعني أن الجميع — كل جهاز، كل تشغيل CI — قد يثبّتون تبعيات مختلفة. إعادة إنتاج الأخطاء تصبح وضعاً جهنمياً. مشروع بدون lockfile مثل حذاء جديد لم تجربه: تكتشف أنه يؤلم فقط في المعركة.

2) لا تلتزم أبداً بـ .venv

البيئة الافتراضية قطعة أثرية محلية — يجب أن تكون في .gitignore. uv يضيف تلقائياً .venv لملف تجاهل المشروع؛ فقط تأكد من وجوده.

3) قيّد التبعيات عند الإمكان

في pyproject.toml، تجنب requests مجرداً — فضّل requests>=2.31,<3 أو أكثر تحديداً. uv add يضيف قيوداً معقولة بشكل افتراضي؛ عند التعديل اليدوي، لا تترك النطاق واسعاً جداً.

4) استخدم uv sync أو uv pip sync في CI

# مثال GitHub Actions
- run: uv sync
- run: uv run pytest

زامن أولاً، ثم شغّل — يضمن أن البيئة تطابق lockfile. لا تشغّل uv add في CI؛ ذلك يعدّل lockfile وقد يخلق فروقات غير متوقعة.

5) ضع أدوات التطوير في optional / dev

uv add --dev pytest ruff mypy

الاختبارات والـ lint وفحص الأنواع لا تؤثر على تبعيات الإنتاج ولن تُحزَّم في wheel. صور الإنتاج تحتاج فقط uv sync --no-dev.

المخاطر الشائعة

المخطر 1: خلط pip وuv add

لا تستخدم كلاً من pip install وuv add في نفس venv — lockfile سيُفقَد من المزامنة. اختر مساراً واحداً وتمسك به.

المخطر 2: استخدام uvx لأدوات المشروع

أدوات المشروع التي تحتاج إصداراً مثبّتاً (مثل pytest وmypy) → استخدم uv add --dev + uv run.
الاستخدام المؤقت لمرة واحدة → استخدم uvx.

المخطر 3: تعديل pyproject.toml يدوياً بدون قراءته أولاً

لتغييرات التبعيات، فضّل uv add / uv remove — يتجنب مشاكل الصيغة والفقدان من تحديثات lockfile.

المخطر 4: عدم تثبيت uv في CI

أنظمة CI كثيرة تدعم الآن uv — يثبّت بسرعة ويعمل أسرع. استخدم المثبّت الرسمي أو pip install uv؛ لا تستمر في استخدام pip لحل التبعيات إلى الأبد.

المخطر 5: لا requires-python في المشروع

في pyproject.toml، حدد requires-python = ">=3.12" إلخ.، حتى تعرف الأدوات والمتعاونون متطلب الحد الأدنى من الإصدار. يمنع كارثة "يعمل على 3.12 لديّ، ينهار على 3.8 لديك."

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