Do you replicate type hints of function within the docstring of the function? PEP Guidelines?

Question

Background

Propose that there is function:

def do_product(a: int, b: int) -> int:
    return a * b

And I start documenting my function:

def do_product(a: int, b: int) -> int:
    """This function gets two integers and returns the product

    :param a: first integer 
    :param b: second integer

    :return: return the product of a and b"""
    return a * b

When I use Sphinx, I use get the type hinting imported into the API documentation by using the sphinx-autodoc-typehints extension of sphinx. The advantage of doing that is that I declare types only once when programming and can not have disambiguation between documentation and functional declaration. I am currently working on a PR where I was asked to declare the types within the docstring. This would then look like this:

def do_product(a: int, b: int) -> int:
    """This function gets two integers and returns the product

    :param int a: first integer 
    :param int b: second integer

    :return int: return the product of a and b"""
    return a * b

This doesn't make sense as this seems like replication of the declaration within the function..

Question:

1. When writing docstrings, do you need to define types?
2. What are the best practises for documenting type hinting in python?
3. Is there a PEP standard for this? I could find the appropriate one..

Answer 1

According to PEP 257,

[t]he docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).

There is no concrete specifications (as per PEP) to whether docstrings and types shall be used at the same time, the only thing remotely fitting is under PEP 484:

Docstrings. There is an existing convention for docstrings, based on the Sphinx notation (:type arg1: description). This is pretty verbose (an extra line per parameter), and not very elegant. We could also make up something new, but the annotation syntax is hard to beat (because it was designed for this very purpose).

Anyhow, according to PEP 257, multi-line docstrings (as you are using them) shall be used if the type of the arguments isn't directly indicated.

Generally, I wouldn't recommend duplicating the type hints from the function signature in the documentation as it can increase the likelihood of repetition or redundancy errors. By choosing either way, the code is clearly understandable and/or readable. For changes in the signature, you would need to change at least two sources of information and thus you may introduce inconsistent code snippets.

As stated above by you, sphinx-autodoc-typehints is a good way of approaching this topic - by using that, you would be able to automatically add the type hints into the documentation (and thus void the risk of making redundancy errors).