Warning: This document is for the development version of Geo-Python. The main version is master.

This page was generated from source/notebooks/L4/modules.ipynb.

Loading and using modules

Modules, packages and libraries?

Python module is simply a Python .py file that contains 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:

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!")

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.

import math as m

m.sqrt(49)

7.0

type(m)

module

In this example we now see that when the math module is imported, it is imported to be usable with the name m instead of math. It doesn’t matter much in our toy example here since math is not a long module name, but we will see other examples later in the course where renaming the modules is very helpful. 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.

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 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

plt.figure()

<Figure size 432x288 with 0 Axes>

<Figure size 432x288 with 0 Axes>

This creates a new figure window for a pyplot figure. Again, we’ll see how this works and what it means later in the course.

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__', '__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', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'trunc']

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

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).

help(math.sin)

Help on built-in function sin in module math:

sin(...)
    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.

Extra: installing packages

For those using their own computers, we recommend using the Conda package management system that comes with the Anaconda distribution. Using conda, you can always list package names and versions using the conda list command line command. Read more about installing Anaconda, and about managing Python packages using conda on the course webpages and Conda documentation.

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.

Checking all available modules in a Jupyter Notebook

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.
#help("modules")