Outdated version of the documentation. Find the latest one here.

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 une bonne idée générale des principales fonctionnalités.

Dès la version 0.9, QGIS intégrait un support optionnel pour le langage Python. Nous avons choisi Python car c’est un des langages les plus adaptés pour la création de scripts. Les dépendances PyQGIS proviennent de SIP et PyQt4. 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 dépendances Python pour Qt (PyQt) sont opérées via SIP, ce qui permet une intégration parfaite de PyQGIS avec PyQt.

Il y a de nombreuses façons d’utiliser les dépendances Python de QGIS; elles sont mentionnées en détail dans les sections suivantes :

  • exécuter automatiquement un programme Python quand QGIS démarre

  • lancer des commandes dans la console Python de QGIS

  • créer et utiliser des plugins en Python

  • créer des applications personnalisées basées sur l’API QGIS

Les dépendances Python sont aussi disponibles pour QGIS Server:

  • à partir de la version 2.8, les extensions Python sont également disponibles pour QGIS Server (see: Server Python Plugins)

  • depuis la version 2.11 (Master du 11-08-2015), la librairie QGIS Server possède des dépendances Python qui peuvent être utilisées pour intégrer QGIS Server dans une application Python

Il y a une documentation complète de l’API QGIS qui détaille les classes des librairies QGIS. L’API Python de QGIS est presque identique à l’API en C++.

Pour vous familiariser avec les extensions, vous pouvez en télécharger depuis le Dépôt des Extensions Python et examiner leur code. Aussi, le répertoire python/plugins/ dans votre installation de QGIS contient des extensions que vous pouvez utiliser pour apprendre à développer les vôtres et à effectuer quelques-unes des tâches les plus courantes.

Exécuter un programme Python au démarrage de QGIS

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

Variables d’environnement PYQGIS_STARTUP

Vous pouvez exécuter un programme Python juste avant la fin de l’initialisation de QGIS en affectant le chemin d’accès à un fichier Python existant à la variable d’environnement PYQGIS_STARTUP.

Vous aurez probablement rarement besoin de cette méthode, mais il est utile de la mentionner ici car c’est une des façons d’exécuter un programme Python dans QGIS et parce que ce programme s’exécutera avant que l’initialisation de QGIS ne soit complète. Cette méthode est très utile pour nettoyer sys.path, qui peut contenir des chemins d’accès indésirables, ou pour isoler/charger l’environnement initial sans avoir recours à un environnement virtuel, par ex. homebrew ou MacPorts sur Mac.

Le fichier : startup.py

Chaque fois que QGIS démarre, le fichier nommé startup.py est recherché dans le répertoire Python principal de l’utilisateur (généralement : .qgis2/python). Si ce fichier existe, il est exécuté par l’interpréteur Python intégré.

La Console Python

Il est possible de tirer partie de la console Python intégrée pour créer des scripts et les exécuter. La console peut être ouverte grâce au menu: Extension ‣ Console Python. La console s’ouvre comme une fenêtre utilitaire non modale :

../../_images/console.png

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 vecteur, afficher le nombre 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.

A la convenance de l’utilisateur, les déclarations qui suivent sont exécutées lors du lancement de la console (à l’avenir, il sera possible de paramétrer d’autres commandes d’initialisation):

from qgis.core import *
import qgis.utils

Pour ceux qui utilisent souvent la console, il peut être utile de définir un raccourci pour déclencher la console (dans le menu Préférences ‣ Configurer les raccourcis...)

Extensions Python

QGIS permet d’enrichir ses fonctionnalités à l’aide d’extensions. Au départ, ce n’était possible qu’avec le langage C++. Avec l’ajout du support de Python dans QGIS, il est également possible d’utiliser les extensions écrites en Python. Le principal avantage sur des extensions C++ est leur simplicité de distribution (pas de compilation nécessaire pour chaque plate-forme) et la facilité du développement.

De nombreuses extensions couvrant diverses fonctionnalités ont été écrites depuis l’introduction du support de Python. L’installateur d’extensions permet aux utilisateurs de facilement chercher, mettre à niveau et supprimer les extensions Python. Voir la page du Dépôt des Extensions Python pour diverses sources d’extensions.

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

Note

Les extensions Python sont aussi disponibles dans QGIS Server (QGIS comme serveur de données OGC), voyez Extensions Python pour QGIS Server pour plus d’information.

Applications Python

Souvent lors du traitement de données SIG, il est très pratique de créer des scripts pour automatiser le processus au lieu de faire la même tâche encore et encore. 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 ou toute autre fonction. Le module qgis.gui vous apporte 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

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.

# When your script is complete, call exitQgis() to remove the provider and
# layer registries from memory
qgs.exitQgis()

Nous commençons par importer le module qgis.core et ensuite 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 faisant appel à la méthode setPrefixPath. Le second argument de la méthode setPrefixPath est mis à True, ce qui contrôle si les chemins par défaut sont utilisés.

Le chemin d’installation de QGIS varie suivant XXXXX ; le moyen le plus simple pour trouver celle qui correspond à votre système est d’utiliser la La Console Python

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 nous n’envisageons pas d’utiliser une interface graphique étant donné que nous écrivons un script indépendant. QgsApplication étant configuré, nous chargeons les fournisseurs de données de QGIS et le registre de couches via la méthode qgs.initQgis(). Avec l’initialisation de QGIS, nous sommes désormais prêts à écrire le reste de notre script. A la fin, 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 path to 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, which we need to do
# 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.

# When your script is complete, call exitQgis() 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ù trouver 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

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 est inconnu du système d’exploitation et vous allez encore récupérer une erreur d’import (le message peut varier selon le système):

>>> import qgis.core
ImportError: libqgis_core.so.1.5.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;%PATH%

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 s’occuper des 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 sera 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 Mac OS X et laisser l’installation de QGIS par l’utilisateur (via son gestionnaire de paquets) pour Linux.