Defensive Programming using Exceptions

Defensive programming: Code written in such a way that if errors do occur, they are handled in a graceful, fast and informative manner.

Exceptions: Used in Defensive programming to disrupts the normal flow of instructions. When Python encounters code that it cannot execute, it will throw an exception.

We all know that mistakes are a regular part of life.

In coding, every line of code is at risk for potential errors, so naturally, we want a way of defending our functions against potential issues.

Defensive programming is code written in such a way that, if errors do occur, they are handled in a graceful, fast and informative manner.

If something goes wrong, we don’t want the code to crash on its own terms - we want it to fail gracefully, in a way we pre-determined.

To help soften the landing, we write code that throws our own Exceptions.

Exceptions are used in Defensive programming to disrupt the normal flow of instructions. When Python encounters code that it cannot execute, it will throw an exception.

def exponent_a_list(numerical_list, exponent=2):
    new_exponent_list = list()
    for number in numerical_list:
        new_exponent_list.append(number ** exponent)
    return new_exponent_list

numerical_string = "123"
exponent_a_list(numerical_string)

TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'

Detailed traceback: 
  File "<string>", line 1, in <module>
  File "<string>", line 4, in exponent_a_list

Before we dive into exceptions, let’s revisit our function exponent_a_list().

It works somewhat well, but what happens if we try to use it with an input string instead of a list.

We get an error that explains a little bit of what’s causing the issue but not directly.

This error, called a TypeError here, is itself a Python exception. But the error message, which is a default Python message, is not super clear.

This is where raising our own Exception steps in to help.

Exceptions

def exponent_a_list(numerical_list, exponent=2):

    if type(numerical_list) is not list:
        raise Exception("You are not using a list for the numerical_list input.")

    new_exponent_list = list()
    for number in numerical_list:
        new_exponent_list.append(number ** exponent)
    return new_exponent_list

numerical_string = "123"
exponent_a_list(numerical_string)

Exception: You are not using a list for the numerical_list input.

Detailed traceback: 
  File "<string>", line 1, in <module>
  File "<string>", line 4, in exponent_a_list

(Note that in the interest of avoiding new syntax, we are using a simple way of checking if an object is of a certain data type. For a more robust approach see here.)

Exceptions disrupt the regular execution of our code. When we raise an Exception, we are forcing our own error with our own message.

If we wanted to raise an exception to solve the problem on the last slide, we could do the following.

Let’s take a closer look.

The first line of code is an if statement - what needs to occur to trigger this new code we’ve written.

This code translates to “If numerical_list is not of the type list…”.

The second line does the complaining.

We tell it to raise an Exception (throw an error) with this message.

Now we get an error message that is straightforward on why our code is failing.

Exception: You are not using a list for the numerical_list input.

I hope we can agree that this message is easier to decipher than the original.

The new message made the cause of the error much clearer to the user, making our function more usable.

Why raise Exceptions

if type(numerical_list) is not list:
    raise Exception("You are not using a list for the numerical_list input.")

Here we check if numerical_list is of the type we expect it to be, in this case, a list.

Checking the datatype is a helpful exception since the user can quickly correct for a simple mistake.

Exception types

if type(numerical_list) is not list:
    raise Exception("You are not using a list for the numerical_list input.")

Here is a full list containing other types of exceptions available.

Let’s now learn more about the possible different types of Exceptions.

The exception type called Exception is a generic, catch-all exception type.

There are also many other exception types; for example, you may have encountered ValueError or a TypeError at some point.

Exception, which is used in our previous examples, may not be the best option for the raises we made.

if type(numerical_list) is not list:
   raise Exception("You are not using a list for the numerical_list input.")

def exponent_a_list(numerical_list, exponent=2):

    if type(numerical_list) is not list:
        raise TypeError("You are not using a list for the numerical_list input.")

    new_exponent_list = list()
    for number in numerical_list:
        new_exponent_list.append(number ** exponent)
    return new_exponent_list

numerical_string = "123"
exponent_a_list(numerical_string)

TypeError: You are not using a list for the numerical_list input.

Detailed traceback: 
  File "<string>", line 1, in <module>
  File "<string>", line 4, in exponent_a_list

For the full list of exception types take a look at this resource.

Let’s take a look now at the exception we wrote that checks if the input value for numerical_list was the correct type.

Since this is a type error, a better-raised exception over Exception would be TypeError.

Let’s make our correction here and change Exception in our function to TypeError.

Exception Documentation

def exponent_a_list(numerical_list, exponent=2):
    """
    Creates a new list containing specified exponential values of the input list. 
    
    Parameters
    ----------
    numerical_list : list
        The list from which to calculate exponential values from
    exponent : int or float, optional
        The exponent value (the default is 2, which implies the square).
        
    Returns
    -------
    new_exponent_list : list
        A new list containing the exponential value specified of each 
        of the elements from the input list 
        
    Raises
    ------
    TypeError
        If the input argument numerical_list is not of type list
        
    Examples
    --------
    >>> exponent_a_list([1, 2, 3, 4])
    [1, 4, 9, 16]
    """

Now that we can write exceptions, it’s important to document them.

It’s a good idea to include details of any included exceptions in our function’s docstring.

Under the NumPy docstring format, we explain our raised exception after the “Returns” section.

We first specify the exception type and then an explanation of what causes the exception to be raised.

For example, we’ve added a “Raises” section in our exponent_a_list docstring here.

Let’s apply what we learned!