SRSG UNIVERSE-HPC Training

The power of libraries

Most of the power of a programming language lies in its libraries.

A library, or a package is a collection of files (each called a module) that contains functions, types etc. for use in other programs.

May also contain data values (e.g., numerical constants) and other things.
A good libraries content will be related, but there's no way to enforce that.

The Python standard library is an extensive suite of modules that comes with Python itself.

Many additional libraries are available from PyPI (the Python Package Index) or elsewhere.
We will later see how to write our own libraries.

Using libraries brings several benefits:

We don't have to write everything ourselves, often the task you are trying to accomplish has been done before.
Good libraries may also be documented, tested, optimised and continually maintained such that they are more reliable than our own code.
Our code is easier to understand to others, since they may be familiar with the library we are using.
We can learn good programming practices from libraries.
- How did they accomplish something?

Libraries and modules

A library is a collection of modules, but the terms are often used interchangeably, especially since many libraries only consist of a single module, so don't worry if you mix the terms.

Importing modules

A module must be imported before it can be used.

Use an import statement to load a library module into a program's memory.
Once imported, we refer to "things" from the module as module_name.thing_name.
- Python uses . to mean "part of".
- Modules can be nested within one another e.g. module_name.submodule.function.

Using math, one of the modules in the standard library:

import math

print('pi is', math.pi)
print('cos(pi) is', math.cos(math.pi))

pi is 3.141592653589793
cos(pi) is -1.0

We always have to refer to each item with the module's name.

math.cos(pi) won't work: the reference to pi doesn't somehow "inherit" the function's reference to math.

Use `help` on modules

We can find more out about a module with help, this works just like with a function.

help(math)

Help on module math:

NAME
    math

MODULE REFERENCE
    http://docs.python.org/3/library/math

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

DESCRIPTION
    This module is always available.  It provides access to the
    mathematical functions defined by the C standard.

FUNCTIONS
    acos(x, /)
        Return the arc cosine (measured in radians) of x.
⋮ ⋮ ⋮

Importing specific items

We can simplify and speed up our programs by importing only what we need.

Use the form from ... import ... to load only specific items from a library module.
Then refer to them directly without library name as prefix.

from math import cos, pi

print('cos(pi) is', cos(pi))

cos(pi) is -1.0

Creating aliases

We can create an alias for a library module when importing it to make our programs clearer and shorter.

Use the form import ... as ... to give a library a short alias while importing it.
Then refer to items in the library using that shortened name.

import math as m

print('cos(pi) is', m.cos(m.pi))

cos(pi) is -1.0

Commonly used for libraries that are frequently used or have long names.
- E.g., the matplotlib plotting library is often aliased as mpl. Overusing aliasing can make programs harder to understand, since readers must learn your program's aliases.

We can, of course, also combine both selective importing and aliasing using from ... import ... as ... to do both things at once.

from matplotlib import pyplot as plt

Will alias just the matplotlib.pyplot module into plt.

Locating the Right Module

You want to select a random character from a string:

bases = 'ACTTGCTTGAC'

Which standard library [stdlib] module could help you?
Which function would you select from that module? Are there alternatives?
Try to write a program that uses the function.

The random module seems like it could help you.

The string has 11 characters, each having a positional index from 0 to 10. You could use either random.randrange or random.randint functions to get a random integer between 0 and 10, and then pick out the character at that position:

from random import randrange

random_index = randrange(len(bases))
print(bases[random_index])

or more compactly:

from random import randrange

print(bases[randrange(len(bases))])

Perhaps you found the random.sample function? It allows for slightly less typing:

from random import sample

print(sample(bases, 1)[0])

Note that this function returns a list of values. We will learn about lists later.

There's also other functions you could use, but with more convoluted code as a result.

When is Help Available?

When a colleague of yours types help(math), Python reports an error:

NameError: name 'math' is not defined

What has your colleague forgotten to do?

Importing With Aliases

Fill in the blanks so that the program below prints 90.0.
Rewrite the program so that it uses import without as.
Which form do you find easier to read?

import math as m
angle = ____.degrees(____.pi / 2)
print(____)

import math as m
angle = m.degrees(m.pi / 2)
print(angle)

can be written as

import math
angle = math.degrees(math.pi / 2)
print(angle)

Since you just wrote the code and are familiar with it, you might actually find the first version easier to read. But when trying to read a huge piece of code written by someone else, or when getting back to your own huge piece of code after several months, non-abbreviated names are often easier, except where there are clear abbreviation conventions.

Many Ways To Import Libraries

Match the following print statements with the appropriate library calls.

Print commands:

print("sin(pi/2) =", sin(pi/2))
print("sin(pi/2) =", m.sin(m.pi/2))
print("sin(pi/2) =", math.sin(math.pi/2))

Library calls:

from math import sin, pi
import math
import math as m
from math import *

Library calls 1 and 4. In order to directly refer to sin and pi without the library name as prefix, you need to use the from ... import ... statement. Whereas library call 1 specifically imports the two functions sin and pi, library call 4 imports all functions in the math module.
Library call 3. Here sin and pi are referred to with a shortened library name m instead of math. Library call 3 does exactly that using the import ... as ... syntax - it creates an alias for math in the form of the shortened name m.
Library call 2. Here sin and pi are referred to with the regular library name math, so the regular import ... call suffices.

Note: although library call 4 works, importing all names from a module using a wildcard import is not recommended as it makes it unclear which names from the module are used in the code. In general it is best to make your imports as specific as possible and to only import what your code uses. In library call 1, the import statement explicitly tells us that the sin function is imported from the math module, but library call 4 does not convey this information.

Importing specific items

Fill in the blanks so that the program below prints 90.0.
Do you find this version easier to read than preceding ones?
Why wouldn't programmers always use this form of import?

____ math import ____, ____
angle = degrees(pi / 2)
print(angle)

from math import degrees, pi
angle = degrees(pi / 2)
print(angle)

Most likely you find this version easier to read since it's less dense. The main reason not to use this form of import is to avoid name clashes. For instance, you wouldn't import degrees this way if you also wanted to use the name degrees for a variable or function of your own. Or if you were to also import a function named degrees from another library.

Reading Error Messages

Read the code below and try to identify what the errors are without running it.
Run the code, and read the error message. What type of error is it?

from math import log
log(0)

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
<ipython-input-1-d72e1d780babin <module>
      1 from math import log
----2 log(0)

ValueError: math domain error

The logarithm of x is only defined for x > 0, so 0 is outside the domain of the function.
You get an error of type ValueError, indicating that the function received an inappropriate argument value. The additional message "math domain error" makes it clearer what the problem is.

Libraries

The power of libraries

Libraries and modules

Importing modules

Use help on modules

Importing specific items

Creating aliases

Locating the Right Module

When is Help Available?

Importing With Aliases

Many Ways To Import Libraries

Importing specific items

Reading Error Messages

Useful links

Use `help` on modules