Développer des extensions Python¶

Fichiers de l’extension¶

Vous pouvez voir ici la structure du répertoire de notre exemple d’extension

PYTHON_PLUGINS_PATH/
  MyPlugin/
    __init__.py    --> *required*
    mainPlugin.py  --> *required*
    metadata.txt   --> *required*
    resources.qrc  --> *likely useful*
    resources.py   --> *compiled version, likely useful*
    form.ui        --> *likely useful*
    form.py        --> *compiled version, likely useful*

A quoi correspondent ces fichiers?

• __init__.py = Le point d’entrée de l’extension. Il doit comporter une méthode classFactory() et peut disposer d’un autre code d’initialisation.

• mainPlugin.py = Le code principal de l’extension. Contient toutes les informations sur les actions de l’extension et le code principal.

• resources.qrc = Le document .xml créé par Qt Designer. Contient les chemins relatifs vers les ressources des formulaires.

• resources.py = La traduction en Python du fichier resources.qrc décrit ci-dessus.

• form.ui = L’interface graphique créée avec Qt Designer.

• form.py = La traduction en Python du fichier form.ui décrit ci-dessus.

• metadata.txt = Requis pour QGIS >= 1.8.0. Contient les informations générales, la version, le nom et d’autres métadonnées utilisées par le site des extensions et l’infrastructure de l’extension. A partir de QGIS 2.0, les métadonnées du fichier __init__.py ne seront plus acceptées et le fichier metadata.txt sera requis.

Vous trouverez ici une méthode automatisée en ligne pour créer les fichiers de base (le squelette) d’une classique extension Python sous QGIS.

Il existe également une extension QGIS nommée Plugin Builder qui crée un modèle d’extension depuis QGIS et ne nécessite pas de connexion Internet. C’est l’option recommandée car elle produit des sources compatibles avec la version 2.0.

Métadonnées de l’extension¶

Tout d’abord, le gestionnaire d’extensions a besoin de récupérer des informations de base sur l’extension par exemple son nom, sa description, etc. Le fichier metadata.txt est le bon endroit où mettre cette information.

Par défaut, les extensions sont placées dans le menu Extension (nous verrons dans la section suivante comment ajouter une entrée de menu pour notre extension) mais elles peuvent également être placées dans les menus Raster, Vecteur, Base de données et Internet.

Une entrée “category” existe dans les métadonnées afin de spécifier cela, pour que l’extension soit classée en conséquence. Cette entrée de métadonnées est utilisée comme astuce pour les utilisateurs et leur dit où (dans quel menu) l’extension peut être trouvée. Les valeurs autorisées pour “category” sont : Vector, Raster, Database ou Web. Par exemple, si votre extension sera disponible dans le menu Raster, ajoutez ceci à metadata.txt :

category=Raster

Un exemple pour ce fichier metadata.txt

; the next section is mandatory

[general]
name=HelloWorld
email=me@example.com
author=Just Me
qgisMinimumVersion=2.0
description=This is an example plugin for greeting the world.
    Multiline is allowed:
    lines starting with spaces belong to the same
    field, in this case to the "description" field.
    HTML formatting is not allowed.
about=This paragraph can contain a detailed description
    of the plugin. Multiline is allowed, HTML is not.
version=version 1.2
; end of mandatory metadata

; start of optional metadata
category=Raster
changelog=The changelog lists the plugin versions
    and their changes as in the example below:
    1.0 - First stable release
    0.9 - All features implemented
    0.8 - First testing release

; Tags are in comma separated value format, spaces are allowed within the
; tag name.
; Tags should be in English language. Please also check for existing tags and
; synonyms before creating a new one.
tags=wkt,raster,hello world

; these metadata can be empty, they will eventually become mandatory.
homepage=http://www.itopen.it
tracker=http://bugs.itopen.it
repository=http://www.itopen.it/repo
icon=icon.png

; experimental flag (applies to the single version)
experimental=True

; deprecated flag (applies to the whole plugin and not only to the uploaded version)
deprecated=False

; if empty, it will be automatically set to major version + .99
qgisMaximumVersion=2.0

__init__.py¶

Ce fichier est requis par le système d’import de Python. QGIS impose aussi que ce fichier contienne une fonction classFactory() qui est appelée lorsque l’extension est chargée dans QGIS. Elle reçoit une référence vers une instance de la classe QgisInterface et doit renvoyer l’instance de la classe de l’extension située dans le fichier mainplugin.py. Dans notre cas, elle s’appelle TestPlugin (voir plus loin). Voici à quoi devrait ressembler le fichier __init__.py :

def classFactory(iface):
  from mainPlugin import TestPlugin
  return TestPlugin(iface)

## any other initialisation needed

mainPlugin.py¶

C’est l’endroit où tout se passe et voici à quoi il devrait ressembler (ex: mainPlugin.py) :

from PyQt4.QtCore import *
from PyQt4.QtGui import *
from qgis.core import *

# initialize Qt resources from file resources.py
import resources

class TestPlugin:

  def __init__(self, iface):
    # save reference to the QGIS interface
    self.iface = iface

  def initGui(self):
    # create action that will start plugin configuration
    self.action = QAction(QIcon(":/plugins/testplug/icon.png"), "Test plugin", self.iface.mainWindow())
    self.action.setObjectName("testAction")
    self.action.setWhatsThis("Configuration for test plugin")
    self.action.setStatusTip("This is status tip")
    QObject.connect(self.action, SIGNAL("triggered()"), self.run)

    # add toolbar button and menu item
    self.iface.addToolBarIcon(self.action)
    self.iface.addPluginToMenu("&Test plugins", self.action)

    # connect to signal renderComplete which is emitted when canvas
    # rendering is done
    QObject.connect(self.iface.mapCanvas(), SIGNAL("renderComplete(QPainter *)"), self.renderTest)

  def unload(self):
    # remove the plugin menu item and icon
    self.iface.removePluginMenu("&Test plugins", self.action)
    self.iface.removeToolBarIcon(self.action)

    # disconnect form signal of the canvas
    QObject.disconnect(self.iface.mapCanvas(), SIGNAL("renderComplete(QPainter *)"), self.renderTest)

  def run(self):
    # create and show a configuration dialog or something similar
    print "TestPlugin: run called!"

  def renderTest(self, painter):
    # use painter for drawing to map canvas
    print "TestPlugin: renderTest called!"

Les seules fonctions de l’extension qui doivent exister dans le fichier source principal de l’extension (ex: mainPlugin.py) sont :

• __init__ –> qui donne accès à l’interface de QGIS

• initGui() –> appelée lorsque l’extension est chargée.

• unload() –> chargée lorsque l’extension est déchargée.

Vous pouvez voir que dans l’exemple ci-dessus, la fonction addPluginToMenu() est utilisée. Elle ajoute l’entrée de menu correspondante au menu Extension. Il existe d’autres méthodes pour ajouter l’action dans un menu différent. Voici une liste de ces méthodes :

• addPluginToRasterMenu()
• addPluginToVectorMenu()
• addPluginToDatabaseMenu()
• addPluginToWebMenu()

Toutes ont la même syntaxe que la méthode addPluginToMenu().

Ajouter votre extension dans un des menus prédéfinis est une méthode recommandée pour conserver la cohérence de l’organisation des entrées d’extensions. Toutefois, vous pouvez ajouter votre propre groupe de menus directement à la barre de menus, comme le montre l’exemple suivant :

def initGui(self):
    self.menu = QMenu(self.iface.mainWindow())
    self.menu.setObjectName("testMenu")
    self.menu.setTitle("MyMenu")

    self.action = QAction(QIcon(":/plugins/testplug/icon.png"), "Test plugin", self.iface.mainWindow())
    self.action.setObjectName("testAction")
    self.action.setWhatsThis("Configuration for test plugin")
    self.action.setStatusTip("This is status tip")
    QObject.connect(self.action, SIGNAL("triggered()"), self.run)
    self.menu.addAction(self.action)

    menuBar = self.iface.mainWindow().menuBar()
    menuBar.insertMenu(self.iface.firstRightStandardMenu().menuAction(), self.menu)

def unload(self):
    self.menu.deleteLater()

N’oubliez pas de paramétrer la propriété objectName de QAction et de QMenu avec un nom spécifique à votre extension pour qu’elle puisse être personnalisée.

Fichier de ressources¶

Vous pouvez voir que dans la fonction initGui(), nous avons utilisé une icône depuis le fichier ressource (appelé resources.qrc dans notre cas)

<RCC>
  <qresource prefix="/plugins/testplug" >
     <file>icon.png</file>
  </qresource>
</RCC>

Il est bon d’utiliser un préfixe qui n’entrera pas en collision avec d’autres extensions ou toute autre partie de QGIS sinon vous risquez de récupérer des ressources que vous ne voulez pas. Vous devez juste générer un fichier python qui contiendra ces ressources. Cela peut être fait avec la commande pyrcc4.

pyrcc4 -o resources.py resources.qrc

Et c’est tout ! Rien de bien compliqué :)

Si tout a été réalisé correctement, vous devriez pouvoir trouver et charger votre extension dans le gestionnaire d’extensions et voir un message dans la console lorsque l’icône de barre d’outils ou l’entrée de menu appropriée est sélectionnée.

Lorsque vous travaillez sur une extension réelle, il est sage d’écrire l’extension dans un autre répertoire et de créer un fichier makefile qui générera l’interface graphique et les fichiers ressources en terminant par l’installation de l’extension dans l’installation QGIS.