تجهيز VS Code لتطوير Python: البيئة والمفسر والفحص والاختبارات والمصحح

تجهيز VS Code لتطوير Python: البيئة والمفسر والفحص والاختبارات والمصحح

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

نمر بالإضافات والبيئة، واختيار المفسر، والفحص بـ Ruff، وفحص الأنواع بـ Pyright، والاختبارات بـ pytest، ثم المصحح وملف launch.json.

الإضافات والبيئة

code --install-extension ms-python.python          # documented: Python, Pylance, Debugger
code --install-extension charliermarsh.ruff         # documented: lint + format
python3 -m venv .venv                               # real 2.242 s
.venv/bin/pip install ruff pytest debugpy pyright   # real 11.132 s, venv 100 MB
# ruff 0.17.5   pytest 9.2.0   debugpy 1.8.22   pyright 1.1.414
الإضافات والبيئة
الإضافات والبيئة

إضافة Python الرسمية تثبت معها Pylance للإكمال وفحص الأنواع، ومصحح Python. وإضافة Ruff تفحص وتنسق. وكل أداة منها لها نسخة سطر أوامر ثبتناها في بيئة المشروع، لأن ما يعمل في الطرفية هو ما يجب أن يعمل في خط CI، فلا يختلف حكم المحرر عن حكم الخادم. وإنشاء البيئة أخذ 2.2 ثانية، وتثبيت الأدوات الأربع 11 ثانية بحجم 100 ميغابايت. وتجهيز البيئات لمشاريع البيانات بتفصيل أكبر في تجهيز بيئة Python لعلوم البيانات.

اختيار المفسر

.vscode/settings.json   (documented, not run: no GUI in the lab)
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.testing.pytestEnabled": true,
  "[python]": { "editor.defaultFormatter": "charliermarsh.ruff", "editor.formatOnSave": true }
}
Command Palette -> "Python: Select Interpreter" -> ./.venv/bin/python

أكثر مشكلة يقع فيها المبتدئ أن يثبت مكتبة في بيئة ويختار المحرر مفسراً آخر، فيظهر خط أحمر تحت import مع أن المكتبة مثبتة. ويكتشف VS Code مجلد .venv في جذر المشروع تلقائياً، والأوضح تثبيته في settings.json داخل المشروع، فيعمل لكل من يفتح المجلد. والمفسر المختار يظهر في شريط الحالة أسفل النافذة، وانظر إليه أول ما تفتح مشروعاً. وعلى ويندوز يصبح المسار .venv\Scripts\python.exe.

الفحص بـ Ruff

$ ruff check src            (default rules)                     real 0.011 s
src/cart.py:1:1:  I001  Import block is un-sorted or un-formatted
src/cart.py:1:8:  F401  `os` imported but unused
src/cart.py:1:12: F401  `sys` imported but unused
src/cart.py:2:1:  UP035 `typing.List` is deprecated, use `list` instead
src/cart.py:4:19: UP006 Use `list` instead of `List` for type annotation
src/cart.py:8:5:  F841  Local variable `unused` is assigned to but never used
Found 6 errors.  [*] 4 fixable with `--fix`
with --select E,F,UP,I,B: 8 errors (adds E401 multiple imports, E711 "== None")
الفحص بأداة Ruff
الفحص بأداة Ruff

كتبنا ملفاً من 14 سطراً فيه أخطاء شائعة: استيرادات غير مستخدمة، ومتغير لا يُقرأ، ومقارنة بـ None بعلامة المساواة، وجمع نص مع رقم. وRuff وجد ستة بالقواعد الافتراضية في 11 مللي ثانية، وثمانية حين وسعنا القواعد، وأربعة منها يصلحها تلقائياً. وهذه السرعة سبب أنه يعمل مع كل ضغطة حفظ دون أن تشعر به. لكن لاحظ أنه لم يرَ الخطأ الأخطر في الملف، جمع النص مع الرقم، لأن ذلك يحتاج معرفة الأنواع.

فحص الأنواع بـ Pyright

def label(n: int) -> str:
    ...
    return "items: " + n
$ pyright src                                                    real 1.479 s
src/cart.py:14:12 - error: Operator "+" not supported for types "Literal['items: ']" and "int"
1 error, 0 warnings, 0 informations

Pyright هو المحرك الذي تقوم عليه Pylance داخل VS Code، ويقرأ تلميحات الأنواع في الكود. ووجد الخطأ الذي فات Ruff: الدالة تقول إن n عدد صحيح، ثم تجمعه مع نص، وهذا سيفشل عند التشغيل. أخذ 1.5 ثانية لأنه يحلل الأنواع في الملف كله، وفي المحرر يعمل على الملف المفتوح فيظهر الخط الأحمر فوراً. ولهذا تحتاج الأداتين معاً: Ruff للأسلوب والأخطاء السطحية، وPyright للأنواع. ويمكن رفع صرامة الفحص إلى strict في الإعدادات.

الاختبارات بـ pytest

$ pytest --collect-only -q          3 tests collected in 0.01s
$ pytest -q                                                       real 0.201 s
>       assert label(3) == "items: 3"
E       TypeError: can only concatenate str (not "int") to str
FAILED tests/test_cart.py::test_label - TypeError: can only concatenate str ...
1 failed, 2 passed in 0.01s
الاختبارات بأداة pytest
الاختبارات بأداة pytest

لوحة الاختبارات في VS Code تشغل pytest --collect-only لتعرض قائمة الاختبارات، ثم pytest لتشغيلها وتلوين كل اختبار بالأخضر أو الأحمر. ووجد pytest ثلاثة اختبارات، ونجح اثنان وفشل الثالث بالخطأ نفسه الذي توقعه Pyright قبل التشغيل. وهذا ترتيب مفيد للتفكير: الفحص الثابت يلتقط الخطأ وأنت تكتب، والاختبار يؤكده بالتشغيل. وكل ذلك في أقل من ربع ثانية لهذا المشروع.

المصحح وملف launch.json

.vscode/launch.json  {"type": "debugpy", "request": "launch", "program": "${file}", "justMyCode": true}
what F5 does, reproduced with a 36-line DAP client:
$ python -m debugpy --listen 127.0.0.1:9660 --wait-for-client src/debug_me.py
breakpoint verified: True
stopped: reason=breakpoint after 0.226 s
frame: total line 9 cart.py   <- frame: <module> line 3 debug_me.py
  discount = 0.1   p = 3.25   prices = [10, 20.5, 3.25]   s = 33.75   unused = 3
warning: frozen modules may make the debugger miss breakpoints -> -Xfrozen_modules=off
المصحح وبروتوكول DAP
المصحح وبروتوكول DAP

حين تضغط F5 يشغل VS Code برنامجك تحت debugpy، ثم يكلمه ببروتوكول Debug Adapter Protocol، وهو رسائل JSON بسيطة: ضع نقطة توقف في السطر 9، ابدأ، أخبرني حين تتوقف، أعطني المتغيرات. وكتبنا عميلاً صغيراً يرسل هذه الرسائل نفسها، فتوقف البرنامج عند نقطة التوقف بعد 0.23 ثانية، وقرأنا المتغيرات المحلية في تلك اللحظة: مجموع جزئي 33.75 لثلاثة أسعار. وهذا ما تراه في لوحة المتغيرات. ونبهنا debugpy إلى أن الوحدات المجمدة في Python الحديثة قد تفوت نقاط توقف، والحل خيار -Xfrozen_modules=off. وكيف ينفذ Python الكود أصلاً في ما هي لغة Python.

أخطاء شائعة

مفسر المحرر غير مفسر المشروع

انظر إلى شريط الحالة، وثبته في settings.json.

الاكتفاء بأداة فحص واحدة

Ruff لم يرَ خطأ الأنواع الذي وجده Pyright.

أدوات في المحرر لا في المشروع

ثبتها في البيئة ليحكم CI بالحكم نفسه.

تجاهل تحذير المصحح

نقاط توقف تُفوت بلا سبب ظاهر.

أسئلة يطرحها الناس

هل أستخدم PyCharm بدل VS Code؟

PyCharm يجمع الأدوات في برنامج واحد، وVS Code أخف ويعتمد على الإضافات، والأدوات خلفهما متشابهة.

هل أحتاج Black مع Ruff؟

لا، ruff format يؤدي العمل نفسه بقواعد متوافقة معه.

الخلاصة

خلف VS Code أربع أدوات شغلناها في المختبر: Ruff وجد ستة أخطاء في 11 مللي ثانية، وPyright وجد خطأ الأنواع الذي فاته في 1.5 ثانية، وpytest جمع ثلاثة اختبارات وفشل منها واحد بالخطأ نفسه في 0.2 ثانية، وdebugpy توقف عند نقطة التوقف بعد 0.23 ثانية وأعطى المتغيرات عبر البروتوكول نفسه الذي يستخدمه المحرر. والمحرر نفسه لم يُشغل لغياب الواجهة الرسومية.