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.

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 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 Complementos de Python de QGIS Server) y los enlaces de Python que se pueden usar para incrustar QGIS Server en una aplicación de Python.

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

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

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

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…)

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 Developing Python Plugins para instrucciones detalladas.

Nota

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

Ejecutar código Python cuando QGIS se inicia.

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

  1. Crear un script startup.py

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

El fichero startup.py

Cada vez que se inicia QGIS, el directorio de inicio de Python del usuario

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

se busca un archivos llamado startup.py. Si ese archivo existe, lo ejecuta el intérprete de Python incorporado.

Nota

La ruta predeterminada depende de cada sistema operativo. Para encontrar la ruta que pueda funcionar en su caso, abra la consola de Python y ejecute QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) para ver el listado de directorios predeterminados.

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.

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 puede que desee crear una aplicación interactiva que utiliza la funcionalidad de los SIG — realizar mediciones, exportar un mapa en PDF … El módulo qgis.gui proporciona varios componentes de interfaz gráfica, sobre todo el widget de lienzo de mapa que se puede incorporar a la aplicación con soporte para 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.

Usando PyQGIS en scripts individuales

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

from qgis.core import *

# Supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.  Setting the
# second argument to False disables the GUI.
qgs = QgsApplication([], False)

# Load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory

qgs.exitQgis()

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

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 utilizar la Desarrollar scripts en la consola de Python desde dentro de QGIS y mirar la salida de la ejecución de QgsApplication.prefixPath().

Después de configurar la ruta del prefijo, guardamos una referencia a QgsApplication en la variable qgs. El segundo argumento se establece en False, especificando que no planeamos usar la GUI ya que estamos escribiendo un script independiente. Con``QgsApplication`` configurado, cargamos los proveedores de datos QGIS y el registro de capas llamando al método qgs.initQgis(). Con QGIS inicializado, estamos listos para escribir el resto del script. Por último, terminamos llamando a qgs.exitQgis() para eliminar los proveedores de datos y el registro de capas de la memoria.

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 instancias de QgsApplication. Pase True en lugar de False para indicar que se planea usar una GUI.

from qgis.core import *

# Supply the path to the qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.
# Setting the second argument to True enables the GUI.  We need
# this since this is a custom application.

qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.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 :-)

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.

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.