flake8-docstrings

1.7.0 · active · verified Fri Apr 10

flake8-docstrings is an extension for the `flake8` linter that integrates `pydocstyle` to enforce PEP 257 docstring conventions and other common docstring styles. It allows developers to check for issues like missing docstrings, incorrect formatting, and adherence to specific style guides (e.g., Google, NumPy) directly within their `flake8` workflow. The current stable version is 1.7.0, and it maintains an active release cadence.

Warnings

breaking Older versions of `flake8-docstrings` (before 1.0.0) supported Python 2.7. Modern versions, including 1.7.0, require Python 3.8 or later.
Fix: Ensure your project uses Python 3.8 or a newer compatible version. For older Python 3 versions, consider pinning an earlier `flake8-docstrings` version if necessary, though it's recommended to upgrade Python.
gotcha `flake8-docstrings` acts as a wrapper for `pydocstyle`. While `flake8-docstrings` integrates `pydocstyle` into `flake8`, the actual docstring checks and their error codes (e.g., D100, D205) originate from `pydocstyle`. Issues with specific docstring check logic or behavior should often be reported to the `pydocstyle` project.
Fix: When debugging docstring issues, refer to `pydocstyle`'s documentation for specific error codes and their meaning. If you believe a check is incorrect, consider checking `pydocstyle`'s issue tracker or reporting there directly.
gotcha By default, `pydocstyle` (and thus `flake8-docstrings`) enforces PEP 257. If your project uses other docstring conventions like Google or NumPy style, you must explicitly configure `flake8` with `--docstring-convention google` or `--docstring-convention numpy`. Without this, non-PEP 257 compliant docstrings will trigger many errors.
Fix: Add `docstring-convention = google` (or `numpy`) to your `[flake8]` configuration in `setup.cfg`, `.flake8`, or `tox.ini`. You may also need to `extend-ignore` specific `pydocstyle` codes that conflict with your chosen style.
gotcha When using `docstring-convention = all` (which enables all `pydocstyle` rules), you might encounter conflicting checks, as `pydocstyle` itself defines some mutually exclusive rules. This will lead to many false positives or undesirable warnings.
Fix: If using `docstring-convention = all`, carefully review the generated errors and use `extend-ignore` in your `flake8` configuration to disable conflicting or unwanted `pydocstyle` (D-prefixed) codes.

Install

pip install flake8-docstrings Install stable version

Quickstart

After installation, `flake8-docstrings` automatically integrates with `flake8`. You can run `flake8` as usual. To apply specific docstring conventions (like Google or NumPy style) or to ignore certain checks, configure `flake8` using a configuration file (e.g., `setup.cfg`, `.flake8`, `tox.ini`) under the `[flake8]` section, or via command-line arguments like `--docstring-convention`.

# my_module.py
def my_function(arg):
    """This is a missing docstring summary.

    :param arg: An argument.
    :return: None
    """
    pass

# Configure in setup.cfg, .flake8, or tox.ini
# [flake8]
# docstring-convention = google
# extend-ignore = D205,D212,D415 # Common ignores for Google style

# Run flake8 from your terminal
# $ flake8 my_module.py

view raw JSON →