darglint

1.8.1 · maintenance · verified Sun Apr 12

Darglint is a functional docstring linter that checks whether a docstring's description matches the actual function or method implementation. It supports Google, Sphinx, and Numpy style docstrings, ensuring that parameters, returns, yields, and raises sections are consistent with the function signature and body. The project is currently in maintenance mode, with the author focusing on accepting pull requests rather than adding significant new features.

Warnings

breaking Prior to version 1.5.8, `darglint` error codes used prefixes like 'I' and 'S'. These were changed to 'DAR' to avoid collisions with other Flake8 plugins. Code or configurations relying on old error codes will break.
Fix: Update any `ignore` lists in your configuration files (e.g., `.darglint`, `setup.cfg`, `tox.ini`) or `noqa` comments to use the new 'DAR' prefixed error codes.
deprecated Support for Python 3.5 was deprecated and effectively removed around versions 1.6.x/1.7.x due to CI build breaks.
Fix: Users on Python 3.5 should upgrade to Python 3.6 or newer to use current `darglint` versions, or alternatively, pin to an older `darglint` release compatible with Python 3.5.
gotcha `darglint` can be significantly slow on large projects. For very large codebases, alternatives like `pydoclint` (which claims to be thousands of times faster) might be considered for better performance.
Fix: For large codebases, evaluate `darglint`'s performance. If too slow, consider using `pydoclint` or running `darglint` selectively on changed files (e.g., via `pre-commit`).
gotcha `darglint` can be configured using a configuration file, which must be named `.darglint`, `setup.cfg`, or `tox.ini`. It must also contain a section header `[darglint]`. Incorrect file names or section headers will lead to configuration not being applied.
Fix: Ensure your configuration file is correctly named and contains the `[darglint]` section header. For example, a `.darglint` file in your project root with `[darglint]` at the top.
gotcha When checking Sphinx-style docstrings, `darglint` enforces strict formatting rules: all fields (e.g., `:param:`, `:returns:`) must be the last items, grouped together, and use four-space indents. Deviations from these specifics will trigger errors.
Fix: Adhere strictly to `darglint`'s Sphinx-style docstring requirements, ensuring fields are at the end, grouped, and correctly indented with four spaces.
gotcha When comparing docstring types to actual type annotations, `darglint` may not correctly parse or may mark as missing argument types specified with parentheses (e.g., `(str)` in docstrings), expecting types like `str` or `list[str]` directly. This can lead to a `DAR101` error.
Fix: Avoid using parentheses around simple types in docstring type annotations (e.g., write `str` instead of `(str)`). For complex types, ensure they follow Python's `PEP 484` without additional enclosing parentheses in the docstring type description.
gotcha While `darglint` has a command-line interface, it is often used as a `flake8` plugin for integrated linting workflows. Direct programmatic import and usage of `darglint`'s internal API for linting are not officially supported or commonly documented.
Fix: Utilize `darglint` either as a command-line tool (`darglint <files>`) or by installing it alongside `flake8` in the same environment. Avoid relying on internal `darglint` modules for programmatic linting.

Install

pip install darglint Install darglint

Quickstart

To quickly check a Python file with darglint, save your code to a .py file and run darglint directly from your terminal. It will output any docstring inconsistencies.

# my_module.py
def add_numbers(a: int, b: int) -> int:
    """Adds two numbers.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The sum of a and b.
    """
    return a + b

# To run: save the above as my_module.py, then execute in your terminal:
# darglint my_module.py

view raw JSON →