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.