.. contents::
    :depth: 2
    
Download this page as:
    
    - :download:`a commented Python script <modules.py>`
    - :download:`a minimal Python script <modules_bare.py>`

Modules
=================

Importing modules
--------------------

One of the strengths of Python is that there are many built-in add-ons - or
*modules* - which allow you to do complex tasks in only a few lines of code. In addition, there are many other third-party modules (e.g. Numpy, Scipy,
Matplotlib) that can be installed, and you can also develop your own modules
that include functionalities you commonly use. From experience, it is advised to
break down your workflow in the most basic and general elementary functions, that
are responsible for one specific task (e.g. input/output). These can then easily
be reused in later projects, or used to build complex programs.

The built-in modules are referred to as the *Standard Library*, and you can
find a full list of the available functionality in the `Python Documentation
<http://docs.python.org/library/index.html>`_.

To use modules in your Python session or script, you need to import them. The
following example shows how to import the built-in ``os`` module, which
contains amongst other things many useful functions relating to files and
paths:
    
.. ipython::
    
    In [1]: import os

This will give you access to functions available within this module, which you
can now access if you use the module name as a prefix. For example, if we want
to check if a file ``data/m31.fits`` exists, we can use the ``os.path.exists``
function:

.. ipython::
    
    In [1]: os.path.exists('data/m31.fits')

In this case, we can use the function in an ``if`` statement, since it returns a boolean:

.. ipython::
    
    In [1]: if os.path.exists('data/m31.fits'):
       ...:    print("The file exists")
       ...:else:
       ...:    print("The file does not exist")
       ...: 

.. note:: As with objects in Python, once you have imported a module, you can
          (in IPython) type the name of the module, followed by ``.``, then
          press TAB to see the available functions!

If a module name is too long to be conveniently written each time you want to use a function, you can define a shortcut when you import it:

.. ipython::
    
    In [1]: import matplotlib.pyplot as plt
    
    In [1]: fig = plt.figure()

In the following workshops we will look at a number of third-party modules in
more detail, such as ``numpy`` for creating and manipulating high performance
arrays, ``scipy`` for scientific computing and ``matplotlib.pyplot`` for
plotting.

Scripts and modules
-----------------------

The main difference between *scripts* and *modules* is that if you execute scripts,
typically a series of tasks will be performed, while if you execute modules, typically
only a number of functions become available. Consider this small example of a
script, where we happen to have also defined a function::
    
    def add_two_numbers(x1,x2):
        return x1+x2
    
    y = add_two_numbers(4,3)
    print(y)
    
If you save the contents to a :download:`file <myscript.py>`, you can execute it in a terminal::
    
    $:> python myscript.py
    7
    
Consider also this small example of a module, where nothing is executed::
    
    def add_two_numbers(x1,x2):
        return x1+x2

saving this to a :download:`file <mymodule.py>` and executing it, will not do anything::
    
    $:> python mymodule.py

Python does not make a clear distinction between the script and a module, in the
sense that you can also import a script. What Python will do is execute the script,
while at the same time the function becomes available:

.. sourcecode:: ipython

    In [1]: import myscript
    7
 
    In [2]: myscript.add_two_numbers(4,3)
    7
        
    
It is **not** good practice to run a Python script by importing it! Still, you might want to make a certain script also available as a module, if you defined some generally useful
functions in there. You can do this by adding the statement ``if __name__=="__main__"``::
    
    def add_two_numbers(x1,x2):
        return x1+x2
    
    if __name__=="__main__":
        y = add_two_numbers(4,3)
        print(y)
        
This statement checks if a script is imported as a module or is run from a terminal.
If you save this to a :download:`file <myscript2.py>`, then you get the
following behaviour from a terminal::
    
    $:> python myscript2.py
    7

and from a Python script:
    
.. sourcecode:: ipython

    In [1]: import myscript2
    
    In [2]: myscript2.add_two_numbers(4,3)
    7
    
Note that now, the import statement does not execute the part hidden in the ``if``
statement.


Creating your own package
--------------------------

You can readily import any Python file that is located in the current working
directory. If you want to make your own packages globally available or you want
to share them with other people, there are two ways of advancing:
    
    1. Simply add the directory where you package is located to the ``PYTHONPATH``.
       For example in bash::
           
           $:> export PYTHONPATH="$PYTHONPATH:/home/user/python"
       
       This statement can be added to your ``bash_profile``, so that it is
       evaluated each time you open a terminal.
           
    2. Use ``distutils`` to package your library. This allows users to install
       your package into their default Python installation. It is extremely
       powerful, in the sense that it can also automatically compile Fortran and
       C extensions.