Comment désactiver les avertissements "docstring manquant" au niveau d'un fichier dans Pylint ?

Question

Pylint envoie des messages d'erreur indiquant qu'il manque des chaînes de caractères à certains fichiers. J'essaie d'ajouter des docstrings à chaque classe, méthode et fonction, mais il semble que Pylint vérifie également que les fichiers doivent avoir un docstring au début. Puis-je désactiver cela d'une manière ou d'une autre ?

J'aimerais être informé de l'absence d'une docstring dans une classe, une fonction ou une méthode, mais il ne devrait pas être obligatoire pour un fichier d'avoir une docstring.

(Existe-t-il un terme pour désigner le jargon juridique que l'on trouve souvent au début d'un fichier source propriétaire ? Des exemples ? Je ne sais pas si c'est bien de poster séparément une question aussi triviale).

Answer 1

Il est intéressant pour un module Python d'avoir une docstring, expliquant ce que fait le module, ce qu'il fournit, des exemples d'utilisation des classes. Ceci est différent des commentaires que l'on voit souvent au début d'un fichier, donnant les informations de copyright et de licence, qui IMO ne devraient pas figurer dans la docstring (certains soutiennent même qu'ils devraient disparaître complètement, voir par ex. Se débarrasser des modèles de code source )

Avec Pylint 2.4 et plus, vous pouvez faire la distinction entre les différents types de missing-docstring en utilisant les trois sous-messages suivants :

• C0114 ( missing-module-docstring )
• C0115 ( missing-class-docstring )
• C0116 ( missing-function-docstring )

Ainsi, le texte suivant .pylintrc devrait fonctionner :

[MASTER]
disable=
    C0114, # missing-module-docstring

Pour les versions précédentes de Pylint, il n'y a pas de code séparé pour les différents endroits où les docstrings peuvent apparaître, donc tout ce que vous pouvez faire est de désactiver C0111 . Le problème est que si vous désactivez cette fonction au niveau du module, elle sera désactivée partout dans le module (c'est-à-dire que vous n'obtiendrez aucune ligne C pour une fonction / classe / méthode manquante dans la docstring. Ce qui n'est pas très agréable.

Je suggère donc d'ajouter cette petite docstring manquante, en disant quelque chose comme :

"""
high level support for doing this and that.
"""

Assez rapidement, vous trouverez des choses utiles à y mettre, comme des exemples d'utilisation des différentes classes/fonctions du module qui n'appartiennent pas nécessairement aux docstrings individuels des classes/fonctions (comme la façon dont elles interagissent, ou quelque chose comme un guide de démarrage rapide).

Answer 2

Comme mentionné par followben dans les commentaires, une meilleure solution consiste à désactiver les règles que nous voulons désactiver plutôt que d'utiliser la fonction --errors-only . Cette opération peut être réalisée à l'aide de --disable=<msg ids>, -d <msg ids> .

La liste des ID de messages est disponible aquí . Pour l'erreur spécifique mentionnée dans la question, l'ID du message est le suivant C0111 .

Pour l'utilisation de --disable= param dans votre choix d'IDE ou d'éditeur de texte, vous devrez trouver comment le faire.

Pour VS Code, cela peut être fait en ajoutant ceci dans settings.json :

"python.linting.pylintArgs": ["--disable=C0111"]

Answer 3

Il suffit de placer les lignes suivantes au début de tout fichier pour lequel vous souhaitez désactiver ces avertissements.

# pylint: disable=missing-module-docstring
# pylint: disable=missing-class-docstring
# pylint: disable=missing-function-docstring

Answer 4

Je voulais juste ajouter à ce que @Milovan Tomašević affichée ci-dessus. J'ai décidé d'utiliser python.linting.pylintArgs dans le code VSCode paramètres globaux car c'était bien plus pratique que d'utiliser un .pylintrc fichier.
De plus, au lieu d'utiliser un identifiant pour le commutateur (tel que C0115 ), j'ai utilisé les noms symboliques.

Référence complète à Les options et les commutateurs de Pylint sont ici .

{
    "python.linting.pylintArgs": [
        "--disable=missing-class-docstring",
        "--disable=missing-function-docstring"
    ]
}

Answer 5

Dans mon cas, avec Pylint 2.6.0, les messages de docstring manquants ne disparaissaient pas, même après la désactivation explicite de missing-module-docstring , missing-class-docstring y missing-function-docstring dans mon .pylintrc fichier. Finalement, la configuration suivante a fonctionné pour moi :

[MESSAGES CONTROL]

disable=missing-docstring,empty-docstring

Apparemment, Pylint 2.6.0 valide toujours les chaînes de documents à moins que les deux contrôles ne soient désactivés.