==========================
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, wehart@sandia.gov
+ Mailing List
* pyutilib-forum@googlegroups.com
- The main list for help and announcements
* pyutilib-developers@googlegroups.com
- Where developers of PyUtilib discuss new features
--------------------
Third Party Software
--------------------
The pyutilib.virtualenv package depends on the following Python packages:
- virtualenv