Paramétrage de l’EDI pour la création et le débogage d’extensions

Bien que chaque développeur dispose de son EDI/éditeur de texte préféré, voici quelques recommandations pour paramétrer les EDI populaires pour créer et déboguer des extensions QGIS en Python.

Note sur la configuration de l’EDI sous Windows

Sous GNU/Linux, il n’y a pas besoin de configuration supplémentaire pour développer des extensions. En revanche, sous Windows, vous devez vous assurer que vous disposez des mêmes variables d’environnement et que vous utilisez les mêmes bibliothèques et interpréteurs que QGIS. Le moyen le plus simple consiste à modifier le fichier batch de démarrage de QGIS.

Si vous avez utilisé l’installateur OSGeo4W, vous pouvez le trouver dans le dossier bin de votre installation OSGeo4W. Cherchez quelque chose du genre C:\OSGeo4W\bin\qgis-unstable.bat.

Voici ce que vous avez à faire pour utiliser l’IDE Pyscripter:

  • Faites une copie du fichier qgis-unstable.bat et renommez-le en pyscripter.bat.

  • Ouvrez-le dans un éditeur et supprimez la dernière ligne, celle qui lance QGIS.

  • Ajoutez une ligne qui pointe vers l’exécutable de Pyscripter et ajoutez l’argument de ligne de commande qui paramètre la version de Python à employer (2.7 dans le cas de QGIS >= 2.0).

  • Ajoutez également un argument qui pointe vers le répertoire où Pyscripter peut trouver les DLL Python utilisées par QGIS. Vous pouvez le trouver dans le répertoire bin de votre installation OSGeo4W

    @echo off
SET OSGEO4W_ROOT=C:\OSGeo4W
call "%OSGEO4W_ROOT%"\bin\o4w_env.bat
call "%OSGEO4W_ROOT%"\bin\gdal16.bat
@echo off
path %PATH%;%GISBASE%\bin
Start C:\pyscripter\pyscripter.exe --python25 --pythondllpath=C:\OSGeo4W\bin

Désormais, lorsque vous cliquerez sur ce fichier batch, il lancera Pyscripter avec le chemin correct.

Plus populaire que Pyscripter, Eclipse est un choix courant parmi les développeurs. Dans les sections qui suivent, nous allons expliquer comment le configurer pour le développement et les tests des extensions. Pour préparer votre environnement d’utilisation d’Eclipse sous Windows, vous devriez également créer un fichier batch et l’utiliser pour lancer Eclipse.

Pour créer ce fichier de commandes, suivez ces étapes:

  • Trouvez le répertoire où est stocké le fichier qgis_core.dll. Normalement, il s’agit de C:\OSGeo4W\apps\qgis\bin mais si vous avez compilé votre propre application QGIS, il sera dans votre répertoire de compilation output/bin/RelWithDebInfo.

  • Localisez votre exécutable eclipse.exe.

  • Créez le script qui suit et utilisez-le pour démarrer Eclipse lorsque vous développez des extensions QGIS.

call "C:\OSGeo4W\bin\o4w_env.bat"
set PATH=%PATH%;C:\path\to\your\qgis_core.dll\parent\folder
C:\path\to\your\eclipse.exe

Débogage à l’aide d’Eclipse et PyDev

Installation

Afin d’utiliser Eclipse, assurez-vous d’avoir installé

Préparation de QGIS

Il faut faire un peu de préparation dans QGIS lui-même. Deux extensions sont nécessaires : Remote Debug et Plugin reloader.

  • Allez dans Extension ‣ Installer/Gérer les extensions.

  • Cherchez l’extension Remote Debug (pour l’instant, elle est en version expérimentale et vous devrez donc activer les extensions expérimentales dans l’onglet Paramètres pour pouvoir l’afficher). Installez-la.

  • Cherchez l’extension Plugin reloader et installez-la de la même manière. Elle vous permettra de recharger une extension sans avoir à redémarrer QGIS.

Configuration d’Eclipse

Sous Eclipse, créez un nouveau projet. Vous pouvez choisir Projet Général et relier vos sources réels plus tard. L’endroit où vous placez le projet n’est donc pas vraiment important.

../../_images/eclipsenewproject.png

Projet Eclipse

Maintenant faites un clic-droit sur votre nouveau projet et choisissez Nouveau ‣ Dossier.

Cliquez sur [Avancé] et choisissez Lier à un emplacement alternatif (répertoire lié). Dans le cas où vous avez déjà des fichiers sources que vous voulez déboguer, choisissez les. Si ce n’est pas le cas, créez un répertoire tel qu’expliqué auparavant.

Désormais, votre arbre de fichiers sources est présent dans la vue Explorateur de Projet et vous pouvez commencer à travailler avec le code. Vous pouvez profiter dès maintenant de la coloration syntaxique ainsi que des autres puissants outils de votre EDI.

Configurer le débogueur

Pour faire fonctionner le débogueur, basculez dans la perspective de Débogage d’Eclipse (Fenêtre ‣ Ouvrir une perspective ‣ Autre ‣ Debug).

Maintenant, démarrez le serveur de débogage PyDev en choisissant PyDev=>Démarrez Serveur de Débogage.

Eclipse attend maintenant une connexion de QGIS au serveur de débogage. Lorsque QGIS se connectera au serveur de débogage, cela permettra à ce dernier de contrôler les scripts Python. C’est pour cela que nous avons installé l’extension Remote Debug. Démarrez QGIS au cas où ce n’est pas déjà fait et cliquez sur le symbole du bogue.

Maintenant, vous pouvez paramétrer un point d’arrêt et, dès que le code y parviendra, son exécution sera stoppée et vous pourrez inspecter l’état courant de votre extension. (Le point d’arrêt est le point vert dans l’image ci-dessous. On peut le marquer en double-cliquant sur l’espace en blanc à gauche de la ligne où vous voulez poser le point d’arrêt).

../../_images/breakpoint.png

Point d’arrêt

Une chose très intéressante que vous pouvez désormais utiliser est la console de débogage. Assurez-vous que l’exécution est parvenue à un point d’arrêt avant de commencer.

Ouvrez la vue Console ((Fenêtre ‣ Montrer la vue). Elle montrera la console Serveur de débogage ce qui n’est pas très intéressant. Mais il existe un bouton [Ouvrir Console] qui vous permet de basculer vers la console de débogage PyDev. Cliquez sur la flèche près de [Ouvrir Console] et choisissez Console PyDev. Une fenêtre apparaît, vous demandant quelle console vous souhaitez lancer. Choisissez Console PyDev Debug. Dans le cas où ce choix est grisé et qu’on vous demande de démarrer le débogueur et de sélectionner le cadre valide, assurez-vous que le débogueur à distance est bien connecté et que vous êtes sur un point d’arrêt.

../../_images/console-buttons.png

Console de débogage de PyDev

vous avez maintenant une console interactive qui vous permet de tester n’importe quelle commande du contexte courant. Vous pouvez manipuler les variables ou lancer des appels à l’API, ou ce que vous voulez.

Un point un peu ennuyeux: chaque fois que vous saisissez une commande, la console bascule vers le Serveur de Débogage. Pour stopper ce comportement, vous pouvez cliquer sur le bouton Attacher la Console lorsque vous êtes sur la page du serveur de débogage. Ce choix devrait perdurer tout le long de la session de débogage courante.

Permettre à Eclipse de comprendre l’API

Une fonctionnalité très pratique est de faire en sorte qu’Eclipse tienne compte de l’API de QGIS. Cela vous permet de vérifier les erreurs de syntaxe. Cela permet également à Eclipse de vous aider grâce au complément automatique du code en fonction des appels à l’API.

Pour faire tout cela, Eclipse analyse les fichiers de bibliothèque QGIS et en récupère toute l’information utile. La seule chose que vous avez à faire est de dire à Eclipse où trouver ces bibliothèques.

Cliquez sur Fenêtre ‣ Préférences ‣ PyDev ‣ Interpreteur ‣ Python.

Vous pourrez observer la configuration de l’interpréteur Python dans la partie supérieure de la fenêtre (pour le moment Python 2.7) ainsi que des onglets dans la partie inférieure. Les onglets qui vous intéressent sont nommés Bibliothèques et Compilation forcée.

../../_images/interpreter-libraries.png

Console de débogage de PyDev

Ouvrez d’abord l’onglet Bibliothèques. Ajoutez un nouveau répertoire et choisissez le répertoire Python de votre installation QGIS. Si vous ne savez pas où est situé ce répertoire (il ne s’agit pas du répertoire des extensions), ouvrez QGIS et démarrez une console Python et entrez simplement qgis en pressant Entrée. Cela vous montrera quel module QGIS est utilisé ainsi que son chemin. Supprimer la fin du chemin qui contient /qgis/__init__.pyc et vous avez l’emplacement que vous cherchez.

Vous devriez également ajouter le répertoire de vos extensions (sous Linux, c’est ~/.qgis2/python/plugins).

Ensuite, allez dans l’onglet Compilation forcée, cliquez sur Nouveau... et saisissez qgis. Cela permettra à Eclipse d’analyser l’API QGIS. Vous pouvez également ajouter l’API de PyQt4. Il doit sans doute être déjà présent dans votre onglet Bibliothèques.

Cliquer sur OK et c’est fini.

Note

Chaque fois que l’API de QGIS évolue (ex: si vous avez compilé la branche master de QGIS et que le fichier sip a changé), vous devriez retourner sur cette page et cliquer simplement sur Appliquer. Eclipse se chargera d’analyser toutes les bibliothèques.

Pour une autre configuration d’Eclipse pour travailler avec des extensions Python de QGIS, consultez ce lien

Débogage à l’aide de PDB

Si vous n’utilisez pas d’EDI comme Eclipse, vous pouvez déboguer vos extensions en utilisant PDB et en suivant les étapes qui suivent.

D’abord, ajoutez ce code à l’endroit que vous souhaitez déboguer:

# Use pdb for debugging
import pdb
# These lines allow you to set a breakpoint in the app
pyqtRemoveInputHook()
pdb.set_trace()

Ensuite exécutez QGIS depuis la ligne de commande.

Sur Linux, faites:

$ ./Qgis

Sur Mac OS X, faites:

$ /Applications/Qgis.app/Contents/MacOS/Qgis

Lorsque votre application atteint le point d’arrêt, vous pouvez taper des commandes dans la console !

A FAIRE :

Ajouter des informations sur les tests