Belangrijk

Vertalen is een inspanning van de gemeenschap waaraan u deel kunt nemen <translation_guidelines>. Deze pagina is momenteel voor 100.00% vertaald.

3. Code schrijven voor het PyQGIS kookboek

Als u van plan bent om enkele hoofdstukken aan het PyQGIS Developer Cookbook toe te voegen of bij te werken, dan zou u enkele regels moeten volgen om het automatisch testen van de codesnippers in te schakelen.

Testen is bijzonder belangrijk omdat het het automatisch controleren van de code mogelijk maakt. Codesnippers met fouten of code die gedateerde methoden gebruikt zal mislukken en de notificatie zal u helpen bij het repareren van de problemen.

Voor het testen gebruiken we de ` extensie Sphinx doctest <https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html>`_. Bekijk de documentatie van de extensie voor meer gedetailleerde informatie.

3.1. Hoe te testen codesnippers te schrijven

Het schrijven van te testen codesnippers verschilt niet veel van de oude methode. In de basis dient u een andere Sphinx directive te gebruiken.

3.1.1. Doctest Sphinx directives

In plaats van de code in te bedden in een .. code-block:: python directive (wat automatisch de syntaxis van de code zou accentueren), dient u het nu in te bedden in een .. testcode::. Dat is, in plaats van dit:

.. code-block:: python

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

Gebruikt u nu dit:

.. testcode::

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

Nadat u de voorbeeldcode hebt geschreven, zou u enkele assertion moeten toevoegen die de code zal evalueren en die automatisch zal worden uitgevoerd.

In het bovenstaande voorbeeld maakt u een CRS en met assert crs.isValid() test u of die geldig is. Als de code een verkeerde syntaxis voor Python heeft of de crs.isValid() geeft False terug, zal deze codesnipper mislukken bij het testen.

U moet alle klassen importeren en in de codesnippers gebruikte variabelen declareren om de testen op snippers met succes uit te kunnen voeren. U kunt deze opnemen in de codesnipper zelf (zichtbaar in de HTML-pagina’s) of u kunt ze toevoegen aan een directive .. testsetup:: (verborgen in de HTML-pagina’s). De .. testsetup:: dient te worden geplaatst vóór de .. testcode:::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

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

Als de codesnipper geen objecten maakt (en u daarom niet iets kunt gebruiken als assert object.isValid()), kunt u de code testen met behulp van de methode print(), en de verwachte resultaten toevoegen in een directive .. testoutput:: om de verwachte uitvoer te vergelijken:

.. testcode::

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

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Standaard wordt de inhoud van .. testoutput:: weergegeven in de uitvoer HTML. Gebruik de optie :hide: om het voor de HTML te verbergen:

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Notitie

Als de codesnipper argumenten voor afdrukken bevat, dan MOET u een testoutput met de verwachte uitvoer toevoegen; anders zal de test mislukken.

3.1.2. Testen groeperen

Voor elk rst-document worden de codesnippers in serie getest, wat betekent dat u één .. testsetup:: kunt gebruiken voor alle volgende codesnippers en dat latere snippers toegang zullen hebben tot in eerdere gedeclareerde variabelen in het document.

Als alternatief kunt u groepen gebruiken om de voorbeelden op dezelfde pagina op te delen in verschillende testen.

U voegt de codesnipper aan groepen toe door één of meer groepsnamen (gescheiden door komma’s) in het respectievelijke directive:

.. testcode:: crs_crsfromID [, morenames]

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

De doctest zal elke groepsnipper oppakken en ze onafhankelijk uitvoeren.

Notitie

Gebruik groepsnamen die een betekenis hebben met de daaraan gerelateerde inhoud. Gebruik iets soortgelijks als <chapter>_<subchapter>, bijvoorbeeld: crs_intro, crs_fromwkt. In het geval van mislukken zal dit helpen om te identificeren waar de fouten optreden.

Als u geen groepen declareert, zal de codesnipper worden toegevoegd aan een groep, genaamd default. Als u in plaats daarvan * gebruikt als naam voor een groep, zal de snipper worden gebruikt in alle testgroepen, iets wat normaal gesproken nuttig is om te gebruiken in de instelling voor de test:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. Hoe snippers te testen op uw lokale machine

Notitie

Instructies zijn geldig voor systemen van Linux.

U hebt een installatie van QGIS nodig om codesnippers voor Python te testen. Hiervoor bestaan vele opties. U kunt:

  • Uw systeeminstallatie van QGIS met Sphinx gebruiken vanuit een virtuele omgeving voor Python:

    make -f venv.mk doctest

  • Een handmatig gebouwde installatie van QGIS gebruiken. U dient:

    1. Een aangepaste extensie Makefile te maken, bovenop het bestand venv.mk, bijvoorbeeld een bestand user.mk met de volgende inhoud:

      # Root installation folder
QGIS_PREFIX_PATH = /home/user/apps/qgis-master

include venv.mk

      Of

      # build output folder
QGIS_PREFIX_PATH = /home/user/dev/QGIS-build-master/output

include venv.mk

    2. Gebruik dat dan om het doel doctest uit te voeren:

      make -f user.mk doctest

  • Doel doctest uitvoeren binnen de officiële QGIS docker image:

    make -f docker.mk doctest

    U dient eerst Docker te hebben geïnstalleerd, omdat dat een docker image met QGIS erin gebruikt.