Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
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
Debug
Known issues
breakingOlder versions of `flake8-docstrings` (before 1.0.0) supported Python 2.7. Modern versions, including 1.7.0, require Python 3.8 or later.fixEnsure 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.
affects: <1.0.0 (Python 2.7 support), >=1.0.0 (Python 3+), >=1.7.0 (Python 3.8+)
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.fixWhen 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.
affects: All versions
gotchaBy 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.fixAdd `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.
affects: All versions
gotchaWhen 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.fixIf 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.
affects: All versions
Errors
Common errors & fixes
D100 Missing docstring in public module
This error occurs when a public Python module, class, function, or method lacks a docstring, which is required by PEP 257 conventions.
fixAdd a triple-quoted docstring at the beginning of the module, class, function, or method, describing its purpose.
D205 1 blank line required between summary line and description
This error is triggered when a multi-line docstring's summary (first line) is not separated from the more detailed description by a single blank line, violating PEP 257.
fixEnsure there is exactly one blank line between the docstring's summary and its more elaborate description.
D400 First line should end with a period
This error indicates that the first line of a docstring (the summary line) does not end with a period, as recommended by PEP 257.
fixAppend a period to the end of your docstring's summary line.
D401 First line should be in imperative mood
This error occurs when the summary line of a docstring is not written in the imperative mood (e.g., 'Return' instead of 'Returns' or 'Returning'), which is a PEP 257 recommendation.
fixRephrase the docstring's summary line to start with an imperative verb (e.g., 'Return the ...', 'Validate the ...').
flake8-docstrings does not detect docstrings written in a non-default style (e.g., Google, NumPy)
By default, `flake8-docstrings` (via `pydocstyle`) uses the `pep257` convention. If your project uses a different docstring style like Google or NumPy, you need to explicitly configure `flake8-docstrings` to use that convention.
fixSpecify the desired docstring convention in your `flake8` configuration file (e.g., `.flake8`, `setup.cfg`, `pyproject.toml`) by adding `docstring-convention = google` or `docstring-convention = numpy` under the `[flake8]` section, or by using the command-line flag `--docstring-convention=google`.
Upgrade
Version history
1.7.0latest on PyPI · released Jan 25, 2023
Audit
Dependencies
flake8requiredCore linter that flake8-docstrings extends.
pydocstylerequiredProvides the underlying docstring style checks.