Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sjkingo/virtualenv-api

An API for virtualenv/pip
https://github.com/sjkingo/virtualenv-api

python python-2 python-3 virtualenv

Last synced: about 11 hours ago
JSON representation

An API for virtualenv/pip

Awesome Lists containing this project

README 

        
virtualenv-api - an API for virtualenv

======================================



|Build Status|

|Latest version|

|BSD License|



`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 all supported versions of Python.



.. _virtualenv: http://www.virtualenv.org/

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



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



.. _PyPi: https://pypi.python.org/pypi/virtualenv-api



Usage

-----



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



If you have already activated a virtualenv and wish to operate on it, simply

call ``VirtualEnvironment`` without the path argument:



.. code:: python



    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:



.. 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')



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



.. code:: python



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



.. code:: python



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



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