Function Docstrings

def squares_a_list(numerical_list):
    new_squared_list = list()
    
    for number in numerical_list:
        new_squared_list.append(number ** 2)
    
    return new_squared_list

Functions can get very complicated, so it is not always obvious what they do just from looking at the name, arguments, or code.

Therefore, people like to explain what the function does.

The standard format for doing this is called a docstring.

A docstring is a literal string that comes directly after the function def and documents the function’s purpose and usage.

Writing a docstring documents what your code does so that collaborators (and you in 6 months’ time!) are not struggling to decipher and reuse your code.

In the last section we had our function squares_a_list().

Although our function name is quite descriptive, it could mean various things.

How do we know what data type it takes in and returns?

Having documentation for it can be useful in answering these questions.

Here is the code for a function from the pandas package called truncate().

You can view the complete code here.

I think we can all agree that it would take a bit of time to figure out what the function is doing, the expected input variable types, and what the function is returning.

Luckily pandas provides detailed documentation to explain the function’s code.

Ah. This documentation gives us a much clearer idea of what the function is doing and how to use it.

We can see what it requires as input arguments and what it returns.

It also explains the expectations of the function.

Reading this instead of the code saved us some time and definitely potential confusion.

There are several styles of docstrings; this one and the one we’ll be using is called the NumPy style.

string1 = """This is a string"""
type(string1)

str

The NumPy format includes 4 main sections:

• A brief description of the function
  
• Explaining the input Parameters
  
• What the function Returns
  
• Examples

All docstrings, not just the Numpy formatted ones, are contained within 3 sets of quotations""". We discussed in module 4 that this was one of the ways to implement string values.

Adding this additional string to our function has no effect on our code, and the sole purpose of the docstring is for human consumption.

The NumPy format includes 4 main sections:

• A brief description of the function
  
• Explaining the input Parameters
  
• What the function Returns
  
• Examples

NumPy Format

def squares_a_list(numerical_list):
    """
    Squared every element in a list.
    
    Parameters
    ----------
    numerical_list : list
        The list from which to calculate squared values 
        
    Returns
    -------
    list
        A new list containing the squared value of each of the elements from the input list 
        
    Examples
    --------
    >>> squares_a_list([1, 2, 3, 4])
    [1, 4, 9, 16]
    """
    new_squared_list = list()
    for number in numerical_list:
        new_squared_list.append(number ** 2)
    return new_squared_list

Writing documentation for squares_a_list() using the NumPy style takes the following format.

We can identify the brief description of the function at the top, the parameters that it takes in, and what object type they should be, as well as what to expect as an output.

Here we can even see examples of how to run it and what is returned.

def function_name(param1, param2):
    """The first line is a short description of the function.
    
    A paragraph describing in a bit more detail what the function
    does and what algorithms it uses and common use cases.
    
    Parameters
    ----------
    param1 : datatype
        A description of param1.
    param2 : datatype
        A longer description because maybe this requires
        more explanation, and we can use several lines.
    
    Returns
    -------
    datatype
        A description of the output, data types, and behaviors.
        Describe special cases and anything the user needs to know 
        to use the function.
    
    Examples
    --------
    >>> function_name(3, 8, -5)
    2.0
    """

Functions using the NumPy docstring style follow this general form (reproduced from the SciPy/NumPy docs).

Default Arguments

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 
        
    Examples
    --------
    >>> exponent_a_list([1, 2, 3, 4])
    [1, 4, 9, 16]
    """

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

If our function contains optional arguments, we need to communicate this in our docstring.

Using exponent_a_list(), a function from the previous section as an example, we include an optional note in the parameter definition and an explanation of the default value in the parameter description.

Side Effects

def function_name(param1, param2):
    """The first line is a short description of the function. 
    
    If your function includes side effects, explain it clearly here.
    
    
    Parameters
    ----------
    param1 : datatype
        A description of param1.
    
    .
    .
    .
    Etc.
    """

Ah, remember how we talked about side effects back at the beginning of this module?

Although we recommend avoiding side effects in your functions, there may be occasions where they’re unavoidable or required.

In these cases, we must make it clear in the documentation so that the user of the function knows that their objects are going to be modified. (As an analogy: If someone wants you to babysit their cat, you would probably tell them first if you were going to paint it red while you had it!)

So how we include side effects in our docstrings?

It’s best to include your function side effects in the first sentence of the docstring.

How to read a docstring

?function_name

For example, if we want the docstring for the function len():

?len

Signature: len(obj, /)
Docstring: Return the number of items in a container.
Type:      builtin_function_or_method

Ok great! Now that we’ve written and explained our functions with a standardized format, we can read it in our file easily, but what if our function is located in a different file?

How can we learn what it does when reading our code?

We learned in the first assignment that we can read more about built-in functions using the question mark before the function name.

This returns the docstring of the function.

?squares_a_list

Signature: squares_a_list(numerical_list)
Docstring:
Squared every element in a list.

Parameters
----------
numerical_list : list
    The list from which to calculate squared values 

Returns
-------
list
    A new list containing the squared value of each of the elements from the input list 

Examples
--------
>>> squares_a_list([1, 2, 3, 4])
[1, 4, 9, 16]
File:      ~/<ipython-input-1-7e6e50ac7556>
Type:      function

The same thing can be done to get the documentation of functions that we have defined.

Getting the documentation for our function squares_a_list() is as easy as ?squares_a_list.

This returns the docstring that we created.

Let’s apply what we learned!