المفاهيم الجوهرية لـ Python uv: pyproject.toml وLockfile والبيئات الافتراضية

قبل كتابة الأوامر عشوائياً، احصل على هذه المفاهيم الأربعة في ذهنك: ستكون أوضح بشأن "أين تذهب التبعيات، ما فائدة lockfile، متى يُنشأ venv".

المفهوم 1: pyproject.toml هو بطاقة هوية مشروعك

بيانات المشروع والتبعيات تعيش هنا جميعاً — إنه تنسيق معيار PEP 518.

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.31",
]

• التعديل اليدوي: عدّل pyproject.toml مباشرةً
• مدفوع بالأوامر: uv add requests وuv remove requests يحدّثانه تلقائياً

لا تخلط الطريقتين — إما عدّل يدوياً أو استخدم الأوامر. فعل كليهما يسبب تعارضات.

المفهوم 2: uv.lock هو لقطة للتبعيات

pyproject.toml يقول "ما أريده" (مثلاً requests>=2.31). uv.lock يسجّل "ما ثُبِّت فعلياً" — دقيق لكل تبعية عابرة.

• لماذا lockfile؟ يضمن أن الجميع — كل زملائك وCI والإنتاج — يثبّتون نفس شجرة التبعيات بالضبط. لا مزيد من "يعمل على جهازي، يكسر على جهازك."
• هل تلتزم به؟ نعم. uv.lock يجب أن يكون في التحكم بالإصدارات حتى يستخدم الفريق وCI نفس شجرة التبعيات.

# تحديث lockfile (مثلاً ترقية حزمة)
uv lock --upgrade-package requests

المفهوم 3: .venv هو صندوق رمل مشروعك

ينشئ uv .venv في جذر المشروع — جميع حزم uv add تذهب هنا، معزولة عن Python النظام.

• هل تحتاج تفعيله يدوياً؟ لا. uv run يستخدم هذه البيئة تلقائياً.
• هل تلتزم به؟ لا. .venv يجب أن يكون في .gitignore.

# مزامنة البيئة يدوياً (مثلاً بعد استنساخ جديد)
uv sync
source .venv/bin/activate  # بعد هذا يمكنك استخدام python وpytest وغيرها مباشرةً

المفهوم 4: uv run هو نقطة الدخول السهلة

uv run سيقوم بـ:

1. التحقق من اتساق lockfile مع pyproject.toml
2. التأكد من مزامنة .venv مع lockfile
3. تنفيذ الأمر المحدد في البيئة الصحيحة

uv run python main.py
uv run pytest
uv run flask run -p 3000

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

الخطوات التالية

بمجرد استيعاب المفاهيم الجوهرية، انتقل إلى العمليات عالية التردد: إدارة التبعيات وuvx وتنفيذ السكريبت.
👉 الأنماط الشائعة