1. 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.

La permission de copier, distribuer, modifier ce document est accordée sous les termes de la GNU Free Documentation License, dans sa version 1.3 ou plus récente telle que publiée par la Free Software Foundation ; sans modification de son contenu, sans ajouts la précédant ou la suivant.

A copy of the license is included in the section Licence GNU de documentation libre.

Cette licence s’applique aussi à tous les bouts de code présents dans le document.

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 algorithmes de traitement

  • Créer des fonctions pour des expressions dans QGIS

  • 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 QGIS server et Python) et des liaisons qui peuvent être intégrées pour intégrer QGIS Server dans une application Python.

Il existe une référence complete QGIS C++ API qui documente les classes des bibliothèques QGIS. L’API Pythonique QGIS (pyqgis) est presque identique à l’API C++.

Une autre bonne ressource pour apprendre à effectuer des tâches courantes est de télécharger des plugins existants depuis le dépôt de plugins et d’examiner leur code.

1.1. Scripter dans la console Python

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

../../_images/console.png

Fig. 1.4 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 futur, 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 Préférences ► Raccourcis clavier…).

1.2. 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 QGIS server et Python pour plus de détails.

1.2.1. Extensions avec Processing

Les plugins Processing peuvent être utilisés pour traiter des données. Ils sont plus faciles à développer, plus spécifiques et plus légers que les plugins Python. Créer une extension avec Processing explique quand l’utilisation d’algorithmes Processing est appropriée et comment les développer.

1.3. 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.

  1. Créer un script startup.py

  2. Définir la variable d’environnement PYQGIS_STARTUP sur un fichier python

1.3.1. 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.

1.3.2. 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.

1.4. Applications Python

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

Vous pouvez aussi créer une application interactive qui utilise les fonctionnalités du SIG — effectuer des mesures, exporter une carte au format PDF, … Le module qgis.gui fournit divers composants d’interface graphique, notamment le widget de canevas de carte qui peut être incorporé dans l’application avec le support du zoom, du panoramique et/ou d’autres outils de carte personnalisés.

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.

1.4.1. 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:

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

Tout d’abord, nous importons le module qgis.core et configurons le chemin du préfixe. Le chemin du préfixe est l’endroit où QGIS est installé sur votre système. Il est configuré dans le script en appelant la méthode setPrefixPath(). Le deuxième argument de setPrefixPath() est défini sur True, spécifiant que les chemins par défaut doivent être utilisés.

Le chemin d’installation de QGIS varie en fonction de la plate-forme ; le moyen le plus simple de le trouver pour votre système est d’utiliser la commande Scripter dans la console Python à partir de QGIS et de regarder la sortie de l’exécution :

QgsApplication.prefixPath()

Une fois le chemin du préfixe configuré, nous enregistrons une référence à QgsApplication dans la variable qgs. Le second argument est défini à False, spécifiant que nous ne prévoyons pas d’utiliser l’interface graphique puisque nous écrivons un script autonome. Avec QgsApplication configuré, nous chargeons les fournisseurs de données QGIS et le registre des couches en appelant la méthode initQgis().

qgs.initQgis()

Avec QGIS initialisé, nous sommes prêts à écrire le reste du script. Enfin, nous terminons en appelant exitQgis() pour supprimer de la mémoire les fournisseurs de données et le registre des couches.

qgs.exitQgis()

1.4.2. 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 est le second argument lors de l’instanciation de la QgsApplication. Passez True au lieu de False pour indiquer que nous prévoyons d’utiliser une interface graphique.

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

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

1.4.3. 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 .

1.5. 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.