Multiple return values in reStructuredText doc strings (Python 3)

Question

I document all my Python functions with reStructuredText doc strings. Unfortunately, I am missing a way to describe multiple return values. All standard references I found only refer to the case of one return value, such as Sphinx-Doc or Realpython.

Example:

def get_linear_function_2d(p1, p2):
    """
    Compute 2d linear function in slope-intercept form
       y = mx + n
    based on two coinciding (x,y) points.

    :param tuple p1: (x,y) tuple describing one point that lies on the line
    :param tuple p2: (x,y) tuple describing another point that lies on the line (has to differ in x)
    <START OF ISSUE: How to document?>
      :return float: slope (m)
      :return float: y-intercept (n)
    <END OF ISSUE>
    """
    assert isinstance(p1, tuple) and len(p1) == 2 and all([isinstance(val, (int, float)) for val in p1])
    assert isinstance(p2, tuple) and len(p2) == 2 and all([isinstance(val, (int, float)) for val in p2])
    assert p1[0] != p2[0]
    m = (p2[1] - p1[1]) / (p2[0] - p1[0])
    n = p1[1] - m * p1[0]
    return m, n

Remark: This question has been raised for Python 2, see How to document multiple return values using reStructuredText in Python 2?.

However:

• that question had been dedicated to Python 2
• some years have passed
• the answers do not link any official reference
• even if there is no official reference for multiple return values, it is not clear to me what is best practice (none of the two answers stands out) - I think it is a pretty common issue and I am eager to see how you guys work around this lack of standard!

Answer 1

Python doesn't technically have multiple return values. Comma-separated values in a return statement in Python just means you are returning a single tuple value. Document it as a tuple.