PyUtilib INSTALL
================

These installation instructions summarize how PyUtilib can be downloaded
and installed.  PyUtilib will install on Python 2.4 or newer, but some
functionality is disabled when using Python 2.4.


--------------------
Downloading PyUtilib
--------------------

The latest development version of PyUtilib can be downloaded using
subversion:

  svn checkout https://software.sandia.gov/svn/public/pyutilib/trunk pyutilib

Alternatively, the latest releases of PyUtilib can be downloaded from
the PyUtilib website as (1) a source tarball or (2) a Python EGG package.

Finally, you can download and install PyUtilib from the PyPi site using the
Python setuptools package (see http://pypi.python.org/pypi/setuptools):

  easy_install PyUtilib


-------------------
Installing PyUtilib
-------------------

There are two different ways that PyUtilib can be used: (1) from the source
tree or (2) from a Python installation.

1. Source Tree

If you have downloaded the source tarball, then you need to untar them.
For example:

  tar xvzf pyutilib.tar.gz

The PyUtilib source tree can be used without further installation by setting
the PYTHONPATH environmental variable.  For example, if PyUtilib is downloaded
into /home/jdoe/pyutilib, then you would set your PYTHONPATH as follows

  setenv PYTHONPATH /home/jdoe/pyutilib    # csh

or

  export PYTHONPATH=/home/jdoe/pyutilib    # bash

Now, PyUtilib can be accessed within Python.

2. Python Installation

You can install PyUtilib in the system Python installation
to avoid the need to update the PYTHONPATH environment.  If you have
downloaded the source tarball, then you need to untar it (see above).
Then, you can install PyUtilib by moving to the top-level source
directory, and executing:

  python setup.py install

If you cannot directly perform this setup, you may need to use the 'sudo'
utility:

  sudo python setup.py install


--------------------
Third-Party Software
--------------------

Most of the functionality of PyUtilib is available without third-party
software.  Thus, installation of PyUtilib is not strictly dependent on
these additional tools.  The following list describes the third-party
software tools that can be used within PyUtilib:

- Python 'nose' package

This is needed to perform unit testing in pyutilib/test.

  See http://www.somethingaboutorange.com/mrl/projects/nose/ for details.

- Pythons 'coverage' module

This is needed to generate coverage reports in the PyUtilib tests.  Tests
can be run without this module, but an error message will be generated.

  See http://nedbatchelder.com/code/modules/coverage.html for details.

- Python 'ply' package

Several Ply utilities are included in pyutilib.ply.

  See http://www.dabeaz.com/ply/ for details.


--------------
Using PyUtilib
--------------

PyUtilib contains a variety of Python packages.  Most of these packages
are accessible by simply importing the PyUtilib software:

  import pyutilib

A variety of PyUtilib packages are conditionally imported depending on
the existence of other Python package installations.

