pydoclint 0.5.0

A Python docstring linter that checks arguments, returns, yields, and raises sections

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
  • 2.1. As a native command line tool
  • 2.2. As a flake8 plugin
  • 2.3. As a pre-commit hook
  • 2.4. Native vs flake8
  • 2.5. How to configure pydoclint
  • 2.6. How to ignore certain violations in flake8 mode
• 3. Style violation codes
• 4. 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. As a pre-commit hook

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.

2.4. Native vs flake8

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

2.5. How to configure pydoclint

Please read this page: How to configure pydoclint

2.6. How to ignore certain violations in flake8 mode

Please read this page: How to ignore certain violations

3. Style violation codes

pydoclint currently has 6 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" statements

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

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