Loading and using modules

Attention

Finnish university students are encouraged to use the CSC Notebooks platform.
CSC badge

Others can follow the lesson and fill in their student notebooks using Binder.
Binder badge

Modules, packages and libraries?

Python module refers to a piece of Python code that is designed to execute a spesific task. Technically, modules are simply Python script files (file extension.py) that contain function definitions and other statements. Python packages are a way of organizing modules into larger entities.

Modules and packages are similar to what are more generally called libraries in programming languages, which again contain code related to a specific task such as mathematical operations. There are a HUGE number of Python modules/packages, and many of them greatly extend what can be done in a normal Python program. In fact, the abundance of free Python modules is one of the best reasons to learn and start using Python.

The words “module”, “package” and “library” are often used interchangeably.

Loading modules

Python modules can be loaded in a number of different ways.

Let’s start simple with the math module. Here, we’ll load the math module using the import statement and try out some of the functions in the module, such as the square root function sqrt.

import math
math.sqrt(81)
9.0

Here we have loaded the math module by typing import math, which tells Python to read in the functions in the math module and make them available for use. In our example, we see that we can use a function within the math library by typing the name of the module first, a period, and then the name of function we would like to use afterward (e.g., math.sqrt()).

Built-in functions

Built-in functions such as print() are always available without importing anything:

print("Hello world!")
Hello world!

Technically, the built-in functions belong to a module called builtins.

Renaming imported modules

We can also rename modules when they are imported. This can be helpful when using modules with longer names. Let’s import the math module but rename it to m using the format import module as name. Then we can using the sqrt function from the math library and check the type of our module named m.

import math as m
m.sqrt(49)
7.0
type(m)
module

Here, we imported the math module to be usable with the name m instead of math. We will see other examples later in the course where using an alternate name is rather useful. For example, next week we will start using the pandas library for data analysis. It is customary to import pandas as pd:

import pandas as pd

Importing a single function

It is also possible to import only a single function from a module, rather than the entire module. This is sometimes useful when needing only a small piece of a large module. We can do this using the form from module import function. Let’s import the sqrt function from the math module using this form. Again, we can test using our resulting function afterward.

from math import sqrt
sqrt(121)
11.0

Though this can be useful, it has the drawback that the imported function could conflict with other built-in or imported function names, and you lose the information about which module contains the imported function. You should only do this when you truly need to.

Importing a submodule

Some modules have submodules that can also be imported without importing the entire module. We may see examples of this later when making data plots using the pyplot sub-module of the Matplotlib module. In case you’re curious, here is an example.

import matplotlib.pyplot as plt
# Plot a simple x y line graph with default settings
plt.plot([1, 2, 3, 4, 5], [5, 4, 3, 2, 1])
[<matplotlib.lines.Line2D at 0x7f57bdfe7590>]
../../_images/modules_18_1.png

You can read more about the plotting function in matplotlib pyplot documentation. We will introduce matplotlib in detail during week 7.

Using module functions

As we see above, the easiest way to use a module is to import it an then use its functions by typing modulename.functionname() and providing the necessary arguments. Yes, it is that simple.

However, there are times you may not know the names of all of the functions in a given module, or which are part of a module. You can view the list of functions that are part of a module by using the dir() function.

print(dir(math))
['__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'acos', 'acosh', 'asin', 'asinh', 'atan', 'atan2', 'atanh', 'ceil', 'copysign', 'cos', 'cosh', 'degrees', 'e', 'erf', 'erfc', 'exp', 'expm1', 'fabs', 'factorial', 'floor', 'fmod', 'frexp', 'fsum', 'gamma', 'gcd', 'hypot', 'inf', 'isclose', 'isfinite', 'isinf', 'isnan', 'ldexp', 'lgamma', 'log', 'log10', 'log1p', 'log2', 'modf', 'nan', 'pi', 'pow', 'radians', 'remainder', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'tau', 'trunc']

You can also browse the available modules by typing in modulename. and then pressing the tab-key:

view module keys img

So that’s helpful, but what about when you don’t know what a given function does? The easiest solution is to use the help() function (after importing the module). Let’s check the help for the math.sin function.

help(math.sin)
Help on built-in function sin in module math:

sin(x, /)
    Return the sine of x (measured in radians).

Note that you’ll need to press q to exit the help viewer.

What should I not do?

Here are a few things to avoid.

from X import *

Don’t use from X import *. This may be easier to understand by way of an example, but assuming X above is a Python module, from X import * will import all of the functions in module X. Though you might think this is helpful, it is much better to simply import X or import X as Y to keep the connection between the functions and their module. It is also much more likely you will encounter conflicting names when using from X import *.

Poor names when renaming on import

Don’t use confusing names when renaming on import. Be smart when you import modules, and follow generally used conventions (import pandas as pd is a good way to do things!). If you want to make the module name shorter on import, pick a reasonable abbreviation. For instance, import matplotlib as m could be confusing, especially if you’re also using import math as m in other Jupyter notebooks or script files. Similarly, import matplotlib as math is perfectly OK syntax in Python, but bound to cause a world of trouble. Remember, people need to be able to read and understand the code you write, keep it simple and logical.

What does PEP 8 say about imports?

According to good coding practices described in PEP 8, we should always import modules at the top of the file. In this lesson, we are demonstrating how to import different modules along the way, but in general it would be better to import requried modules as the very first thing. PEP 8 refers more to traditional script files, but we can apply the guideline to Jupyter Notebook files by placing our imports the first code cell in the Jupyter Notebook.

Installing packages

For those using their own computers, we recommend using the Conda package management system that comes with the Anaconda and Miniconda Python installers. Using Conda, you can always list package names and versions using the conda list command line command. Read more about installing Python and Conda tools for the purposes of this course in here.

It’s also good to be aware of pip - the package installer for python. Pip and conda are often used for similar purposes, but the key difference is that pip is used for installing packages written in Python, while conda handles packages which might also contain code written in other languages. Generally, we encourage you to use conda when installing packages (and within conda, prefer to use the same channel for installations). However, sometimes you might need a package that is not available via conda, but can be installed with pip. Read more about differences and similarities of conda an pip in here.

In a Jupyter Notebook, you can type in `help("modules")` to check the complete list of installed packages in Python. However, the output is a bit clumsy and hard to read...
# List all available modules. Note: when running this command, you might first get several warnings related to deprecated packages etc.
# We have commented the command out here to limit output on the course website
# help("modules")