The Python return Statement: Usage and Best Practices

Explicit return Statements

An explicit return statement immediately terminates a function execution and sends the return value back to the caller code. To add an explicit return statement to a Python function, you need to use return followed by an optional return value:

>>> def return_42():
...     return 42  # An explicit return statement
...

>>> return_42()  # The caller code gets 42
42

When you define return_42(), you add an explicit return statement (return 42) at the end of the function’s code block. 42 is the explicit return value of return_42(). This means that any time you call return_42(), the function will send 42 back to the caller.

If you define a function with an explicit return statement that has an explicit return value, then you can use that return value in any expression:

>>> num = return_42()
>>> num
42

>>> return_42() * 2
84

>>> return_42() + 5
47

Since return_42() returns a numeric value, you can use that value in a math expression or any other kind of expression in which the value has a logical or coherent meaning. This is how a caller code can take advantage of a function’s return value.

Note that you can use a return statement only inside a function or method definition. If you use it anywhere else, then you’ll get a SyntaxError:

>>> return 42
  File "<stdin>", line 1
SyntaxError: 'return' outside function

When you use return outside a function or method, you get a SyntaxError telling you that the statement can’t be used outside a function.

You can use any Python object as a return value. Since everything in Python is an object, you can return strings, lists, tuples, dictionaries, functions, classes, instances, user-defined objects, and even modules or packages.

For example, say you need to write a function that takes a list of integers and returns a list containing only the even numbers in the original list. Here’s a way of coding this function:

>>> def get_even(numbers):
...     even_nums = [num for num in numbers if not num % 2]
...     return even_nums
...

>>> get_even([1, 2, 3, 4, 5, 6])
[2, 4, 6]

get_even() uses a list comprehension to create a list that filters out the odd numbers in the original numbers. Then the function returns the resulting list, which contains only even numbers.

A common practice is to use the result of an expression as a return value in a return statement. To apply this idea, you can rewrite get_even() as follows:

>>> def get_even(numbers):
...     return [num for num in numbers if not num % 2]
...

>>> get_even([1, 2, 3, 4, 5, 6])
[2, 4, 6]

The list comprehension gets evaluated and then the function returns with the resulting list. Note that you can only use expressions in a return statement. Expressions are different from statements like conditionals or loops.

For a further example, say you need to calculate the mean of a sample of numeric values. To do that, you need to divide the sum of the values by the number of values. Here’s an example that uses the built-in functions sum() and len():

>>> def mean(sample):
...     return sum(sample) / len(sample)
...

>>> mean([1, 2, 3, 4])
2.5

In mean(), you don’t use a local variable to store the result of the calculation. Instead, you use the expression directly as a return value. Python first evaluates the expression sum(sample) / len(sample) and then returns the result of the evaluation, which in this case is the value 2.5.

Implicit return Statements

A Python function will always have a return value. There is no notion of procedure or routine in Python. So, if you don’t explicitly use a return value in a return statement, or if you totally omit the return statement, then Python will implicitly return a default value for you. That default return value will always be None.

Say you’re writing a function that adds 1 to a number x, but you forget to supply a return statement. In this case, you’ll get an implicit return statement that uses None as a return value:

>>> def add_one(x):
...     # No return statement at all
...     result = x + 1
...

>>> value = add_one(5)
>>> value

>>> print(value)
None

If you don’t supply an explicit return statement with an explicit return value, then Python will supply an implicit return statement using None as a return value. In the above example, add_one() adds 1 to x and stores the value in result but it doesn’t return result. That’s why you get value = None instead of value = 6. To fix the problem, you need to either return result or directly return x + 1.

An example of a function that returns None is print(). The goal of this function is to print objects to a text stream file, which is normally the standard output (your screen). So, this function doesn’t need an explicit return statement because it doesn’t return anything useful or meaningful:

>>> return_value = print("Hello, World")
Hello, World

>>> print(return_value)
None

The call to print() prints Hello, World to the screen. Since this is the purpose of print(), the function doesn’t need to return anything useful, so you get None as a return value.

Regardless of how long and complex your functions are, any function without an explicit return statement, or one with a return statement without a return value, will return None.

Returning None Explicitly

Some programmers rely on the implicit return statement that Python adds to any function without an explicit one. This can be confusing for developers who come from other programming languages in which a function without a return value is called a procedure.

There are situations in which you can add an explicit return None to your functions. In other situations, however, you can rely on Python’s default behavior:

• If your function performs actions but doesn’t have a clear and useful return value, then you can omit returning None because doing that would just be superfluous and confusing. You can also use a bare return without a return value just to make clear your intention of returning from the function.

• If your function has multiple return statements and returning None is a valid option, then you should consider the explicit use of return None instead of relying on the Python’s default behavior.

These practices can improve the readability and maintainability of your code by explicitly communicating your intent.

When it comes to returning None, you can use one of three possible approaches:

1. Omit the return statement and rely on the default behavior of returning None.
2. Use a bare return without a return value, which also returns None.
3. Return None explicitly.

Here’s how this works in practice:

>>> def omit_return_stmt():
...     # Omit the return statement
...     pass
...
>>> print(omit_return_stmt())
None

>>> def bare_return():
...     # Use a bare return
...     return
...
>>> print(bare_return())
None

>>> def return_none_explicitly():
...     # Return None explicitly
...     return None
...
>>> print(return_none_explicitly())
None

Whether or not to return None explicitly is a personal decision. However, you should consider that in some cases, an explicit return None can avoid maintainability problems. This is especially true for developers who come from other programming languages that don’t behave like Python does.

Remembering the Return Value

When writing custom functions, you might accidentally forget to return a value from a function. In this case, Python will return None for you. This can cause subtle bugs that can be difficult for a beginning Python developer to understand and debug.

You can avoid this problem by writing the return statement immediately after the header of the function. Then you can make a second pass to write the function’s body. Here’s a template that you can use when coding your Python functions:

def template_func(args):
    result = 0  # Initialize the return value
    # Your code goes here...
    return result  # Explicitly return the result

If you get used to starting your functions like this, then chances are that you’ll no longer miss the return statement. With this approach, you can write the body of the function, test it, and rename the variables once you know that the function works.

This practice can increase your productivity and make your functions less error-prone. It can also save you a lot of debugging time.

Avoiding Complex Expressions

As you saw before, it’s a common practice to use the result of an expression as a return value in Python functions. If the expression that you’re using gets too complex, then this practice can lead to functions that are difficult to understand, debug, and maintain.

For example, if you’re doing a complex calculation, then it would be more readable to incrementally calculate the final result using temporary variables with meaningful names.

Consider the following function that calculates the variance of a sample of numeric data:

>>> def variance(data, ddof=0):
...     mean = sum(data) / len(data)
...     return sum((x - mean) ** 2 for x in data) / (len(data) - ddof)
...

>>> variance([3, 4, 7, 5, 6, 2, 9, 4, 1, 3])
5.24

The expression that you use here is quite complex and difficult to understand. It’s also difficult to debug because you’re performing multiple operations in a single expression. To work around this particular problem, you can take advantage of an incremental development approach that improves the readability of the function.

Take a look at the following alternative implementation of variance():

>>> def variance(data, ddof=0):
...     n = len(data)
...     mean = sum(data) / n
...     total_square_dev = sum((x - mean) ** 2 for x in data)
...     return total_square_dev / (n - ddof)
...

>>> variance([3, 4, 7, 5, 6, 2, 9, 4, 1, 3])
5.24

In this second implementation of variance(), you calculate the variance in several steps. Each step is represented by a temporary variable with a meaningful name.

Temporary variables like n, mean, and total_square_dev are often helpful when it comes to debugging your code. If, for example, something goes wrong with one of them, then you can call print() to know what’s happening before the return statement runs.

In general, you should avoid using complex expressions in your return statement. Instead, you can break your code into multiple steps and use temporary variables for each step. Using temporary variables can make your code easier to debug, understand, and maintain.

Returning Values vs Modifying Globals

Functions that don’t have an explicit return statement with a meaningful return value often preform actions that have side effects. A side effect can be, for example, printing something to the screen, modifying a global variable, updating the state of an object, writing some text to a file, and so on.

Modifying global variables is generally considered a bad programming practice. Just like programs with complex expressions, programs that modify global variables can be difficult to debug, understand, and maintain.

When you modify a global variable, you’re potentially affecting all the functions, classes, objects, and any other parts of your programs that rely on that global variable.

To understand a program that modifies global variables, you need to be aware of all the parts of the program that can see, access, and change those variables. So, good practice recommends writing self-contained functions that take some arguments and return a useful value (or values) without causing any side effect on global variables.

Additionally, functions with an explicit return statement that return a meaningful value are easier to test than functions that modify or update global variables.

The following example show a function that changes a global variable. The function uses the global statement, which is also considered a bad programming practice in Python:

>>> counter = 0

>>> def increment():
...     global counter
...     counter += 1
...

>>> increment()
>>> counter
1

In this example, you first create a global variable, counter, with an initial value of 0. Inside increment(), you use a global statement to tell the function that you want to modify a global variable. The last statement increments counter by 1.

The result of calling increment() will depend on the initial value of counter. Different initial values for counter will generate different results, so the function’s result can’t be controlled by the function itself.

To avoid this kind of behavior, you can write a self-contained increment() that takes arguments and returns a coherent value that depends only on the input arguments:

>>> counter = 0

>>> def increment(var):
...     return var + 1
...

>>> increment(counter)
1

>>> counter
0

>>> # Explicitly assign a new value to counter
>>> counter = increment(counter)
>>> counter
1

Now the result of calling increment() depends only on the input arguments rather than on the initial value of counter. This makes the function more robust and easier to test.

Additionally, when you need to update counter, you can do so explicitly with a call to increment(). This way, you’ll have more control over what’s happening with counter throughout your code.

In general, it’s a good practice to avoid functions that modify global variables. If possible, try to write self-contained functions with an explicit return statement that returns a coherent and meaningful value.

Using return With Conditionals

Python functions are not restricted to having a single return statement. If a given function has more than one return statement, then the first one encountered will determine the end of the function’s execution and also its return value.

A common way of writing functions with multiple return statements is to use conditional statements that allow you to provide different return statements depending on the result of evaluating some conditions.

Suppose you need to code a function that takes a number and returns its absolute value. If the number is greater than 0, then you’ll return the same number. If the number is less than 0, then you’ll return its opposite, or non-negative value.

Here’s a possible implementation for this function:

>>> def my_abs(number):
...     if number > 0:
...         return number
...     elif number < 0:
...         return -number
...

>>> my_abs(-15)
15

>>> my_abs(15)
15

my_abs() has two explicit return statements, each of them wrapped in its own if statement. It also has an implicit return statement. If number happens to be 0, then neither condition is true, and the function ends without hitting any explicit return statement. When this happens, you automatically get None.

Take a look at the following call to my_abs() using 0 as an argument:

>>> print(my_abs(0))
None

When you call my_abs() using 0 as an argument, you get None as a result. That’s because the flow of execution gets to the end of the function without reaching any explicit return statement. Unfortunately, the absolute value of 0 is 0, not None.

To fix this problem, you can add a third return statement, either in a new elif clause or in a final else clause:

>>> def my_abs(number):
...     if number > 0:
...         return number
...     elif number < 0:
...         return -number
...     else:
...         return 0
...

>>> my_abs(0)
0

>>> my_abs(-15)
15

>>> my_abs(15)
15

Now, my_abs() checks every possible condition, number > 0, number < 0, and number == 0. The purpose of this example is to show that when you’re using conditional statements to provide multiple return statements, you need to make sure that every possible option gets its own return statement. Otherwise, your function will have a hidden bug.

Finally, you can implement my_abs() in a more concise, efficient, and Pythonic way using a single if statement:

>>> def my_abs(number):
...     if number < 0:
...         return -number
...     return number
...

>>> my_abs(0)
0

>>> my_abs(-15)
15

>>> my_abs(15)
15

In this case, your function hits the first return statement if number < 0. In all other cases, whether number > 0 or number == 0, it hits the second return statement. With this new implementation, your function looks a lot better. It’s more readable, concise, and efficient.

If you’re using if statements to provide several return statements, then you don’t need an else clause to cover the last condition. Just add a return statement at the end of the function’s code block and at the first level of indentation.

Returning True or False

Another common use case for the combination of if and return statements is when you’re coding a predicate or Boolean-valued function. This kind of function returns either True or False according to a given condition.

For example, say you need to write a function that takes two integers, a and b, and returns True if a is divisible by b. Otherwise, the function should return False. Here’s a possible implementation:

>>> def is_divisible(a, b):
...     if not a % b:
...         return True
...     return False
...

>>> is_divisible(4, 2)
True

>>> is_divisible(7, 4)
False

is_divisible() returns True if the remainder of dividing a by b is equal to 0. Otherwise, it returns False. Note that in Python, a 0 value is falsy, so you need to use the not operator to negate the truth value of the condition.

Sometimes you’ll write predicate functions that involve operators like the following:

• The comparison operators ==, !=, >, >=, <, and <=
• The membership operator in
• The identity operator is
• The Boolean operator not

In these cases, you can directly use a Boolean expression in your return statement. This is possible because these operators return either True or False. Following this idea, here’s a new implementation of is_divisible():

>>> def is_divisible(a, b):
...     return not a % b
...

>>> is_divisible(4, 2)
True

>>> is_divisible(7, 4)
False

If a is divisible by b, then a % b returns 0, which is falsy in Python. So, to return True, you need to use the not operator.

On the other hand, if you try to use conditions that involve Boolean operators like or and and in the way you saw before, then your predicate functions won’t work correctly. That’s because these operators behave differently. They return one of the operands in the condition rather than True or False:

>>> 0 and 1
0
>>> 1 and 2
2

>>> 1 or 2
1
>>> 0 or 1
1

In general, and returns the first false operand or the last operand. On the other hand, or returns the first true operand or the last operand. So, to write a predicate that involves one of these operators, you’ll need to use an explicit if statement or a call to the built-in function bool().

Suppose you want to write a predicate function that takes two values and returns True if both are true and False otherwise. Here’s your first approach to this function:

>>> def both_true(a, b):
...     return a and b
...
>>> both_true(1, 2)
2

Since and returns operands instead of True or False, your function doesn’t work correctly. There are at least three possibilities for fixing this problem:

1. An explicit if statement
2. A conditional expression (ternary operator)
3. The built-in Python function bool()

If you use the first approach, then you can write both_true() as follows:

>>> def both_true(a, b):
...     if a and b:
...         return True
...     return False
...

>>> both_true(1, 2)
True

>>> both_true(1, 0)
False

The if statement checks if a and b are both truthy. If so, then both_true() returns True. Otherwise, it returns False.

If, on the other hand, you use a Python conditional expression or ternary operator, then you can write your predicate function as follows:

>>> def both_true(a, b):
...     return True if a and b else False
...
>>> both_true(1, 2)
True

>>> both_true(1, 0)
False

Here, you use a conditional expression to provide a return value for both_true(). The conditional expression is evaluated to True if both a and b are truthy. Otherwise, the final result is False.

Finally, if you use bool(), then you can code both_true() as follows:

>>> def both_true(a, b):
...     return bool(a and b)
...

>>> both_true(1, 2)
True

>>> both_true(1, 0)
False

bool() returns True if a and b are true and False otherwise. It’s up to you what approach to use for solving this problem. However, the second solution seems more readable. What do you think?

Short-Circuiting Loops

A return statement inside a loop performs some kind of short-circuit. It breaks the loop execution and makes the function return immediately. To better understand this behavior, you can write a function that emulates any(). This built-in function takes an iterable and returns True if at least one of its items is truthy.

To emulate any(), you can code a function like the following:

>>> def my_any(iterable):
...     for item in iterable:
...         if item:
...             # Short-circuit
...             return True
...     return False

>>> my_any([0, 0, 1, 0, 0])
True

>>> my_any([0, 0, 0, 0, 0])
False

If any item in iterable is true, then the flow of execution enters in the if block. The return statement breaks the loop and returns immediately with a return value of True. If no value in iterable is true, then my_any() returns False.

This function implements a short-circuit evaluation. For example, suppose that you pass an iterable that contains a million items. If the first item in that iterable happens to be true, then the loop runs only one time rather than a million times. This can save you a lot of processing time when running your code.

It’s important to note that to use a return statement inside a loop, you need to wrap the statement in an if statement. Otherwise, the loop will always break in its first iteration.

Recognizing Dead Code

As soon as a function hits a return statement, it terminates without executing any subsequent code. Consequently, the code that appears after the function’s return statement is commonly called dead code. The Python interpreter totally ignores dead code when running your functions. So, having that kind of code in a function is useless and confusing.

Consider the following function, which adds code after its return statement:

>>> def dead_code():
...     return 42
...     # Dead code
...     print("Hello, World")
...

>>> dead_code()
42

The statement print("Hello, World") in this example will never execute because that statement appears after the function’s return statement. Identifying dead code and removing it is a good practice that you can apply to write better functions.

It’s worth noting that if you’re using conditional statements to provide multiple return statements, then you can have code after a return statement that won’t be dead as long as it’s outside the if statement:

>>> def no_dead_code(condition):
...     if condition:
...         return 42
...     print("Hello, World")
...

>>> no_dead_code(True)
42
>>> no_dead_code(False)
Hello, World

Even though the call to print() is after a return statement, it’s not dead code. When condition is evaluated to False, the print() call is run and you get Hello, World printed to your screen.

Returning Multiple Named-Objects

When you’re writing a function that returns multiple values in a single return statement, you can consider using a collections.namedtuple object to make your functions more readable. namedtuple is a collection class that returns a subclass of tuple that has fields or attributes. You can access those attributes using dot notation or an indexing operation.

The initializer of namedtuple takes several arguments. However, to start using namedtuple in your code, you just need to know about the first two:

1. typename holds the name of the tuple-like class that you’re creating. It needs to be a string.
2. field_names holds the names of the fields or attributes of the tuple-like class. It can be a sequence of strings such as ["x", "y"] or a single string with each name separated by whitespace or commas, such as "x y" or "x, y".

Using a namedtuple when you need to return multiple values can make your functions significantly more readable without too much effort. Consider the following update of describe() using a namedtuple as a return value:

import statistics as st
from collections import namedtuple

def describe(sample):
    Desc = namedtuple("Desc", ["mean", "median", "mode"])
    return Desc(
        st.mean(sample),
        st.median(sample),
        st.mode(sample),
    )

Inside describe(), you create a namedtuple called Desc. This object can have named attributes that you can access by using dot notation or by using an indexing operation. In this example, those attributes are "mean", "median", and "mode".

You can create a Desc object and use it as a return value. To do that, you need to instantiate Desc like you’d do with any Python class. Note that you need to supply a concrete value for each named attribute, just like you did in your return statement.

Here’s how describe() works now:

>>> sample = [10, 2, 4, 7, 9, 3, 9, 8, 6, 7]
>>> stat_desc = describe(sample)

>>> stat_desc
Desc(mean=5.7, median=6.0, mode=6)

>>> # Get the mean by its attribute name
>>> stat_desc.mean
5.7

>>> # Get the median by its index
>>> stat_desc[1]
6.0

>>> # Unpack the values into three variables
>>> mean, median, mode = describe(sample)

>>> mean
5.7

>>> mode
6

When you call describe() with a sample of numeric data, you get a namedtuple object containing the mean, median, and mode of the sample. Note that you can access each element of the tuple by using either dot notation or an indexing operation.

Finally, you can also use an iterable unpacking operation to store each value in its own independent variable.