Important

La traduction est le fruit d’un effort communautaire auquel vous pouvez vous joindre. Cette page est actuellement traduite à 100.00%.

3. Écriture de code dans le livre de recettes « PyQGIS Cookbook »

Si vous envisagez d’ajouter ou de mettre à jour certains chapitres du Développement PyQGIS - Livre de recettes, vous devez respecter certaines règles pour activer le test automatique des extraits de code.

Les tests sont vraiment importants car ils permettent un contrôle automatique du code. Les extraits de code avec des erreurs ou un code utilisant des méthodes obsolètes échoueront et la notification vous aidera à résoudre les problèmes.

Pour tester, nous utilisons l’extension Sphinx doctest. Reportez-vous à la documentation de l’extension pour plus d’informations.

3.1. Comment écrire des extraits de code testables

L’écriture d’extraits de code testables n’est pas si différente de l’ancienne méthode. En gros, vous devez utiliser une directive Sphinx différente.

3.1.1. Directives sphinx de Doctest

Au lieu d’intégrer le code dans une directive .. code-block:: python (qui mettrait automatiquement en évidence la syntaxe du code), vous devez maintenant l’intégrer dans un .. testcode::. C’est à la place de ceci

.. code-block:: python

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

Vous utilisez maintenant ceci

.. testcode::

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

Après avoir écrit l’exemple de code, vous devez ajouter une assertion qui évaluera le code et sera exécutée automatiquement.

Dans l’exemple ci-dessus, vous créez un fichier crs et avec assert crs.isValid(), vous testez s’il est valide. Si le code a une mauvaise syntaxe python ou si crs.isValid() renvoie False, cet extrait de code échouera pendant le test.

Pour réussir les tests sur les extraits, vous devez importer toutes les classes et déclarer toutes les variables utilisées dans les extraits de code. Vous pouvez les inclure dans l’extrait de code lui-même (visible dans les pages HTML) ou les ajouter à une directive .. testsetup:: (masquée dans les pages HTML). Le .. testsetup:: doit être placé avant le .. testcode::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

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

Si l’extrait de code ne crée pas d’objets (et que vous ne pouvez donc pas utiliser quelque chose comme assert object.isValid()), vous pouvez tester le code à l’aide de la méthode print(), puis ajouter les résultats attendus dans une directive .. testoutput:: pour comparer la sortie attendue

.. testcode::

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

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Par défaut, le contenu de .. testoutput:: est affiché dans la sortie HTML. Pour le cacher du HTML, utilisez l’option :hide:

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Note

Si l’extrait de code contient des instructions d’impression, vous DEVEZ ajouter un testoutput avec les résultats attendus; sinon le test échouera.

3.1.2. Tests groupés

Pour chaque document « rst », les extraits de code sont testés séquentiellement, ce qui signifie que vous pouvez utiliser un .. testsetup:: pour tous les extraits de code suivants et que les extraits suivants auront accès aux variables déclarées dans les précédents.

Vous pouvez également utiliser des groupes pour décomposer les exemples de la même page dans différents tests.

Vous ajoutez l’extrait de code aux groupes en ajoutant un ou plusieurs noms de groupe (séparés par des virgules) dans la directive respective

.. testcode:: crs_crsfromID [, morenames]

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

doctest va choisir chaque groupe de codes et les exécuter indépendamment.

Note

Utilisez des noms de groupe qui ont un sens avec le contenu associé. Utilisez quelque chose du type <chapter>_<subchapter>, par exemple: crs_intro, crs_fromwkt. En cas d’échec, cela aidera à identifier où les échecs se produisent.

Si vous ne déclarez aucun groupe, l’extrait de code sera ajouté à un groupe nommé default. Si au lieu de cela, vous utilisez * comme nom de groupe, l’extrait de code sera utilisé dans tous les groupes de test, ce qui est normalement utile dans la configuration de test

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. Comment tester des extraits sur votre ordinateur local

Note

Les instructions sont valables pour le système Linux.

Pour tester les extraits de code Python, vous avez besoin d’une installation QGIS. Pour cela, il existe de nombreuses options. Vous pouvez :

  • Utilisez votre installation QGIS avec Sphinx à partir d’un environnement virtuel Python:

    make -f venv.mk doctest

  • Utilisez une installation manuelle de QGIS. Vous aurez besoin de:

    1. Créez une extension Makefile personnalisée en haut du fichier venv.mk, par exemple un fichier user.mk avec le contenu suivant:

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

include venv.mk

      Ou

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

include venv.mk

    2. Ensuite, utilisez-le pour lancer la cible doctest

      make -f user.mk doctest

  • Executez la cible doctest à l’intérieur de l’image officielle du docker QGIS:

    make -f docker.mk doctest

    Vous devez d’abord installer Docker parce que cela utilise une image docker avec QGIS dedans.