virtualenv-api 2.1.15

An API for virtualenv/pip

virtualenv is a tool to create isolated Python environments. Unfortunately, it does not expose a native Python API. This package aims to provide an API in the form of a wrapper around virtualenv.

It can be used to create and delete environments and perform package management inside the environment.

Full support is provided for Python 2.7 and Python 3.3+.

Installation

The latest stable release is available on PyPi:

$ pip install virtualenv-api

Please note that the distribution is named virtualenv-api, yet the Python package is named virtualenvapi.

Alternatively, you may fetch the latest version from git:

$ pip install git+https://github.com/sjkingo/virtualenv-api.git

Usage

To begin managing an environment (it will be created if it does not exist):

from virtualenvapi.manage import VirtualEnvironment
env = VirtualEnvironment('/path/to/environment/name')

If you have already activated a virtualenv and wish to operate on it, simply call VirtualEnvironment without the path argument:

env = VirtualEnvironment()

The VirtualEnvironment constructor takes some optional arguments (their defaults are shown below):

• python=None - specify the Python interpreter to use. Defaults to the default system interpreter (new in 2.1.3)

• cache=None - existing directory to override the default pip download cache

• readonly=False - prevent all operations that could potentially modify the environment (new in 2.1.7)

• system_site_packages=False - include system site packages in operations on the environment (new in 2.1.14)

Operations

Once you have a VirtualEnvironment object, you can perform operations on it.

• Check if the mezzanine package is installed:

>>> env.is_installed('mezzanine')
False

• Install the latest version of the mezzanine package:

>>> env.install('mezzanine')

• A wheel of the latest version of the mezzanine package (new in 2.1.4):

>>> env.wheel('mezzanine')

• Install version 1.4 of the django package (this is pip’s syntax):

>>> env.install('django==1.4')

• Upgrade the django package to the latest version:

>>> env.upgrade('django')

• Upgrade all packages to their latest versions (new in 2.1.7):

>>> env.upgrade_all()

• Uninstall the mezzanine package:

>>> env.uninstall('mezzanine')

Packages may be specified as name only (to work on the latest version), using pip’s package syntax (e.g. django==1.4) or as a tuple of ('name', 'ver') (e.g. ('django', '1.4')).

• A package may be installed directly from a git repository (must end with .git):

>>> env.install('git+git://github.com/sjkingo/cartridge-payments.git')

New in 2.1.10:

• A package can be installed in pip’s editable mode by prefixing the package name with -e (this is pip’s syntax):

>>> env.install('-e git+https://github.com/stephenmcd/cartridge.git')

New in 2.1.15:

• Packages in a pip requirements file can be installed by prefixing the requirements file path with -r:

>>> env.install('-r requirements.txt')

• Instances of the environment provide an installed_packages property:

>>> env.installed_packages
[('django', '1.5'), ('wsgiref', '0.1.2')]

• A list of package names is also available in the same manner:

>>> env.installed_package_names
['django', 'wsgiref']

• Search for a package on PyPI (changed in 2.1.5: this now returns a dictionary instead of list):

>>> env.search('virtualenv-api')
{'virtualenv-api': 'An API for virtualenv/pip'}
>>> len(env.search('requests'))
231

• The old functionality (pre 2.1.5) of env.search may be used:

>>> list(env.search('requests').items())
[('virtualenv-api', 'An API for virtualenv/pip')]

Verbose output from each command is available in the environment’s build.log file, which is appended to with each operation. Any errors are logged to build.err.