Metadata-Version: 2.0
Name: virtualenv-api
Version: 2.1.7
Summary: An API for virtualenv/pip
Home-page: https://github.com/sjkingo/virtualenv-api
Author: Sam Kingston and AUTHORS
Author-email: sam@sjkwi.com.au
License: BSD
Platform: UNKNOWN
Requires-Dist: six

virtualenv-api - an API for virtualenv
======================================

|Build Status| |Latest version| |BSD License| |Stories in Ready|

`virtualenv <http://www.virtualenv.org/>`__ 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 <https://pypi.python.org/pypi/virtualenv-api>`__:

::

    $ 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

Examples
--------

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

.. code:: python

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

You may also specify the Python interpreter to use in this environment
by passing the ``python`` argument to the class constructor (new in
2.1.3):

.. code:: python

    env = VirtualEnvironment('/path/to/environment/name', python='python3')

If you have already activated a virtualenv and wish to operate on it,
simply call ``VirtualEnvironment`` with no arguments:

.. code:: python

    env = VirtualEnvironment()

*New in 2.1.7:*

An optional argument ``readonly`` may be provided (defaults to
``False``) that will prevent all operations that could potentially
modify the environment.

-  Check if the ``mezzanine`` package is installed:

.. code:: python

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

-  Install the latest version of the ``mezzanine`` package:

.. code:: python

    >>> env.install('mezzanine')

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

.. code:: python

    >>> env.wheel('mezzanine')

-  Install version 1.4 of the ``django`` package (this is pip's syntax):

.. code:: python

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

-  Upgrade the ``django`` package to the latest version:

.. code:: python

    >>> env.upgrade('django')

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

.. code:: python

    >>> env.upgrade_all()

-  Uninstall the ``mezzanine`` package:

.. code:: python

    >>> 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``):

.. code:: python

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

-  Instances of the environment provide an ``installed_packages``
   property:

.. code:: python

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

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

.. code:: python

    >>> 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):

.. code:: python

    >>> 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:

.. code:: python

    >>> 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``.

.. |Build Status| image:: https://travis-ci.org/sjkingo/virtualenv-api.svg
   :target: https://travis-ci.org/sjkingo/virtualenv-api
.. |Latest version| image:: https://img.shields.io/pypi/v/virtualenv-api.svg
   :target: https://pypi.python.org/pypi/virtualenv-api
.. |BSD License| image:: https://img.shields.io/pypi/l/virtualenv-api.svg
   :target: https://github.com/sjkingo/virtualenv-api/blob/master/LICENSE
.. |Stories in Ready| image:: https://badge.waffle.io/sjkingo/virtualenv-api.png?label=ready&title=Ready
   :target: https://waffle.io/sjkingo/virtualenv-api


