Pydocstyle

Warnings

• breaking The Pydocstyle project is officially deprecated and no longer actively maintained. Users are strongly recommended to migrate to Ruff, which offers full parity with pydocstyle and active development.
  Fix: Migrate your project's docstring linting to Ruff. Consult the Ruff documentation for migration instructions.
• deprecated Configuration files named `.pep257` and section headers `[pep257]` are deprecated for backwards compatibility. Support for these will be removed in a future major version, which is unlikely to happen given the project's deprecation.
  Fix: Use configuration files like `setup.cfg`, `tox.ini`, `.pydocstyle`, `.pydocstylerc`, or `pyproject.toml` with `[pydocstyle]` or `[tool.pydocstyle]` sections.
• gotcha When using Google or NumPy docstring conventions, pydocstyle might incorrectly default to checking for one style over the other if section names (e.g., 'Returns', 'Yields') overlap. This can lead to false positives or missed errors.
  Fix: Carefully review results when using Google or NumPy conventions. You may need to manually ignore specific errors (`--ignore`) or explicitly select convention checks (`--convention=numpy` or `--convention=google`) to align with your project's chosen style.
• gotcha Support for TOML configuration files (e.g., `pyproject.toml`) is only enabled if the `toml` Python package is installed. If it's missing, pydocstyle will not recognize your TOML configuration.
  Fix: Install pydocstyle with the `toml` extra: `pip install pydocstyle[toml]`.

Install

• pip install pydocstyle Install stable version

Imports

• run_check

  import pydocstyle
  # errors = pydocstyle.run_check(paths=['your_file.py'])

  Pydocstyle is primarily a command-line tool. Programmatic usage often involves internal APIs like `pydocstyle.run_check` for checking files directly or `pydocstyle.checker.Checker` for more fine-grained control. The most common use case is via the CLI.

Quickstart

Pydocstyle is typically used as a command-line tool. Create a Python file (e.g., `example.py`) with docstrings, then run pydocstyle against it. The `--ignore` or `--select` options allow for fine-grained control over which docstring style errors are reported.

import os

def my_function():
    """This is a sample function.

    It returns a string.
    """
    return "Hello"

# Save this to a file, e.g., `example.py`
# Then run from the command line:
# pydocstyle example.py
# You can also customize checks:
# pydocstyle --ignore=D100,D104 example.py