Missing function docstring python

Last updated: Jun 8, 2023
Reading time · 3 min

banner

# Disable the ‘Missing module docstring’ Pylint warning

The «Missing module docstring pylint(missing-module-docstring)» warning is shown when a module has no docstring.

One way to get rid of the warning is to specify a documentation string on the first line of the module.

Copied!
"""Module has a function that prints the name of my site""" def print_site_name(): site = 'bobbyhadz.com' print(site)

Note that empty modules don’t require a docstring.

The module’s docstring is specified on the first line using a triple-quoted string.

If you add the code above to a Python file, you will see that the «Missing module docstring» warning is no longer shown.

However, you might now be seeing the warning «Missing function or method docstring pylint(missing-function-docstring)».

You can add a documentation string below the function’s definition line def abc(): to describe what the function does.

Copied!
"""Module has a function that prints the name of my site""" def print_site_name(): """Function printing the name of my site""" site = 'bobbyhadz.com' print(site)

Now the main.py module has a documentation string and a docstring for the function, so the warnings are no longer shown.

If you work with classes, you might get the «Missing class docstring pylint(missing-class-docstring)» Pylint warning.

You have to add a documentation string to the class just like in the previous examples.

Copied!
"""Module has a function that prints the name of my site""" class Employee(): """Used to create Employee instances""" def __init__(self, name): self.salary = 100 self.name = name

Make sure to also set a docstring in your methods.

Copied!
"""Module has a function that prints the name of my site""" class Employee(): """Used to create Employee instances""" def __init__(self, name): self.salary = 100 self.name = name def print_name(self): """Prints the name of the employee instance""" print(self.name)

The print_name method of the Employee class also has a documentation string.

# Disabling the ‘Missing module docstring’ warning in pylintrc

You can also disable the «Missing module docstring» warning in your pylintrc file.

In your pylintrc file, find the disable key and add the following 3 values:

Copied!
disable=missing-module-docstring, missing-function-docstring, missing-class-docstring

The example disables the 3 warnings but you can adjust this depending on your needs.

After I’ve saved the pylintrc and restarted Visual Studio Code, no warnings are shown in the following file.

Copied!
def print_site_name(): site = 'bobbyhadz.com' print(site) class Employee(): def __init__(self, name): self.salary = 100 self.name = name def print_name(self): print(self.name)

# Disabling the ‘Missing module docstring’ warning in Visual Studio Code

You can also disable the warning directly in Visual Studio Code.

Type user settings json.
Click on Preferences: Open User Settings (JSON)

Copied!
 "python.linting.pylintArgs": [ "--disable=missing-module-docstring", "--disable=missing-function-docstring", "--disable=missing-class-docstring" ], >

Make sure to add the —disable= keys to your existing python.linting.pylintArgs array if it already exists in settings.json .
Make sure to remove the trailing comma if the property comes last.

Save the settings.json file and the missing module docstring warning will be disabled.

If you only want to disable the warning for your current project, use the local .vscode/settings.json file instead.

In the root directory of your project, create a .vscode folder.
Create a settings.json file in the .vscode folder.
Add the following code to your settings.json file.

Copied!
 "python.linting.pylintArgs": [ "--disable=missing-module-docstring", "--disable=missing-function-docstring", "--disable=missing-class-docstring" ] >

The properties in your local .vscode/setting.json only apply to the current project and override any global configuration.

If the issue persists, restart Visual Studio Code.

If you get the warning «String statement has no effect Pylint (pointless-string-statement)», check out the following article.

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.

Источник

Saved searches

Use saved searches to filter your results more quickly

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Erroneous missing-function-docstring with Generics #3605

Comments

This might be related to existing bugs such as #2568,
but I’m running into some false positive errors when using generics with class hierarchies.

Steps to reproduce

Run pylint on a module containing the following code:

"""Module docs.""" # pylint: disable=too-few-public-methods, invalid-name from typing import Generic, TypeVar T = TypeVar('T') class Class1(Generic[T]): """Class Docs.""" def method1(self): """Method Docs.""" class Class2(Class1[T]): """Class Docs.""" class Class3a(Class2[T]): """Class Docs.""" def method1(self): pass class Class3b(Class2): """Class Docs.""" def method1(self): pass class Class3c(Class1[T]): """Class Docs.""" def method1(self): pass

Current behavior

Although a doc-string is defined for method1 in Class1, which Class3a inherits from, Pylint reports
test.py:23:4: C0116: Missing function or method docstring (missing-function-docstring)

Class3b and Class3c show two changes that will make the error go away (removing the generic parameter on Class2 and inheriting directly from Class1, respectively)

Expected behavior

No missing-docstring complaints.

pylint —version output

pylint 2.5.2
astroid 2.4.1
Python 3.7.7 (default, Mar 10 2020, 15:43:33)
[Clang 11.0.0 (clang-1100.0.33.17)]

The text was updated successfully, but these errors were encountered:

Источник

How do I disable «missing docstring» warnings at a file-level in Pylint in Python

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

You can add «—errors-only» flag for Pylint to disable warnings.

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

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.

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=': :,: ' | 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

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

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

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

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:

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.

Ctrl + Shift + P
Then type and click on > preferences:configure language specific settings
and then type «python» after that. Paste the code

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

Источник

Missing function docstring python

Saved searches

Use saved searches to filter your results more quickly

Erroneous missing-function-docstring with Generics #3605

Erroneous missing-function-docstring with Generics #3605

Comments

Steps to reproduce

Current behavior

Expected behavior

pylint —version output