Introduction

Python functions always return one object. When people say a function "returns multiple values," what usually happens is that the function returns one container object and the caller unpacks it. The right container depends on how strongly you want to name the fields, how stable the shape is, and whether the return value should behave like data or like a richer domain object.

The default choice: return a tuple

For a small fixed set of values, a tuple is still the normal answer. Python even lets you write the return without parentheses, but the result is a tuple.

1def divide_and_remainder(a: int, b: int) -> tuple[int, int]:
2    return a // b, a % b
3
4
5quotient, remainder = divide_and_remainder(17, 5)
6print(quotient, remainder)

This is compact and familiar. It works best when the meaning of each position is obvious or when the caller immediately unpacks the result.

Use NamedTuple or a dataclass when names matter

If the return value has structure that deserves field names, a plain tuple starts to become hard to read. NamedTuple or a dataclass makes the result self-documenting.

1from dataclasses import dataclass
2
3
4@dataclass(frozen=True)
5class ParseResult:
6    host: str
7    port: int
8    use_tls: bool
9
10
11def parse_endpoint(text: str) -> ParseResult:
12    return ParseResult(host="db.internal", port=5432, use_tls=True)
13
14
15result = parse_endpoint("db.internal:5432")
16print(result.host, result.port, result.use_tls)

This style is usually better when the result is passed around beyond the immediate call site, because field names carry meaning that positional unpacking does not.

Return a dictionary when the shape is flexible

A dictionary is useful when the set of returned fields may grow or vary, or when the caller naturally works with keyed data.

1def build_user_summary() -> dict[str, object]:
2    return {
3        "name": "Alice",
4        "age": 30,
5        "email": "[email protected]",
6    }
7
8
9summary = build_user_summary()
10print(summary["name"], summary["email"])

The tradeoff is that dictionaries are less strict. A misspelled key fails at runtime, and the expected schema is easier to drift over time unless you document it carefully.

Return a custom object when behavior belongs with the data

Sometimes the returned data is not just a bundle of values. It has methods, invariants, or behavior that belong together. In that case, returning a real class instance is often the cleanest design.

1class Money:
2    def __init__(self, amount: int, currency: str) -> None:
3        self.amount = amount
4        self.currency = currency
5
6    def format(self) -> str:
7        return f"{self.amount / 100:.2f} {self.currency}"
8
9
10def calculate_total() -> Money:
11    return Money(2599, "USD")
12
13
14total = calculate_total()
15print(total.format())

This is more than "multiple return values." It is a signal that the result has domain behavior and should be modeled explicitly.

A generator is not the same thing

Generators created with yield are often mentioned in lists like this, but they solve a different problem. A generator streams a sequence of values over time. It is not the normal replacement for returning a fixed bundle of related results from one function call.

If your function naturally produces a series, use yield. If it produces one structured answer with several parts, return a tuple, dataclass, dict, or object instead.

Common Pitfalls

The most common mistake is returning a plain tuple from a function whose positions are not obvious. That makes the call site brittle because readers have to remember what index 0 or 1 means.

Another issue is using a dictionary when the return shape is actually fixed and important. In that case, a dataclass or NamedTuple gives stronger structure and clearer intent.

Developers also treat generators as if they were "multiple returns." They are not. They represent sequential output, not a fixed structured result.

Finally, avoid returning many loosely related values just because Python makes it easy. If the result has a real concept in the domain, create a type for it.

Summary

• Python returns one object, even when the caller sees several unpacked values.
• Tuples are the standard answer for small fixed return groups.
• Dataclasses and NamedTuple are better when field names matter.
• Dictionaries are useful when the returned shape is flexible or schema-like.
• Generators solve streaming output, not structured multi-field return values.