orb
===

A utility wrapper for pip_ and virtualenv_.

latest
------

+ specify Python2 or Python3 as the python executable to use when
  creating the environment
+ don't hardcode 2.7/3.3 as latest versions - determine it from the
  python2/python3 commands

install
-------

virtualenv_ must be available, eg. in Ubuntu:

    $ sudo apt-get install python-virtualenv

pip_ need not be available - it is installed every time to a new environment.

To install, use easy_install to install from pypi.python.org::

    easy_install -Z orb
    
or simply copy the orb script from the source distribution, eg. ::

    $ sudo cp orb /usr/local/bin

usage
-----

Create a virtualenv with the command

    $ orb init myenv

or

    $ orb init2 myenv

to use the latest Python2 as the executable, or

    $ orb init3 myenv

to use the latest Python3 as the executable, or

    $ orb init?.? myenv

(eg. orb init2.6 or orb init3.2) to specify a particular Python version as
the executable.

.. note::

    the various python versions are assumed to be installed and on the user's
    PATH

This creates a virtualenv called 'myenv.orb' and creates an empty '.orb'
file within the virtualenv directory. Subsequent orb commands first search
for the '.orb' file and from this file's location the virtualenv's bin directory
is known. 

To install packages to the env, run the 'orb install' command
(from within the env directory):

   cd myenv
   orb install Pygments
   orb install BeautifulSoup

which calls 'pip_' to do the actual downloading and installation.

If passed a python script, orb will call it using the virtualenv's python

   eg. orb setup.py install

and if passed any command expression, orb will temporarily alter the
environment (ie. pip's `source activate` step), eval the command,
then restore (pip's `deactivate`).

   eg. (Django): orb django-admin.py startproject myproj
   eg. (Python prompt): orb python
   eg. (Sphinx quickstart): orb sphinx-quickstart
   eg. (Sphinx build): orb make html
   eg. (Arbitrary command) orb ./myshellscript

Other options:

orb ls      - list contents of env's site-packages directory
orb link    - symlink from the virtual env's site-packages to a system package
orb download PACKAGE [DEST]
            - just download package, don't install




.. _virtualenv: http://pypi.python.org/pypi/virtualenv/
.. _pip: http://pip.openplans.org/index.html


