.
I. Prérequis logiciel▲
Les outils suivants doivent être installés pour réaliser les opérations de cet article :
- Python 3 ;
- pip ;
- Visual Studio Code (VSCode).
II. Installation▲
Avec pip, l’outil d’installation classique des modules Python, l’installation est très simple avec la ligne de commande suivante :
pip install pylintVous pouvez vous assurer que l'outil pylint est installé en exécutant la ligne de commande suivante :
2.
3.
4.
5.
6.
7.
8.
9.
10.
$ pip show pylint
Version: 2.5.2
Summary: python code static checker
Home-page: https://github.com/PyCQA/pylint
Author: Python Code Quality Authority
Author-email: code-quality@python.org
License: GPL
Location: /Users/USER/Library/Python/3.7/lib/python/site-packages
Requires: mccabe, isort, astroid, toml
Required-by:
Lors de l'écriture de cet article, la version courante de pylint était la version 2.5.2.
III. Utilisation▲
On peut alors exécuter Pylint depuis l’invite de commande. Il est possible d’analyser le code d’un module ou de tout un package Python (pour être considéré comme un package, un dossier doit contenir le fichier __init__.py).
Pour analyser un module :
pylint my_moduleOu :
pylint directory/my_module.pyPour analyser tous les modules d’un package :
pylint my_packageIl est aussi possible de lister les modules que l’on souhaite analyser plutôt que d’en indiquer qu’un seul. Alors, Pylint analyse le ou les fichier(s) et liste l’ensemble des lignes où les règles ne sont pas respectées. Or, cette liste peut être très longue c’est pourquoi il est possible de configurer quelles règles sont vérifiées par Pylint.
IV. Configuration▲
Les règles imposées par Pylint sont divisées en cinq catégories différentes caractérisées par une lettre, on a donc :
- C : Convention : convention de codage non respectée ;
- R : Refactor : pour détecter les mauvaises pratiques ;
- W : Warning : pour des problèmes spécifiques à Python ;
- E : Error : pour détecter les bugs probables dans le code ;
- F : Fatal : une erreur empêchant Pylint de s’exécuter.
Il existe trois manières de configurer les règles de Pylint. Toutes les règles sont par ailleurs listées dans la documentation de Pylint : https://pylint.readthedocs.io/en/latest/technical_reference/features.html.
IV-A. Ligne de commande▲
La première consiste à activer ou désactiver des règles, ou des catégories de règles, directement en ligne de commande. Par défaut, les règles sont activées, pour n’en désactiver que quelques-unes, on procédera de la façon suivante :
$ pylint module --disable=<symbol>Par exemple :
$ pylint package/module.py --disable=fixme,invalid-nameOu pour désactiver toutes les règles de convention (caractérisées pas la lettre C) :
$ pylint package/module.py --disable=CPour au contraire n’activer qu’un faible nombre de règles, on utilisera l’option disable=all, puis enable en listant l’ensemble des règles que l’on souhaite appliquer.
$ pylint module --disable=all --enable=<symbol>Cette méthode est cependant peu efficace, surtout lorsque l’on veut exécuter Pylint avec le même ensemble de règles à chaque fois. C’est pourquoi il est possible de générer et de modifier un fichier de configuration.
IV-B. Fichier de configuration▲
Pour générer le fichier de configuration :
$ pylint --generate-rcfile >.pylintrcLe fichier .pylintrc est alors généré par Pylint dans le dossier courant. Il contient déjà un certain nombre d’informations et de paramètres ainsi qu’un ensemble de règles désactivées par défaut dans la section « MESSAGES CONTROL » avec le paramètre « disable ».
Il est alors possible de désactiver ou de réactiver des règles en ajoutant les règles à désactiver dans la liste ou en en supprimant de la liste existante. De plus, il est possible de configurer les règles qui sont paramétrables. Par exemple, on peut imposer un nombre de lignes minimal pour la documentation docstring (qui par défaut n’en impose pas, car la valeur est à -1) en modifiant la valeur du paramètre au niveau des lignes suivantes :
2.
3.
# Minimum line length for functions/classes that require
# docstrings, shorter ones are exempt.
docstring-min-length=1
On peut aussi paramétrer la forme des noms que l'on accepte par exemple en imposant que les variables suivent la convention camlCase plutôt que snake_case. D'autres règles n'ont pas de paramètres, comme la règle qui impose de mettre un espace après une virgule.
Il est aussi possible de générer le fichier de configuration en indiquant dans la ligne de commande des options afin qu’elles soient intégrées au fichier.
$ pylint --disable=C --docstring-min-length=2 --generate-rcfileIV-C. Annotations▲
Les annotations permettent d’activer ou de désactiver une ou plusieurs règles plus localement. On peut ajouter des annotations, i.e. des commentaires destinés à Pylint, directement sur le code, afin de modifier les règles appliquées uniquement sur certains blocs de code. Ainsi pour activer ou désactiver une règle, on écrira le code suivant :
# pylint: disable=invalid-name,fixme enable=no-memberCe commentaire est à placer à la fin d’une ligne pour appliquer ces règles sur la seule ligne. Pour appliquer une règle à tout un bloc, on placera l’annotation après la première ligne définissant le bloc (après la ligne def d’une fonction pour l’appliquer à toute la fonction, après la ligne for ou encore après la ligne if, sachant que le if et le else forment deux blocs distincts). Enfin, on peut aussi l’appliquer à tout un fichier en écrivant cette annotation dans les premières lignes du fichier.
V. Intégration avec Visual Studio Code▲
Pour utiliser Pylint avec Visual Studio Code (VSCode), il faut que l'extension Python soit installée. Depuis Visual Studio Code (VSCode), ouvrez le menu Extensions et saisissez Python dans le champ de saisie. Plusieurs choix sont proposés, sélectionnez l'extension développée par Microsoft (normalement la première de la liste). Vous devrez ensuite vérifier que l'interpréteur Python est bien configuré. Pour cela, faites CTRL+SHIFT+P, puis saisissez la valeur Python: Select Interpreter et assurez-vous alors qu'un interpréteur est correctement sélectionné.
Normalement, lorsque Pylint est installé, Visual Studio Code (VSCode) prend automatiquement en considération Pylint. Cependant, il ne vérifie qu’un petit nombre de règles parmi celles proposées par Pylint. Pour imposer les mêmes règles à Visual Studio Code que Pylint en ligne de commande, le plus simple est de générer le fichier de configuration (voir section précédente). Alors les règles vérifiées par Visual Studio Code et par Pylint en ligne de commande seront les mêmes.
Les erreurs et messages de Pylint s’affichent alors en soulignant les parties du code qui posent problème ainsi que dans l’onglet « Problems » (voir figure ci-dessous).
Pour assurer que cet affichage soit complet, il est peut-être nécessaire d’ajuster les paramètres de VSCode : dans Settings, recherchez « Pylint » et vérifiez la sévérité accordée à chaque catégorie de Pylint : si la sévérité est à « Hint », alors les messages de Pylint ne seront (presque) pas visibles, il faut donc choisir une autre sévérité pour que tout s’affiche.
VI. Quelques ajouts intéressants▲
Par défaut, Pylint ne vérifie pas que la documentation est présente, et ne vérifie pas si elle suit correctement un ensemble de conventions. On peut dans un premier temps imposer sa présence en indiquant un nombre de lignes minimal pour la documentation docstring.
2.
3.
# Minimum line length for functions/classes that require
# docstrings, shorter ones are exempt.
docstring-min-length=1
Puis, il est possible d’imposer une vérification sur la documentation : https://docs.pylint.org/en/1.6.0/extensions.html#parameter-documentation-checker. Pour cela, dans la liste des plugins, on ajoute pylint.extensions.docparams. Ceci permet de vérifier que la documentation suit l’une des trois conventions Sphinx, Google ou Numpy.
2.
3.
4.
# List of plugins (as comma separated values of python
# module names) to load, usually to register additional
# checkers.
load-plugins=pylint.extensions.docparams
Cependant, ceci ne permet de vérifier la documentation que lorsqu’elle est présente, et ne vérifie les paramètres et les retours que s’ils sont au moins en partie documentés. Pour forcer la présence de documentation de ceux-ci, il faut ajouter dans la section [BASIC] les paramètres suivants :
2.
3.
4.
5.
[BASIC]
# Enforce all elements of docstring to be present if needed accept-no-param-doc = no
accept-no-raise-doc = no
accept-no-return-doc = no
accept-no-yields-doc = no
VII. Exemple▲
À titre d'exemple, vous trouverez ci-dessous, un fichier de configuration qui avait été généré automatiquement comme indiqué précédemment et qui a été modifié pour obtenir une version simplifiée.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
[MASTER]
# List of plugins (as comma separated values of python module names) to load,
# usually to register additional checkers.
load-plugins=pylint.extensions.docparams
[MESSAGES CONTROL]
# Disable all messages and then only Fatal rules
# and conventions on naming style
disable=all
enable=F,
argument-naming-style,
attr-naming-style,
class-naming-style,
class-attribute-naming-style,
const-naming-style,
function-naming-style,
inlinevar-naming-style,
method-naming-style,
module-naming-style,
variable-naming-style
[BASIC]
# Enforce all elements of docstring to be present if needed.
accept-no-param-doc = no
accept-no-raise-doc = no
accept-no-return-doc = no
accept-no-yields-doc = no
# Minimum line length for functions/classes that require docstrings, shorter
# ones are exempt.
docstring-min-length=1
VIII. Conclusion et remerciements▲
Cet article a montré la mise en place du linter Pylint, pour une utilisation en ligne de commande et une intégration dans l'éditeur Visual Studio Code. Nous avons aussi montré comment activer ou désactiver des règles par l'intermédiaire d'une configuration éphémère (depuis la ligne de commande) ou d'une configuration permanente via un fichier de configuration .pylintrc.
Nous tenons à remercier Claude Leloup pour sa relecture orthographique.