Day3-modules.rst

Loading and using Python modules

What is a module?

A module in Python is simply a Python .py file that contains a list of related functions that can be loaded and used. Modules 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, and many of them greatly extend what can be done in a normal Python interpreter window. In fact, the abundance of free Python modules is one of the best reasons to learn and start using Python.

How can modules be loaded?

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

1. Let's start simple with the math module. Here, we'll load the math module using the import statement.

   >>> 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 such as print() do not require the name of the module first since nothing is explicitly imported.

2. 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 (e.g., matplotlib).

3. It is also possible to import only a single function from a module, rather than the entire module. This is sometimes useful when using large modules that have much more available than the desired use.

   >>> 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 really only do this when you truly need to.

4. Some modules have sub-modules that can also be imported without importing the entire module. We will 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()
   <matplotlib.figure.Figure at 0x10bfac4e0>

   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.

How can modules be used?

As we see above, the easiest way to use a module is to import it and 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', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'trunc']

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.

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

sin(...)
    sin(x)

    Return the sine of x (measured in radians).
(END)

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.

1. 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 *.
2. Don't use confusing names when renaming on import. Be smart when you import modules. 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 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.