3  إعداد بيئة التطوير

3.1 لماذا لا نثبّت بايثون بالطريقة التقليدية؟

تابع المقطع التالي حيث نشرح ذلك بالتفصيل:

وفي هذا المقطع بينا أننا إذا ثبّتنا بايثون بالطريقة التقليدية من موقع python.org صارت كل المشاريع على الجهاز مرتبطة بنفس المفسر ونفس المكتبات. فالمفسر له إصدار معيّن (مثل 3.9 أو 3.12)، والمكتبات مثل NumPy وSciPy وPandas لها إصدارات أيضًا. قد يعمل المشروع الأول على بايثون 3.9 ومكتبة بإصدار معيّن، ثم نرقّي أو نخفّض الإصدار في مشروع ثانٍ، فإذا عدنا للمشروع الأول وجدنا تعارضًا: خواص موجودة في إصدار وغير موجودة في آخر. لذلك لن نثبّت بايثون بهذه الطريقة المشتركة.

3.2 مدير المشاريع: uv

بدل ذلك نستخدم برنامجًا اسمه uv، وهو مدير مشاريع بايثونية. عبره نحمّل مفسر بايثون والمكتبات الخاصة بكل مشروع على حدة، فتُحفظ داخل مجلد مخفي يبدأ بنقطة (مثل .venv) يحتوي الملفات التنفيذية والمكتبات لذلك المشروع فقط، دون أن تتأثر المشاريع الأخرى. وفي مشروع ثانٍ يمكننا عبر uv أيضًا اختيار إصدار مختلف من بايثون ومكتبات مختلفة حسب حاجته. لذلك أول ما نثبّته هو uv، ثم عن طريقه نثبّت بايثون وبقية الحزم.

3.3 محرر النص البرمجي

أما محرر النص البرمجي (Code Editor) فسنختار Visual Studio Code التابع لشركة مايكروسوفت، وهو مختلف عن Visual Studio.

  • وهو مفتوح المصدر (أي: يمكن الاطلاع على نصه البرمجي).
  • ويستعمله 73.6% من 58,121 متجاوب في استبيان StackOverFlow 2024 وما يميزه أنه سهل بالنسبة للمبتدئ، وقوي بالنسبة للمتمكن.
  • وتُعنى الشركة بدعمه وصيانته باستمرار وتطويره، كما يساهم فيه آخرون من خارج الشركة لكوْنه مفتوح المصدر.
  • وتم تصميمه كي يقبل الزيادات واللواحق البرمجية ليختار كل مبرمج ما يناسبه من الأدوات حسب احتياجاته.

موقع المحرر: https://code.visualstudio.com/

3.4 بيئة التطوير

ثم بيئة التطوير (Development Environment) وهي الأدوات البرمجية الأساسية والمساعدة في كتابة النص البرمجي وتنفيذه واختباره وتصحيحه وما إلى ذلك.

ولتشغيل القطع البرمجية راجع هذا الرابط: https://code.visualstudio.com/docs/python/run.

3.5 خطوات إعداد بيئة التطوير

شاهد هذا المقطع لإتمام إعداد بيئة التطوير:

تثبيت Visual Studio Code

في هذا المقطع نحمّل Visual Studio Code من صفحته الرئيسية أو من قسم التنزيل حسب نظام التشغيل، ثم نتبع خطوات التثبيت. في موقع المحرر صفحات مساعدة مثل Get Started وقسم Python مع Quick Start يفيدان في البداية.

بعد التثبيت نفتح مجلد مشروع عبر Explorer (المستكشف) باختيار Open Folder. داخل المجلد ننشئ ملفات مثل main.py؛ تظهر الملفات المفتوحة كـ تبويبات (Tabs) يمكن إغلاقها وإعادة فتحها. يمكننا كتابة أوامر مثل print، لكن تشغيلها يحتاج مفسر بايثون.

تثبيت uv وإنشاء المشروع

نثبّت uv من صفحة التثبيت الرسمية: على macOS وLinux ننسخ أمر التثبيت ونلصقه في شاشة الأوامر (Terminal) داخل VS Code (من القائمة View → Terminal، أو باختصار لوحة المفاتيح). بعد انتهاء التثبيت نتحقق بـ uv --version. ثم نحوّل المجلد إلى مشروع بايثوني بأمر uv init . فيظهر مثلًا ملف .python-version الذي يحدد إصدار بايثون. بعدها uv sync ينشئ بيئة افتراضية في المجلد المخفي .venv وفيه المفسر والمكتبات الخاصة بهذا المشروع فقط.

اختيار المفسر وتشغيل الشيفرة

للتأكد أننا نستخدم مفسر المشروع وليس بايثون النظام، نختار من شريط الحالة المفسر .venv/bin/python (وغالبًا يظهر كـ Recommended). يمكن التحقق في شاشة الأوامر بـ which python لرؤية المسار داخل .venv. تشغيل الملف يعني عمليًا تمرير مسار المفسر ثم مسار الملف؛ زر Run Python File يفعل ذلك تلقائيًا. ويمكن تشغيل أسطر محددة بـ Run Selection، أو بـ Shift+Enter، أو التفاعل في شاشة أوامر بايثون التفاعلية؛ وعند الحاجة نمسح شاشة الأوامر ونفتح واحدة جديدة.

الخلايا ودفاتر Jupyter

طريقة أخرى مفضّلة عند التجريب: وضع فاصل خلية # %% في ملف .py ثم تشغيل الخلية (Run Cell). لذلك نحتاج حزمة ipykernel عبر uv add ipykernel. ويمكن بدل ذلك إنشاء دفتر Jupyter بامتداد .ipynb (Interactive Python Notebook)، واختيار نفس نواة .venv، وتشغيل كل خلية على حدة؛ سياق التنفيذ متصل بين الخلايا ما دامت الجلسة قائمة، وترتيب التشغيل مهم، وRestart يفرّغ الذاكرة.

الإضافات والإعدادات

للتعديل السريع على الإعدادات والسمات نستخدم لوحة الأوامر (Command Palette) بـ Ctrl+Shift+P (مثل اختيار Color Theme). ومن قسم Extensions نثبّت الإضافات المفيدة، وأهمها إضافة Python التي تربط المحرر بالمفسر. للتفاصيل راجع توثيق المحرر نفسه.

3.6 تحميل دفاتر الدروس

في أعلى كثير من الدروس والتمارين ستجد رابط تحميل الدفتر. عند الضغط عليه يفتح المتصفح صفحةً تعرض محتوى الملف كنص JSON (وليس دفترًا تفاعليًا جاهزًا)، بهذا الشكل تقريبًا:

صفحة JSON لدفتر Jupyter بعد فتح رابط التحميل

صفحة JSON لدفتر Jupyter بعد فتح رابط التحميل

لحفظه كدفتر Jupyter:

  1. اضغط Ctrl+S (أو من قائمة المتصفح: Save Page As… / حفظ الصفحة باسم…).
  2. احفظ الملف بامتداد .ipynb (مثل 01_instructions.ipynb). إن اقترح المتصفح امتدادًا آخر مثل .txt فغيّره يدويًا إلى .ipynb.
  3. افتح الملف المحفوظ في Visual Studio Code، واختر نواة المشروع (.venv) كما سبق في إعداد بيئة التطوير.

بهذا يعمل الدفتر محليًا لديك بنفس طريقة أي ملف .ipynb آخر.

3.7 تثبيت الحزم

بايثون وحده لا يكفي لكل شيء. كثير من الأمور المفيدة تأتي جاهزة في حزم (packages): برامج صغيرة يكتبها آخرون، ونحن نثبّتها لنستخدمها. مثلًا:

  • geopy — للعمل مع المواقع الجغرافية
  • ipykernel — لتشغيل دفاتر Jupyter داخل المشروع
  • jupyturtle — للرسم بالسلحفاة
  • matplotlib — لرسم الرسوم البيانية
  • pandas — للتعامل مع الجداول والبيانات

في مشروعنا، أسماء هذه الحزم مسجَّلة في ملف اسمه pyproject.toml (قائمة بما يعتمد عليه المشروع).

أمران للتثبيت: متى نستخدم أيّهما؟

تخيّل أنّ التثبيت له طريقتان:

  1. uv add — هذه الطريقة «الرسمية» على جهازك داخل مشروع uv. تُثبّت الحزمة وتكتب اسمها في قائمة المشروع (pyproject.toml)، حتى تتذكر أنت (وuv) أن المشروع يحتاجها لاحقًا.
  2. uv pip install — تُثبّت الحزمة في البيئة الحالية فقط، بدون تعديل ملفات المشروع. مناسبة لأماكن مؤقتة مثل Google Colab، حيث لا ندير مشروع uv كاملًا كما نفعل محليًا.

علامة التعجب

في خلية الشيفرة داخل Jupyter أو Colab، النظام يفترض أنّ ما تكتبه بايثون. لكن أمر التثبيت ليس بايثونًا؛ هو أمر لشاشة الأوامر (مثل ما تكتبه في الـ Terminal).

لذلك نضع علامة تعجب ! في أول السطر، فنقول للنظام: «نفّذ هذا كأمر شاشة أوامر، لا كبايثون»:

! uv pip install geopy

لو نسيتَ !، سيحاول Jupyter قراءة السطر كبايثون فيفشل.

الطريقة 1: على جهازك (شاشة الأوامر)

افتح شاشة الأوامر وأنت داخل مجلد المشروع، ثم اكتب:

uv add geopy ipykernel jupyturtle matplotlib pandas

الطريقة 2: على Colab (خلية شيفرة)

في خلية داخل الدفتر على Colab، اكتب الأمر التالي (لاحظ ! في البداية):

! uv pip install geopy ipykernel jupyturtle matplotlib pandas