Важно

Перевод - это работа сообщества : ссылка:Вы можете присоединиться. Эта страница в настоящее время переводится |прогресс перевода|.

3. Написание кода в поваренной книге PyQGIS

Если вы планируете добавить или обновить некоторые главы PyQGIS- Разработчик- Книга рецептов, то вам следует соблюдать некоторые правила, чтобы обеспечить автоматическое тестирование фрагментов кода.

Тестирование очень важно, потому что оно позволяет автоматически проверять код. Фрагменты кода с ошибками или код, использующий устаревшие методы, не будут работать, и уведомление поможет вам устранить проблемы.

Для тестирования мы используем расширение Sphinx doctest. За более подробной информацией обращайтесь к документации по расширению.

3.1. Как писать тестируемые фрагменты кода

Написание тестируемых фрагментов кода не так уж сильно отличается от старого метода. По сути, вам нужно использовать другую директиву Sphinx.

3.1.1. Директивы Doctest sphinx

Вместо того чтобы вставлять код в директиву . кодовый блок:: python (которая автоматически выделит синтаксис кода), теперь вам нужно вставить его в . тестовый код::. То есть вместо this:

.. code-block:: python

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

Теперь вы используете это:

.. testcode::

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

После того как вы написали код примера, необходимо добавить ассерцию, которая будет оценивать код и выполняться автоматически.

В приведенном выше примере вы создаете 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. Группировка тестов

Для каждого первого документа фрагменты кода тестируются последовательно, что означает, что вы можете использовать один ...testsetup:: для всех последующих фрагментов кода и что последующие фрагменты будут иметь доступ к переменным, объявленным в предыдущих фрагментах документа.

Кроме того, можно использовать группы, чтобы разбить примеры на одной странице на разные тесты.

Вы добавляете фрагмент кода в группы, добавляя одно или несколько имен групп (через запятую) в соответствующей директиве:

.. testcode:: crs_crsfromID [, morenames]

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

Программа doctest выберет каждую группу фрагментов и выполнит их независимо.

Примечание

Используйте названия групп, которые имеют смысл для связанного с ними контента. Используйте что-то похожее на <chapter>_<subchapter>, например: crs_intro, crs_fromwkt. В случае сбоев это поможет определить, где происходят сбои.

Если вы не объявите ни одной группы, фрагмент кода будет добавлен в группу с именем умолчанию. Если вместо этого вы используете * в качестве имени группы, сниппет будет использоваться во всех группах тестирования, что обычно полезно использовать при настройке тестов:

.. 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 внутри официального докер-образа QGIS:

    make -f docker.mk doctest

    Сначала необходимо установить Docker, потому что он использует образ docker с QGIS.