How to Specify Multiple Return Types Using Type Hints in Python

How to Specify Multiple Return Types Using Type Hints in Python

In Python, type hints improve code readability and help developers understand what kind of values are expected for function arguments and returns. But sometimes, a function can return multiple types, which raises the question: how can we specify these multiple return types?

In this blog post, I’ll walk you through different ways to handle multiple return types using Python type hints, covering various versions of Python and how to use unions, tuples, and type-checking libraries.

Python’s Type Hinting System

Introduced in Python 3.5, type hints allow developers to annotate their functions with expected argument and return types. However, Python is still a dynamically typed language, meaning type hints are not enforced at runtime. Instead, they are more of a developer tool used by static analysis tools like mypy to catch bugs before execution.

Here’s a basic example of type hinting in Python:

def add_numbers(x: int, y: int) -> int:
    return x + y

This example states that the function add_numbers takes two integers (x, y) and returns an integer (int).

Multiple Return Types: Using Union

Sometimes, your function may return values of different types. For example, you might have a function that returns either a list or a boolean. To handle this, we can use Union from the typing module.

Python 3.5 - 3.9: Using Union

In Python versions earlier than 3.10, you need to use Union to define multiple possible return types. Here’s an example:

from typing import Union

def process_data(data: str) -> Union[list, bool]:
    if data == "error":
        return False
    return [char for char in data]

In this example, the function process_data can either return a list (if data processing succeeds) or a bool (if there’s an error).

Python 3.10+: Using | Operator

Starting from Python 3.10, you can use the | operator as a shorthand for Union. This offers a more concise and readable syntax:

def process_data(data: str) -> list | bool:
    if data == "error":
        return False
    return [char for char in data]

This new syntax reduces the verbosity of using Union, making the type hinting easier to read.

Handling Multiple Return Values with Tuple

Another common scenario is when a function returns multiple values of different types. To annotate such functions, we use Tuple from the typing module. A Tuple type hint defines that a function will return a specific number of values, each of a specific type.

Example: Multiple Return Values

Suppose you have a function that returns both a dictionary and a string:

from typing import Tuple

def get_user_info(user_id: int) -> Tuple[dict, str]:
    user_data = {"id": user_id, "name": "Alice"}
    status = "active"
    return user_data, status

Here, the Tuple type hint specifies that the function will return a tuple consisting of a dict and a str.

In Python 3.9+, you can simplify the syntax by using brackets:

def get_user_info(user_id: int) -> tuple[dict, str]:
    user_data = {"id": user_id, "name": "Alice"}
    status = "active"
    return user_data, status

Optional Types: Optional vs. Union

Sometimes, you might want to indicate that a function can return a specific type or None. While you could use Union for this, Optional provides a cleaner, more explicit way to indicate that None is a valid return value.

Example: Using Optional

from typing import Optional

def find_user(user_id: int) -> Optional[dict]:
    users = {1: {"name": "Alice"}, 2: {"name": "Bob"}}
    return users.get(user_id)

This example defines that the function find_user can return either a dict (if the user is found) or None (if the user is not found). The Optional[dict] is syntactic sugar for Union[dict, None].

Enforcing Type Checking at Runtime

While Python’s type hints are not enforced by default, you can use third-party libraries like typeguard to enforce them at runtime.

Example: Enforcing Type Checks with typeguard

from typeguard import typechecked

@typechecked
def multiply_numbers(x: int, y: int) -> int:
    return x * y

# This will raise a TypeError because 'y' is a string
result = multiply_numbers(5, '10')

Using the @typechecked decorator ensures that any mismatch between the provided and expected types raises an error during execution.

Best Practices

1. Use Unions Wisely: If your function returns different types depending on input, try to structure it so that each return type is easy to understand and use.

2. Prefer Exceptions Over Booleans: If you’re using bool to indicate error states, consider using exceptions instead. This approach keeps return types focused and makes error handling more explicit.

3. Document Your Functions: Although type hints make your code more self-explanatory, always provide clear docstrings to describe the behavior of your function, especially when it returns multiple types.

Type hints are a powerful tool that helps developers understand and maintain Python code more easily. By using Union, Tuple, and Optional, you can specify multiple return types in a clear and Pythonic way. While Python won’t enforce these types at runtime, tools like mypy and typeguard can help catch bugs early in the development process.