Reputation: 44988

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

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

Upvotes: 213

Answers (18)

Glib Martynenko

Reputation: 338

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"
  ]

2024 - Documentation:

Three args are necessary to disable doc, module and functions documentation:

Upvotes: 11

Christopher Adams

Reputation: 1290

I couldn't find this anywhere and this is the only thing that actually worked. I searched in settings for pylint and noticed the syntax looked different that was was being explained in comments here. This is my exact user > settings.json file and how I was able to get it so no linting errors showed for docs-strings in VS Code.

{
    "workbench.colorTheme": "Default High Contrast",
    "editor.fontSize": 15,
    "debug.console.fontSize": 16,
    "terminal.integrated.fontSize": 16,
    "terminal.integrated.defaultProfile.osx": "bash",
    "editor.tabSize": 2,
    "[python]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4
      },
      "pylint.args": [
        "--disable=missing-class-docstring",
        "--disable=missing-function-docstring",
        "--disable=missing-module-docstring"
      ]
}

After changing that file I did a CMD+shift+P and search for Developer reload window and did a reload of VS code. Save your python file, and you should not see the linting error for doc string.

Upvotes: 1

Michał Jabłoński

Reputation: 1277

For ruff users that would be

[lint]
select = ["D"] # enable docstring checks in ruff
ignore = ["D100"] # ignore missing module docstring

inside your ruff.toml file.

Upvotes: 0

Mohsen Bashash

Reputation: 31

Open User Settings(JSON) and copy and paste the following lines in between the the curly braces, then save and exit the file.

"pylint.args": [
    "disable=missing-module-docstring",
    "disable=missing-class-docstring",
    "disable=missing-function-docstring"
]

This worked for me out of the above solution.

Upvotes: 3

aaronlhe

Reputation: 1132

For me, I like to have total control on where and when I put my docstrings without having VSCode (or any IDE / code editor) throw visual chaos at me - hence I have simply inserted

[pylint.messages control]
disable = missing-docstring

in my .pylintrc file. This file is not committed e.g. part of gitignore - hence each team member working on the project can have their own setting. This only works if there is already a standard that the project adheres to (else everyone will be doing their own thing with these comments and docstrings and its chaos) - so make sure you know what you're doing before using this setup. works with teams that have been working together for a long time and who adhere to internal standards on how to write code for the project.

Upvotes: 0

Nilesh Kevlani

Reputation: 1336

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"]

Upvotes: 117

howdoicode

Reputation: 961

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

Upvotes: 17

Milovan Tomašević

Reputation: 8673

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

Upvotes: 8

Ernesto Elsäßer

Reputation: 1267

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.

Upvotes: 15

Mohammed Hrima

Reputation: 22

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

"python.linting.pydocstyleEnabled": false

Upvotes: 0

Mohamed Atef

Reputation: 627

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

Upvotes: 5

Keven Li

Reputation: 634

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

Upvotes: 27

aarw76

Reputation: 87

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

Upvotes: 5

Pierre.Sassoulas

Reputation: 4282

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

Upvotes: 13

henryJack

Reputation: 4614

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

Upvotes: 7

mattsl

Reputation: 428

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

Upvotes: 13

gurney alex

Reputation: 13645

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

Upvotes: 215

Carlos E Rodriguez

Reputation: 319

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.

Upvotes: 11

How do I disable &quot;missing docstring&quot; warnings at a file-level in Pylint?

Answers (18)

2024 - Documentation:

Related Questions

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