flake8-docstrings-complete Now Checks for Duplicate Descriptions

Version v1.1.0 of flake8-docstrings-complete has added new rules that ensure you only document each argument, raised exception and class attribute once:

  • DCO025: function/ method has one or more arguments described in the docstring multiple times.
  • DCO056: function/ method has one or more exceptions described in the docstring multiple times.
  • DCO065: class has one or more attributes described in the docstring multiple times.

This ensures that you don’t accidentally document an argument, exception or attribute multiple times such as is the case for the following code:

# source.py
def foo(bar):
    """Perform foo action.

    Args:
        bar: the value to perform the foo action on.
        bar: the value to perform the foo action on.
    """

The linter now warns:

flake8 source.py 
source.py:3:5: DCO025 "bar" argument documented multiple times, more information: https://github.com/jdkandersson/flake8-docstrings-complete#fix-dco025

Additionally, version v1.0.4 previously relaxed the class attribute checking by making only class attributes required attributes. Instance attributes, such as those assigned in the __init__ method, no longer have to be documented. The check that all described attributes should be either class or instance attributes remains.

You can read more about writing great docstrings in the following blog post: Writing Great Docstrings in Python

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s