كيف تُعدّ مشروع Python سريعاً وقابلاً لإعادة الإنتاج باستخدام uv

حين توجّه وكيل برمجة بالذكاء الاصطناعي مثل Claude Code أو Codex إلى مشروع Python، فإن نصف الاحتكاك لا علاقة له بالنموذج إطلاقاً. إنه ينبع من البيئة: حزم مفقودة، أو إصدار Python الخاطئ، أو بيئة افتراضية نسي الوكيل تفعيلها، أو زميل في الفريق "يعمل على جهازي أنا". والحلّ هو مشروع قابل لإعادة الإنتاج افتراضياً، وأسرع طريقة للحصول على واحد اليوم هي uv، سلسلة أدوات Python المبنية على Rust من Astral.

يحلّ uv محلّ pip وvenv وpip-tools وpyenv بأمر واحد سريع، ويكتب ملف قفل (lockfile) بحيث تُثبَّت شجرة الاعتماديات نفسها بالضبط في كل مكان. يأخذك هذا الدليل من لا شيء إلى مشروع مُثبّت وقابل للتشغيل خلال دقائق قليلة.

لماذا تهمّ البيئة بالنسبة للوكيل

يشغّل وكيل الذكاء الاصطناعي أوامر في طرفيتك (shell) ويقرأ الأخطاء العائدة منها. فإن لم يكن لمشروعك اعتماديات معلَنة ولا إصدار Python مثبَّت، يضطرّ الوكيل إلى التخمين — والتخمين الخاطئ يرسله في متاهة من تثبيت الحزم على المستوى العام أو تعديل المفسّر الخاطئ. أما المشروع الذي يحوي pyproject.toml وuv.lock فيمنح الوكيل مصدراً واحداً للحقيقة: يمكنه تشغيل uv sync، والحصول على الحزم الصحيحة، والمضيّ قُدماً. عندها تنفق وقت مراجعتك على المنطق، لا على التنقيب الأثري في البيئة.

تثبيت uv

على macOS أو Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

على Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

إن uv ملفّ تنفيذي واحد قائم بذاته، لذا لا شيء آخر تحتاج إلى ضبطه.

ابدأ مشروعاً بأمر واحد

uv init weather-cli
cd weather-cli

هذا يُنشئ هيكل مشروع عامل: ملف pyproject.toml للبيانات الوصفية والاعتماديات، وملف .python-version، وملف main.py كنقطة انطلاق، وملف README.md، وملف .gitignore. أنت لا تُنشئ بيئة افتراضية أو تُفعّلها يدوياً — فـ uv يدير .venv نيابة عنك لحظة احتياجك إليها.

إضافة الاعتماديات (ولماذا يهمّ ملف القفل)

uv add requests

يقوم هذا بثلاثة أمور دفعة واحدة: يسجّل requests في pyproject.toml، ويحلّ شجرة الاعتماديات الكاملة، ويكتب uv.lock بإصدارات مثبَّتة بدقّة وعابرة للمنصّات. ويمكنك التثبيت عند الإضافة أيضاً:

uv add 'requests==2.31.0'

أضِف uv.lock إلى Git. فهو الفرق بين "ثبّت أحدث إصدار من requests" (الذي ينحرف مع مرور الوقت) و"ثبّت الشجرة الدقيقة التي اختبرناها". وعندما يشغّل وكيلك — أو نظام التكامل المستمر (CI) لديك، أو زميل جديد — الأمر uv sync، يحصلون على بيئة مطابقة بايتاً ببايت.

شغّل الكود دون تفعيل أي شيء

uv run main.py

يضمن uv run أن البيئة متزامنة، ثم يُنفّذ داخلها — دون رقصة source .venv/bin/activate. وهذا مهمّ للوكلاء على وجه الخصوص: فكل استدعاء أداة غالباً ما يكون طرفية جديدة، لذا فإن "فعّل ثم شغّل" يتعطّل كثيراً، بينما uv run المنفرد يعمل دائماً. ويمكنك تغليف أي أمر:

uv run -- pytest -q
uv run -- flask run -p 3000

ثبّت إصدار Python كي يتّفق الوكيل ونظام CI

uv python pin 3.12

هذا يكتب الإصدار في .python-version، وسيقوم uv بتنزيل ذلك المفسّر واستخدامه تلقائياً — دون الحاجة إلى Python على مستوى النظام. والآن، الإصدار الذي تطوّر عليه هو الإصدار نفسه الذي يستخدمه وكيلك وزملاؤك ونظام CI لديك جميعاً.

مثال عملي مختصر

لنفترض أنك طلبت من وكيل "إضافة أمر يجلب طقس اليوم". مع وجود uv، تكون الحلقة بأكملها نظيفة:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# the agent edits main.py to call an API...
uv run main.py

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

إلى أين يتّجه uv

إن uv وأداتيه الشقيقتين ruff (المدقّق/المنسّق) وty (مدقّق الأنواع) واسعة الاعتماد — فـ uv وحده يشهد ما يزيد عن 100 مليون تنزيل شهرياً. وفي مارس 2026، وافقت OpenAI على الاستحواذ على Astral، الشركة التي تقف خلفها، لدمج سلسلة الأدوات في منصّتها Codex، مع الالتزام بإبقاء الأدوات المرخّصة بترخيص MIT مفتوحة المصدر (OpenAI، Simon Willison). وفي الوقت الحالي، تبقى الخلاصة العملية ثابتة دون تغيير: إن uv هو أسرع طريق إلى مشروع Python يستطيع وكيل الذكاء الاصطناعي البناء عليه دون تخمين.

مرجع سريع

المهمة	الأمر
إنشاء مشروع	uv init <name>
إضافة اعتمادية	uv add <package>
تثبيت إصدار Python	uv python pin 3.12
تشغيل الكود	uv run <file or command>
إعادة إنتاج البيئة	uv sync
تحديث ملف القفل	uv lock --upgrade-package <pkg>