Python Function Annotations: How to annotate multiple return values

As you know, it is possible to return multiple values from a Python function.

However, it can become difficult to keep track of what each value represents, especially when working with complex functions that return many values. This is where annotations come in handy.

An annotation is a way of adding additional information to a variable, function, or class in Python. Annotations can be used to specify the type of data a variable holds, the type of arguments a function expects, and the type of value a function returns.

When it comes to annotating multiple return values in Python, there are a few different approaches you can take.

Here are some approaches to help you get started:

How to annotate multiple return values in a Python function

1. Use a tuple to annotate a function’s multiple return values

One of the simplest ways to return multiple values from a function is to use a tuple. Tuples are immutable sequences of objects in Python, and they are often used to group related data together.

Here’s an example of how to use a tuple to return multiple values from a function:

def calculate_stats(numbers):
    total = sum(numbers)
    mean = total / len(numbers)
    variance = sum((x - mean) ** 2 for x in numbers) / len(numbers)
    return total, mean, variance

In this example, the function calculates the total, mean, and variance of a list of numbers, and then returns all three values as a tuple.

To annotate this function, you can use the “->” operator to specify the type of the return value. Here’s how you can annotate the above function:

from typing import List, Tuple

def calculate_stats(numbers: List[float]) -> Tuple[float, float, float]:
    total = sum(numbers)
    mean = total / len(numbers)
    variance = sum((x - mean) ** 2 for x in numbers) / len(numbers)
    return total, mean, variance

In this annotated version of the function, we’ve specified that the “numbers” argument should be a list of floats, and that the function should return a tuple containing three floats (total, mean, and variance).

In Python, a function can return multiple values, but it can be challenging to annotate the types of all the return values individually.

Tuples provide an elegant and straightforward solution to this problem by allowing multiple values to be returned as a single object.

Tuple annotations are easy to understand, read and write, making it faster to specify the type of multiple return values of a function.

2. Use named tuples to annotate a function’s multiple return values

Another way to annotate multiple return values in Python is to use named tuples.

Named tuples are a subclass of tuples that allow you to give each element a name, making it easier to understand what each value represents.

Named tuples in Python provide an effective way of giving a name to each item in a tuple. Using named tuples to annotate a function’s multiple return values can be beneficial in several ways.

Firstly, named tuples provide more context and clarity to the code.

When a function returns a named tuple, it’s immediately clear what each value represents. This makes the code more readable, easier to understand and reduces the chance of errors resulting from misinterpretation of the data returned by the function.

For instance, consider a function that returns the total sales, cost of goods sold, and profit for a retail business.

Instead of returning a regular tuple with just the values, we can use a named tuple to give a meaningful name to each value:

from typing import NamedTuple

class FinancialSummary(NamedTuple):
    total_sales: float
    cost_of_goods_sold: float
    profit: float

def calculate_financial_summary() -> FinancialSummary:
    total_sales = 1000000.0
    cost_of_goods_sold = 750000.0
    profit = total_sales - cost_of_goods_sold
    return FinancialSummary(total_sales, cost_of_goods_sold, profit)

The results:

In the above example, the named tuple FinancialSummary clearly defines what each value represents, which makes the code more understandable.

Secondly, named tuples provide a way to ensure type safety.

By specifying the types of each value in the named tuple, we can ensure that the data returned by the function is of the correct type.

This can help catch errors early on in the development process, and make the code more robust.

Here’s an example:

Let’s say we have a function that calculates the average, minimum, and maximum of a list of numbers, and returns them as a named tuple:

from typing import List, NamedTuple

class Stats(NamedTuple):
    average: float
    minimum: float
    maximum: float

def calculate_stats(numbers: List[float]) -> Stats:
    if not numbers:
        raise ValueError("The input list cannot be empty.")
    average = sum(numbers) / len(numbers)
    minimum = min(numbers)
    maximum = max(numbers)
    return Stats(average, minimum, maximum)

By using a named tuple to annotate the return type, we ensure that the returned values are always of the correct type, which in this case is a Stats named tuple with three float values.

If we mistakenly returned a regular tuple or a list instead, the type checker would catch the error and raise a warning.

For example, if we changed the return statement to:

return (average, minimum, maximum)

The type checker would generate just a bunch of numbers that a programmer would not understand:

(3.0, 2, 4)

By providing additional information using named tuple annotation, a developer can understand what the return data type of the function is.

Stats(average=3.0, minimum=2, maximum=4)

3. Use a dictionary to annotate a function’s multiple return values

In Python, dictionaries can be used to annotate a function’s multiple return values. This approach is particularly useful when the values returned from a function do not have a natural order or when many values are being returned.

To use a dictionary to annotate a function’s multiple return values, you can define the return type as a dictionary with string keys and type values.

The keys in the dictionary correspond to the names of the values being returned, while the values represent their types.

The function can then return a dictionary with the values as key-value pairs.

For example, let’s consider a function that returns information about a person, such as their name, age, and address.

We can use a dictionary to annotate the multiple return values as follows:

from typing import Union

def get_person_info(person_id: int) -> dict[str, Union[str, int]]:
    # retrieve person's information from a database
    name = "John Doe"
    age = 30
    address = "123 Main Street"

    # create a dictionary to hold the person's information
    person_info = {
        "name": name,
        "age": age,
        "address": address
    }

    return person_info

In this example, the return type is defined as a dictionary with string keys and values that can be either a string or an integer.

The function returns a dictionary with the keys "name", "age", and "address", which correspond to the values returned by the function.

If you take the function further, you can connect to the database to retrieve personal information from the database like this:

import sqlite3
from typing import Union, Dict

def get_person_info(person_id: int) -> Dict[str, Union[str, int]]:
    # create a connection to the database
    conn = sqlite3.connect("mydatabase.db")
    cursor = conn.cursor()

    # retrieve person's information from the database
    cursor.execute("SELECT name, age, address FROM persons WHERE id = ?", (person_id,))
    row = cursor.fetchone()

    # create a dictionary to hold the person's information
    person_info = {
        "name": row[0],
        "age": row[1],
        "address": row[2]
    }

    # close the database connection and return the person's information
    conn.close()
    return person_info

print(get_person_info(1))

We still get the same results, assuming you have a SQLite database named mydatabase.db with a table named “persons” that has columns for “name”, “age”, “address”, and “id”.

You can annotate multiple return values in Python using tuples, named tuples, or dictionaries. You use annotations to specify the types of these return values. This approach makes your code more understandable and maintainable for yourself and other developers.

How to show annotations in Python?

You can show annotations for each function using the default __annotations__ variable provided by Python.

One way to access annotations for a function is by using the special __annotations__ attribute. This attribute is a dictionary that maps parameter names to their types, and the key “return” to the return type of the function.

How to use __annotations__ to access function annotations

Define a function with annotations. For example:

def multiply(a: int, b: int) -> int:
    return a * b

In this function, we’ve added annotations to the “a” and “b” parameters to indicate that they should be integers, and we’ve added an annotation to the return type to indicate that the function should return an integer.

Access the function annotations using the __annotations__ attribute:

annotations = multiply.__annotations__

This will create a dictionary that maps parameter names to their types, and the key “return” to the return type of the function.

Print the annotations to see what they contain:

print(annotations)

This will output the dictionary containing the annotations:

By accessing the annotations for a function, we can get a better understanding of how the function is supposed to be used, and we can use this information to help catch errors and bugs in our code.

FAQs

What does the function attribute __annotations__ return?

In Python, the __annotations__ function attribute returns a dictionary that contains the annotations of a function. The keys of the dictionary correspond to the parameter names, while the values are the annotations themselves.

The dictionary also includes a special key called “return”, which maps to the annotation of the function’s return type.

Annotations are optional and can be used to provide metadata about the types of the function’s arguments and return values.

By accessing the __annotations__ attribute, we can programmatically obtain information about the expected types of the function arguments and its return value, which can be useful in ensuring proper usage of the function and for type checking purposes.

What is the difference between comments and annotations?

Comments and annotations are both used in programming to provide additional information and context about code.

However, there are some key differences between the two.

Comments are used to provide human-readable descriptions or explanations of code. They are often used to document code, to provide context for future developers, or to temporarily disable code that is causing issues.

Comments in Python are denoted by the “#” symbol.

Annotations, on the other hand, are used to provide metadata about code that can be read and used by other programs or tools. Annotations are typically used for type hinting, documenting function signatures, or other forms of metadata that can be processed programmatically.

In Python, annotations are specified using the “:” symbol.

One important difference between comments and annotations is that comments are ignored by the Python interpreter and have no effect on how code is executed. Annotations, however, can be used by tools such as linters, type checkers, and IDEs to provide additional information and to help catch errors and bugs at runtime.

Here’s a table showing the difference between comments and annotations in Python:

Python comments (#)	Python function annotations (:)
Provide human-readable descriptions or explanations of code	Provide metadata that can be processed programmatically
Begin with the “#” symbol	Specified using the “:” or “->” symbols
Comments can be added anywhere in a code file	Annotations are typically added to function parameters and return types.

What is the difference between annotations and docstring

Annotations and docstrings are two different ways to add metadata and information to Python code, but they serve different purposes and have different syntaxes.

Annotations are used to add type hints and other metadata to function arguments and return values. They are defined using a colon after the argument or return value, followed by the type hint or metadata.

For example:

def divide(a: int, b: int) -> float:
    return a / b

In this function, we’ve added annotations to the “a” and “b” parameters to indicate that they should be integers, and we’ve added an annotation to the return type to indicate that the function should return a float.

Docstrings, on the other hand, are used to add documentation and explanations about the code. They are defined using a string that appears at the beginning of a function, class, or module.

For example:

def divide(a, b):
    """
    This function divides two numbers.

    Arguments:
    a -- the numerator
    b -- the denominator

    Returns:
    The result of dividing a by b.
    """
    return a / b

In this function, we’ve added a docstring that explains what the function does, what arguments it takes, and what it returns.

The main difference between annotations and docstrings is that annotations are used to provide type hints and metadata for the code, while docstrings are used to provide documentation and explanations about the code.

Should I use annotations or docstrings for my Python program?

Deciding whether to use annotations or docstrings for your Python program depends on your specific needs and goals.

Here are some nuances to consider:

1. Readability: Annotations can make your code more readable by providing clear information about function arguments and return values. However, too many annotations can clutter your code and make it harder to read. Docstrings can provide more detailed explanations about the purpose of the code and how it works, making it easier for other developers to understand and use.
2. Compatibility: Annotations were introduced in Python 3.0, so if you’re working with an older version of Python, you may not be able to use them. Docstrings, on the other hand, have been around since the early days of Python and are compatible with all versions of the language.