pydoclint
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 quite a few style violations that darglint cannot.
Currently, pydoclint supports three docstring styles: numpy, Google, and Sphinx, with some minor style deviations.
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
- 1. Installation
- 2. Usage
- 3. Style violation codes
- 4. Additional notes for users
- 5. Notes for developers
1. Installation
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.)
2. Usage
2.1. As a native command line tool
pydoclint <FILE_OR_FOLDER>
Replace <FILE_OR_FOLDER> with the file/folder names you want, such as ..
2.2. As a flake8 plugin
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.
2.3. Native vs flake8
Should you use pydoclint as a native command line tool or a flake8 plugin? Here's comparison:
| Pros | Cons | |
|---|---|---|
| Native tool | Slightly faster; supports "baseline" [*]; supports inline # noqa |
Project-wide omission support coming soon [**] |
| 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.
**) Configuration-file / CLI-based suppression controls are planned for a future release.
Tip: In native mode you can suppress DOC violations inline with
# noqa: DOCxxx. Use the--native-mode-noqa-locationoption (valid values: "docstring" or "definition") to decide whether the comment lives on the definition line or at the end of the docstring (after the triple quotes).
2.4. As a pre-commit hook
pydoclint can be use as a pre-commit hook, both in the "native" mode or as a flake8 plugin.
To use it, put the following in your .pre-commit-config.yaml file:
2.4.1. Native mode
- repo: https://github.com/jsh9/pydoclint
rev: <latest_tag>
hooks:
- id: pydoclint
args: [--style=google, --check-return-types=False]
(Replace <latest_tag> with the latest release tag in
https://github.com/jsh9/pydoclint/releases)
2.4.2. As a flake8 plugin
- repo: https://github.com/jsh9/pydoclint
rev: <latest_tag>
hooks:
- id: pydoclint-flake8
args: [--style=google, --check-return-types=False]
2.5. How to configure pydoclint
pydoclint offers many configuration options for you to tune it according to your team's style convention and preference. Inline suppression is already available; broader suppression toggles via config files and CLI flags will arrive shortly.
Please read this page for instructions on configuring pydoclint: How to configure pydoclint
2.6. How to ignore certain violations
Please read this page: How to ignore certain violations
2.7. Additional tips, tricks, and pitfalls
2.7.1. How to not document certain functions?
If you don't write any docstring for a function, pydoclint will not check it.
Also, if you write a docstring with only a description (without the argument
section, the return section, etc.), pydoclint will not check this docstring,
because the --skip-checking-short-docstrings is True by default. (You can
set it to False.)
2.7.2. How to gradually adopt pydoclint?
pydoclint provides a "baseline" feature that allows you to log the current violation state of your existing project. You'll only need to fix new style violations, and you can fix the "baseline" violations later.
You can use "baseline" with these 3 config options:
--baseline--generate-baseline--auto-regenerate-baseline
For more details, please read the documentations on these options.
2.7.3. Pitfall: default values of arguments
pydoclint does not like adding default values of arguments in the docstring, even if this style is allowed in the numpy docstring style guide.
For more rationale, please read this page.
3. Style violation codes
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" and "assert" statementsDOC6xx: Violations about class attributes
For detailed explanations of each violation code, please read this page: pydoclint style violation codes.
4. Additional notes for users
Here are some additional notes to help you use pydoclint more easily:
- Notes for users
- (Contains frequently encountered issues)
- Checking class attributes
- Names with leading underscores
- Notes on
GeneratorvsIterator - More about docstring style mismatch (
DOC003)
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.
5. Notes for developers
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.
1 maintainer
Metadata
1 maintainer
Release files for pydoclint 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pydoclint-0.10.0.tar.gz | 221.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pydoclint-0.10.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 311.6 kB
Release files / pydoclint-0.10.0.tar.gz
| Download URL | pydoclint-0.10.0.tar.gz |
|---|---|
| Size | 221.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
248cf17f43fceb8c6c70ed143c6b89efdb8029b6e70b44e655316713b0af71c3
|
|
BLAKE2b-256 checksum How to use checksums |
f66b4a5f2916ec04191394eba75500ab4fe978703442c1c1606f0fc67bc72834
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pydoclint-0.10.0-py3-none-any.whl
| Download URL | pydoclint-0.10.0-py3-none-any.whl |
|---|---|
| Size | 90.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
752b30542b060c19c016134fc8438614489c3b8c0f5c715112dbe53ed90110b8
|
|
BLAKE2b-256 checksum How to use checksums |
ad189dc98449392814ebbf990b9c88e7617aa8dd2ba50bc6d379fedfd69df0b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
