Explicitreturn Statements

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

>>>defreturn_42():...return42# An explicit return statement...>>>return_42()# The caller code gets 4242

When you definereturn_42(), you add an explicitreturn statement (return 42) at the end of the function’s code block.42 is the explicit return value ofreturn_42(). This means that any time you callreturn_42(), the function will send42 back to the caller.

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

>>>num=return_42()>>>num42>>>return_42()*284>>>return_42()+547

Sincereturn_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 areturn statement only inside a function or method definition. If you use it anywhere else, then you’ll get aSyntaxError:

>>>return42  File"<stdin>", line1SyntaxError:'return' outside function

When you usereturn outside a function or method, you get aSyntaxError 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 returnstrings, 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:

>>>defget_even(numbers):...even_nums=[numfornuminnumbersifnotnum%2]...returneven_nums...>>>get_even([1,2,3,4,5,6])[2, 4, 6]

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

A common practice is to use the result of anexpression as a return value in areturn statement. To apply this idea, you can rewriteget_even() as follows:

>>>defget_even(numbers):...return[numfornuminnumbersifnotnum%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 useexpressions in areturn statement. Expressions are different fromstatements likeconditionals orloops.

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 functionssum() andlen():

>>>defmean(sample):...returnsum(sample)/len(sample)...>>>mean([1,2,3,4])2.5

Inmean(), you don’t use a localvariable to store the result of the calculation. Instead, you use the expression directly as a return value. Python first evaluates the expressionsum(sample) / len(sample) and then returns the result of the evaluation, which in this case is the value2.5.

Implicitreturn 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 areturn statement, or if you totally omit thereturn statement, then Python will implicitly return a default value for you. That default return value will always beNone.

Say you’re writing a function that adds1 to a numberx, but you forget to supply areturn statement. In this case, you’ll get animplicitreturn statement that usesNone as a return value:

>>>defadd_one(x):...# No return statement at all...result=x+1...>>>value=add_one(5)>>>value>>>print(value)None

If you don’t supply an explicitreturn statement with an explicit return value, then Python will supply an implicitreturn statement usingNone as a return value. In the above example,add_one() adds1 tox and stores the value inresult but it doesn’t returnresult. That’s why you getvalue = None instead ofvalue = 6. To fix the problem, you need to eitherreturn result or directlyreturn x + 1.

An example of a function that returnsNone isprint(). 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 explicitreturn statement because it doesn’t return anything useful or meaningful:

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

The call toprint() printsHello, World to the screen. Since this is the purpose ofprint(), the function doesn’t need to return anything useful, so you getNone as a return value.

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

ReturningNone Explicitly

Some programmers rely on the implicitreturn 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 aprocedure.

There are situations in which you can add an explicitreturn 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 usefulreturn value, then you can omit returningNone because doing that would just be superfluous and confusing. You can also use a barereturn without a return value just to make clear your intention of returning from the function.

• If your function has multiplereturn statements and returningNone is a valid option, then you should consider the explicit use ofreturn 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 returningNone, you can use one of three possible approaches:

1. Omit thereturn statement and rely on the default behavior of returningNone.
2. Use a barereturn without a return value, which also returnsNone.
3. ReturnNone explicitly.

Here’s how this works in practice:

>>>defomit_return_stmt():...# Omit the return statement...pass...>>>print(omit_return_stmt())None>>>defbare_return():...# Use a bare return...return...>>>print(bare_return())None>>>defreturn_none_explicitly():...# Return None explicitly...returnNone...>>>print(return_none_explicitly())None

Whether or not to returnNone explicitly is a personal decision. However, you should consider that in some cases, an explicitreturn 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 returnNone for you. This can cause subtle bugs that can be difficult for a beginning Python developer tounderstand and debug.

You can avoid this problem by writing thereturn 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:

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

If you get used to starting your functions like this, then chances are that you’ll no longer miss thereturn 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 ofdebugging 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 usingtemporary variables with meaningful names.

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

>>>defvariance(data,ddof=0):...mean=sum(data)/len(data)...returnsum((x-mean)**2forxindata)/(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 ofvariance():

>>>defvariance(data,ddof=0):...n=len(data)...mean=sum(data)/n...total_square_dev=sum((x-mean)**2forxindata)...returntotal_square_dev/(n-ddof)...>>>variance([3,4,7,5,6,2,9,4,1,3])5.24

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

Temporary variables liken,mean, andtotal_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 callprint() to know what’s happening before thereturn statement runs.

In general, you should avoid using complex expressions in yourreturn 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 explicitreturn statement with a meaningful return value often preform actions that haveside effects. Aside effect can be, for example, printing something to the screen, modifying aglobal 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 writingself-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 explicitreturn statement that return a meaningful value are easier totest than functions that modify or update global variables.

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

>>>counter=0>>>defincrement():...globalcounter...counter+=1...>>>increment()>>>counter1

In this example, you first create a global variable,counter, with an initial value of0. Insideincrement(), you use aglobal statement to tell the function that you want to modify a global variable. The last statement incrementscounter by1.

The result of callingincrement() will depend on the initial value ofcounter. Different initial values forcounter 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-containedincrement() that takes arguments and returns a coherent value that depends only on the input arguments:

>>>counter=0>>>defincrement(var):...returnvar+1...>>>increment(counter)1>>>counter0>>># Explicitly assign a new value to counter>>>counter=increment(counter)>>>counter1

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

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

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

Usingreturn With Conditionals

Python functions are not restricted to having a singlereturn statement. If a given function has more than onereturn 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 multiplereturn statements is to useconditional statements that allow you to provide differentreturn statements depending on the result of evaluating some conditions.

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

Here’s a possible implementation for this function:

>>>defmy_abs(number):...ifnumber>0:...returnnumber...elifnumber<0:...return-number...>>>my_abs(-15)15>>>my_abs(15)15

my_abs() has two explicitreturn statements, each of them wrapped in its ownif statement. It also has an implicitreturn statement. Ifnumber happens to be0, then neither condition is true, and the function ends without hitting any explicitreturn statement. When this happens, you automatically getNone.

Take a look at the following call tomy_abs() using0 as an argument:

>>>print(my_abs(0))None

When you callmy_abs() using0 as an argument, you getNone as a result. That’s because the flow of execution gets to the end of the function without reaching any explicitreturn statement. Unfortunately, the absolute value of0 is0, notNone.

To fix this problem, you can add a thirdreturn statement, either in a newelif clause or in a finalelse clause:

>>>defmy_abs(number):...ifnumber>0:...returnnumber...elifnumber<0:...return-number...else:...return0...>>>my_abs(0)0>>>my_abs(-15)15>>>my_abs(15)15

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

Finally, you can implementmy_abs() in a more concise, efficient, andPythonic way using a singleif statement:

>>>defmy_abs(number):...ifnumber<0:...return-number...returnnumber...>>>my_abs(0)0>>>my_abs(-15)15>>>my_abs(15)15

In this case, your function hits the firstreturn statement ifnumber < 0. In all other cases, whethernumber > 0 ornumber == 0, it hits the secondreturn statement. With this new implementation, your function looks a lot better. It’s more readable, concise, and efficient.

If you’re usingif statements to provide severalreturn statements, then you don’t need anelse clause to cover the last condition. Just add areturn statement at the end of the function’s code block and at the first level of indentation.

ReturningTrue orFalse

Another common use case for the combination ofif andreturn statements is when you’re coding apredicate orBoolean-valued function. This kind of function returns eitherTrue orFalse according to a given condition.

For example, say you need to write a function that takes two integers,a andb, and returnsTrue ifa is divisible byb. Otherwise, the function should returnFalse. Here’s a possible implementation:

>>>defis_divisible(a,b):...ifnota%b:...returnTrue...returnFalse...>>>is_divisible(4,2)True>>>is_divisible(7,4)False

is_divisible() returnsTrue if the remainder of dividinga byb is equal to0. Otherwise, it returnsFalse. Note that in Python, a0 value isfalsy, so you need to use thenot 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 operatorin
• The identity operatoris
• The Boolean operatornot

In these cases, you can directly use aBoolean expression in yourreturn statement. This is possible because these operators return eitherTrue orFalse. Following this idea, here’s a new implementation ofis_divisible():

>>>defis_divisible(a,b):...returnnota%b...>>>is_divisible(4,2)True>>>is_divisible(7,4)False

Ifa is divisible byb, thena % b returns0, which is falsy in Python. So, to returnTrue, you need to use thenot operator.

On the other hand, if you try to use conditions that involve Boolean operators likeor andand 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 thanTrue orFalse:

>>>0and10>>>1and22>>>1or21>>>0or11

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 explicitif statement or a call to the built-in functionbool().

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

>>>defboth_true(a,b):...returnaandb...>>>both_true(1,2)2

Sinceand returns operands instead ofTrue orFalse, your function doesn’t work correctly. There are at least three possibilities for fixing this problem:

1. An explicitif statement
2. Aconditional expression (ternary operator)
3. The built-in Python functionbool()

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

>>>defboth_true(a,b):...ifaandb:...returnTrue...returnFalse...>>>both_true(1,2)True>>>both_true(1,0)False

Theif statement checks ifa andb are both truthy. If so, thenboth_true() returnsTrue. Otherwise, it returnsFalse.

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

>>>defboth_true(a,b):...returnTrueifaandbelseFalse...>>>both_true(1,2)True>>>both_true(1,0)False

Here, you use a conditional expression to provide a return value forboth_true(). The conditional expression is evaluated toTrue if botha andb are truthy. Otherwise, the final result isFalse.

Finally, if you usebool(), then you can codeboth_true() as follows:

>>>defboth_true(a,b):...returnbool(aandb)...>>>both_true(1,2)True>>>both_true(1,0)False

bool() returnsTrue ifa andb are true andFalse 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

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

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

>>>defmy_any(iterable):...foriteminiterable:...ifitem:...# Short-circuit...returnTrue...returnFalse>>>my_any([0,0,1,0,0])True>>>my_any([0,0,0,0,0])False

If anyitem initerable is true, then the flow of execution enters in theif block. Thereturn statement breaks the loop and returns immediately with a return value ofTrue. If no value initerable is true, thenmy_any() returnsFalse.

This function implements ashort-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 areturn statement inside a loop, you need to wrap the statement in anif statement. Otherwise, the loop will always break in its first iteration.

Recognizing Dead Code

As soon as a function hits areturn statement, it terminates without executing any subsequent code. Consequently, the code that appears after the function’sreturn statement is commonly calleddead 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 itsreturn statement:

>>>defdead_code():...return42...# Dead code...print("Hello, World")...>>>dead_code()42

The statementprint("Hello, World") in this example will never execute because that statement appears after the function’sreturn 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 multiplereturn statements, then you can have code after areturn statement that won’t be dead as long as it’s outside theif statement:

>>>defno_dead_code(condition):...ifcondition:...return42...print("Hello, World")...>>>no_dead_code(True)42>>>no_dead_code(False)Hello, World

Even though the call toprint() is after areturn statement, it’s not dead code. Whencondition is evaluated toFalse, theprint() call is run and you getHello, World printed to your screen.

Returning Multiple Named-Objects

When you’re writing a function that returns multiple values in a singlereturn statement, you can consider using acollections.namedtuple object to make your functions more readable.namedtuple is a collection class that returns a subclass oftuple that has fields or attributes. You can access those attributes usingdot notation or anindexing operation.

The initializer ofnamedtuple takes several arguments. However, to start usingnamedtuple 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 anamedtuple when you need to return multiple values can make your functions significantly more readable without too much effort. Consider the following update ofdescribe() using anamedtuple as a return value:

importstatisticsasstfromcollectionsimportnamedtupledefdescribe(sample):Desc=namedtuple("Desc",["mean","median","mode"])returnDesc(st.mean(sample),st.median(sample),st.mode(sample),)

Insidedescribe(), you create anamedtuple calledDesc. 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 aDesc object and use it as a return value. To do that, you need to instantiateDesc 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 yourreturn statement.

Here’s howdescribe() works now:

>>>sample=[10,2,4,7,9,3,9,8,6,7]>>>stat_desc=describe(sample)>>>stat_descDesc(mean=5.7, median=6.0, mode=6)>>># Get the mean by its attribute name>>>stat_desc.mean5.7>>># Get the median by its index>>>stat_desc[1]6.0>>># Unpack the values into three variables>>>mean,median,mode=describe(sample)>>>mean5.7>>>mode6

When you calldescribe() with a sample of numeric data, you get anamedtuple 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.