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.

TODO:
Getting PyQGIS to work (Manual compilation, Troubleshooting)

There are several ways how to use QGIS python bindings, they are covered in detail in the following sections:

  • 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

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

There are some resources about programming with PyQGIS on QGIS blog. See QGIS tutorial ported to Python for some examples of simple 3rd party apps. A good resource when dealing with plugins is to download some plugins from plugin repository and examine their code. Also, the python/plugins/ folder in your QGIS installation contains some plugin that you can use to learn how to develop such plugin and how to perform some of the most common tasks

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.

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.

Using PyQGIS in custom application

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.

First of all you have to import qgis module, set QGIS path where to search for resources — database of projections, providers etc. When you set prefix path with second argument set as True, QGIS will initialize all paths with standard dir under the prefix directory. Calling initQgis() function is important to let QGIS search for the available providers.

from qgis.core import *

# supply path to where is your qgis installed
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# load providers
QgsApplication.initQgis()

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

When you are done with using QGIS library, call exitQgis() to make sure that everything is cleaned up (e.g. clear map layer registry and delete layers):

QgsApplication.exitQgis()

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.