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 can be thousands of times faster than darglint (or its maintained fork darglint2).
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) |
Additionally, pydoclint can detect some quite a few style violations that darglint cannot.
Currently, pydoclint supports three docstring styles:
- The numpy stlyle
- The Google style
- The Sphinx style
Another note: this linter and pydocstyle serves complementary purposes. It is recommended that you use both together.
Table of Contents
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.
pydoclint is configured for pre-commit and can be
set up as a hook with the following .pre-commit-config.yaml
configuration:
- repo: https://github.com/jsh9/pydoclint
rev: <latest_tag>
hooks:
- id: pydoclint
args:
- "--config=pyproject.toml"
You will need to install pre-commit
and run pre-commit install
.
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
Please read this page: How to configure pydoclint
Please read this page: How to ignore certain violations
pydoclint currently has 6 categories of style violation codes:
DOC0xx
: Docstring parsing issuesDOC1xx
: Violations about input argumentsDOC2xx
: Violations about return argument(s)DOC3xx
: Violations about class docstring and class constructorDOC4xx
: Violations about "yield" statementsDOC5xx
: Violations about "raise" statements
For detailed explanations of each violation code, please read this page: pydoclint style violation codes.
If you'd like to use pydoclint for your project, it is recommended that you read these additional notes here.
If you'd like to contribute to the code base of pydoclint, thank you!
This guide can hopefully help you get familiar with the code base faster.