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

score 198 · Accepted Answer · edited Jan 21 '21 at 19:45

198

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

edited Jan 21 '21 at 19:45

Peter Mortensen

30,738
21
105
131

answered Oct 24 '11 at 16:21

gurney alex

13,247
4
43
57

14

+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. – Jonathan Hartley Jan 31 '12 at 15:16
25

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?" – Cerin Apr 16 '12 at 18:11
22

`$ cat my_module/test/__init__.py` `"Hey, PyLint? SHUT UP"` – clacke May 06 '15 at 12:50
2

Pylint says *`String statement has no effect (pointless-string-statement)`* when using your docstring example. – jww Apr 06 '19 at 15:14
6

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 Dec 12 '19 at 13:24

Nilesh Kevlani · Answer 2 · 2023-01-28T13:43:09.927

111

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 with --disable=<msg ids>, -d <msg ids>.

The list of message IDs can be found here. For the specific error mentioned in the question, the message ID is C0111.

For using --disable= param in your choise of IDE or Text Editor, you will need to figure out how to do it.

For VS Code, this can be done by adding this in settings.json:

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

edited Jan 28 '23 at 13:43

answered Nov 10 '17 at 16:35

Nilesh Kevlani

1,278
1
10
10

46

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. – followben Apr 06 '18 at 10:14
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. – Erik Aronesty Dec 12 '19 at 13:25
2

Nice fix but the downside to this method is it ignores unused variables – Caleb Mar 30 '21 at 16:46
1

@EricDuminil, thanks for pointing that out. I have updated the answer to specify that the mentioned solution is IDE / Text Editor specifc. – Nilesh Kevlani Jan 28 '23 at 13:46

score 19 · Answer 3 · edited Jan 21 '21 at 20:03

19

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

edited Jan 21 '21 at 20:03

Peter Mortensen

30,738
21
105
131

answered Jan 21 '20 at 07:29

Keven Li

524
3
8

3

If you want to disable everything you just need to disable `missing-docstring` (works for version prior to 2.4.0). – Pierre.Sassoulas Apr 26 '20 at 17:29
Wait, what? If you don't want to litter your code with uninformative docstrings, your solution is to litter them with boilerplate comments? – Eric Duminil Jan 27 '23 at 10:39

score 14 · Answer 4 · answered Nov 11 '21 at 02:54

I just wanted to add to what @Milovan Tomašević posted above. I decided to use python.linting.pylintArgs in VSCode's global settings, as it was far more convenient than using a .pylintrc file.
Also, instead of using an ID for the switch (such as C0115), I used the symbolic names instead.

Full reference to Pylint options and switches is here.

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

score 13 · Answer 5 · edited Jan 21 '21 at 19:48

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

score 12 · Answer 6 · edited Jan 21 '21 at 20:02

12

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

edited Jan 21 '21 at 20:02

Peter Mortensen

30,738
21
105
131

answered Sep 10 '19 at 13:31

Pierre.Sassoulas

3,733
3
33
48

score 11 · Answer 7 · answered Nov 23 '16 at 03:34

11

I think the fix is relative easy without disabling this feature.

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

All you need to do is add the triple double quotes string in every function.

answered Nov 23 '16 at 03:34

Carlos E Rodriguez

319
2
5

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 – Zerontelli Aug 15 '18 at 04:53

score 10 · Answer 8 · edited Jan 21 '21 at 20:10

In my case, with Pylint 2.6.0, the missing docstring messages wouldn't disappear, even after explicitly disabling missing-module-docstring, missing-class-docstring and missing-function-docstring in my .pylintrc file. Finally, the following configuration worked for me:

[MESSAGES CONTROL]

disable=missing-docstring,empty-docstring

Apparently, Pylint 2.6.0 still validates docstrings unless both checks are disabled.

score 7 · Answer 9 · edited Jan 21 '21 at 19:53

7

No. Pylint doesn't currently let you discriminate between doc-string warnings.

However, you can use Flake8 for all Python code checking along with the doc-string extension to ignore this warning.

Install the doc-string extension with pip (internally, it uses pydocstyle).

pip install flake8_docstrings

You can then just use the --ignore D100 switch. For example, flake8 file.py --ignore D100

edited Jan 21 '21 at 19:53

Peter Mortensen

30,738
21
105
131

answered Oct 02 '17 at 09:44

henryJack

4,220
2
20
24

score 6 · Answer 10 · answered Oct 17 '21 at 19:56

6

If you are a Visual Studio Code user who wants to ignore this, you can add python.linting.pylintArgs to .vscode/settings.json:

{
    ...
    "python.linting.pylintArgs": [
        "--disable=C0114",
        "--disable=C0115",
        "--disable=C0116",
    ],
    ...
}

answered Oct 17 '21 at 19:56

Milovan Tomašević

6,823
1
50
42

1

It looks like `"python.linting.pylintArgs": ["--disable=C0114,C0115,C0116"]` is also accepted. – Eric Duminil Feb 28 '23 at 09:46

score 5 · Answer 11 · edited Jan 21 '21 at 20:03

Edit file "C:\Users\Your User\AppData\Roaming\Code\User\settings.json" and add these python.linting.pylintArgs lines at the end as shown below:

{
    "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"
    ],
}

score 4 · Answer 12 · edited Jan 21 '21 at 20:06

4

Ctrl + Shift + P
Then type and click on > preferences:configure language specific settings

and then type "python" after that. Paste the code

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

edited Jan 21 '21 at 20:06

Peter Mortensen

30,738
21
105
131

answered Mar 27 '20 at 05:15

Mohamed Atef

477
4
6

This works for me. Try reloading the vscode. – Aamer Sep 03 '22 at 03:46

score 1 · Answer 13 · answered May 08 '23 at 17:47

1

I'm using VSCode (1.78.0) and it looks like they changed the parameters.
You should use

"pylint.args": [
"--disable=C0116",
"--disable=C0111",
"--disable=C0114"

]

answered May 08 '23 at 17:47

Glib Martynenko

128
1
9

python isn't a builtin VS Code extension. Likely the change you see is tied to an update in one of the Python extensions instead of VS Code itself. A link to an issue ticket / PR would be nice. – starball May 08 '23 at 18:50

score 0 · Answer 14 · edited Jan 21 '21 at 20:10

0

Go to file "settings.json" and disable the Python pydocstyle:

"python.linting.pydocstyleEnabled": false

edited Jan 21 '21 at 20:10

Peter Mortensen

30,738
21
105
131

answered Sep 16 '20 at 23:59

Mohammed Hrima

22
1

1

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. – Jarmos Apr 12 '21 at 08:52

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

14 Answers14

Linked