3. Scrivere codice nel PyQGIS Cookbook

Se hai intenzione di aggiungere o aggiornare alcuni capitoli del Cookbook PyQGIS per gli sviluppatori, allora dovresti seguire alcune regole per permettere il test automatico dei blocchi di codice.

I test sono molto importanti perché permettono il controllo automatico del codice. I blocchi di codice con errori o il codice che usa metodi obsoleti fallirà e la notifica ti aiuterà a risolvere i problemi.

Per i test, usiamo l’estensione «Sphinx doctest» <https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html>`_. Fai riferimento alla documentazione dell’estensione per informazioni più dettagliate.

3.1. Come scrivere parti di codice testabili

Scrivere pezzi di codice testabili non è così diverso dal vecchio metodo. Fondamentalmente, è necessario utilizzare una diversa «direttiva» di Sphinx.

3.1.1. Direttive Doctest sphinx

Invece di nidificare il codice in una frase .. code-block:: python (che evidenzierebbe automaticamente la sintassi del codice), ora devi incorporarlo in un .. testcode::. Cioè, invece di questo:

.. code-block:: python

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

Ora usa questo:

.. testcode::

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

Dopo che hai scritto il codice di esempio, dovresti aggiungere qualche attestazione che valuterà il codice e che verrà eseguita automaticamente.

Nell’esempio di cui sopra, stai creando un SR e con assert crs.isValid() fai un test se è valido. Se il codice ha una sintassi python sbagliata o la crs.isValid() restituisce False, questo frammento di codice fallirà durante il test.

Per eseguire con successo i test sugli snippet, devi importare tutte le classi e dichiarare tutte le variabili usate negli snippet di codice. Puoi includerle nello snippet stesso (visibile nelle pagine HTML) o puoi aggiungerle ad una frase .. testsetup:: (nascosta nelle pagine HTML). La frase .. testsetup:: deve essere messa prima della frase .. testcode:::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

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

Se lo snippet di codice non crea oggetti (e quindi non puoi usare qualcosa come assert object.isValid()), puoi testare il codice usando il metodo print(), quindi aggiungi i risultati attesi all’interno di una direttiva .. testoutput:: per confrontare l’output atteso:

.. testcode::

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

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Per impostazione predefinita, il contenuto di .. testoutput:: viene mostrato nell’output HTML. Per nasconderlo dall’HTML usa l’opzione :hide::

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Nota

Se il frammento di codice contiene delle istruzioni di stampa, DEVI aggiungere un testoutput con gli output previsti; altrimenti il test fallirà.

3.1.2. Raggruppare i test

Per ogni documento rst, gli snippet di codice sono testati in modo sequenziale, il che significa che si può usare un .. testsetup:: per tutti gli snippet di codice successivi e che gli snippet successivi avranno accesso alle variabili dichiarate in quelli precedenti nel documento.

In alternativa, puoi usare i gruppi per suddividere gli esempi sulla stessa pagina in diversi test.

Aggiungi il frammento di codice ai gruppi aggiungendo uno o più nomi di gruppo (separati da virgole) nella rispettiva direttiva:

.. testcode:: crs_crsfromID [, morenames]

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

Il doctest sceglierà ciascun gruppo di snippet e li eseguirà indipendentemente.

Nota

Usa nomi di gruppo che abbiano senso con il contenuto correlato. Usa qualcosa di simile a <chapter>_<subchapter>, per esempio: crs_intro, crs_fromwkt. In caso di errori, questo aiuterà a identificare dove si verificano gli errori.

Se non dichiari alcun gruppo, lo snippet di codice sarà aggiunto a un gruppo chiamato default. Se invece usi * come nome del gruppo, lo snippet sarà usato in tutti i gruppi di test, cosa normalmente utile da usare nella configurazione dei test:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. Come testare pezzi di codice sulla tua macchina locale

Nota

Le istruzioni sono valide per il sistema Linux.

Per testare pezzi di codice Python, hai bisogno di un’installazione QGIS. Per questo, ci sono molte opzioni. Puoi:

  • Utilizzare la tua installazione QGIS di sistema con Sphinx da un ambiente virtuale Python:

    make -f venv.mk doctest

  • Utilizzare un’installazione costruita manualmente di QGIS. Avrai bisogno di:

    1. Creare un’estensione personalizzata Makefile sopra il file venv.mk, per esempio un file user.mk con il seguente contenuto:

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

include venv.mk

      O:

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

include venv.mk

    2. Poi, usatelo per eseguire il test doctest:

      make -f user.mk doctest

  • Esegui il test doctest all’interno dell’immagine originale di QGIS:

    make -f docker.mk doctest

    Devi installare prima Docker perché questo usa un’immagine con QGIS originale al suo interno.