How

How to import code from python files

Given a <file.py> file in a directory any other python process in the same directory can import that file as it would a normal library.

Tip

import <file>

At that stage it is possible to uses any python object (a function, a class, a variable) by referring to the <file.py> as library:

<file>.function
<file>.class
<file>.variable

See the Tutorial for examples of this.

How to break up code in to modular components

When modularising code aim to identify specific components of the code that can be isolated from the rest.

In practice this means writing multiple functions that use the correct inputs and outputs in chain for an overall goal.

Often this allows us to write a more comprehensive docstring that explains specific parts of the implemented process.

As an example, consider the problem of wanting to pay a shared bill after applying a tip, the following function will do this:

def add_tip_and_get_bill_share(total, tip_proportion, number_of_payers):
    """
    This returns the share of a bill to be paid by `number_of_payers`
    ensuring the total paid includes a tip.

    Parameters
    ----------
    total : float
        The total amount of the bill
    tip_proportion : float
        The proportion of the bill that should be added as a tip (a number
        between 0 and 1)
    number_of_payers : int
        The number of people sharing the bill

    Returns
    -------
    float
        The amount each person should contribute
    """
    tip_amount = tip_proportion * total
    total += tip_amount
    return total / number_of_payers

We can check that this works:

add_tip_and_get_bill_share(total=100, tip_proportion=0.2, number_of_payers=6)

20.0

An improvement of the above would be:

def add_tip(total, tip_proportion):
    """
    This adds the given proportion to a bill total.

    Note that tip_proportion is a number between 0 and 1. A tip_proportion of 0
    corresponds to no tip and a tip_proportion of 1 corresponds to paying the
    total twice.

    Parameters
    ----------
    total : float
        The total amount of the bill
    tip_proportion : float
        The proportion of the bill that should be added as a tip (a number
        between 0 and 1)

    Returns
    -------
    float
        The total value of the bill (including tip)
    """
    tip_amount = tip_proportion * total
    return total + tip_amount


def get_bill_share(total, number_of_payers):
    """
    This returns the share of a bill by dividing the total by the number of
    payers.

    Parameters
    ----------
    total : float
        The total amount of the bill
    number_of_payers : int
        The number of people sharing the bill

    Returns
    -------
    float
        The amount each person should contribute
    """
    return total / number_of_payers

Then to use the above we would be able to explicitly write out each step which ensures that there is clarity in what is being done:

total = add_tip(total=100, tip_proportion=0.2)
get_bill_share(total=total, number_of_payers=6)

20.0

You can read more and find reference texts about modularisation at Why modularise?.