virtualenv.el --- Virtualenv for Python  -*- coding: utf-8 -*-

Copyright (c) 2010, 2012 Aaron Culich

Author: Aaron Culich <[email protected]>
Maintainer: Aaron Culich <[email protected]>
Version: 1.2
Created: September 2010
Updated: September 2012
Keywords: python virtualenv
Vcs-git: git://github.com/aculich/virtualenv.git
Vcs-Browser: http://github.com/aculich/virtualenv

virtualenv.el is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.

virtualenv.el is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along
with virtualenv.el.  If not, see <http://www.gnu.org/licenses/>.

 Commentary:

This is a minor mode for setting the virtual environment for the
Python shell using virtualenv and supports both python-mode.el and
python.el. This minor mode was inspired by an earlier
implementation by Jesse Legg and Jeremiah Dodds, however this code
is a complete re-write with a GPLv3 license consistent with
GNU Emacs and python-mode.el.

There are two ways to use virtualenv.

1) The quickest way to get started is to simply type:
     M-x virtualenv-workon
   Which will prompt you to enter the name of a directory in
   ~/.virtualenvs that contains your chosen environment. You can
   hit tab to show the available completions.

   You'll know that you're in virtualenv mode now when you see the
   name of the virtualenv you selected in brackets. So if I were to
   select my turbogears environment that I call tg2.1 then I would
   see [tg2.1] appear in the mode line. To make sure you're new
   python shell is set up correctly you can try running this little
   snippet of python code:

     import os, sys
     print os.environ
     print sys.path

2) The recommended way to use virtualenv minor mode is to use a
.dir-locals.el file in the root of your project directory.

REQUIRES: Emacs 23.1 or higher.

There are two buffer-local variables that you can set for virtualenv as shown
in this example:

in file /path/to/project/.dir-locals.el:
((nil . ((virtualenv-workon . "tg2.1")
	 (virtualenv-default-directory . "/path/to/project/subdir"))))

The .dir-locals.el is new in Emacs23 and is useful for other
things, too. You should read the dir-locals docs to understand the
format. The variable virtualenv-workon should just be a string the
same as you'd give to the interactive function. The variable
virtualenv-default-directory is useful when you want to have your
python process rooted in a particular directory when it starts, so
that no matter where you are in your project's hierarchy, if you
launch a python shell. This method is recommended because it is
more flexible and will allow multiple virtualenvs running at once
in future versions.

 Notes:

 virtualenv-workon will now modify Emacs' exec-path as well as the
 shell environment's PATH so that if you run shell-command or launch a
 command in an emacs subprocess it will use any commands it finds in
 your ~/.virtualenvs/<env>/bin directory.

 virtualenv-deactivate will restore exec-path and PATH back to their
 original state prior to using the virtualenv-workon command.

 Bugs:

 All bug reports can be filed by opening a new issue on github at:
 http://github.com/aculich/virtualenv/issues

 TODO:

* support for multiple python processes in different virtualenvs

* add "paster shell" features