16.3. إعدادات بيئة التطوير المتكاملة (IDE) لكتابة الإضافات وتصحيحها

مع أن لكل مبرمج بيئة التطوير المتكاملة أو محرر النصوص المفضّل لديه، إليك بعض التوصيات لإعداد بيئات التطوير المتكاملة الشائعة لكتابة إضافات QGIS المكتوبة بلغة Python وتصحيحها.

16.3.1. إضافات مفيدة لكتابة إضافات Python

بعض الإضافات مريحة عند كتابة إضافات Python. من Plugins ► Manage and Install plugins… ثبّت ما يلي:

• Plugin reloader: تتيح لك إعادة تحميل إضافة وجلب التغييرات الجديدة دون إعادة تشغيل QGIS.

• First Aid: تضيف وحدة تحكم Python ومنقّح أخطاء محليًا لفحص المتغيرات عند إطلاق استثناء من إحدى الإضافات.

تحذير

رغم جهودنا المستمرة، قد لا تكون المعلومات بعد هذا السطر محدّثة لـ QGIS 3.

16.3.2. ملاحظة حول إعداد بيئة التطوير المتكاملة (IDE) على Linux و Windows

على Linux، كل ما يلزم عادةً هو إضافة مواقع مكتبات QGIS إلى متغير البيئة PYTHONPATH الخاص بالمستخدم. في معظم التوزيعات يمكن ذلك بتحرير ~/.bashrc أو ~/.bash-profile وإضافة السطر التالي (جُرّب على OpenSUSE Tumbleweed):

export PYTHONPATH="$PYTHONPATH:/usr/share/qgis/python/plugins:/usr/share/qgis/python"

احفظ الملف وطبّق إعدادات البيئة باستخدام أمر الطرفية التالي:

source ~/.bashrc

على Windows، عليك التأكد من أن لديك إعدادات البيئة نفسها وأنك تستخدم المكتبات والمفسّر نفسيهما اللذين يستخدمهما QGIS. أسرع طريقة لذلك هي تعديل ملف التشغيل الدفعي (batch) الخاص بـ QGIS.

إذا استخدمت مثبّت OSGeo4W، فستجد هذا الملف داخل المجلد bin في مجلد تثبيت OSGeo4W. ابحث عن ملف مثل C:\OSGeo4W\bin\qgis-unstable.bat.

16.3.3. التنقيح باستخدام Pyscripter IDE (Windows)

لاستخدام بيئة Pyscripter IDE، إليك ما عليك فعله:

1. أنشئ نسخة من qgis-unstable.bat وأعد تسميتها إلى pyscripter.bat.

2. افتحها في محرر نصوص، واحذف السطر الأخير، وهو السطر الذي يشغّل QGIS.

3. أضف سطرًا يشير إلى الملف التنفيذي لـ Pyscripter، وأضف وسيط سطر الأوامر الذي يحدد إصدار Python المراد استخدامه

4. أضف أيضًا الوسيط الذي يشير إلى المجلد الذي يجد فيه Pyscripter ملف dll الخاص بـ Python الذي يستخدمه QGIS، وتجده داخل المجلد bin في مجلد تثبيت OSGeoW

   @echo off
   SET OSGEO4W_ROOT=C:\OSGeo4W
   call "%OSGEO4W_ROOT%"\bin\o4w_env.bat
   call "%OSGEO4W_ROOT%"\bin\gdal16.bat
   @echo off
   path %PATH%;%GISBASE%\bin
   Start C:\pyscripter\pyscripter.exe --python25 --pythondllpath=C:\OSGeo4W\bin
   

5. الآن عند النقر المزدوج على هذا الملف الدفعي سيعمل Pyscripter بالمسار الصحيح.

يُعدّ Eclipse أكثر شيوعًا من Pyscripter، وهو خيار شائع بين المطورين. في القسم التالي سنشرح كيفية إعداده لتطوير الإضافات واختبارها.

16.3.4. التنقيح باستخدام Eclipse و PyDev

16.3.4.1. التركيب

لاستخدام Eclipse، تأكد من أنك ثبّتّ ما يلي

• بيئة Eclipse

• إضافة Aptana Studio 3 أو PyDev

• QGIS 3.x

• قد ترغب أيضًا في تثبيت إضافة QGIS المسماة Remote Debug. وهي لا تزال تجريبية حاليًا، لذا فعّل Experimental plugins ضمن Plugins ► Manage and Install plugins... ► Options مسبقًا.

لتهيئة بيئتك لاستخدام Eclipse على Windows، عليك أيضًا إنشاء ملف دفعي واستخدامه لتشغيل Eclipse:

1. حدّد موقع المجلد الذي يوجد فيه qgis_core.dll. عادةً يكون C:\OSGeo4W\apps\qgis\bin، لكن إن كنت قد بنيت تطبيق QGIS بنفسك فهو في مجلد البناء ضمن output/bin/RelWithDebInfo

2. حدّد موقع الملف التنفيذي eclipse.exe.

3. أنشئ السكربت التالي واستخدمه لتشغيل Eclipse عند تطوير إضافات QGIS.

   call "C:\OSGeo4W\bin\o4w_env.bat"
   set PATH=%PATH%;C:\path\to\your\qgis_core.dll\parent\folder
   start /B C:\path\to\your\eclipse.exe
   

16.3.4.2. إعداد Eclipse

1. في Eclipse، أنشئ مشروعًا جديدًا. يمكنك اختيار General Project وربط مصادرك الفعلية لاحقًا، لذا لا يهم كثيرًا أين تضع هذا المشروع.

   

   شكل 16.18 مشروع Eclipse

2. انقر بالزر الأيمن على مشروعك الجديد واختر New ► Folder.

3. انقر Advanced واختر Link to alternate location (Linked Folder). إن كانت لديك مصادر تريد تنقيحها فاخترها، وإن لم تكن لديك فأنشئ مجلدًا كما شُرح سابقًا.

الآن ستظهر شجرة مصادرك في العرض Project Explorer ويمكنك البدء بالعمل على الشيفرة. يتوفر لديك بالفعل تلوين الصياغة وجميع أدوات بيئة التطوير القوية الأخرى.

16.3.4.3. إعداد المنقّح

لتشغيل المنقّح:

1. انتقل إلى منظور Debug في Eclipse (Window ► Open Perspective ► Other ► Debug).

2. شغّل خادم التنقيح الخاص بـ PyDev باختيار PyDev ► Start Debug Server.

3. أصبح Eclipse الآن ينتظر اتصالًا من QGIS بخادم التنقيح الخاص به، وعندما يتصل QGIS بخادم التنقيح سيسمح له بالتحكم في سكربتات Python. ولهذا بالضبط ثبّتنا إضافة Remote Debug. لذا شغّل QGIS إن لم تكن قد شغّلته بعد، وانقر رمز الحشرة.

الآن يمكنك تعيين نقطة توقف، وبمجرد أن تصل الشيفرة إليها سيتوقف التنفيذ ويمكنك فحص الحالة الحالية لإضافتك. (نقطة التوقف هي النقطة الخضراء في الصورة أدناه؛ عيّن واحدة بالنقر المزدوج في المساحة البيضاء على يسار السطر الذي تريد تعيين نقطة التوقف عنده).

شكل 16.19 نقطة توقف

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

1. افتح عرض Console (Window ► Show view). سيعرض وحدة التحكم Debug Server وهي ليست مفيدة كثيرًا. لكن يوجد زر Open Console يتيح لك الانتقال إلى وحدة تحكم أكثر فائدة هي PyDev Debug Console.

2. انقر السهم المجاور للزر Open Console واختر PyDev Console. ستُفتح نافذة تسألك عن وحدة التحكم التي تريد تشغيلها.

3. اختر PyDev Debug Console. إن كان الخيار باهتًا ويطلب منك تشغيل المنقّح واختيار إطار صالح، فتأكد من أن المنقّح البعيد متصل وأنك متوقف حاليًا عند نقطة توقف.

   

   شكل 16.20 وحدة تحكم التنقيح PyDev Debug Console

لديك الآن وحدة تحكم تفاعلية تتيح لك اختبار أي أوامر ضمن السياق الحالي. يمكنك التعامل مع المتغيرات أو إجراء استدعاءات API أو أي شيء تريده.

نصيحة

من الأمور المزعجة قليلًا أن وحدة التحكم تعود إلى Debug Server في كل مرة تُدخل فيها أمرًا. لإيقاف هذا السلوك، يمكنك النقر على الزر Pin Console عندما تكون في صفحة Debug Server، ويُفترض أن يتذكر هذا القرار على الأقل لجلسة التنقيح الحالية.

16.3.4.4. جعل Eclipse يفهم واجهة API

من الميزات المفيدة جدًا أن يعرف Eclipse واجهة QGIS API فعليًا. يتيح له ذلك فحص شيفرتك بحثًا عن الأخطاء الإملائية. وليس هذا فحسب، بل يتيح أيضًا لـ Eclipse مساعدتك بالإكمال التلقائي من عبارات الاستيراد وحتى استدعاءات API.

لتحقيق ذلك، يحلّل Eclipse ملفات مكتبة QGIS ويستخرج كل المعلومات منها. كل ما عليك فعله هو إخبار Eclipse بمكان المكتبات.

1. انقر Window ► Preferences ► PyDev ► Interpreter ► Python.

   سترى مفسّر Python المُعدّ لديك في الجزء العلوي من النافذة (حاليًا python2.7 لـ QGIS) وبعض التبويبات في الجزء السفلي. التبويبان المهمان لنا هما Libraries و Forced Builtins.

   

   شكل 16.21 وحدة تحكم التنقيح PyDev Debug Console

2. افتح أولًا تبويب Libraries.

3. أضف مجلدًا جديدًا (New Folder) واختر مجلد python في تثبيت QGIS لديك. إن لم تكن تعرف مكان هذا المجلد (وهو ليس مجلد الإضافات):

   1. افتح QGIS

   2. شغّل وحدة تحكم Python

   3. أدخل qgis

   4. واضغط Enter. سيعرض لك وحدة QGIS التي يستخدمها ومسارها.

   5. احذف الجزء الأخير /qgis/__init__.pyc من هذا المسار وستحصل على المسار الذي تبحث عنه.

4. عليك أيضًا إضافة مجلد الإضافات هنا (وهو python/plugins داخل مجلد ملف تعريف المستخدم).

5. انتقل بعد ذلك إلى تبويب Forced Builtins، وانقر New... وأدخل qgis. سيجعل هذا Eclipse يحلّل واجهة QGIS API. وغالبًا ستريد أيضًا أن يعرف Eclipse واجهة PyQt API، لذا أضف PyQt أيضًا بوصفها forced builtin. ومن المحتمل أنها موجودة بالفعل في تبويب المكتبات.

6. انقر OK وتكون قد انتهيت.

ملاحظة

في كل مرة تتغير فيها واجهة QGIS API (مثلًا إن كنت تبني فرع master من QGIS وتغيّر ملف SIP)، عليك العودة إلى هذه الصفحة والنقر ببساطة على Apply. سيتيح هذا لـ Eclipse تحليل جميع المكتبات من جديد.

16.3.5. التنقيح باستخدام PyCharm على Ubuntu مع QGIS مبني من المصدر

PyCharm بيئة تطوير متكاملة للغة Python من تطوير JetBrains. يوجد منها إصدار مجاني اسمه Community Edition وإصدار مدفوع اسمه Professional. يمكنك تنزيل PyCharm من الموقع: https://www.jetbrains.com/pycharm/download

نفترض أنك بنيت QGIS على Ubuntu بمجلد البناء ~/dev/qgis/build/master. ليس إلزاميًا أن يكون لديك QGIS مبني ذاتيًا، لكن هذه الحالة وحدها هي التي اختُبرت. يجب تعديل المسارات بما يناسبك.

1. في PyCharm، ضمن Project Properties ثم Project Interpreter، سننشئ بيئة Python افتراضية باسم QGIS.

2. انقر رمز الترس الصغير ثم Add.

3. اختر Virtualenv environment.

4. اختر موقعًا عامًا لجميع مشاريع Python لديك مثل ~/dev/qgis/venv لأننا سنستخدم مفسّر Python هذا لجميع إضافاتنا.

5. اختر مفسّر Python 3 أساسيًا متوفرًا على نظامك وفعّل الخيارين التاليين Inherit global site-packages و Make available to all projects.

1. انقر OK، ثم عد إلى رمز الترس الصغير وانقر Show all.

2. في النافذة الجديدة، اختر مفسّرك الجديد QGIS وانقر الأيقونة الأخيرة في القائمة العمودية Show paths for the selected interpreter.

3. أخيرًا، أضف المسار المطلق التالي إلى القائمة ~/dev/qgis/build/master/output/python.

1. أعد تشغيل PyCharm ويمكنك البدء باستخدام بيئة Python الافتراضية الجديدة هذه لجميع إضافاتك.

سيتعرّف PyCharm على واجهة QGIS API وكذلك على واجهة PyQt API إن استخدمت Qt الذي يوفره QGIS مثل from qgis.PyQt.QtCore import QDir. يُفترض أن يعمل الإكمال التلقائي ويستطيع PyCharm فحص شيفرتك.

في الإصدار الاحترافي من PyCharm يعمل التنقيح البعيد جيدًا. أما في إصدار Community فالتنقيح البعيد غير متاح. يمكنك فقط الوصول إلى منقّح محلي، أي يجب أن تعمل الشيفرة داخل PyCharm (كسكربت أو unittest) لا في QGIS نفسه. أما لشيفرة Python التي تعمل في QGIS فيمكنك استخدام إضافة First Aid المذكورة أعلاه.

16.3.6. التنقيح باستخدام PDB

إن لم تكن تستخدم بيئة تطوير متكاملة مثل Eclipse أو PyCharm، فيمكنك التنقيح باستخدام PDB باتباع الخطوات التالية.

1. أضف أولًا هذه الشيفرة في الموضع الذي تريد التنقيح عنده

   # Use pdb for debugging
   import pdb
   # also import pyqtRemoveInputHook
   from qgis.PyQt.QtCore import pyqtRemoveInputHook
   # These lines allow you to set a breakpoint in the app
   pyqtRemoveInputHook()
   pdb.set_trace()
   

2. ثم شغّل QGIS من سطر الأوامر.

   على Linux نفّذ:

   $ ./Qgis
   

   على macOS نفّذ:

   $ /Applications/Qgis.app/Contents/MacOS/Qgis
   

3. وعندما يصل التطبيق إلى نقطة التوقف يمكنك الكتابة في وحدة التحكم!

مهام قادمة:

إضافة معلومات حول الاختبار