# .. 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:
#     

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

os.path.exists('data/m31.fits')

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

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

import matplotlib.pyplot as plt
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.
#