1. Introducción

Este documento pretende ser tanto un tutorial y una guía de referencia. Aunque no enumera todos los casos de uso posibles, debe proporcionar una buena visión general de la funcionalidad principal.

Se otorga permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia de Documentación Libre GNU, Versión 1.3 o cualquier versión posterior publicada por la Free Software Foundation; sin secciones invariantes, sin textos de portada y sin textos de contraportada.

Se incluye una copia de la licencia en la sección Licencia de Documentación Libre de GNU.

Esta licencia también se aplica a todos los fragmentos de código de este documento.

El soporte de Python se introdujo por primera vez en QGIS 0.9. Hay varias maneras de utilizar Python en QGIS Desktop (cubierto en las siguientes secciones):

  • Emita comandos en la consola de Python dentro de QGIS

  • Crear y usar plugins

  • Ejecute automáticamente código Python cuando se inicie QGIS

  • Crear algoritmos de procesamiento

  • Crear funciones para expresiones en QGIS

  • Crear aplicaciones personalizadas basadas en la API de QGIS

Los enlaces de Python también están disponibles para QGIS Server, incluidos los plugins de Python (vea Servidor QGIS y Python) y los enlaces de Python que se pueden usar para incrustar QGIS Server en una aplicación de Python.

Hay una referencia API completa de QGIS C++ que documenta las clases de las librerías de QGIS. The Pythonic QGIS API (pyqgis) es casi idéntica a la API de C++.

Otro buen recurso para aprender a realizar tareas comunes es descargar complementos existentes desde el repositorio de complementos y examine su código.

1.1. Desarrollar scripts en la consola de Python

QGIS provee una consola Python integrada para scripting. Se puede abrir desde el menu: Complementos ► Consola de Python

../../_images/console.png

Figura 1.4 Consola Python de QGIS

La captura de pantalla anterior ilustra cómo obtener la capa seleccionada actualmente en la lista de capas, mostrar su ID y opcionalmente, si se trata de una capa vectorial, mostrar el recuento de entidades. Para la interacción con el entorno QGIS, hay una variable iface que es una instancia de la clase: QgisInterface <qgis.gui.QgisInterface>. Esta interfaz permite el acceso al lienzo del mapa, menús, barras de herramientas y otras partes de la aplicación QGIS.

Para mayor comodidad del usuario, las siguientes instrucciones se ejecutan cuando se inicia la consola (en el futuro será posible establecer más comandos iniciales)

from qgis.core import *
import qgis.utils

Para aquellos que utilizan la consola a menudo, puede ser útil establecer un acceso directo para activar la consola (dentro de Configuración ► Atajos de teclado…)

1.2. Plugins Python

La funcionalidad de QGIS se puede ampliar utilizando complementos. Los complementos se pueden escribir en Python. La principal ventaja sobre los complementos de C++ es la simplicidad de la distribución (sin compilación para cada plataforma) y el desarrollo más fácil.

Muchos complementos que cubren diversas funciones se han escrito desde la introducción del soporte de Python. El instalador de complemento permite a los usuarios buscar, actualizar y eliminar fácilmente complementos Python. Consulte la página Complementos de Python para más información sobre complementos y desarrollo de complementos.

Crear plugins con Python es simple, vea Desarrollando Plugins Python para instrucciones detalladas.

Nota

Los plugins de Python están también disponibles para QGIS Server. Vea Servidor QGIS y Python para más detalles.

1.2.1. Complementos de procesamiento

Los complementos de procesamiento se pueden utilizar para procesar datos. Son más fáciles de desarrollar, más específicos y más livianos que los complementos de Python. Escribir nuevos complementos de procesamiento explica cuándo es adecuado el uso de algoritmos de Processing y cómo desarrollarlos.

1.3. Ejecutar código Python cuando QGIS se inicia.

Existen diferentes métodos para ejecutar código Python cada vez que se inicia QGIS.

  1. Crear un script startup.py

  2. Configurar la variable de entorno PYQGIS_STARTUP a un fichero Python existente

  3. Especificación de un script de inicio mediante el parámetro --code init_qgis.py.

1.3.1. El fichero startup.py

Cada vez que se inicia QGIS, se busca en el directorio de Python del usuario y en una lista de rutas del sistema un fichero llamado startup.py. Si ese archivo existe, es ejecutado por el intérprete de Python incrustado.

La ruta en el directorio personal del usuario suele encontrarse en:

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

Las rutas predeterminada del sistema dependen del sistema operativo. Para encontrar las rutas que funcionan para usted, abra la consola de Python y ejecute QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) para ver la lista de directorios por defecto.

El script startup.py se ejecuta inmediatamente después de inicializar python en QGIS, al inicio de la aplicación.

1.3.2. La variable de entorno PYQGIS_STARTUP

Al configurar la variable de entorno PYQGIS_STARTUP con la ruta de un fichero Python existente, puede ejecutar código Python justo antes de que la inicialización de QGIS se haya completado.

Este código se ejecutará antes de que se complete la inicialización de QGIS. Este método es muy útil para la limpieza de sys.path, que puede tener rutas no deseables, o para aislar/cargar el entorno inicial sin necesidad de un entorno virtual, por ejemplo, homebrew o MacPorts se instala en Mac.

1.3.3. El parámetro --code

Puede proporcionar código personalizado para ejecutar como parámetro de inicio a QGIS. Para ello, cree un archivo python, por ejemplo qgis_init.py, para ejecutar e iniciar QGIS desde la línea de comandos usando qgis --code qgis_init.py.

El código proporcionado a través de --code se ejecuta al final de la fase de inicialización de QGIS, después de que se hayan cargado los componentes de la aplicación.

1.3.4. Argumentos adicionales para Python

Para proporcionar argumentos adicionales para tu script --code o para otro código python que se ejecute, puedes usar el argumento --py-args. Cualquier argumento que venga después de --py-args y antes de -- arg (si está presente) será pasado a Python pero ignorado por la propia aplicación QGIS.

En el siguiente ejemplo, myfile.tif estará disponible a través de sys.argv en Python pero no será cargado por QGIS. Mientras que otherfile.tif será cargado por QGIS pero no está presente en sys.argv.

qgis --code qgis_init.py --py-args myfile.tif -- otherfile.tif

Si quiere acceder a todos los parámetros de la línea de comandos desde Python, puedes utilizar QCoreApplication.arguments().

QgsApplication.instance().arguments()

1.4. Aplicaciones Python

A menudo es útil crear scripts para automatizar procesos. Con PyQGIS, esto es perfectamente posible — importe el módulo qgis.core, Inicialícelo y estará listo para el procesamiento.

O tal vez desee crear una aplicación interactiva que utilice la funcionalidad GIS — realizar mediciones, exportar un mapa como PDF, … El módulo qgis.gui proporciona varios componentes GUI, en particular el widget de lienzo del mapa que se puede incorporar a la aplicación con soporte para hacer zoom, paneo y/o cualquier otra herramienta de mapa personalizada.

Las aplicaciones personalizadas de PyQGIS o los scripts independientes deben configurarse para localizar los recursos QGIS, como la información de proyección y los proveedores para leer capas vectoriales y ráster. Los recursos de QGIS se inician añadiendo unas pocas líneas al principio de su aplicación o script. El código para inicializar QGIS para aplicaciones personalizadas y scripts independientes es similar. A continuación se proporcionan ejemplos de cada uno de ellos.

Nota

No utilice qgis.py como nombre para su script. Python no podrá importar los enlaces, ya que el nombre del script será su sombra.

1.4.1. Usando PyQGIS en scripts individuales

Para iniciar un script independiente, inicialice los recursos QGIS al principio del script:

 1from qgis.core import *
 2
 3# Supply path to qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.  Setting the
 7# second argument to False disables the GUI.
 8qgs = QgsApplication([], False)
 9
10# Load providers
11qgs.initQgis()
12
13# Write your code here to load some layers, use processing
14# algorithms, etc.
15
16# Finally, exitQgis() is called to remove the
17# provider and layer registries from memory
18qgs.exitQgis()

Primero importa el módulo qgis.core y configura el prefijo de ruta. El prefijo de ruta es la ubicación donde está instalado QGIS en su sistema. Se configura en el script llamando al método setPrefixPath(). El segundo argumento de setPrefixPath() es establecido a True, especificando que se utilizarán las rutas predeterminadas.

La ruta de instalación de QGIS varía según la plataforma; la forma más fácil de encontrarlo para su sistema es usar Desarrollar scripts en la consola de Python desde dentro de QGIS y ver el resultado de ejecutar:

QgsApplication.prefixPath()

Una vez configurada la ruta del prefijo, guardamos una referencia a QgsApplication en la variable qgs. El segundo argumento está establecido como False, especificando que no planeamos usar la GUI ya que estamos escribiendo un script independiente. Con QgsApplication configurado, cargamos los proveedores de datos de QGIS y el registro de capas llamando al método initQgis().

qgs.initQgis()

Con QGIS inicializado, estamos listos para escribir el resto del script. Finalmente, terminamos llamando a exitQgis() para eliminar los proveedores de datos y el registro de capas de la memoria.

qgs.exitQgis()

1.4.2. Usando PyQGIS en aplicaciones personalizadas

La única diferencia entre Usando PyQGIS en scripts individuales y una aplicación PyQGIS personalizada es el segundo argumento al crear una instancia del QgsApplication. Pase True en lugar de False para indicar que planeamos utilizar una IGU.

 1from qgis.core import *
 2
 3# Supply the path to the qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.
 7# Setting the second argument to True enables the GUI.  We need
 8# this since this is a custom application.
 9
10qgs = QgsApplication([], True)
11
12# load providers
13qgs.initQgis()
14
15# Write your code here to load some layers, use processing
16# algorithms, etc.
17
18# Finally, exitQgis() is called to remove the
19# provider and layer registries from memory
20qgs.exitQgis()

Ahora puede trabajar con la API de QGIS - carga de capas y realizar algún procesamiento o encender una GUI con un lienzo de mapa. Las posibilidades son infinitas :-)

1.4.3. Ejecutar aplicaciones personalizadas

Necesita indicar a su sistema dónde buscar las bibliotecas QGIS y módulos de Python apropiados si no están en una ubicación conocida - de lo contrario Python se quejará:

>>> import qgis.core
ImportError: No module named qgis.core

Esto se puede solucionar estableciendo la variable de entorno PYTHONPATH . En los siguientes comandos, <qgispath> deberá ser reemplazado con su ruta de instalación de QGIS actual:

  • en Linux: export PYTHONPATH=/<qgispath>/share/qgis/python

  • en Windows: set PYTHONPATH=c:\<qgispath>\python

  • en macOS: export PYTHONPATH=/<qgispath>/Contents/Resources/python

Ahora, se conoce la ruta de acceso a los módulos PyQGIS, pero dependen de las bibliotecas qgis_core y qgis_gui (los módulos de Python solo sirven como contenedores). La ruta de acceso a estas bibliotecas puede ser desconocida para el sistema operativo, y luego obtendrá un error de importación de nuevo (el mensaje puede variar dependiendo del sistema):

>>> import qgis.core
ImportError: libqgis_core.so.3.2.0: cannot open shared object file:
  No such file or directory

Para solucionar, agregar los directorios donde residen las bibliotecas QGIS a la ruta de búsqueda del enlazador dinámico:

  • en Linux: export LD_LIBRARY_PATH=/<qgispath>/lib

  • en Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% donde <qgisrelease> debe ser reemplazado por el tipo de enlace apuntado (por ejemplo: qgis-ltr, qgis, qgis-dev)

Estos comandos se pueden poner en un script de arranque que se encargará del inicio. Al implementar aplicaciones personalizadas con PyQGIS, normalmente hay dos posibilidades:

  • requiere que el usuario instale QGIS antes de instalar la aplicación. El instalador de la aplicación debe buscar ubicaciones predeterminadas de las bibliotecas QGIS y permitir al usuario establecer la ruta si no se encuentra. Este enfoque tiene la ventaja de ser más sencillo, sin embargo, requiere que el usuario haga más pasos.

  • paquete QGIS junto con su aplicación. Lanzar la aplicación puede ser más difícil y el paquete será más grande, pero el usuario se salvará de la carga de descargar e instalar piezas adicionales de software.

Los dos modelos de implementación pueden ser mixtos. Puede proporcionar aplicaciones independientes en Windows y macOS, pero para Linux dejar la instalación de SIG en manos del usuario y su administrador de paquetes.

1.5. Notas técnicas sobre PyQt y SIP

Se ha decidido por Python, ya que es uno de los lenguajes más favoritos para el scripting. Los enlaces PyQGIS en QGIS 3 dependen de SIP y PyQt5. La razón para usar SIP en lugar del ampliamente utilizado SWIG es que el código QGIS depende de las bibliotecas Qt. Los enlaces de Python para Qt (PyQt) se realizan utilizando SIP y esto permite la integración perfecta de PyQGIS con PyQt.