3. كتابة الشيفرة في كتاب وصفات PyQGIS

إذا كنت تخطط لإضافة بعض فصول دليل مطوّري PyQGIS (PyQGIS Developer Cookbook) أو تحديثها، فعليك اتباع بعض القواعد لتمكين الاختبار الآلي لمقتطفات الشيفرة.

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

نستخدم في الاختبار امتداد Sphinx doctest. راجع توثيق الامتداد للحصول على معلومات أكثر تفصيلًا.

3.1. كيف تكتب مقتطفات شيفرة قابلة للاختبار

لا تختلف كتابة مقتطفات شيفرة قابلة للاختبار كثيرًا عن الطريقة القديمة. ببساطة، عليك استخدام directive مختلف من Sphinx.

3.1.1. موجّهات Sphinx الخاصة بـ Doctest

بدلًا من تضمين الشيفرة في الموجّه .. code-block:: python (الذي يُبرز صياغة الشيفرة تلقائيًا)، عليك الآن تضمينها في .. testcode::. أي بدلًا من هذا:

.. code-block:: python

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

تستخدم الآن هذا:

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

بعد كتابة الشيفرة المثال، عليك إضافة تأكيد (assertion) يقيّم الشيفرة ويُشغَّل تلقائيًا.

في المثال أعلاه، تنشئ نظام إحداثيات مرجعيًا (crs)، ومن خلال assert crs.isValid() تختبر ما إذا كان صالحًا. إذا كانت صياغة Python في الشيفرة خاطئة أو أعادت crs.isValid() القيمة False، فسيفشل هذا المقتطف أثناء الاختبار.

لتشغيل الاختبارات على المقتطفات بنجاح، يجب أن تستورد جميع الأصناف وتعرّف أي متغيرات مستخدمة في مقتطفات الشيفرة. يمكنك تضمينها في المقتطف نفسه (فتظهر في صفحات HTML) أو إضافتها إلى الموجّه .. testsetup:: (فتُخفى في صفحات HTML). ويجب وضع .. testsetup:: قبل .. testcode:::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

إذا كان المقتطف لا ينشئ كائنات (وبالتالي لا يمكنك استخدام شيء مثل assert object.isValid())، فيمكنك اختبار الشيفرة باستخدام الدالة print()، ثم إضافة النتائج المتوقعة داخل الموجّه .. testoutput:: لمقارنة المخرجات المتوقعة:

.. testcode::

   print("QGIS CRS ID:", crs.srsid())
   print("PostGIS SRID:", crs.postgisSrid())

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

افتراضيًا، يظهر محتوى .. testoutput:: في مخرجات HTML. لإخفائه من HTML استخدم الخيار :hide::

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

ملاحظة

إذا احتوى المقتطف على أي تعليمات طباعة، فيجب عليك إضافة testoutput يتضمن المخرجات المتوقعة؛ وإلا فسيفشل الاختبار.

3.1.2. تجميع الاختبارات

في كل مستند reST، تُختبر مقتطفات الشيفرة بالتتابع، أي يمكنك استخدام .. testsetup:: واحد لجميع المقتطفات التالية، وستتمكن المقتطفات اللاحقة من الوصول إلى المتغيرات المعرّفة في المقتطفات السابقة في المستند.

بدلًا من ذلك، يمكنك استخدام المجموعات لتقسيم الأمثلة في الصفحة نفسها إلى اختبارات مختلفة.

تضيف المقتطف إلى المجموعات بإضافة اسم مجموعة واحد أو أكثر (مفصولة بفواصل) في الموجّه المعني:

.. testcode:: crs_crsfromID [, morenames]

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

سيأخذ doctest مقتطفات كل مجموعة ويشغّلها بشكل مستقل.

ملاحظة

استخدم أسماء مجموعات منطقية ومرتبطة بالمحتوى. استخدم صيغة مشابهة لـ <chapter>_<subchapter>، مثل: crs_intro و crs_fromwkt. فعند حدوث أخطاء، سيساعد ذلك على تحديد موضعها.

إذا لم تعرّف أي مجموعة، فسيُضاف المقتطف إلى مجموعة اسمها default. أما إذا استخدمت * اسمًا للمجموعة، فسيُستخدم المقتطف في جميع مجموعات الاختبار، وهو أمر مفيد عادةً في إعداد الاختبار:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. كيف تختبر المقتطفات على جهازك المحلي

ملاحظة

هذه التعليمات صالحة لنظام Linux.

لاختبار مقتطفات شيفرة Python، تحتاج إلى تثبيت QGIS. ولذلك خيارات عديدة، إذ يمكنك:

• استخدام QGIS المثبّت على نظامك مع Sphinx من بيئة Python افتراضية:

  make -f venv.mk doctest
  

• استخدام نسخة من QGIS بنيتها يدويًا. وستحتاج إلى:

  1. إنشاء امتداد Makefile مخصص فوق الملف venv.mk، مثل ملف user.mk بالمحتوى التالي:

     # Root installation folder
     QGIS_PREFIX_PATH = /home/user/apps/qgis-master
     
     include venv.mk
     

     أو

     # build output folder
     QGIS_PREFIX_PATH = /home/user/dev/QGIS-build-master/output
     
     include venv.mk
     

  2. ثم استخدمه لتشغيل الهدف doctest:

     make -f user.mk doctest
     

• تشغيل الهدف doctest داخل صورة docker الرسمية لـ QGIS:

  make -f docker.mk doctest
  

  عليك تثبيت Docker أولًا لأن هذه الطريقة تستخدم صورة docker تحتوي على QGIS.