Tutoriel pour apprendre à utiliser Pylint en ligne de commande et sous Visual Studio Code

| Jennie Andersen | Mickael Baron |

Cet article est une introduction au linter Pylint, un vérificateur de code qui permet de signaler les erreurs Python ainsi que toutes les parties de code qui ne respectent pas un ensemble de conventions. Il permet donc d’éviter les erreurs et d’avoir un code homogène. Les règles qu’impose Pylint par défaut suivent le guide de style Python PEP 8 https://www.python.org/dev/peps/pep-0008. L'article présentera également l'utilisation de Pylint en ligne de commande et son intégration avec Visual Studio Code.

Pour réagir au contenu de cet article, un espace de dialogue vous est proposé sur le forum Commentez .

- Titre : Tutoriel pour apprendre à utiliser Pylint en ligne de commande et sous Visual Studio Code

- Auteurs : Jennie Andersen, Mickael Baron

- Parution : 25 juin 2020

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2020 Jennie Andersen. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Prérequis logiciel

- II. Installation

- III. Utilisation

- IV. Configuration

- IV-A. Ligne de commande

- IV-B. Fichier de configuration

- IV-C. Annotations

- V. Intégration avec Visual Studio Code

- VI. Quelques ajouts intéressants

- VII. Exemple

- VIII. Conclusion et remerciements

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 pylint

Vous pouvez vous assurer que l'outil pylint est installé en exécutant la ligne de commande suivante :

1. $ pip show pylint

2. Version: 2.5.2

3. Summary: python code static checker

4. Home-page: https://github.com/PyCQA/pylint

5. Author: Python Code Quality Authority

6. Author-email: code-quality@python.org

7. License: GPL

8. Location: /Users/USER/Library/Python/3.7/lib/python/site-packages

9. Requires: mccabe, isort, astroid, toml

10. 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_module

Ou :

pylint directory/my_module.py

Pour analyser tous les modules d’un package :

pylint my_package

Il 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-name

Ou pour désactiver toutes les règles de convention (caractérisées pas la lettre C) :

$ pylint package/module.py --disable=C

Pour 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 >.pylintrc

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

1. # Minimum line length for functions/classes that require

2. # docstrings, shorter ones are exempt.

3. 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-rcfile

IV-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-member

Ce 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.

1. # Minimum line length for functions/classes that require

2. # docstrings, shorter ones are exempt.

3. 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.

1. # List of plugins (as comma separated values of python

2. # module names) to load, usually to register additional

3. # checkers.

4. 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 :

1. [BASIC]

2. # Enforce all elements of docstring to be present if needed accept-no-param-doc = no

3. accept-no-raise-doc = no

4. accept-no-return-doc = no

5. 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.

1. [MASTER]

3. # List of plugins (as comma separated values of python module names) to load,

4. # usually to register additional checkers.

5. load-plugins=pylint.extensions.docparams

7. [MESSAGES CONTROL]

9. # Disable all messages and then only Fatal rules

10. # and conventions on naming style

11. disable=all

12. enable=F,

13. argument-naming-style,

14. attr-naming-style,

15. class-naming-style,

16. class-attribute-naming-style,

17. const-naming-style,

18. function-naming-style,

19. inlinevar-naming-style,

20. method-naming-style,

21. module-naming-style,

22. variable-naming-style

23. [BASIC]

24. # Enforce all elements of docstring to be present if needed.

25. accept-no-param-doc = no

26. accept-no-raise-doc = no

27. accept-no-return-doc = no

28. accept-no-yields-doc = no

29. # Minimum line length for functions/classes that require docstrings, shorter

30. # ones are exempt.

31. 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.