.. contents::
   :depth: 2

Understanding packages
========================


One of the key features of Python is that the actual core language is fairly small.
This is an intentional design feature to maintain simplicity. Much of the powerful
functionality comes through the `standard library <http://docs.python.org/2/library/>`_
(*batteries included*) and external modules and packages.

Modules
--------

A `module <http://docs.python.org/2/tutorial/modules.html>`_ is simply a file containing Python definitions, functions, and statements. Putting code into modules is useful because of the ability to `import <http://docs.python.org/2/reference/simple_stmts.html#import>`_ the module functionality into your script or IPython session, for instance::
    
    import numpy
    data = numpy.loadtxt('mydatafile.txt')
    
You'll see a bunch of ``import`` statements in virtually every Python script and
soon it will be second nature. It might seem like a lot of overhead in typing,
but it keeps everything modular and separate. Different packages can contain
functions with the same name (e.g. ``read()``), and specifying the package where
it comes from avoids clashes.

.. tip::
    
    The ``import`` statement is a little bit more flexible than shown above.
    
    First, there is a possibility to only load the functions you need from a
    package::
        
        from numpy import loadtxt
        data = loadtxt('mydatafile.txt')
    
    You can also make *all* functions local::
        
        from numpy import *
    
    This can be handy when you work in an interactive environment (IPython),
    but it is strongly discouraged when writing scripts since it makes the
    scripts less readable to others. If you want to have
    access to functions such as ``sin`` and ``cos`` without typing ``numpy``
    in front of it, you should import those functions explicitly (as in the
    previous example) or create a shorthand for the module::
        
        import numpy as np
        from matplotlib import pyplot as plt
        
    You will see these import frequently in many scripts.


Packages
----------

A `package <http://docs.python.org/2/tutorial/modules.html#packages>`_ is just a
way of collecting related modules together within a single tree-like hierarchy.
Very complex packages like NumPy or SciPy have hundreds of individual modules so
putting them into a directory-like structure keeps things organized and avoids
name collisions. For example here is a partial list of sub-packages available
within SciPy.

================================== ======================================================
scipy.fftpack                      Discrete Fourier Transform algorithms 
scipy.stats                        Statistical Functions 
scipy.lib                          Python wrappers to external libraries 
scipy.lib.blas                     Wrappers to BLAS library 
scipy.lib.lapack                   Wrappers to LAPACK library 
scipy.integrate                    Integration routines 
scipy.linalg                       Linear algebra routines 
scipy.sparse.linalg                Sparse Linear Algebra 
scipy.sparse.linalg.eigen          Sparse Eigenvalue Solvers 
scipy.sparse.linalg.eigen.arpack   Eigenvalue solver using iterative methods. 
================================== ======================================================

.. admonition:: Exercise: Import a package module and learn about it
  
  Import the Linear algebra module from the SciPy package and find out what
  functions it provides.

.. raw:: html

   <p class="flip0">Solution (Click to Show/Hide)</p> <div class="panel0">
   
Start an interactive IPython session and import the linear algebra module.
Use the ``dir`` and ``help`` functions to learn more:
       
.. ipython::
       
   In [1]: import scipy.linalg
       
   In [1]: print(dir(scipy.linalg))
   
   In [1]: help(scipy.linalg.eig)
       
       

.. raw:: html

   </div>


Finding and installing packages
--------------------------------


If you've gotten this far you have a working scientific Python environment that
has *most* of what you will ever need.  Nevertheless it is almost certain that
you will eventually find a need that is not met within your current
installation.  Here we learn **where** to find other useful packages and
**how** to install them. 

Package resources
^^^^^^^^^^^^^^^^^^

Google
#######

Google "python blah blah" or "python astronomy blah blah"

.. tip:: Good vs. bad resources

   When you find some package on the web, look for a few things:
   
      - Good modern-looking documentation with examples
      - Installs easily without lots of dependencies (or has detailed
        installation instructions)
      - Actively developed


Resource lists
###############

There are a number of sites specifically devoted to Python for astronomy with
organized lists of useful resources and packages.

  - `Astropython.org resources <http://www.astropython.org/resources>`_
  - `Comfort at 1 AU
    <http://oneau.wordpress.com/2010/10/02/python-for-astronomy/>`_
  - `Astronomical Python <http://www.astro.washington.edu/users/rowen/AstroPy.html>`_

PyPI
#######

The `Python Package Index <http://pypi.python.org/pypi>`_ is the main
repository for 3rd party Python packages (about 14000 packages and growing).
An increasing number of `astronomy related packages
<http://pypi.python.org/pypi?:action=browse&show=all&c=385&c=387>`_
are available on PyPI, but this list misses a lot of available options.

The advantage of being on PyPI is the ease of installation/uninstallation using::
    
    $:> pip install <package_name>
    $:> pip uninstall <package_name>
    
These commands might require root access. If you don't have root access, you
can use either::

    $:> pip install --user <package_name>
    $:> pip uninstall --user <package_name>
    
Or better yet, use the :ref:`virtualenv <virtualenv_title>` framework

.. admonition:: Exercise: Find packages for coordinate manipulations

  Find one or more Python packages that will transform coordinates from Galactic to FK5 ecliptic.
  
  *Hint*: tags are helpful at astropython.org and don't forget the "next" button at
  the bottom.