How do I disable "missing docstring" warnings at a file-level in Pylint?

Question

Pylint throws errors that some of the files are missing docstrings. I try and add docstrings to each class, method and function, but it seems that Pylint also checks that files should have a docstring at the beginning of them. Can I disable this somehow?

I would like to be notified of a docstring is missing inside a class, function or method, but it shouldn't be mandatory for a file to have a docstring.

(Is there a term for the legal jargon often found at the beginning of a proprietary source file? Any examples? I don't know whether it is a okay to post such a trivial question separately.)

Solution 1

It is nice for a Python module to have a docstring, explaining what the module does, what it provides, examples of how to use the classes. This is different from the comments that you often see at the beginning of a file giving the copyright and license information, which IMO should not go in the docstring (some even argue that they should disappear altogether, see e.g. Get Rid of Source Code Templates)

With Pylint 2.4 and above, you can differentiate between the various missing-docstring by using the three following sub-messages:

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

So the following .pylintrc file should work:

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

For previous versions of Pylint, it does not have a separate code for the various place where docstrings can occur, so all you can do is disable C0111. The problem is that if you disable this at module scope, then it will be disabled everywhere in the module (i.e., you won't get any C line for missing function / class / method docstring. Which arguably is not nice.

So I suggest adding that small missing docstring, saying something like:

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

Soon enough, you'll be finding useful things to put in there, such as providing examples of how to use the various classes / functions of the module which do not necessarily belong to the individual docstrings of the classes / functions (such as how these interact, or something like a quick start guide).

Solution 2

[Updated on 21 Dec 2021]

As mentioned by followben in the comments, a better solution is to just disable the rules that we want to disable rather than using --errors-only.

This can be done by adding this in settings:

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

[Old answer]

I found this here.

You can add "--errors-only" flag for Pylint to disable warnings.

To do this, go to settings. Edit the following line:

"python.linting.pylintArgs": []

As

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

And you are good to go!

Solution 3

I came looking for an answer because, as cerin said, in Django projects it is cumbersome and redundant to add module docstrings to every one of the files that Django automatically generates when creating a new application.

So, as a workaround for the fact that Pylint doesn't let you specify a difference in docstring types, you can do this:

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

You have to update the msg-template, so that when you grep you will still know the file name. This returns all the other missing-docstring types excluding modules.

Then you can fix all of those errors, and afterwards just run:

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

Solution 4

Just put the following lines at the beginning of any file you want to disable these warnings for.

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

Solution 5

With Pylint 2.4 and above you can differentiate between the various missing-docstring by using the three following sub-messages:

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

So the following .pylintrc file should work:

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

View more solutions

Comments

[Jonathan Hartley]

+1 for legal (and other) boilerplate disappearing from source code. Every component of a car does not have legal notifications attached. By all means create a file with your project's legal text in it. Don't put copies of that into every file.

[Cerin]

Disappointing answer. Especially for Django projects. forms.py "These are models...JUST KIDDING! They're forms. Because, you know, the file is named forms.py. This isn't the The Da Vinci Code. What did you think would be here?"

[clacke]

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

[followben]

It's useful, though "python.linting.pylintArgs": ["--disable=C0111"], is probably moreso as it just quiets docstring warnings. However setting addresses the OP's question of how to disable these warnings only at a module level.

[Zerontelli]

well it's still annoying for example if you working on a Django project it will create a bunch of module files and you have to go into each one of those to do it.It's better to only show error message than warning with ""--errors-only" in the pylint user settings

[jww]

Pylint says String statement has no effect (pointless-string-statement) when using your docstring example.

[Erik Aronesty]

The most important thing documentation needs to tell you is why a function is needed. If that's all your documentation does, then it's often good enough. The second most useful thing is "how" ... (recursive, thread-unsafe, hits the network api hard, etc.). The least important things is "what" it does .. this should be clear from the name and the associated unit tests and how clean and readably it's written. But, just remember "why first" and you'll know all you need to know about documentation.

[Erik Aronesty]

So sad when I see a project that has resorted to this. pylint is such a good tool for keeping code clean. It just needs some love.

[Pierre.Sassoulas]

If you want to disable everything you just need to disable missing-docstring (works for version prior to 2.4.0).

[Caleb Okai]

Nice fix but the downside to this method is it ignores unused variables

[Jarmos]

I believe you should also mention what that code snippet you share for the settings.json is meant for? For those of you wondering, it's for VSCode.