16.3. Paramètres de l’IDE pour l’écriture et le débogage de plugins

Bien que chaque programmeur ait son éditeur IDE/Text préféré, voici quelques recommandations pour mettre en place des IDE populaires pour l’écriture et le débogage de plugins Python QGIS.

16.3.1. Plugins utiles pour écrire des plugins Python 

Certains plugins sont pratiques pour écrire des plugins Python. De Plugins ► Manage and Install plugins…, install :

Rechargeur de plugin : Cela vous permet de recharger un plugin et d’effectuer de nouvelles modifications sans avoir à redémarrer QGIS.
Premiers secours : Ceci ajoutera une console Python et un débogueur local pour inspecter les variables lorsqu’une exception est levée d’un plugin.

Avertissement

Despite our constant efforts, information beyond this line may not be updated for QGIS 3. Refer to https://qgis.org/pyqgis/master for the python API documentation or, give a hand to update the chapters you know about. Thanks.

16.3.2. Une note sur la configuration de votre IDE sous Linux et Windows 

Sur Linux, il suffit généralement d’ajouter les emplacements de la bibliothèque QGIS à la variable d’environnement PYTHONPATH de l’utilisateur. Sous la plupart des distributions, cela peut être fait en éditant ~/.bashrc ou ~/.bash-profile avec la ligne suivante (testé sur OpenSUSE Tumbleweed) :

export PYTHONPATH="$PYTHONPATH:/usr/share/qgis/python/plugins:/usr/share/qgis/python"

Enregistrez le fichier et implémentez les paramètres d’environnement en utilisant la commande shell suivante :

source ~/.bashrc

Sur Windows, vous devez vous assurer que vous avez les mêmes paramètres d’environnement et que vous utilisez les mêmes bibliothèques et interpréteur que QGIS. La façon la plus rapide de le faire est de modifier le fichier 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 comme C:\OSGeo4W\bin\qgis-unstable.bat.

16.3.3. Débogage à l’aide de l’IDE Pyscripter (Windows)

Pour l’utilisation de Pyscripter IDE, voici ce que vous devez faire :

Faites une copie de qgis-unstable.bat et renommez le pyscripter.bat.
Ouvrez-le dans un éditeur. Et supprimez la dernière ligne, celle qui lance QGIS.
Ajoutez une ligne qui pointe vers votre exécutable Pyscripter et ajoutez l’argument de la ligne de commande qui définit la version de Python à utiliser

Ajoutez également l’argument qui pointe vers le dossier où Pyscripter peut trouver la dll Python utilisée par QGIS, vous pouvez le trouver sous le dossier bin de votre installation OSGeoW

@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

Maintenant, lorsque vous double-cliquez sur ce fichier, Pyscripter se lance, avec le chemin d’accès correct.

Plus populaire que Pyscripter, Eclipse est un choix commun parmi les développeurs. Dans la section suivante, nous expliquerons comment le configurer pour développer et tester des plugins.

16.3.4. Débogage à l’aide d’Eclipse et PyDev 

16.3.4.1. Installation 

Pour utiliser Eclipse, assurez-vous que vous avez installé les éléments suivants

Eclipse
Aptana Studio 3 Plugin or PyDev
QGIS 2.x
Vous pouvez également installer Remote Debug, un plugin QGIS. Pour le moment, il est encore expérimental, donc activez Plugins expérimentaux sous Plugins ► Gérer et installer des plugins… ► Options au préalable.

Pour préparer votre environnement à l’utilisation d’Eclipse dans Windows, vous devez également créer un fichier batch et l’utiliser pour démarrer Eclipse :

Localisez le dossier dans lequel se trouve qgis_core.dll. Normalement, il s’agit de C:\OSGeo4W\apps\qgis\bin, mais si vous avez compilé votre propre application QGIS, il se trouve dans votre dossier de compilation dans output/bin/RelWithDebInfo.
Localisez votre exécutable eclipse.exe.

Créez le script suivant et utilisez-le pour démarrer eclipse lors du développement des plugins QGIS.

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

16.3.4.2. Mise en place d’Eclipse 

Dans Eclipse, créez un nouveau projet. Vous pouvez sélectionner Projet général et lier vos sources réelles par la suite, de sorte que l’endroit où vous placez ce projet n’a pas vraiment d’importance.

Fig. 16.111 Projet Eclipse
Faites un clic droit sur votre nouveau projet et choisissez New ► Folder.
Cliquez sur avance et choisissez lien vers un autre lieu (dossier lie). Si vous avez déjà des sources que vous voulez déboguer, choisissez celles-ci. Si vous n’en avez pas, créez un dossier comme cela a déjà été expliqué.

Maintenant, dans la vue Project Explorer, votre arbre des sources apparaît et vous pouvez commencer à travailler avec le code. Vous disposez déjà de la coloration syntaxique et de tous les autres puissants outils de l’IDE.

16.3.4.3. Configuration du débogueur 

Pour faire fonctionner le débogueur :

Passez à la perspective Debug dans Eclipse (Window ► Open Perspective ► Other ► Debug).
démarrer le serveur de débogage PyDev en choisissant PyDev ► Start Debug Server.
Eclipse attend maintenant une connexion de QGIS à son serveur de débogage et lorsque QGIS se connectera au serveur de débogage, il lui permettra de contrôler les scripts python. C’est exactement pour cela que nous avons installé le plugin Remote Debug. Démarrez donc QGIS au cas où vous ne l’auriez pas déjà fait et cliquez sur le symbole de bogue.

Vous pouvez maintenant définir un point d’arrêt et dès que le code le touche, l’exécution s’arrête et vous pouvez inspecter l’état actuel de votre plugin. (Le point d’arrêt est le point vert dans l’image ci-dessous, que vous pouvez définir en double-cliquant dans l’espace blanc à gauche de la ligne où vous voulez que le point d’arrêt soit défini).

../../../_images/breakpoint.png — Fig. 16.112 Point d’arrêt

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

Ouvrez la vue Console (Fenêtre ► Afficher la vue). Elle affichera la console Debug Server qui n’est pas très intéressante. Mais il y a un bouton Open Console qui vous permet de passer à une console de débogage PyDev plus intéressante.
Cliquez sur la flèche à côté du bouton Open Console et choisissez PyDev Console. Une fenêtre s’ouvre pour vous demander quelle console vous voulez démarrer.
Choisissez PyDev Debug Console. Au cas où elle serait grisée et vous demanderait de démarrer le débogueur et de sélectionner la trame valide, assurez-vous que le débogueur distant est connecté et que vous êtes actuellement sur un point d’arrêt.

Fig. 16.113 PyDev Debug Console

Vous disposez maintenant d’une console interactive qui vous permet de tester les commandes dans le contexte actuel. Vous pouvez manipuler des variables ou faire des appels d’API ou tout ce que vous voulez.

Astuce

Un peu ennuyeux, c’est que chaque fois que vous entrez une commande, la console repasse sur le serveur de débogage. Pour arrêter ce comportement, vous pouvez cliquer sur le bouton Console Pin lorsque vous êtes sur la page du serveur de débogage et il devrait se souvenir de cette décision au moins pour la session de débogage en cours.

16.3.4.4. Faire comprendre l’API à eclipse 

Une fonction très pratique est de faire en sorte qu’Eclipse connaisse réellement l’API QGIS. Cela lui permet de vérifier si votre code contient des fautes de frappe. Mais ce n’est pas tout : Eclipse peut également vous aider à effectuer l’autocomplétion des importations et des appels d’API.

Pour ce faire, Eclipse analyse les fichiers de la bibliothèque QGIS et diffuse toutes les informations. La seule chose que vous devez faire est de dire à Eclipse où se trouvent les bibliothèques.

Cliquez sur Window ► Preferences ► PyDev ► Interpreter ► Python.

Vous verrez votre interpréteur python configuré dans la partie supérieure de la fenêtre (actuellement python2.7 pour QGIS) et quelques onglets dans la partie inférieure. Les onglets intéressants pour nous sont Bibliothèques et Constructions forcées.

Fig. 16.114 PyDev Debug Console
Ouvrez d’abord l’onglet Bibliothèques.
Ajoutez un nouveau dossier et choisissez le dossier python de votre installation QGIS. Si vous ne savez pas où se trouve ce dossier (ce n’est pas le dossier des plugins) :
1. Ouvrir QGIS
2. Démarrer une console python
3. Entrez qgis.
4. et appuyez sur la touche Entrée. Il vous indiquera le module QGIS qu’il utilise et son chemin.
5. Enlevez le « /qgis/__init__.pyc « de ce chemin et vous avez le chemin que vous cherchez.
Vous devez également ajouter votre dossier de plugins ici (il se trouve dans le dossier python/plugins sous le dossier user_profile).
Passez ensuite à l’onglet Forced Builtins, cliquez sur Nouveau… et entrez qgis. Ceci fera en sorte qu’Eclipse analyse l’API QGIS. Vous voulez probablement aussi qu’Eclipse connaisse l’API PyQt. Par conséquent, ajoutez également PyQt en tant qu’intégration forcée. Cela devrait probablement déjà être présent dans votre onglet bibliothèques.
Cliquez sur OK et vous avez terminé.

Note

Chaque fois que l’API QGIS change (par exemple, si vous compilez QGIS Master et que le fichier SIP a changé), vous devez retourner à cette page et cliquer simplement sur appliquer. Cela permettra à Eclipse d’analyser à nouveau toutes les bibliothèques.

16.3.5. Débogage avec PyCharm sur Ubuntu avec QGIS compilé 

PyCharm est un IDE pour Python développé par JetBrains. Il existe une version gratuite appelée Community Edition et une version payante appelée Professional. Vous pouvez télécharger PyCharm sur le site web : https://www.jetbrains.com/pycharm/download

Nous supposons que vous avez compilé QGIS sur Ubuntu avec le répertoire de compilation donné ~/dev/qgis/build/master. Il n’est pas obligatoire d’avoir un QGIS auto-compilé, mais seul celui-ci a été testé. Les chemins doivent être adaptés.

Dans PyCharm, dans propriétés projet, Project Interpreter, nous allons créer un environnement virtuel Python appelé QGIS.
Cliquez sur le petit engrenage et ensuite sur Ajouter.
Sélectionnez Virtualenv environment.
Sélectionnez un emplacement générique pour tous vos projets Python tel que ~/dev/qgis/venv car nous utiliserons cet interpréteur Python pour tous nos plugins.
Choisissez un interpréteur de base Python 3 disponible sur votre système et cochez les deux options suivantes Hériter des ensembles site-packages et Rendre disponible à tous les projets.

Cliquez sur OK, revenez sur la petite gear et cliquez sur Show all (Afficher tout).
Dans la nouvelle fenêtre, sélectionnez votre nouvel interprète QGIS et cliquez sur la dernière icône du menu vertical Montre les chemins pour l’interprèteur sélectionné`.
Enfin, ajoutez le chemin absolu suivant à la liste : file:~/dev/qgis/build/master/output/python.

../../../_images/pycharm-adding-path.png

Redémarrez PyCharm et vous pourrez commencer à utiliser ce nouvel environnement virtuel Python pour tous vos plugins.

PyCharm connaîtra l’API QGIS et aussi l’API PyQt si vous utilisez Qt fourni par QGIS comme « from qgis.PyQt.QtCore import QDir ». L’auto-complétion devrait fonctionner et PyCharm peut inspecter votre code.

Dans la version professionnelle de PyCharm, le débogage à distance fonctionne bien. Pour la version communautaire, le débogage à distance n’est pas disponible. Vous ne pouvez avoir accès qu’à un débogueur local, ce qui signifie que le code doit être exécuté à l’intérieur de PyCharm (sous forme de script ou de test unitaire), et non dans le QGIS lui-même. Pour le code Python qui tourne dans QGIS, vous pouvez utiliser le plugin First Aid mentionné ci-dessus.

16.3.6. Débogage à l’aide de PDB 

Si vous n’utilisez pas un IDE tel qu’Eclipse ou PyCharm, vous pouvez déboguer en utilisant PDB, en suivant ces étapes.

Ajoutez d’abord ce code à l’endroit où vous souhaitez déboguer

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

Ensuite, lancez QGIS depuis la ligne de commande.

Sur Linux, faites :
```
$ ./Qgis
```
Sur macOS faire :
```
$ /Applications/Qgis.app/Contents/MacOS/Qgis
```
Et lorsque l’application atteint votre point d’arret, vous pouvez taper dans la console !

A FAIRE :: Ajouter des informations sur les tests