Viktigt

Översättning är en gemenskapsinsats du kan gå med i. Den här sidan är för närvarande översatt till 100.00%.

3. Skriva kod i PyQGIS Cookbook

Om du planerar att lägga till eller uppdatera några kapitel i PyQGIS-utvecklarens kokbok, bör du följa vissa regler för att möjliggöra automatisk testning av kodsnuttarna.

Testning är mycket viktigt eftersom det möjliggör automatisk kontroll av koden. Kodsnuttar med fel eller kod som använder föråldrade metoder kommer att misslyckas och meddelandet hjälper dig att åtgärda problemen.

För testning använder vi tillägget Sphinx doctest extension. Se dokumentationen för tillägget för mer detaljerad information.

3.1. Så här skriver du testbara kodsnuttar

Att skriva testbara kodsnuttar skiljer sig inte så mycket från den gamla metoden. I grund och botten måste du använda ett annat Sphinx-direktiv.

3.1.1. Doctest sfinx direktiv

Istället för att bädda in koden i ett .. code-block:: python-direktiv (vilket skulle markera kodsyntaxen automatiskt), måste du nu bädda in den i en .. testcode::. Det vill säga, istället för detta:

.. code-block:: python

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

Du använder nu detta:

.. testcode::

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

När du har skrivit exempelkoden bör du lägga till någon assertion som utvärderar koden och som körs automatiskt.

I exemplet ovan skapar du en crs och med assert crs.isValid() testar du om den är giltig. Om koden har en felaktig python-syntax eller om crs.isValid() returnerar False, kommer detta kodavsnitt att misslyckas under testningen.

För att kunna köra testerna på kodavsnitten måste du importera alla klasser och deklarera alla variabler som används i kodavsnitten. Du kan inkludera dessa i själva kodavsnittet (synligt på HTML-sidorna) eller lägga till dem i ett ...testsetup::-direktiv (dolt på HTML-sidorna). ... testsetup:: måste placeras före ... testcode:::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

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

Om kodavsnittet inte skapar objekt (och du därför inte kan använda något som assert object.isValid()) kan du testa koden med hjälp av print()-metoden och sedan lägga till de förväntade resultaten i ett .. testoutput::-direktiv för att jämföra den förväntade utmatningen:

.. testcode::

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

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Som standard visas innehållet i .. testoutput:: i HTML-utmatningen. Om du vill dölja det från HTML använder du alternativet :hide::

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Observera

Om kodavsnittet innehåller några utskriftssatser MÅSTE du lägga till en testoutput med de förväntade utdata; annars kommer testet att misslyckas.

3.1.2. Gruppering av tester

För varje första dokument testas kodsnuttarna sekventiellt, vilket innebär att du kan använda en .. testsetup:: för alla följande kodsnuttar och att senare snuttar kommer att ha tillgång till variabler som deklarerats i tidigare i dokumentet.

Alternativt kan du använda grupper för att dela upp exemplen på samma sida i olika tester.

Du lägger till kodsnutten i grupper genom att lägga till ett eller flera gruppnamn (åtskilda med kommatecken) i respektive direktiv:

.. testcode:: crs_crsfromID [, morenames]

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

doctest kommer att välja varje grupp utdrag och köra dem oberoende av varandra.

Observera

Använd gruppnamn som är logiska i förhållande till det relaterade innehållet. Använd något som liknar <chapter>_<subchapter>, till exempel: crs_intro, crs_fromwkt. I händelse av fel hjälper detta till att identifiera var felen inträffar.

Om du inte anger någon grupp kommer kodavsnittet att läggas till i en grupp med namnet default. Om du istället använder * som gruppnamn kommer kodavsnittet att användas i alla testgrupper, något som normalt är användbart i testuppsättningen:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. Så här testar du snippets på din lokala maskin

Observera

Anvisningarna gäller för Linux-system.

För att testa Python-kodsnuttar behöver du en QGIS-installation. För detta finns det många alternativ. Det kan du göra:

  • Använd din system QGIS-installation med Sphinx från en virtuell Python-miljö:

    make -f venv.mk doctest

  • Använd en manuellt byggd installation av QGIS. Du skulle behöva:

    1. Skapa ett eget Makefile-tillägg ovanpå filen venv.mk, till exempel en fil user.mk med följande innehåll:

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

include venv.mk

      Eller

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

include venv.mk

    2. Använd den sedan för att köra målet doctest:

      make -f user.mk doctest

  • Kör målet doctest inuti den officiella QGIS dockeravbildningen:

    make -f docker.mk doctest

    Du måste installera Docker först eftersom det här använder en dockeravbildning med QGIS i den.