==========================
pyutilib.virtualenv README
==========================

This Python package includes the **vpy_create** script, which is
used to create **virtualenv** bootstrap scripts that automate the installation of
**virtualenv** along with other Python packages.

---------------
Getting Started
---------------

Overview
~~~~~~~~

The **vpy_create** script integrates a Python module into a **virtualenv**
bootstrap script.  A user defines a **configure()** function in this module to
control the configuration of the **virtualenv** installation.  For example, the
following function declares the default installation directory, and that the
virtual Python repository contains the **virtualenv** and **nose** Python packages::

  def configure(installer):
        installer.default_dirname = 'venv'
        installer.add_repository('virtualenv', pypi='virtualenv')
        installer.add_repository('nose', pypi='nose')
        installer.add_repository(
            'pyutilib.subprocess', 
            root='https://software.sandia.gov/svn/public/pyutilib.subprocess', 
            dev=True)
        return installer

The **add_repository** method can specify a PyPI package with the *pypi*
option.  Alternatively, the root of a subversion repository can be specified
with the *root* option.  If the *dev* option is specified, then this
repository is checked out and installed in the **<root>/src** directory.
Further, this package is installed in *develop* mode.


A virtual Python bootstrap script is created by calling
**vpy_create** and specifying the Python module and script
name.::

  vpy_create venv.py venv_install

The bootstrap script, **venv_install**, creates the virtual Python
installation in the specified directory, **venv**:

  venv_install

The user can also specify the installation directory::

  venv_install venvdir


By default, the bootstrap script installs the latest software release.
In PyPI, this is the latest revision.  In subversion, this is the latest
revision in either the *tags* or *releases* directory.  The trunk branch of
the subversion repository can also be installed using the **--trunk** option::

  venv_install --trunk venv

Similarly, the bootstrap script recognizes stable branches, which can
be installed with the **--stable** option.  Note that if stable branches are
not available, then the latest release is installed.


Internet Connectivity
~~~~~~~~~~~~~~~~~~~~~

By default, the bootstrap script uses an internet connection to download the 
Python packages that are installed.  Note that a proxy server may be needed
for the bootstrap script to work correctly.  The user can define the
HTTP_PROXY environmental variable to specify the name of a proxy server.
Alternatively, the **--proxy** option can be specified.

The bootstrap script also provides a mechanism for enabling offline virtualenv
installations.  This requires a two-stage process.  First, the
**--preinstall** option is used to create a ZIP file that contains the Python
packages.  For example, the command::

  venv_install --preinstall

creates a **venv** directory, which includes the file **venv/venv.zip**.
The preinstall step must be executed on a machine with internet
connectivity.  However, this ZIP file can be used to perform an off-line
installation with the **--offline** option.  For example, the following
command will uses the **venv.zip** file to perform off-line installation
in the **temp** directory::

  venv_install --offline --zip=venv.zip test

Note that this technique also installs the **setuptools** packages offline.
Thus, the bootstrap script generated by **vpy_create** 
supports a purely offline setup of virtualenv environments, which is not supported
by the **virtualenv** bootstrap process.


A Configurable Installer
~~~~~~~~~~~~~~~~~~~~~~~~

The **vpy_install** script provided with **pyutilib.virtualenv** is a **virtualenv**
bootstrap script that can be configured with INI files.  For example, the
consider the following INI file::

    ;
    ; This INI file can be used by vpy_install to create a virtual
    ; Python installation.
    ;
    [installer]
    description=This is an example.
    README="#
     # This is a README file created by the bootstrap script.
     #"

    [nose]
    pypi=nose

    [pyutilib.subprocess]
    root=https://software.sandia.gov/svn/public/pyutilib/pyutilib.subprocess
    dev=True

The default installation directory for **vpy_install** is **python**.
This INI file will install the **nose** and **pyutilib.subprocess**
packages, and the **pyutilib.subprocess** package will be installed in
**python/src/pyutilib.subprocess** as an editable *develop* package.

Note that **vpy_install** does not require a user to install
**setuptools**.  The **setuptools** package is only required when the
**--preinstall** option is specified.  Thus, the default behavior of
**vpy_install** (and other bootstrap scripts) does not require the
installation of any third-party packages.  The **vpy_install** script
can be distributed independent of **pyutilib.virtualenv**, and it can
generally be used as a stand-alone script.

The **vpy_install** script supports an **--update** option that allows the
user to update virtual Python installations.  This option does the following
updates:

* PyPI packages are upgraded
* Subversion packages are updated and reinstalled

Note that this option does not search for a newer release of a subversion
package.  This limitation reflects the manner in which subversion packages
are checked out within the virtual Python installation, which may be revised
in the future.


-------
License
-------

BSD.  See the LICENSE.txt file.


------------
Organization
------------

+ Directories

  * pyutilib - The root directory for PyUtilib source code

+ Documentation and Bug Tracking

  * Trac wiki: https://software.sandia.gov/trac/pyutilib
 
  * Examples in the pyutilib.virtualenv/example directory

+ Authors

  * See the AUTHORS.txt file.

+ Project Managers

  * William E. Hart, [email protected]

+ Mailing List

  * [email protected]
    - The main list for help and announcements
  * [email protected]
    - Where developers of PyUtilib discuss new features

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

The pyutilib.virtualenv package depends on the following Python packages:
    - virtualenv