How Do Functions Return Multiple Values?

Python has no syntax for returning several values. A return statement takes one expression, so if you want to hand back more than one value then you return a tuple. The parentheses are usually left off, because a comma on its own already creates a tuple.

def min_and_max(values):
    if not values:
        return None, None
    return min(values), max(values)


smallest, largest = min_and_max([4, 9, 2, 7])
print(smallest, largest)          # 2 9

# The tuple is a normal object, so you can index it or keep it.
result = min_and_max([4, 9, 2, 7])
print(result)                    # (2, 9)
print(result[0], type(result).__name__)

# Unpacking needs a real sequence.
try:
    value, = 42
except TypeError as err:
    print('TypeError:', err)

The comma in the return statement builds a tuple, and the unpacking on the left of the assignment splits that tuple back apart. It works because a tuple has a fixed length that Python knows about, so Python can unpack it directly instead of building a temporary list first.

There are two things to watch here. If the two sides have different lengths, the unpacking raises a ValueError that tells you how many values were expected. That is a useful failure, but it also means that a function whose return shape changes from call to call is a design smell. The single-value case is worth understanding too, because unpacking with a trailing comma requires a real sequence. Trying to unpack the integer 42 raises a TypeError, while unpacking a string would split it into its individual characters. So a function that sometimes returns a string and sometimes returns a tuple is asking for trouble.

If you need to return a variable number of values, then return a list or a tuple and unpack it with a star, as in head, *rest = result.

The reason is that a return statement evaluates exactly one expression, and the language has no separate syntax for multiple return values. A tuple is the natural fit, because it is immutable, it has a fixed length, and it is a single object. The consequence is that return a, b really returns one tuple, which is why the type of the result is tuple, and why unpacking it twice means writing the call twice.

That has a practical downside. With two or three values, a tuple is fine and it reads well. With four or more, the caller has to remember the order, and nothing in the code says which value is which. This is where returning a dictionary or a dataclass becomes better, because the caller can name what they want. For example, a Stats dataclass with fields smallest, largest, and count lets the caller write result.largest instead of remembering whether the third element was the count or the maximum.

A dataclass gives you named access, a helpful repr, and equality for free. A plain dictionary does the same job with less ceremony, and it is the right choice when the set of fields really does change from one call to the next. The dataclass is better when the shape is fixed and known, because the attribute names are checked by a type checker and the mistakes show up earlier.

There is one more option that is worth knowing for larger return values, and that is the NamedTuple. It is a tuple, so it is immutable and it can be unpacked like a tuple, but its fields are also named. That gives you the best of both when you want positional unpacking and named access at the same time.