darglint

library1.8.1pypypiunverified

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.

testing

pip install darglint

package ↗

INSTALL

IMPORT

SIG · DARGLINT

darglint

testingpythonv1.8.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

darglint --version

Debug

Known issues

breakingPrior 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.

affects: <1.5.8

deprecatedSupport 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.

affects: >=1.6.0

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`).

affects: All

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.

affects: All

gotchaWhen 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.

affects: All

gotchaWhen 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.

affects: All

gotchaWhile `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.

affects: All

Errors

Common errors & fixes

DAR101: The docstring is missing a parameter in the definition.

The function's signature includes a parameter that is not documented in the docstring's parameters section.

fix

Add the missing parameter to the docstring's 'Args' (Google style), ':param:' (Sphinx style), or 'Parameters' (Numpy style) section, ensuring its name matches the function signature.

DAR201: The docstring is missing a return from definition.

The function's signature or body indicates a return value, but the docstring lacks a 'Returns' section or a description for the return value.

fix

Add a 'Returns' (Google style), ':returns:' (Sphinx style), or 'Returns' (Numpy style) section to the docstring, describing the value returned by the function.

DAR402: The docstring describes an exception not explicitly raised.

The docstring's 'Raises' section documents an exception that is not actually raised within the function's implementation.

fix

Either remove the undocumented exception from the docstring's 'Raises' section or ensure the function's body explicitly raises the described exception.

DAR001: The docstring was not parsed correctly due to a syntax error.

The docstring contains a syntax error or is formatted in a way that `darglint` cannot interpret according to the configured style (Google, Sphinx, or Numpy). This can also be caused by improperly escaped characters like '\n'.

fix

Review the docstring for syntax errors, incorrect indentation (e.g., DAR003), or extra newlines (e.g., DAR004), and ensure it strictly adheres to the chosen docstring style guide. Using an IDE with docstring formatting assistance can help.

Upgrade

Version history

1.8.1latest on PyPI · released Oct 18, 2021

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Amazon

Resources

packagehttps://pypi.org/project/darglint/ ↗