add more hooks based on suggestion from Chris Hasenpflug; add documentation

Author: dhellmann

.hgignore

@@ -2,3 +2,4 @@ README.html
 virtualenvwrapper.egg-info
 paver-minilib.zip
 setup.py
+trace.txt

README

@@ -28,31 +28,59 @@ Sometimes it is desirable to share installed packages that are not in the system
 3. Run: ``add2virtualenv``.
 4. A usage message and list of current "extra" paths is printed.
 
-==================
-Activation Scripts
-==================
-
-virtualenvwrapper adds two separate hook scripts you can use to change your settings when moving between environments.  They are *sourced* by ``workon`` at the appropriate trigger time, allowing them to modify your shell environment.
+============
+Hook Scripts
+============
 
-Both scripts are bash shell scripts and need to be saved in ``$VIRTUAL_ENV/bin/``.
+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.
 
-postactivate
-============
+$VIRTUAL_ENV/bin/postactivate
+=============================
 
-The ``postactivate`` script is run after the new environment is enabled.  ``$VIRTUAL_ENV`` refers to the new environment at the time the script runs.
+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.
+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
+    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/premkvirtualenv
+=============================
 
-predeactivate
-=============
+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.
 
-The ``predeactivate`` script is run 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/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
@@ -70,6 +98,9 @@ For more details, refer to the column I wrote for the May 2008 issue of Python M
 Updates
 =======
 
+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.
 

pavement.py

@@ -22,7 +22,7 @@
 
 # What project are we building?
 PROJECT = 'virtualenvwrapper'
-VERSION = '1.8.1'
+VERSION = '1.9'
 
 # Read the long description to give to setup
 README_FILE = 'README'

test.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+
+#set -x
+
+export WORKON_HOME="./WORKON_HOME"
+mkdir -p $WORKON_HOME
+
+function mk_test_hook () {
+    hookname="$1"
+    echo "echo \"$hookname\" \$@" > $WORKON_HOME/$hookname
+    chmod +x $WORKON_HOME/$hookname
+}
+
+mk_test_hook premkvirtualenv
+mk_test_hook postmkvirtualenv
+mk_test_hook prermvirtualenv
+mk_test_hook postrmvirtualenv
+
+echo
+echo "HOOKS:"
+ls -l $WORKON_HOME
+
+bindir=$(dirname $0)
+source "$bindir/virtualenvwrapper_bashrc"
+
+echo
+echo "CREATING AND ACTIVATING"
+mkvirtualenv "env1"
+echo "Current environment: $VIRTUAL_ENV"
+
+echo
+echo "CREATING AND SWITCHING"
+mkvirtualenv "env2"
+echo "Current environment: $VIRTUAL_ENV"
+
+echo
+echo "POSTACTIVATE HOOK"
+echo "echo postactivate" > $WORKON_HOME/env1/bin/postactivate
+workon env1
+
+echo
+echo "DEACTIVATING"
+deactivate
+
+echo
+echo "LISTING ENVIRONMENTS"
+workon
+
+echo
+echo "REMOVING ENVIRONMENTS"
+rmvirtualenv "env1"
+rmvirtualenv "env2"
+
+rm -rf $WORKON_HOME

virtualenvwrapper_bashrc

@@ -28,7 +28,7 @@ then
 fi
 
 # Verify that the WORKON_HOME directory exists
-function verify_workon_home () {
+function virtualenvwrapper_verify_workon_home () {
     if [ ! -d "$WORKON_HOME" ]
     then
         echo "ERROR: Virtual environments directory '$WORKON_HOME' does not exist."
@@ -38,7 +38,7 @@ function verify_workon_home () {
 }
 
 # Verify that the requested environment exists
-function verify_workon_environment () {
+function virtualenvwrapper_verify_workon_environment () {
     typeset env_name="$1"
     if [ ! -d "$WORKON_HOME/$env_name" ]
     then
@@ -49,7 +49,7 @@ function verify_workon_environment () {
 }
 
 # Verify that the active environment exists
-function verify_active_environment () {
+function virtualenvwrapper_verify_active_environment () {
     if [ ! -n "${VIRTUAL_ENV}" ] || [ ! -d "${VIRTUAL_ENV}" ]
     then
         echo "ERROR: no virtualenv active, or active virtualenv is missing"
@@ -58,22 +58,43 @@ function verify_active_environment () {
     return 0
 }
 
+function virtualenvwrapper_source_hook () {
+    scriptname="$1"
+    if [ -f "$scriptname" ]
+    then
+        source "$scriptname"
+    fi
+}
+
+function virtualenvwrapper_run_hook () {
+    scriptname="$1"
+    shift
+    if [ -x "$scriptname" ]
+    then
+        "$scriptname" "$@"
+    fi
+}
+
 # Create a new environment, in the WORKON_HOME.
 #
 # Usage: mkvirtualenv [options] ENVNAME
 # (where the options are passed directly to virtualenv)
 #
 function mkvirtualenv () {
     eval "envname=\$$#"
-    verify_workon_home
-    (cd "$WORKON_HOME"; virtualenv "$@")
+    virtualenvwrapper_verify_workon_home
+    (cd "$WORKON_HOME"; 
+        virtualenv "$@"; 
+        virtualenvwrapper_run_hook "./premkvirtualenv" "$envname"
+        )
     workon "$envname"
+    virtualenvwrapper_source_hook "$WORKON_HOME/postmkvirtualenv"
 }
 
 # Remove an environment, in the WORKON_HOME.
 function rmvirtualenv () {
     typeset env_name="$1"
-    verify_workon_home
+    virtualenvwrapper_verify_workon_home
     if [ "$env_name" = "" ]
     then
         echo "Please specify an enviroment."
@@ -86,13 +107,15 @@ function rmvirtualenv () {
         echo "Either switch to another environment, or run 'deactivate'."
         return 1
     fi
+    virtualenvwrapper_run_hook "$WORKON_HOME/prermvirtualenv" "$env_dir"
     rm -rf "$env_dir"
+    virtualenvwrapper_run_hook "$WORKON_HOME/postrmvirtualenv" "$env_dir"
 }
 
 # List the available environments.
-function show_workon_options () {
-    verify_workon_home
-	ls "$WORKON_HOME" | egrep -v '*.egg' | sort
+function virtualenvwrapper_show_workon_options () {
+    virtualenvwrapper_verify_workon_home
+	ls "$WORKON_HOME" | egrep -v '*.egg' | egrep -v '(pre|post)(rm|mk)virtualenv' | sort
 }
 
 # List or change working virtual environments
@@ -103,12 +126,12 @@ function workon () {
 	typeset env_name="$1"
 	if [ "$env_name" = "" ]
     then
-        show_workon_options
+        virtualenvwrapper_show_workon_options
         return 1
     fi
 
-    verify_workon_home || return 1
-    verify_workon_environment $env_name || return 1
+    virtualenvwrapper_verify_workon_home || return 1
+    virtualenvwrapper_verify_workon_environment $env_name || return 1
 
     activate="$WORKON_HOME/$env_name/bin/activate"
     if [ ! -f "$activate" ]
@@ -117,17 +140,11 @@ function workon () {
         return 1
     fi
 
-    if [ -f "$VIRTUAL_ENV/bin/predeactivate" ]
-    then
-        source "$VIRTUAL_ENV/bin/predeactivate"
-    fi
+    virtualenvwrapper_source_hook "$VIRTUAL_ENV/bin/predeactivate"
 
     source "$activate"
 
-    if [ -f "$VIRTUAL_ENV/bin/postactivate" ]
-    then
-        source "$VIRTUAL_ENV/bin/postactivate"
-    fi
+    virtualenvwrapper_source_hook "$VIRTUAL_ENV/bin/postactivate"
 	return 0
 }
 
@@ -140,13 +157,13 @@ if [ -n "$BASH" ] ; then
     _virtualenvs ()
     {
         local cur="${COMP_WORDS[COMP_CWORD]}"
-        COMPREPLY=( $(compgen -W "`show_workon_options`" -- ${cur}) )
+        COMPREPLY=( $(compgen -W "`virtualenvwrapper_show_workon_options`" -- ${cur}) )
     }
 
     complete -o default -o nospace -F _virtualenvs workon
     complete -o default -o nospace -F _virtualenvs rmvirtualenv
 elif [ -n "$ZSH_VERSION" ] ; then
-    compctl -g "`show_workon_options`" workon rmvirtualenv
+    compctl -g "`virtualenvwrapper_show_workon_options`" workon rmvirtualenv
 fi
 
 # Path management for packages outside of the virtual env.
@@ -163,7 +180,7 @@ fi
 #
 function add2virtualenv () {
 
-    verify_active_environment || return 1
+    virtualenvwrapper_verify_active_environment || return 1
 
     pyvers="`python -c 'import sys; print sys.version[:3]'`"
     site_packages="$VIRTUAL_ENV/lib/python${pyvers}/site-packages"