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.

**A FAIRE : **

Faire fonctionner PyQGIS (compilation manuelle, débogage)

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 :

  • 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

La Console Python

Il est possible de tirer partie d’une console Python intégrée pour créer des scripts et les exécuter. La console peut être ouverte grâce au menu: Plugins ‣ Console Python. La console s’ouvre comme une fenêtre d’utilitaire windows 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.

For convenience of the user, the following statements are executed when the console is started (in future it will be possible to set further initial commands):

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 <http://www.qgis.org/wiki/Python_Plugin_Repositories>`_ 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.

Utiliser PyQGIS dans une application personnalisée

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

Quand vous avez fini d’utiliser la librairie QGIS, appelez la fonction exitQgis() pour vous assurer que tout est nettoyé (par ex, effacer le registre de couche cartographique et supprimer les couches):

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

The path to the PyQGIS modules is now known, however they depend on qgis_core and qgis_gui libraries (the Python modules serve only as wrappers). Path to these libraries is typically unknown for the operating system, so you get an import error again (the message might vary depending on the system):

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

Fix this by adding the directories where the QGIS libraries reside to search path of the dynamic linker:

  • sur Linux: export LD_LIBRARY_PATH=/qgispath/lib

  • sur Windows: set PATH=C:\qgispath;%PATH%

These commands can be put into a bootstrap script that will take care of the startup. When deploying custom applications using PyQGIS, there are usually two possibilities:

  • require user to install QGIS on his platform prior to installing your application. The application installer should look for default locations of QGIS libraries and allow user to set the path if not found. This approach has the advantage of being simpler, however it requires user to do more steps.
  • package QGIS together with your application. Releasing the application may be more challenging and the package will be larger, but the user will be saved from the burden of downloading and installing additional pieces of software.

The two deployment models can be mixed - deploy standalone application on Windows and Mac OS X, for Linux leave the installation of QGIS up to user and his package manager.