Introduction¶

Ce document est à la fois un tutoriel et un guide de référence. Il ne liste pas tous les cas d’utilisation possibles, mais donne un bon aperçu des principales fonctionnalités.

Scripter dans la console Python
Extensions Python
Exécuter du code python quand QGIS démarre
- Le fichier : startup.py
- La variable d’environment PYQGIS_STARTUP
Applications Python
Notes techniques sur PyQt et SIP

Le support de Python a été introduit pour la première fois dans QGIS 0.9. Il y a de nombreuses façons d’utiliser du code python dans QGIS ( elles sont traitées en détail dans les sections suivantes):

lancer des commandes dans la console Python de QGIS
créer et utiliser des extensions
exécuter automatiquement un programme Python quand QGIS démarre
créer des applications personnalisées basées sur l’API QGIS

Des liaisons python sont également disponibles pour QGIS Server, ce qui permet de mettre en œuvre des extensions (see Extensions Python pour QGIS Server) et des liaisons qui peuvent être intégrées pour intégrer QGIS Server dans une application Python.

There is a complete QGIS API reference that documents the classes from the QGIS libraries. The Pythonic QGIS API (pyqgis) is nearly identical to the C++ API.

Une bonne méthode pour apprendre à réaliser des tâches classiques est de télécharger des extensions existantes depuis le dépôt d’extensions <https://plugins.qgis.org/> puis d’examiner leur code.

Scripter dans la console Python ¶

QGIS fourni une console Python intégrée Python console pour créer des scripts. La console peut être ouverte grâce au menu: Extensions ‣ Console Python:

La Console Python de QGIS¶

La capture d’écran ci-dessus montre comment récupérer la couche sélectionnée dans la liste des couches, afficher son identifiant et éventuellement, si c’est une couche vectorielle, afficher le décompte d’entités. Pour interagir avec l’environnement de QGIS, il y a une variable iface, instance de la classe QgsInterface. Cette interface permet d’accéder au canevas de carte, aux menus, barres d’outils et autres composantes de l’application QGIS.

Pour simplifier la vie de l’utilisateur, les déclarations suivantes sont exécutées quand la console est ouverte (Dans le future, il sera possible de définir plus de commandes).

from qgis.core import *
import qgis.utils

Pour ceux qui utilisent fréquemment la console, il peut-être utile de configurer un raccourci clavier pour ouvrir la console ( dans Settings ‣ Keyboard shortcuts…).

Extensions Python ¶

Il est possible d’étendre les fonctionnalités de QGIS en utilisant des extensions. Les extensions peuvent être écrites en Python. Les principaux avantages par rapport aux extensions C++ sont la simplicité de déploiement (pas de compilation pour chaque plateforme) et une plus grande simplicité de développement.

De nombreuses extensions couvrant de nombreuses fonctionnalités ont été écrites depuis l’introduction du support de Python. L’installeur d’extensions permet facilement aux utilisateurs de récupérer, mettre à jour et supprimer des extensions python. Voir la page des extensions python pour plus d’information sur les extensions et le développement d’extensions.

Créer des extensions Python est simple. Voir Développer des extensions Python pour des instructions détaillées.

Note

Des extensions python sont également disponibles pour QGIS server. Voir la page Extensions Python pour QGIS Server pour plus de détails.

Exécuter du code python quand QGIS démarre ¶

Il y a deux façons distinctes d’exécuter un programme Python chaque fois que QGIS démarre.

Créer un script startup.py
Définir la variable d’environnement PYQGIS_STARTUP sur un fichier python

Le fichier : `startup.py`¶

A chaque démarrage de QGIS, le répertoire python du profil utilisateur

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

est exploré à la recherche d’un fichier nommé startup.py. Si ce fichier existe, il est exécuté par l’interpréteur python embarqué.

Note

Le chemin par défaut dépend du système d’exploitation. Pour trouver le chemin qui fonctionne chez vous, ouvrez la console python et exécutez QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) pour voir la liste des répertoires par défaut.

La variable d’environment PYQGIS_STARTUP ¶

Vous pouvez exécuter du code python juste avant la fin de l’initialisation de QGIS en définissant la variable d’environnement PYQGIS_STARTUP avec le chemin d’un fichier python existant.

Ce code va être exécuté avant la fin de l’initialisation de QGIS. Cette méthode est très utile pour nettoyer le chemin sys.path , qui peut être pollué par d’autres chemins, ou pour isoler ou charger un environnement initial sans recourir à un environnement virtuel, par exemple homebrew ou MacPorts sur MacOS.

Applications Python ¶

Il est souvent pratique de créer des scripts pour automatiser des processus. Avec PyQGIS, cela est parfaitement possible — importez le module qgis.core, initialisez-le et vous êtes prêt pour le traitement.

Vous pouvez aussi souhaiter créer une application interactive utilisant certaines fonctionnalités SIG — mesurer des données, exporter une carte en PDF, …. Le module qgis.gui fourni différentes composantes de l’interface, le plus notable étant le canevas de carte qui peut être facilement intégré dans l’application, avec le support du zoom, du déplacement ou de tout autre outil personnalisé de cartographie.

Les applications personnalisées de PyQGIS ou les scripts doivent être configurés pour trouver les ressources QGIS, comme les informations sur les projections et les fournisseurs de données pour lire des couches vecteurs ou raster. Les ressources QGIS sont initialisées en ajoutant quelques lignes au début de votre application ou de votre script. Le code pour initialiser QGIS pour des applications sur mesure ou des scripts autonomes est similaire. Des exemples sont fournis ci dessous.

Note

Note: ne pas utiliser qgis.py comme nom de script test — Python ne sera pas en mesure d’importer les dépendances étant donné qu’elles sont occultées par le nom du script.

Utiliser PyQGIS dans des scripts indépendants ¶

Pour commencer un script indépendant, initialisez les ressources QGIS au début du script tel que dans le code suivant:

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

Nous commençons par importer le module qgis.core puis nous configurons le chemin de préfixe. Le chemin de préfixe est l’endroit où QGIS est installé sur votre système. Il est configuré dans le script en faisant appel à la méthode setPrefixPath. Le second argument setPrefixPath est mis à True, ce qui contrôle si les chemins par défaut sont utilisés.

Le chemin d’installation de QGIS varie selon les plateformes; le moyen le plus simple pour trouver celle qui correspond à votre système est d’utiliser la console Scripter dans la console Python depuis QGIS et de vérifier la sortie de la commande QgsApplication.prefixPath().

Une fois la configuration du chemin faite, nous sauvegardons une références à QgsApplication dans la variable qgs. Le second argument est défini à False, indiquant que n’allons pas utiliser une interface graphique puisque nous écrivons un script autonome. QgsApplication étant configuré, nous chargeons les fournisseurs de données de QGIS et le registre de couches via la méthode qgs.initQgis(). QGIS étant initialisé, nous sommes prêts à écrire le reste de notre script. Pour finir, nous utilisons qgs.exitQgis() pour nous assurer de supprimer de la mémoire les fournisseurs de données et le registre de couches.

Utiliser PyQGIS dans une application personnalisée ¶

La seule différence entre Utiliser PyQGIS dans des scripts indépendants et une application PyQGIS personnalisée réside dans le second argument lors de l’initialisation de QgsApplication. Passer True au lieu de False pour indiquer que nous allons utiliser une interface graphique.

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

Maintenant, vous pouvez travailler avec l’API de QGIS - charger des couches et effectuer des traitements ou lancer une interface graphique avec un canevas de carte. Les possibilités sont infinies :-)

Exécuter des applications personnalisées ¶

Vous devrez indiquer au système où chercher les librairies de QGIS et les modules Python appropriés s’ils ne sont pas à un emplacement connu - autrement, Python se plaindra:

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

Ceci peut être corrigé en définissant la variable d’environnement PYTHONPATH. Dans les commandes suivantes, <qgispath> doit être remplacé par le réel chemin d’accès au dossier d’installation de QGIS:

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

Le chemin vers les modules PyQGIS est maintenant connu. Néanmoins, ils dépendent des bibliothèques qgis_core et qgis_gui (les modules Python qui servent d’encapsulage). Le chemin vers ces bibliothèques peut être inconnu du système d’exploitation auquel cas vous auriez de nouveau une erreur d’import (le message peut varier selon le système):

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

Corrigez ce problème en ajoutant les répertoires d’emplacement des bibliothèques QGIS au chemin de recherche de l’éditeur dynamique de liens:

sur Linux: export LD_LIBRARY_PATH=/<qgispath>/lib
sur Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% où <qgisrelease> devra être remplacé avec le type de release que vous ciblez (ex. qgis-ltr, qgis, qgis-dev)

Ces commandes peuvent être écrites dans un script de lancement qui gérera le démarrage. Lorsque vous déployez des applications personnalisées qui utilisent PyQGIS, il existe généralement deux possibilités:

Imposer à l’utilisateur d’installer QGIS sur la plate-forme avant d’installer l’application. L’installateur de l’application devrait rechercher les emplacements par défaut des bibliothèques QGIS et permettre à l’utilisateur de préciser un chemin si ce dernier n’est pas trouvé. Cette approche a l’avantage d’être plus simple mais elle impose plus d’actions à l’utilisateur.
Créer un paquet QGIS qui contiendra votre application. Publier l’application pourrait être plus complexe et le paquet d’installation sera plus volumineux mais l’utilisateur n’aura pas à télécharger et à installer d’autres logiciels.

Les deux modèles de déploiement peuvent être mélangés: déployer une application autonome sous Windows et MacOS, mais sous Linux laisser l’installation de QGIS à l’utilisateur via son gestionnaire de paquets .

Notes techniques sur PyQt et SIP ¶

Nous avons choisi Python car c’est un des langages les plus adaptés pour la création de scripts. Les liaisons (bindings) PyQGIS sur QGIS3 dépendent de SIP et PyQT5. Le choix de l’utilisation de SIP plutôt que de SWIG plus généralement répandu est dû au fait que le noyau de QGIS dépend des librairies Qt. Les liaisons Python pour Qt (PyQt) sont opérées via SIP, ce qui permet une intégration parfaite de PyQGIS avec PyQt.