Comment désactiver les avertissements «docstring manquant» au niveau du fichier dans Pylint?


94

Pylint renvoie des erreurs selon lesquelles certains fichiers ne contiennent pas de docstrings. J'essaie d'ajouter des docstrings à chaque classe, méthode et fonction, mais il semble que Pylint vérifie également que les fichiers doivent être une docstring au début. Puis-je désactiver cela d'une manière ou d'une autre? Je voudrais être averti qu'une docstring est manquante 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 du jargon juridique que l'on trouve souvent au début d'un fichier source propriétaire? Des exemples? Je ne sais pas s'il est acceptable de publier une question aussi triviale séparément.)

Réponses:


106

C'est bien 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 vous voyez souvent au début d'un fichier donnant les informations de copyright et de licence, que l'OMI ne devrait pas inclure dans la docstring (certains soutiennent même qu'ils devraient disparaître complètement, voir par exemple http: // hackerboss. com / se débarrasser-des-modèles / )

Avec pylint 2.4 et supérieur, vous pouvez différencier les différents missing-docstringen utilisant les trois sous-messages suivants:

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

Donc, le .pylintrcfichier suivant devrait fonctionner:

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

Pour les versions précédentes de Pylint, il n'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 ceci à la portée du module, alors il sera désactivé partout dans le module (c'est-à-dire que vous n'obtiendrez aucune ligne C pour la docstring de fonction / classe / méthode manquante. Ce qui n'est sans doute pas agréable.

Donc, ce que je suggère d'ajouter cette petite docstring manquante, en disant quelque chose comme:

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

Bientôt, vous trouverez des éléments utiles à mettre là-dedans, comme fournir des exemples d'utilisation des différentes classes / fonctions du module qui n'appartiennent pas nécessairement aux docstrings individuels des classes / fonctions (comme comment ces interagir, ou quelque chose comme un guide de démarrage rapide).


9
+1 pour le passe-partout légal (et autre) disparaissant du code source. Chaque composant d'une voiture n'a pas de notifications légales jointes. Créez certainement un fichier contenant le texte légal de votre projet. N'en mettez pas de copies dans chaque fichier.
Jonathan Hartley

22
-1 pour les docstrings qui commencent "This is module foobar." La nature de ce module est déjà évidente. Le reformuler est redondant et a tendance à devenir obsolète si le module change de nom. Incluez simplement la partie «Fournit un support de haut niveau pour ceci et cela».
Jonathan Hartley

@JonathanHartley: d'accord. J'ai mis à jour la dernière partie de la réponse en conséquence.
gurney alex

16
Réponse décevante. Surtout pour les projets Django. forms.py "Ce sont des modèles ... JUST KIDDING! Ce sont des formulaires. Parce que, vous savez, le fichier s'appelle forms.py. Ce n'est pas le Da Vinci Code. Que pensez-vous qu'il y aurait ici?"
Cerin

10
$ cat my_module/test/__init__.py "Hey, PyLint? SHUT UP"
clacke

65

Il est tard, mais je l'ai toujours trouvé utile. Donc partager. J'ai trouvé ça ici .

Vous pouvez ajouter l'indicateur "--errors-only" pour pylint pour désactiver les avertissements.

Pour ce faire, allez dans les paramètres. Modifiez la ligne suivante:

"python.linting.pylintArgs": []

Comme

"python.linting.pylintArgs": ["--errors-only"]

Et vous êtes prêt à partir!


31
C'est utile, bien que "python.linting.pylintArgs": ["--disable=C0111"],probablement plus, car cela ne fait qu'atténuer les avertissements de docstring. Cependant, le réglage aborde la question de l'OP de savoir comment désactiver ces avertissements uniquement au niveau du module.
suivez le

C'est une meilleure option, car vous ne vous souciez que de l'erreur comme la classe manquante, ... au lieu d'un avertissement de chaîne de document
Zerontelli

Tellement triste quand je vois un projet qui a eu recours à cela. pylint est un très bon outil pour garder le code propre. Il a juste besoin d'un peu d'amour.
Erik Aronesty

9

Je pense que le correctif est relativement facile sans désactiver cette fonctionnalité.

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root

Tout ce que vous avez à faire est d'ajouter la chaîne de guillemets doubles triples dans chaque fonction.


Merci. Je viens de trouver que même les guillemets simples fonctionnent
vikas027

eh bien c'est toujours ennuyeux par exemple si vous travaillez sur un projet Django cela créera un tas de fichiers de module et vous devez aller dans chacun de ceux-ci pour le faire. Il vaut mieux n'afficher que le message d'erreur que l'avertissement avec "" --errors -only "dans les paramètres utilisateur du pylint
Zerontelli

8

Je suis venu chercher une réponse car, comme @cerin l'a dit, dans les projets Django, il est fastidieux et redondant d'ajouter des docstrings de module à chacun des fichiers que django génère automatiquement lors de la création d'une nouvelle application.

Donc, pour contourner le fait que pylint ne vous permet pas de spécifier une différence dans les types de docstring, vous pouvez le faire:

pylint */*.py --msg-template='{path}: {C}:{line:3d},{column:2d}: {msg}' | grep docstring | grep -v module

Vous devez mettre à jour le modèle de msg pour que lorsque vous grep vous connaissez toujours le nom du fichier. Cela renvoie tous les autres types de docstring manquants à l'exclusion des modules.

Ensuite, vous pouvez corriger toutes ces erreurs, puis exécutez simplement:

pylint */*.py --disable=missing-docstring

7

Non. Pylint ne vous permet actuellement pas de faire la distinction entre les avertissements de chaînes de documents.

Cependant, vous pouvez utiliser flake8 pour toutes les vérifications de code python avec l'extension doc-string pour ignorer cet avertissement.

Installez l'extension doc-string avec pip (en interne, il utilise pydocstyle ).

pip install flake8_docstrings

Vous pouvez alors simplement utiliser le --ignore D100commutateur. Par exempleflake8 file.py --ignore D100


5

Avec pylint 2.4 et supérieur, vous pouvez différencier les différents missing-docstringen utilisant les trois sous-messages suivants:

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

Donc, le .pylintrcfichier suivant devrait fonctionner:

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

qui a sauvé ma santé mentale
Tsagana Nokhaeva

5

Mettez simplement 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

1
Si vous voulez tout désactiver, il vous suffit de désactiver missing-docstring(fonctionne pour la version antérieure à 2.4.0).
Pierre.Sassoulas le

5

Modifiez "C: \ Users \ Your User \ AppData \ Roaming \ Code \ User \ settings.json" et ajoutez ces python.linting.pylintArgslignes à la fin comme indiqué ci-dessous:

{
    "team.showWelcomeMessage": false,
    "python.dataScience.sendSelectionToInteractiveWindow": true,
    "git.enableSmartCommit": true,
    "powershell.codeFormatting.useCorrectCasing": true,
    "files.autoSave": "onWindowChange",
    "python.linting.pylintArgs": [
        "--load-plugins=pylint_django",
        "--errors-only"
    ],
}

1

(1) CTRL + SHIFT + P (2) Puis tapez et cliquez sur> préférences: configurez les paramètres spécifiques au langage (3) puis tapez python après cela passé le code

{
"python.linting.pylintArgs": [
    "--load-plugins=pylint_django","--errors-only"
],

}

0

Allez dans "settings.json" et désactivez python pydocstyle

"python.linting.pydocstyleEnabled": false

0

Dans mon cas, avec pylint 2.6.0, les messages docstring manquants ne disparaîtraient pas, même après une désactivation explicite missing-module-docstring, missing-class-docstringet missing-function-docstringdans mon .pylintrcfichier. Enfin, la configuration suivante a fonctionné pour moi:

[MESSAGES CONTROL]

disable=missing-docstring,empty-docstring

Apparemment, pylint 2.6.0 valide toujours les docstrings à moins que les deux vérifications ne soient désactivées.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.