Pydoclint is 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: numpy, Google, and Sphinx.
Another note: this linter and pydocstyle serves complementary purposes. It is recommended that you use both together.
The full documentation of pydoclint (including this README) can be found here: https://jsh9.github.io/pydoclint
The corresponding Github repository of pydoclint is: https://github.com/jsh9/pydoclint
Table of Contents
To install only the native pydoclint tooling, run this command:
pip install pydoclint
To use pydoclint as a flake8 plugin, please run this command, which will also install flake8 to the current Python environment:
pip install pydoclint[flake8]
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: [--style=google, --check-return-types=False]
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; supports “baseline” [*] | 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 |
*) “Baseline” allows you to log the current violation state of your existing project, making adoption of pydoclint much easier.
**) This feature may be added in the near future
pydoclint offers many configuration options for you to tune it according to your team’s style convention and preference.
Please read this page for instructions on configuring pydoclint: How to configure pydoclint
Please read this page: How to ignore certain violations
pydoclint currently has 7 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” statementsDOC6xx: Violations about class attributesFor 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.
Specifically, there is a section in the additional notes on how to easily adopt pydoclint for existing legacy projects.
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.