How to specify multiple return types using type-hints

Type hinting is a powerful feature in Python that enables developers to specify the expected types of function arguments, as well as the return type of a function. This feature makes it easier to write clean and maintainable code, and reduces the chances of runtime errors. In Python, it is also possible to specify multiple return types using type hints, which can be useful in some cases. In this article, we will explore how to specify multiple return types using type hints, with code examples.

What are Multiple Return Types?

In Python, functions can return multiple values, which are typically returned as a tuple. For example, consider the following function:

def get_name_and_age() -> Tuple[str, int]: name = "Alice" age = 30 return name, age 

This function returns a tuple with two values, a string (the name) and an integer (the age). However, in some cases, the return value of a function may have different types depending on certain conditions. For example, consider a function that performs a database query and returns either a list of records or an error message:

def query_database(query: str) -> Union[List[Dict[str, Any]], str]: # perform database query if query_successful: return records else: return "Error: query failed" 

In this case, the function can return either a list of records (represented as a list of dictionaries), or an error message (represented as a string). Therefore, we need a way to specify multiple return types using type hints.

Using Union to Specify Multiple Return Types

The most common way to specify multiple return types in Python is to use the Union type hint. The Union type hint allows us to specify a list of types that a function can return. For example, to specify that a function can return either a list of records or an error message, we can use the following type hint:

def query_database(query: str) -> Union[List[Dict[str, Any]], str]: # perform database query if query_successful: return records else: return "Error: query failed" 

In this example, the Union type hint specifies that the function can return either a list of dictionaries or a string. Note that we use the List and Dict types to specify the structure of the list of records (a list of dictionaries with string keys and values of any type) and the str type to specify the error message.

Using Tuple to Specify Multiple Return Types

In addition to using the Union type hint, we can also use the Tuple type hint to specify multiple return types. The Tuple type hint allows us to specify a fixed number of return types, each with its own type. For example, consider the following function that returns the quotient and remainder of a division operation:

def divide(dividend: int, divisor: int) -> Tuple[int, int]: quotient = dividend // divisor remainder = dividend % divisor return quotient, remainder 

In this example, the function returns a tuple with two integers, the quotient and remainder of the division operation. Note that we use the Tuple type hint to specify the return type of the function, with two integer types.

Using Optional to Specify Multiple Return Types

In some cases, a function may not always return a value of a certain type. For example, consider a function that searches for a value in a list and returns its index. If the value is not found, the function should return None. In this case, we can use the Optional type hint to specify that the function may return either an integer (the index) or None. Here's an example:

def find_index(value: Any, lst: List[Any]) -> Optional[int]: try: index = lst.index(value) return index except ValueError: return None 

In this example, the function searches for the value parameter in the lst parameter using the index() method. If the value is found, the method returns the index of the value. If the value is not found, the method raises a ValueError exception, which is caught and handled by the except block. In this case, the function returns None.

Using Type Aliases to Simplify Type Hints

When specifying multiple return types using type hints, the resulting type hint can sometimes become quite long and complex, especially if the types themselves are complex. In such cases, it can be useful to use type aliases to simplify the type hint.

A type alias is simply a new name given to an existing type. For example, consider the following type alias:

Record = Dict[str, Union[str, int, float]] 

In this example, we define a type alias called Record that represents a dictionary with string keys and values that can be either strings, integers, or floats. We can then use this type alias in our function definition, like this:

def query_database(query: str) -> Union[List[Record], str]: # perform database query if query_successful: return records else: return "Error: query failed" 

In this example, we use the Record type alias to specify the structure of the list of records that the function can return, instead of using the full type hint for a dictionary.

Conclusion

In conclusion, specifying multiple return types using type hints in Python is a powerful feature that can help write clean and maintainable code, and reduce the chances of runtime errors. In this article, we explored how to specify multiple return types using the Union, Tuple, and Optional type hints, with code examples. We also looked at how to use type aliases to simplify complex type hints.