virtualenvwrapper / README

#################
virtualenvwrapper
#################

===========
Quick Setup
===========

1. Add two lines to your .bashrc to set the location where the virtual environments should live and the location of the script installed with this package::

    export WORKON_HOME=$HOME/.virtualenvs
    source /usr/local/bin/virtualenvwrapper_bashrc

2. Run: ``source ~/.bashrc``
3. Run: ``workon``
4. A list of environments, empty, is printed.
5. Run: ``mkvirtualenv temp``
6. A new environment, ``temp`` is created and activated.
7. Run: ``workon``
8. This time, the ``temp`` environment is included.


===============
Path Management
===============

Sometimes it is desirable to share installed packages that are not in the system ``site-pacakges`` directory and which you do not want to install in each virtualenv.  In this case, you *could* symlink the source into the environment ``site-packages`` directory, but it is also easy to add extra directories to the PYTHONPATH by including them in a .pth file inside ``site-packages`` using ``add2virtualenv``.

1. Check out the source for a big project, such as Django.
2. Run: ``add2virtualenv path_to_source``.
3. Run: ``add2virtualenv``.
4. A usage message and list of current "extra" paths is printed.

============
Hook Scripts
============

virtualenvwrapper adds several hook points you can use to change your settings when creating,
deleting, or moving between environments. They are either *sourced* (allowing them to modify
your shell environment) or run as an external program at the appropriate trigger time.

$VIRTUAL_ENV/bin/postactivate
=============================

The ``postactivate`` script is sourced after the new environment is enabled. ``$VIRTUAL_ENV``
refers to the new environment at the time the script runs.

This example script for the PyMOTW environment changes the current working directory and the
PATH variable to refer to the source tree containing the PyMOTW source.

::

    pymotw_root=/Users/dhellmann/Documents/PyMOTW
    cd $pymotw_root
    PATH=$pymotw_root/bin:$PATH

$VIRTUAL_ENV/bin/predeactivate
==============================

The ``predeactivate`` script is source before the current environment is deactivated, and can
be used to disable or clear settings in your environment. ``$VIRTUAL_ENV`` refers to the old
environment at the time the script runs.

$WORKON_HOME/postactivate
=============================

The global ``postactivate`` script is sourced after the new environment is enabled and the new
environment's postactivate is sourced (if it exists). ``$VIRTUAL_ENV`` refers to the new
environment at the time the script runs.

This example script adds a space between the virtual environment name and your old PS1 by making
use of ``_OLD_VIRTUAL_PS1``.

::

    PS1="(`basename \"$VIRTUAL_ENV\"`) $_OLD_VIRTUAL_PS1"

$WORKON_HOME/premkvirtualenv
=============================

The ``premkvirtualenv`` script is run as an external program after the virtual environment is
created but before the current environment is switched to point to the new env. The current
working directory for the script is ``$WORKON_HOME`` and the name of the new environment is
passed as an argument to the script.

$WORKON_HOME/postmkvirtualenv
=============================

The ``postmkvirtualenv`` script is sourced after the new environment is created and
activated.

$WORKON_HOME/prermvirtualenv
============================

The ``prermvirtualenv`` script is run as an external program before the environment is
removed. The full path to the environment directory is passed as an argument to the script.

$WORKON_HOME/postrmvirtualenv
=============================

The ``postrmvirtualenv`` script is run as an external program after the environment is
removed. The full path to the environment directory is passed as an argument to the script.

===============
Path Management
===============

The function ``add2virtualenv`` adds the specified directories to the Python path for the
active virtualenv. The directory names passed as argument are added to a path file named
``virtualenv_path_extensions.pth`` inside the virtualenv's site-packages directory. If this
file does not exist, it will be created first.

==================================
Quickly Navigating to a virtualenv
==================================

The functions ``cdsitepackages`` and ``cdvirtualenv`` provide quick shortcuts to quickly
``cd`` into the ``site-packages`` directory of the currently-active virtualenv, and to the
root of the currently-active virtualenv, respectively.

==========
References
==========

For more details, refer to the column published in the May 2008 issue of Python Magazine:
`virtualenvwrapper | And Now For Something Completely Different
<http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html>`_.

=======
Updates
=======

1.14
  - Wrap the virtualenv version of deactivate() with one that lets us invoke
    the predeactivate hooks.
  - Fix virtualenvwrapper_show_workon_options for colorized versions of ls and
    write myself a note so I don't break it again later.
  - Convert test.sh to use true tests with `shunit2 <http://shunit2.googlecode.com/>`_

1.13
  - Fix issue #5 by correctly handling symlinks and limiting the list of envs to things 
    that look like they can be activated.

1.12
  - Check return value of virtualenvwrapper_verify_workon_home everywhere, thanks to 
    Jeff Forcier for pointing out the errors.
  - Fix instructions at top of README, pointed out by Matthew Scott.
  - Add cdvirtualenv and cdsitepackages, contributed by James Bennett.
  - Enhance test.sh.

1.11
  - Optimize virtualenvwrapper_show_workon_options.
  - Add global postactivate hook.

1.10
  - Pull in fix for colorized ls from Jeff Forcier (b42a25f7b74a).

1.9
  - Add more hooks for operations to run before and after creating or deleting environments based on changes from Chris Hasenpflug.

1.8.1
  - Corrected a problem with change to mkvirtualenv that lead to release 1.8 by using an alternate fix proposed by James in comments on release 1.4.

1.8
  - Fix for processing the argument list in mkvirtualenv from jorgevargas (BitBucket issue #1)

1.7
  - Move to bitbucket.org for hosting
  - clean up TODO list and svn keywords
  - add license section below

1.6.1

  - More zsh support (fixes to rmvirtualenv) from Byron Clark.

1.6

  - Add completion support for zsh, courtesy of Ted Leung.

1.5

  - Fix some issues with spaces in directory or env names.  They still don't really work with virtualenv, though.
  - Added documentation for the postactivate and predeactivate scripts.

1.4

  - Includes a new .pth management function based on work contributed by James Bennett and Jannis Leidel.

1.3.x

  - Includes a fix for a nasty bug in rmvirtualenv identified by John Shimek.

=======
License
=======

Copyright Doug Hellmann, All Rights Reserved

Permission to use, copy, modify, and distribute this software and
its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of Doug
Hellmann not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.

DOUG HELLMANN DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
NO EVENT SHALL DOUG HELLMANN BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.