A Python docstring linter to check whether a docstring's sections (arguments, returns, raises, ...) match the function signature or function implementation.
It runs really fast. In fact, it is at least ~1,475 times faster than darglint (another linter of the same purposes which is no longer maintained).
Here is a comparison of linting time on some famous Python projects:
pydoclint | darglint | |
---|---|---|
numpy | 2.0 sec | 49 min 9 sec (1,475x slower) |
scikit-learn | 2.4 sec | 3 hr 5 min 33 sec (4,639x slower) |
Currently, pydoclint supports two docstring styles:
- The numpy stlyle
- The Google style
Support for the Sphinx style may be added in the future if there are requests for it.
Another note: this linter and pydocstyle serves complementary purposes. It is recommended that you use both together.
pip install pydoclint
Note that pydoclint currently only supports Python 3.8 and above. (Python 3.7 support may be added if there are interests and requests.)
pydoclint <FILE_OR_FOLDER>
Replace <FILE_OR_FOLDER>
with the file/folder names you want, such as .
.
Once you install pydoclint you will have also installed flake8. Then you can run:
flake8 --select=DOC <FILE_OR_FOLDER>
If you don't include --select=DOC
in your command, flake8 will also run
other built-in flake8 linters on your code.
Should I use pydoclint as a native command line tool or a flake8 plugin? Here's comparison:
Pros | Cons | |
---|---|---|
Native tool | Slightly faster | No inline or project-wide omission support right now [*] |
flake8 plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together |
*) This feature may be added in the near future
Here is how to configure pydoclint. For detailed explanations of all options, see Section 4 below.
-
Native:
pydoclint --check-arg-order=False <FILE_OR_FOLDER_PATH>
-
Flake8:
flake8 --check-arg-order=False <FILE_OR_FOLDER_PATH>
-
Native:
-
In a
.toml
file somewhere in your project folder, add a section like this (put in the config that you need):[tool.pydoclint] style = 'google' exclude = '\.git|\.tox|tests/data|some_script\.py' require-return-section-when-returning-none = true
-
Then, specify the path of the
.toml
file in your command:pydoclint --config=path/to/my/config.toml <FILE_OR_FOLDER_PATH>
-
-
Flake8:
- In your flake8 config file (see
flake8's official doc),
add the config you need under the section
[flake8]
- In your flake8 config file (see
flake8's official doc),
add the config you need under the section
pydoclint currently has the following style violation codes:
Code | Explanation |
---|---|
DOC001 |
Potential formatting errors in docstring |
Code | Explanation |
---|---|
DOC101 |
Docstring contains fewer arguments than in function signature |
DOC102 |
Docstring contains more arguments than in function signature |
DOC103 |
Docstring arguments are different from function arguments. (Or could be other formatting issues: https://github.com/jsh9/pydoclint#notes-on-doc103) |
DOC104 |
Arguments are the same in the docstring and the function signature, but are in a different order. |
DOC105 |
Argument names match, but type hints do not match |
Other potential causes to DOC103
include:
- Numpy docstring style requires this style:
arg1 : int
(a space betweenarg1
and:
) but people sometimes writearg1: int
. This will triggerDOC103
. - In the Google style, writing an
Args:
section without the preceding summary will also triggerDOC103
.
Code | Explanation |
---|---|
DOC201 |
Function/method does not have a return section in docstring |
DOC202 |
Function/method has a return section in docstring, but there are no return statements or annotations |
Note on DOC201
: Methods with @property
as its last decorator do not need to
have a return section.
Code | Explanation |
---|---|
DOC301 |
__init__() should not have a docstring; please combine it with the docstring of the class |
DOC302 |
The class docstring does not need a "Returns" section, because __init__() cannot return anything |
DOC303 |
The __init__() docstring does not need a "Returns" section, because it cannot return anything |
DOC304 |
Class docstring has an argument/parameter section; please put it in the __init__() docstring |
DOC305 |
Class docstring has a "Raises" section; please put it in the __init__() docstring |
DOC306 |
The class docstring does not need a "Yields" section, because __init__() cannot yield anything |
DOC307 |
The __init__() docstring does not need a "Yields" section, because __init__() cannot yield anything |
Code | Explanation |
---|---|
DOC401 |
Function/method returns a Generator, but the docstring does not have a "Yields" section |
DOC402 |
Function/method has "yield" statements, but the docstring does not have a "Yields" section |
DOC403 |
Function/method has a "Yields" section in the docstring, but there are no "yield" statements or a Generator return annotation |
Code | Explanation |
---|---|
DOC501 |
Function/method has "raise" statements, but the docstring does not have a "Raises" section |
DOC502 |
Function/method has a "Raises" section in the docstring, but there are not "raise" statements in the body |
There are several configuration options available. They can be used invidually or together.
This flag activates the "quite mode", in which no output will be printed to the command line if there are no violations.
By default, this flag is not activated, so the files that are scanned are printed in the command line.
pydoclint --quiet <FILE_OR_FOLDER>
This option is only available in the "native" command-line mode, rather than in flake8. If you use pydoclint in flake8, please use flake8's own verbosity configuration instead.
You can use this option to exclude files within the given folder. It is a regex pattern of full file paths.
For example:
pydoclint --exclude='\.git|\.tox|tests/data' <FOLDER_NAME>
This option is only available in the native command-line mode. If you use
pydoclint within flake8, you can use flake8's
--exclude
option.
Which style of docstring is your code base using. Right now there are two
available choices: numpy
and google
. The default value is numpy
.
pydoclint --style=google <FILE_OR_FOLDER>
or
flake8 --style=google <FILE_OR_FOLDER>
If True
, the type hints in the docstring and in the Python code need to
exactly match.
To turn this option on/off, do this:
pydoclint --check-type-hint=False <FILE_OR_FOLDER>
or
flake8 --check-type-hint=False <FILE_OR_FOLDER>
If True
, the input argument order in the docstring needs to match that in the
function signature.
To turn this option on/off, do this:
pydoclint --check-arg-order=False <FILE_OR_FOLDER>
or
flake8 --check-arg-order=False <FILE_OR_FOLDER>
If True
, pydoclint
won't check functions that have only a short description
in their docstring.
To turn this option on/off, do this:
pydoclint --skip-checking-short-docstrings=False <FILE_OR_FOLDER>
or
flake8 --skip-checking-short-docstrings=False <FILE_OR_FOLDER>
If True
, pydoclint won't report DOC501
or DOC502
if there are raise
statements in the function/method but there aren't any "raises" sections in the
docstring (or vice versa).
If it is set to True
, having a docstring for class constructors
(__init__()
) is allowed, and the arguments are expected to be documented
under __init__()
rather than in the class docstring.
If False
, a "return" section is not necessary in the docstring if the
function implicitly returns None
(for example, doesn't have a return
statement, or has -> None
as the return annotation).