Importante
La traducción es un esfuerzo comunitario al que puedes unirte. Esta página está actualmente traducida en 100.00%.
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:
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
)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.
Crear un script startup.py
Configurar la variable de entorno
PYQGIS_STARTUP
a un fichero Python existenteEspecificació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 utilizando 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.