دليل Pyright: حالات التثبيت والتكوين والاستخدام

هل سبق لك أن أردت التحقق بشكل أسرع من نوع Python دون إبطاء سير عملك؟ يمكن لأدوات مثل MyPy اكتشاف أخطاء الكتابة، لكنها غالبًا ما تبدو بطيئة أو منفصلة عن تجربة المحرر. هذا هو المكان الذي يأتي فيه Pyright. Pyright هو مدقق نوع ثابت قائم على المعايير لـ Python مصمم للسرعة والتعليقات السريعة. يتم تشغيله كأداة سطر أوامر وكخادم لغة، مما يتيح التشخيص في الوقت الفعلي أثناء كتابة التعليمات البرمجية. فهو يتكامل بشكل وثيق مع أدوات Python من Microsoft ويعمل عبر المحررين من خلال بروتوكول خادم اللغة (LSP).

ما هو بيرايت؟

يستخدم Pyright نظام تكوين قائم على المشروع يحدد الملفات التي يتم تحليلها وكيفية حل الواردات. كما يسمح للفرق بتحديد إصدار Python المستهدف والتحكم في مستوى صرامة التحقق من النوع. تسهل هذه المرونة البدء بعمليات الفحص الأساسية وإدخال قواعد أكثر صرامة تدريجيًا مع نضوج قاعدة التعليمات البرمجية. يتكامل Pyright بشكل جيد مع سير عمل CI ويتوسع بشكل فعال في المشاريع الكبيرة، مما يمكّن الفرق من اعتماد الكتابة الثابتة دون تعطيل ممارسات التطوير الحالية.

إذا كنت تريد معرفة أساسيات Python لبناء وكلاء الذكاء الاصطناعي، فاطلع على الدورة التدريبية المجانية الخاصة بنا حول ABC للبرمجة لوكلاء البناء.

الغرض والميزات الأساسية

يساعد Pyright المطورين على اكتشاف أخطاء الكتابة مبكرًا في كود Python. نظرًا لأن كتابة Python تظل اختيارية في وقت التشغيل، فإن التحليل الثابت يساعد في تحديد المشكلات قبل التنفيذ، مثل أنواع الوسيطات غير الصحيحة وغير الآمنة None الوصول والتعيينات غير صالحة. يتبع Pyright معايير الكتابة الخاصة بـ Python ويقدم تعليقات سريعة حتى في قواعد التعليمات البرمجية الكبيرة.

يقوم Pyright بتحليل التعليمات البرمجية باستخدام محرك على مستوى المشروع يقوم بتوزيع الملفات وربطها والتحقق من نوعها بموجب قواعد قابلة للتكوين. كما أنه يتكامل مع المحررين من خلال خادم اللغة، مما يتيح التشخيص في الوقت الحقيقي أثناء التطوير.

تشمل الميزات الأساسية ما يلي:

• التحليل على مستوى المشروع: يتم تحليل الملفات وربطها وفحص نوعها عبر المشروع.
• الكتابة الحساسة للتدفق: يتم تضييق الأنواع بناءً على تدفق التحكم.
• دعم خادم اللغة: يوفر التشخيص في الوقت الحقيقي في المحررين.
• اكتب فحوصات الاكتمال: يساعد في التحقق من صحة معلومات النوع للمكتبات.
• إمكانية النقل عبر المحرر: تم تنفيذه في TypeScript لدعم الأدوات المتسقة.

اقرأ أيضًا: برنامج تعليمي كامل لبايثون لتعلم علوم البيانات من الصفر

تثبيت بيرايت

Pyright متاح كأداة لسطر الأوامر وكخادم لغة. يتم استخدام CLI لفحوصات CI والفحوصات المحلية. يتم استخدام خادم اللغة من قبل المحررين من خلال بروتوكول خادم اللغة. كلاهما يستخدم نفس المحرك الأساسي.

طريقة التثبيت الأكثر شيوعًا هي من خلال npm. يبدو الإعداد النموذجي كما يلي:

npm install -g pyright 
pyright --version

يمكنك بعد ذلك تشغيل عمليات التحقق من النوع باستخدام:

{
  "include": ("."),
  "exclude": ("**/__pycache__", "**/.venv", "**/.git"),
  "typeCheckingMode": "basic",
  "pythonVersion": "3.12"
}

لبدء خادم اللغة مباشرة، استخدم:

pyright-langserver --stdio 

تتوفر أيضًا أغلفة مجتمع Python. يقوم هؤلاء بتثبيت Node وحزمة Pyright npm تلقائيًا. إنهم لا يغيرون المدقق نفسه.

في كود الاستوديو المرئي، يستخدمها المطورون بشكل شائع البيريت خلال بيلانس، الذي يدير Pyright تحت غطاء محرك السيارة. يمكنك التحكم في سلوك التحقق من النوع من خلال إعدادات مساحة العمل مثل python.analysis.typeCheckingMode و python.analysis.diagnosticMode. إذا كنت تفضل تشغيل Pyright مباشرة، فيمكنك تثبيت البرنامج المنفصل تمديد بيرايت.

في الجددعادةً ما يقوم المطورون بتشغيل Pyright من خلال خادم اللغة. تستخدم العديد من الاجهزة nvim-lspconfig لتكوينه. يبدأ Neovim الخادم بـ pyright-langserver، ويمكنك تحديد إعدادات التحليل ضمن settings.python.analysis للسيطرة على الصرامة ونطاق مساحة العمل.

عملاء LSP الآخرين

يعمل Pyright عبر العديد من المحررين لأنه يعمل كخادم لغة. أي محرر يدعم بروتوكول خادم اللغة (LSP) يمكن أن تبدأ pyright-langserver. يقرأ الخادم التكوين من pyrightconfig.json أو tool.pyright القسم في pyproject.toml، مما يحافظ على اتساق سلوك التحقق من النوع عبر الأدوات المختلفة.

المحررين مثل ايماكس و نص سامية الاتصال مباشرة ب pyright-langserver والتعامل مع المهام مثل الكشف عن البيئة وبدء تشغيل الخادم. لا تزال شركة Pyright نفسها تقوم بجميع عمليات فحص النوع والتشخيص.

الخصائص الرئيسية:

• يعمل مع أي محرر متوافق مع LSP
• الاستخدامات pyright-langserver كالخلفية
• مرتبة الشرف ملفات تكوين المشروع
• يوفر التشخيص المتسق عبر المحررين

التكوين باستخدام pyrightconfig.json

يوفر Pyright طريقتين رئيسيتين لتحديد تكوين المشروع. يمكنك وضع أ pyrightconfig.json ملف في جذر المشروع أو تحديد ملف tool.pyright القسم داخل pyproject.toml. إذا كان كلاهما موجودا، pyrightconfig.json يأخذ الأولوية.

يركز التكوين على بعض الجوانب الأساسية لكيفية تحليل بيرايت للمشروع.

ملفات للتحليل

• تسيطر عليها include, exclude، و ignore
• الملفات المدرجة في exclude لا يزال من الممكن تحليلها إذا تم استيرادها
• الملفات المدرجة في ignore قمع التشخيص

بيئة بايثون

• تم تعريفه بواسطة pythonVersion و pythonPlatform
• executionEnvironments يسمح بأهداف متعددة
• يمكن استخدام دقة الاستيراد extraPaths و venv إعدادات

صرامة التحقق من النوع

• typeCheckingMode يحدد مستوى خط الأساس
• يمكن تمكين القواعد الصارمة لملفات أو مجلدات معينة

تكوين التشخيص

• يمكن تخصيص قواعد التقارير الفردية
• يمكن أن تكون مستويات الخطورة none, info, warning، أو error

أمثلة لأنواع المشاريع الشائعة

توضح الأمثلة التالية إعدادات Pyright الشائعة. إنهم عنيدون ولكن عمليون. يستخدم كل واحد خيارات موثقة. الهدف هو تحقيق التوازن بين الإشارة والأداء وسرعة الاعتماد.

برنامج نصي من ملف واحد أو ريبو بنمط دفتر الملاحظات

هذا الإعداد يفضل ردود الفعل السريعة. يتجنب الصرامة في وقت مبكر. إنه يعمل بشكل جيد للتجارب والأدوات الصغيرة.

• تشمل واسعة النطاق للقبض على القضايا الواضحة
• الفحص الأساسي للاحتكاك المنخفض
• نسخة بايثون صريحة

حزمة الريبو مع src/ التخطيط والاختبارات

يعمل هذا الإعداد على استقرار الواردات. إنه يعكس كيفية تنفيذ الحزمة فعليًا. ومن الشائع للمكتبات والخدمات.

• متفرق src و tests الدلائل
• استخدم مستوى فحص النوع القياسي
• تكوين executionEnvironments لحل مسارات الاستيراد بشكل صحيح

{
  "include": ("src", "tests"),
  "exclude": ("**/__pycache__", "**/.venv", ".tox", "dist", "build"),
  "typeCheckingMode": "standard",
  "pythonVersion": "3.12",
  "executionEnvironments": (
    {
      "root": "src",
      "extraPaths": ("src")
    }
  )
}

هذا الإعداد يدعم الحجم. إنها مركزية القواعد. يسمح بالاعتماد التدريجي الصارم لكل حزمة.

• التكوين الأساسي المشترك
• تجاوزات لكل حزمة
• فحص صارم فقط للكود الجديد

التكوين الجذر:

{
  "exclude": ("**/__pycache__", "**/.venv", "**/.git", "**/node_modules"),
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard",
  "reportMissingImports": "error",
  "reportMissingTypeStubs": "none"
}

تكوين الحزمة:

{
  "extends": "../../pyrightconfig.base.json",
  "include": ("src", "tests"),
  "strict": ("src/new_code"),
  "executionEnvironments": (
    { "root": "src", "extraPaths": ("src") }
  )
}

تطبيق جانغو

هذا الإعداد يقلل من الضوضاء. إنه يتجنب الملفات التي تم إنشاؤها. إنه يبقي الأنواع المفقودة مرئية ولكن لا يتم حظرها.

• استبعاد عمليات الترحيل والملفات الثابتة
• تحذير على بذرة مفقودة
• دليل كعب الروتين المخصص

{
  "include": ("."),
  "exclude": (
    "**/__pycache__",
    "**/.venv",
    "**/migrations/**",
    "static",
    "media"
  ),
  "typeCheckingMode": "standard",
  "reportMissingTypeStubs": "warning",
  "stubPath": "typings"
}

خدمة FastAPI

يؤدي هذا الإعداد إلى الكتابة الصارمة. إنه يسلط الضوء على العناصر المجهولة دون كسر البنيات.

• فحص قياسي
• تحذير على أنواع غير معروفة
• مناسب جيدًا للأطر الديناميكية

{
  "include": ("app", "tests"),
  "exclude": ("**/__pycache__", "**/.venv"),
  "typeCheckingMode": "standard",
  "reportUnknownParameterType": "warning",
  "reportUnknownVariableType": "warning"
}

هذه الأنماط هي نقاط البداية. من المفترض أن تتطور. يعمل Pyright بشكل أفضل عندما تزداد الصرامة تدريجيًا.

متى تختار بيرايت؟

اقرأ أيضًا: أساسيات برمجة بايثون للمبتدئين

خاتمة

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