## What
Python provides nice [[syntax]] for ‘returning multiple values’. In reality, only one value is returned: a [[tuple]] containing the 'multiple' values.
## Syntax
A function can return multiple values separated by commas after `return`, e.g., `return 4, 6`; Python automatically groups them into a single tuple. Parentheses around the values are optional—`return a, b` and `return (a, b)` are equivalent.
On the calling side, multiple assignment targets separated by commas unpack the returned tuple's elements positionally, e.g., `q, r = division(19, 2)`. This is just Python's general multiple-assignment syntax, not something specific to `return`—but it's what makes 'returning multiple values' useful. The number of assignment targets must match the number of values in the tuple, or Python raises an error.
## Why
By 'returning multiple values' and using Python's convenient syntax, you group return values without defining a dedicated [[data structure]], and unpack each one straight into its own variable rather than indexing into a returned [[object]]. This can make your code more readable, or at least more convenient to write, than using a dedicated data structure.
> [!WARNING] Risk when returning lots of values
> The advantages of returning multiple values disappears once you're returning more than a couple of values: a long, undifferentiated tuple becomes just as hard to read and maintain as the dedicated data structure it was avoiding. At that point, it's worth switching to something more intentional, like a dictionary or a custom object.
## Examples
### Returning an implicit tuple
Python automatically groups comma-separated return values into a tuple, without needing parentheses. This is the more common style in real Python code.
```python
def division(dividend, divisor):
quotient = dividend // divisor
remainder = dividend % divisor
return quotient, remainder # an implicit tuple is returned
results = division(23, 5) # results = (4, 3)
q, r = division(19, 2) # q = 9, r = 1
```
### Returning an explicit tuple
Parentheses make the grouping explicit. This can help readability when there are many values, or when the return statement is far from where it's called.
```python
def division(dividend, divisor):
quotient = dividend // divisor
remainder = dividend % divisor
return (quotient, remainder) # an explicit tuple is returned
results = division(23, 5) # results = (4, 3)
q, r = division(19, 2) # q = 9, r = 1
```
### Returning too many values
Returning a long, undifferentiated tuple becomes hard to track—both at the call site and when reading the function itself. The call site has to match the exact order of values in the function's `return` statement, and nothing stops you getting that order wrong. In a situation like this, you would be better using a dictionary.
```python
def analyse_scores(scores):
count = len(scores)
total = sum(scores)
mean = total / count
lowest = min(scores)
highest = max(scores)
spread = highest - lowest
return count, total, mean, lowest, highest, spread
# lowest and highest have swapped position by mistake—Python won't catch this
count, total, mean, highest, lowest, spread = analyse_scores([62, 75, 81, 49, 90])
```