Functions

Unit 4

More on Functions

So far, we have used functions from python or other packages, such as numpy, to perform a generic task. What if there is no function for a specific task you need to carry out? If you anticipate that you will need to carry out the task again in the future, just write your own function! Moreover, if the program you’re coding is complex, it is good coding practice to partition your program into individual chunks of code (i.e., your own functions). This will help future readers substantially to understand your program.

So let’s write our first own functions!

def years2days():
    print("One year has 365 days!")

years2days()
One year has 365 days!

Let’s make it more useful..

def years2days(years):
    days = years * 365
    return days

days = years2days(2)
print(days)
730

And let’s write a brief statement of what our function does into the docstring:

def years2days(years):
    """
    Convert years to days

    This function takes a number of years as input and calculates 
    the equivalent number of days.
    """
    days = years * 365
    return days

A docstring is a special type of comment used in Python to describe what a function does. Think of a docstring as an instruction manual for a gadget. The code itself is the gadget, and the docstring is the manual that explains how to use it, what it does, and what to expect from it. While the code makes everything work, the docstring makes sure that anyone using or modifying the code knows exactly what it’s for and how to use it. You should use it yourself as often as possible!

A docstring is written inside triple quotes (“““) and placed right after the definition of a function. Docstrings typically follow a standard format, which makes them particularly useful for auto-generating documentation. You can access the docstring of a function using the help() function. We will get to see more docstring formatting soon.

#04-01: Functions for time conversion
  1. Copy the previous code block containing the function years2days into a file 04_unit/time_conversion.py and execute the function definition of our function years2days()
  2. What happens if you execute years2days??
  3. Write your own function days2hours() into the same file.
  4. Write your own function years2hours() into the same file and re-use the previous two functions in the conversion.
# This python file contains some useful functions for time conversion

def years2days(years):
    """
    Convert years to days

    This function takes a number of years as input and calculates 
    the equivalent number of days.
    """
    days = years * 365
    return days

def days2hours(days):
    """
    Convert days to hours

    This function takes a number of days as input and calculates 
    the equivalent number of hours.
    """
    hours = days * 24
    return hours

def years2hours(years):
    """
    Convert years to hours

    This function takes a number of years as input and calculates 
    the equivalent number of hours by using the previous two functions.
    """
    days = years2days(years)
    hours = days2hours(days)
    return hours

We have already used functions that took more than one argument. Let’s modify our function years2days() in a way that a user could specify the number of leap years that happened in the given time period.

def years2days(years, n_leapyears=0):
    days = (years * 365) + n_leapyears
    return days

print(years2days(1))
print(years2days(1, n_leapyears=1))
print(years2days(1, 1))
365
366
366

The above implementation of our function makes use of two types of function arguments. years is a positional argument. It is called this way, because its position matters (it has to be the first argument provided to the function), and it is required for the function to run successfully. n_leapyears is called a keyword argument, and it is defined as a pair (keyword_argument=<default_value>). The value provided with the keyword argument is a default value, so that the user can specify the number of leap years but does not have to. In case the user only provides input for years, the function assumes n_leapyears equal to 0. Keyword arguments can either be provided to the function at the correct position, or by providing the keyword–value pair.

Further resources

We have discussed most relevant aspects of writing your own functions in class. However, if you are interested to read up more, I recommend the second half of the online course PY4E on Functions (from the Section Adding new functions to the end).

Learning checklist

  • I can write my own functions and document their purpose with a docstring.
  • I have a foundational understanding of the flow of program execution.
  • I know the difference between parameters and arguments.
  • I know how to pass arguments to functions and I know how to return variables from functions.
  • I know the difference between positional and keyword arguments, and I know how to specify a default value for a function that I coded myself.
  • I understand the advantages of using functions to build modular code that can be reused.