1. Introduzione¶

Questo documento vuole essere sia un’esercitazione che un manuale. Anche se non elenca tutti i possibili casi, dovrebbe comunque fornire una buona panoramica delle funzioni principali.

Scripting nel terminale python
Plugin Python
Esegui il codice Python all’avvio di QGIS
- Il file startup.py
- La variabile ambientale `PYQGIS_STARTUP
Applicazioni Python
Note tecniche su PyQt e SIP

Il supporto Python è stato introdotto per la prima volta in QGIS 0.9. Ci sono diversi modi per utilizzare Python in QGIS Desktop (trattato nelle seguenti sezioni):

Tramite i comandi nella console Python in QGIS
Crea e usa plugin
Esegui automaticamente il codice Python all’avvio di QGIS
Crea algoritmi di elaborazione
Crea funzioni per espressioni in QGIS
Create custom applications based on the QGIS API

Python è disponibile anche per QGIS Server, inclusi i plugin Python (vedi QGIS Server and Python) e i collegamenti Python che possono essere utilizzati per incorporare il server QGIS in un’applicazione Python.

Esiste un riferimento complete QGIS API che documenta le classi dalle librerie QGIS. The Pythonic QGIS API (pyqgis) è quasi identica all’API C ++.

Una buona risorsa per imparare come eseguire attività comuni è scaricare plugin esistenti dal plugin repository ed esaminare il loro codice.

1.1. Scripting nel terminale python ¶

QGIS fornisce un terminale python. Puoi aprirlo dal menu Plugins ▶ Python Console :

Fig. 1.4 Console python di GIS¶

La schermata sopra ti mostra come puoi prendere il layer attualmente selezionato nell’elenco dei layer, mostrare il suo ID e, facoltativamente, se è un vettore, ti può mostrare il conteggio degli elementi. Per l’interazione con l’ambiente QGIS, esiste una variabile iface, che è un’istanza della :classe:`QgisInterface <qgis.gui.QgisInterface>`. Questa interfaccia ti consente l’accesso all’area della mappa, ai menu, alle barre degli strumenti e ad altre parti di QGIS.

Per comodità, esegui le seguenti istruzioni all’avvio del terminale (in futuro sarà possibile impostare ulteriori comandi iniziali)

from qgis.core import *
import qgis.utils

Se fai spesso uso del terminale, può essere utile impostare una scorciatoia per attivarlo (con Impostazioni ▶ Scorciatoie da tastiera…)

1.2. Plugin Python ¶

Puoi estendere i comandi di QGIS tramite plugin, che possono essere scritti in python. Il vantaggio principale rispetto ai plugin C ++ è la semplicità della distribuzione (nessuna compilazione per ogni piattaforma) e uno sviluppo più semplice.

Molti plugin che coprono varie funzionalità sono stati scritti dal supporto Python. Il programma di installazione del plugin ti consente di recuperare, aggiornare e rimuovere facilmente i plugin python. Vedi la pagina Python Plugins <https://plugins.qgis.org/> per maggiori informazioni sui plugin e sullo sviluppo dei plugin.

Creare un plugin in python è semplice, vedi Developing Python Plugins per avere istruzioni dettagliate.

Nota

I plugin python sono disponibili anche per il server QGIS. Per ulteriori dettagli, vedi QGIS Server and Python .

1.3. Esegui il codice Python all’avvio di QGIS ¶

Esistono du metodi distinti per avviare codice Python all’avvio di QGIS.

Crea uno script startup.py
Configura la variabile ambientale PYQGIS_STARTUP per un file python esistente

1.3.1. Il file `startup.py`¶

Ad ogni avvio di QGIS, la cartella principale di Python

Linux: .local/share/QGIS/QGIS3
Windows: AppData\Roaming\QGIS\QGIS3
macOS: Library/Application Support/QGIS/QGIS3

viene cercato un file denominato startup.py. Se quel file esiste, viene eseguito dall’interprete Python installato.

Nota

Il percorso predefinito dipende dal sistema operativo. Per trovare il percorso adatto a te, apri il terminale Python ed esegui QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) pre vedere la list delle cartelle predefinite.

1.3.2. La variabile ambientale `PYQGIS_STARTUP¶

Puoi eseguire il codice Python appena prima del completamento dell’inizializzazione di QGIS impostando la variabile ambiente PYQGIS_STARTUP sul percorso di un file Python esistente.

Questo codice verrà eseguito prima del completamento dell’inizializzazione di QGIS. Questo metodo è molto utile per pulire sys.path, che può avere percorsi indesiderati, o per isolare/caricare l’ambiente iniziale senza richiedere un ambiente virtuale, ad es. homebrew o MacPorts si installa su Mac.

1.4. Applicazioni Python ¶

Spesso può risultarti utile creare script per l’automazione dei processi. Con PyQGIS, questo è perfettamente possibile — importa il modulo qgis.core, inizializzalo e sei pronto per l’elaborazione.

Oppure potresti voler creare un’applicazione interattiva che utilizza comandi GIS - esegue misure, esporta una mappa come PDF, … Il modulo qgis.gui fornisce vari componenti della GUI, in particolare il quadro di mappa che può essere incorporato nell’applicazione con supporto per ingrandimento, panoramica e/o qualsiasi altro strumento di mappa personalizzato.

Le applicazioni personalizzate PyQGIS o i singoli script autonomi devono essere configurati per individuare le risorse QGIS, come le informazioni di proiezione e gli operatori per la lettura dei vettori e dei raster. Le risorse di QGIS vengono inizializzate aggiungendo alcune righe all’inizio dell’applicazione o dello script. Il codice per inizializzare QGIS per applicazioni personalizzate e singoli script è simile. Di seguito sono riportati esempi di ciascuno.

Nota

Non usare qgis.py come nome per il tuo script. Python non sarà in grado di importare i collegamenti poiché il nome dello script li confonderà.

1.4.1. Usare PyQGIS in script ¶

Per avviare un singolo script, attiva le risorse QGIS all’inizio dello 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()

Dapprima importa il modulo qgis.core e configura il percorso prefisso, che è la posizione dove è installato QGIS sul tuo sistema. Lo configuri nello script chiamando il metodo setPrefixPath . Il secondo argomento setPrefixPath è impostato su True, specificando che devono essere utilizzati i percorsi predefiniti.

Il percorso di installazione di QGIS varia in base alla piattaforma; per il tuo sistema puoi trovarlo con Scripting nel terminale python e guardare il risultato dal comando``QgsApplication.prefixPath()``.

Dopo aver configurato il percorso, salva un riferimento a QgsApplication` nella variabile qgs. Il secondo argomento è impostato su False, specificando che non prevedi di utilizzare la GUI poiché stai scrivendo uno script. Con QgsApplication configurato, carichi i dati QGIS e il registro dei layer chiamando il metodo qgs.initQgis(). Con QGIS inizializzato, puoi scrivere il resto dello script. Infine, concludi chiamando qgs.exitQgis() per rimuovere dalla memoria i fornitori di dati e il registro dei layer.

1.4.2. Usare PyQGIS in applicazioni personalizzate ¶

L’unica differenza tra Usare PyQGIS in script e un’applicazione PyQGIS personalizzata è il secondo argomento quando crei un’istanza di QgsApplication. Segna True anziché False per indicare che intendi utilizzare 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()

Ora puoi lavorare con l’API QGIS: caricare i livelli ed eseguire alcune elaborazioni o avviare una GUI con un’area della mappa. Le possibilità sono infinite :-)

1.4.3. Avviare applicazioni personalizzate ¶

Devi dire al tuo sistema dove cercare le librerie QGIS e i moduli Python se non si trovano in una posizione già nota, altrimenti Python lo segnalerà:

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

Puoi risolvere impostando la variabile ambiente PYTHONPATH. Nei seguenti comandi, <qgispath> deve essere sostituito con il percorso di installazione di QGIS:

su Linux: export PYTHONPATH=/<qgispath>/share/qgis/python
su Windows: set PYTHONPATH=c:\<qgispath>\python
su macOS: export PYTHONPATH=/<qgispath>/Contents/Resources/python

Ora, il percorso dei moduli PyQGIS è noto, ma questi dipendono dalle librerie qgis_core e qgis_gui (i moduli Python servono solo come contenitori). Il percorso di queste librerie potrebbe essere sconosciuto al sistema operativo, quindi verrà visualizzato nuovamente un errore di importazione (il messaggio potrebbe variare in base al sistema):

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

Risolvi questo aggiungendo le cartelle delle librerie QGIS nel percorso di ricerca del collegamento dinamico:

su Linux: export LD_LIBRARY_PATH=/<qgispath>/lib
su Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% dove <qgisrelease> dovrebbe essere sostituito con il tuo tipo di versione (es. qgis-ltr, qgis, qgis-dev)

Questi comandi possono essere inseriti in uno script che se ne occuperà all’avvio del programma. Quando si fa uso di applicazioni personalizzate utilizzando PyQGIS, esistono di solito due possibilità:

richiede all’utente di installare QGIS prima di installare l’applicazione. Il programma di installazione dell’applicazione dovrebbe cercare percorsi predefiniti delle librerie QGIS e consentire all’utente di impostare il percorso se non trovato. Questo approccio ha il vantaggio di essere più semplice, tuttavia richiede all’utente di fare più passaggi.
impacchetta QGIS insieme alla tua applicazione. Rilasciare l’applicazione può essere più impegnativo e il pacchetto sarà più grande, ma l’utente sarà risparmiato dall’onere di scaricare e installare parti addizionali del programma.

I due modelli di distribuzione possono essere combinati. È possibile fornire applicazioni indipendenti su Windows e macOS, ma per Linux lasciare l’installazione di GIS all’utente e al suo gestore dei pacchetti.

1.5. Note tecniche su PyQt e SIP ¶

Python è una dei linguaggi preferiti per lo scripting. I collegamenti PyQGIS in QGIS 3 dipendono da SIP e PyQt5. La ragione per usare SIP invece del SWIG più usato è che il codice QGIS dipende dalle librerie Qt. I collegamenti Python per Qt (PyQt) vengono eseguiti utilizzando SIP e ciò consente una perfetta integrazione di PyQGIS con PyQt.