PyDocLint

0.8.3 · active · verified Wed Apr 15

PyDocLint is a fast Python docstring linter that verifies whether a function's docstring sections (arguments, returns, yields, and raises) accurately match its signature and implementation. It currently supports NumPy, Google, and Sphinx docstring styles, running significantly faster than older alternatives. The library is actively maintained with frequent releases, and its current version is 0.8.3.

Warnings

breaking Python 3.9 support was dropped in version 0.7.4. Users on older Python versions will need to upgrade their Python environment to at least 3.10 to use pydoclint 0.7.4 and newer.
Fix: Upgrade Python to 3.10 or higher, or pin pydoclint to a version older than 0.7.4.
gotcha Configuration file validation was enhanced in version 0.7.4. Previously, malformed `pyproject.toml` or other config files might have been silently ignored or partially applied. Now, invalid configurations might lead to errors.
Fix: Review `pyproject.toml` or other config files against the official documentation to ensure correct syntax and options.
gotcha Earlier versions (prior to approximately 0.7.0) primarily supported NumPy-style docstrings, with Google and Sphinx style support added later. Users expecting full support for Google or Sphinx styles should ensure they are on a recent version.
Fix: Upgrade pydoclint to the latest version (0.7.0 or newer) for comprehensive Google and Sphinx docstring style support.
gotcha PyDocLint performs static analysis and expects exact matches for type hints between docstrings and function signatures. It does not recognize conventions like 'int, optional' for `Optional[int]`, requiring verbatim matching. Also, non-standard Pythonic naming (e.g., renaming `classmethod`) might lead to unexpected linting results.
Fix: Ensure type hints in docstrings precisely mirror those in function signatures. Adhere to standard Python naming conventions for methods and parameters.

Install

pip install pydoclint Install native CLI
pip install pydoclint[flake8] Install as Flake8 plugin

Quickstart

To get started, install pydoclint and run it as a command-line tool on your Python files or directories. Configuration can be managed via a `pyproject.toml` file or command-line arguments.

# my_module.py
def my_function(arg1: int, arg2: str) -> None:
    """
    A sample function.

    Parameters
    ----------
    arg1 : int
        The first argument.
    arg2 : str
        The second argument.
    """
    print(f'{arg1}, {arg2}')

# pyproject.toml
[tool.pydoclint]
style = "numpy"
check-arg-order = true

# Terminal
# Run pydoclint on a file or folder
pydoclint my_module.py
# Or with a config file
pydoclint --config=pyproject.toml my_module.py
# Or as a pre-commit hook (add to .pre-commit-config.yaml)
# - repo: https://github.com/jsh9/pydoclint
#   rev: <latest_tag> # e.g., 0.8.3
#   hooks:
#     - id: pydoclint
#       args: ["--config=pyproject.toml"]

view raw JSON →