Importante

La traducción es un esfuerzo comunitario puede unirse. Esta página está actualmente traducida en |progreso de traducción|.

3. Escribiendo código en el PyQGIS Cookbook

Si está planeando agregar o actualizar algunos capítulos de Libro de Recetas para Desarrollador PyQGIS, debe seguir algunas reglas para habilitar la prueba automática de los fragmentos de código.

La verificación es realmente importante porque permite la comprobación automática del código. Los fragmentos de código con errores o el código que utiliza métodos obsoletos fallarán y la notificación le ayudará a solucionar los problemas.

Para verificación, usamos Sphinx doctest extension. Consulte la documentación de la extensión para obtener información más detallada.

3.1. Cómo escribir fragmentos de código comprobables

Escribir fragmentos de código comprobables no es tan diferente del método antiguo. Básicamente, necesitas usar una directiva Sphinx diferente.

3.1.1. Consignas Doctest sphinx

En lugar de incrustar el código en una directiva .. code-block:: python (que resaltaría automáticamente la sintaxis del código), ahora necesita incrustarlo en un .. testcode::. Es decir, en lugar de esto:

.. code-block:: python

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

Ahora utiliza esto:

.. testcode::

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

Después de escribir el código de ejemplo, debe agregar alguna afirmación que evaluará el código y se ejecutará automáticamente.

En el ejemplo anterior, está creando un SRC y con assert crs.isValid() está verificando si es válido. Si el código posee una sintaxis python incorrecta o si crs.isValid()` devuelve False, este fragmento de código fallará durante la verificación.

Para ejecutar con éxito las pruebas en los fragmentos de código, debe importar todas las clases y declarar cualquier variable utilizados en sus fragmentos de código. Puede incluirlos en el mismo fragmento de código (visible en las páginas HTML) o agregarlos a una directiva ..testsetup:: (oculta en las páginas HTML). El ..testsetup:: se debe colocar antes del ..testcode:::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

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

Si el fragmento de código no crea objetos (y, por lo tanto, no puede usar algo así como assert object.isValid()), puede probar el código usando el método print(), luego agregue los resultados esperados dentro de una directiva ..testoutput:: para comparar el resultado esperado:

.. testcode::

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

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

De manera predeterminada, el contenido de .. testoutput:: es mostrado en la salida HTML. Para ocultarlo, use la opción :hide::

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Nota

Si el fragmento de código contiene declaraciones del tipo print, DEBE agregar un testoutput con los resultados esperados; de lo contrario la prueba fallará.

3.1.2. Agrupamiento de pruebas

Por cada documento rst, los fragmentos de código se prueban secuencialmente, lo que significa que puede usar un ..testsetup:: para todos los subsiguientes fragmentos de código y éstos tendrán acceso a las variables declaradas anteriormente en el documento.

Alternativamente, puede usar grupos para desglosar los ejemplos en la misma página en diferentes pruebas.

Agregando el fragmento de código a los grupos sumando uno o más nombres de grupos (separados por comas) en el directorio respectivo:

.. testcode:: crs_crsfromID [, morenames]

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

El doctest elegirá los fragmentos de código de cada grupo y los ejecutará independientemente uno de otro.

Nota

Utilice nombres de grupo que tengan sentido con el contenido relacionado. Use algo similar a <chapter>_<subchapter>, por ejemplo: crs_intro, crs_fromwkt. En caso de fallas, esto ayudará a identificar dónde ocurren las mismas.

Si no declara ningún grupo, el fragmento de código se agregará a un grupo llamado default. Si, por el contrario, usa * como nombre de grupo, el fragmento de código se usará en todos los grupos de prueba, algo que normalmente es útil para usar en la configuración de la prueba:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. Cómo probar fragmentos de código en su máquina local

Nota

Las instrucciones son válidas para el sistema Linux.

Para probar fragmentos de código de Python, necesita una instalación QGIS. Para esto, hay muchas opciones. Usted puede:

• Utilice la instalación QGIS de su sistema con Sphinx desde un entorno virtual de Python:

  make -f venv.mk doctest
  

• Utilice una instalación compilada manualmente de QGIS. Necesitarías:

  1. Crear un argumento personalizado Makefile en la parte superior del archivo venv.mk, por ejemplo, un archivo user.mk con el siguiente contenido:

     # 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. Luego, debes ejecutarlo apuntando a doctest:

     make -f user.mk doctest
     

• Ejecutar doctest desde la imagen docker oficial de QGIS:

  make -f docker.mk doctest
  

  Primero debe instalar Docker porque esto utiliza una imagen de Docker con QGIS en esta.