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:

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
  • 2.1. As a native command line tool
  • 2.2. As a flake8 plugin
  • 2.3. Native vs flake8
  • 2.4. As a pre-commit hook
    • 2.4.1. Native mode
    • 2.4.2. As a flake8 plugin
  • 2.5. How to configure pydoclint
  • 2.6. How to ignore certain violations
  • 2.7. Additional tips, tricks, and pitfalls
    • 2.7.1. How to not document certain functions?
    • 2.7.2. How to gradually adopt pydoclint?
    • 2.7.3. Pitfall: default values of arguments
• 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:

*) "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-location option (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 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

Here are some additional notes to help you use pydoclint more easily:

• Notes for users
  • (Contains frequently encountered issues)
• Checking class attributes
• Notes on Generator vs Iterator
• 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.