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

1. Installation
2. Usage
3. Style violation codes
4. Additional notes for users
5. Notes for developers
6. Miscellaneous notes

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" [*]	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

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.

Please read this page for instructions on configuring pydoclint:
How to configure pydoclint

2.6. How to ignore certain violations in flake8 mode

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 issues
DOC1xx: Violations about input arguments
DOC2xx: Violations about return argument(s)
DOC3xx: Violations about class docstring and class constructor
DOC4xx: Violations about "yield" statements
DOC5xx: Violations about "raise" and "assert" statements
DOC6xx: Violations about class attributes

For detailed explanations of each violation code, please read this page:
pydoclint style violation codes.

4. Additional notes for users

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.

6. Miscellaneous notes

Dependencies of pydoclint (4).
Dependency	Optional
click	false
docstring_parser_fork	false
tomli	false
flake8	true

Package profile

pydoclint

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description