fix #33 with improved installation instructions and a better error message

Author: dhellmann

docs/source/history.rst

@@ -7,6 +7,9 @@ Dev
   - Add support for ksh.  Thanks to Doug Latornell for doing the
     research on what needed to be changed.
   - Switch to ``tempfile`` command for creating temporary hook files.
+  - Test import of virtualenvwrapper.hook_loader on startup and report
+    the error in a way that should help the user figure out how to fix
+    it.
 
 2.0.2
 

docs/source/index.rst

@@ -53,6 +53,27 @@ and the location of the script installed with this package::
 After editing it, reload the startup file (e.g., run: ``source
 ~/.bashrc``).
 
+Python Interpreter and $PATH
+============================
+
+During startup, ``virtualenvwrapper.sh`` finds the first ``python`` on
+the ``$PATH`` and remembers it to use later.  This eliminates any
+conflict as the ``$PATH`` changes, enabling interpreters inside
+virtual environments where virtualenvwrapper is not installed.
+Because of this behavior, it is important for the ``$PATH`` to be set
+**before** sourcing ``virtualenvwrapper.sh``.  For example::
+
+    export PATH=/usr/local/bin:$PATH
+    source /usr/local/bin/virtualenvwrapper.sh
+
+To override the ``$PATH`` search, set the variable
+``VIRTUALENVWRAPPER_PYTHON`` to the full path of the interpreter to
+use (also **before** sourcing ``virtualenvwrapper.sh``).  For
+example::
+
+    export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
+    source /usr/local/bin/virtualenvwrapper.sh
+
 Quick-Start
 ===========
 

tests/test.sh

@@ -63,5 +63,15 @@ test_get_python_version() {
     assertSame "$expected" "$actual"
 }
 
+test_python_interpreter_set_incorrectly() {
+    return_to="$(pwd)"
+    cd "$WORKON_HOME"
+    mkvirtualenv --no-site-packages no_wrappers
+    output=`VIRTUALENVWRAPPER_PYTHON=$VIRTUAL_ENV/bin/python $SHELL $return_to/virtualenvwrapper.sh 2>&1`
+    assertTrue "Unexpected message: $output" "echo \"$output\" | grep 'Could not find Python module virtualenvwrapper.hook_loader'"
+    assertFalse "Failed to detect invalid Python location" "VIRTUALENVWRAPPER_PYTHON=$VIRTUAL_ENV/bin/python $SHELL $return_to/virtualenvwrapper.sh >/dev/null 2>&1"
+    cd "$return_to"
+    deactivate
+}
 
 . "$test_dir/shunit2"

virtualenvwrapper.sh

@@ -99,11 +99,17 @@ virtualenvwrapper_run_hook () {
 # Set up virtualenvwrapper properly
 virtualenvwrapper_initialize () {
     virtualenvwrapper_verify_workon_home -q || return 1
+    # Test for the virtualenvwrapper package we need so we can report
+    # an installation problem.
+    "$VIRTUALENVWRAPPER_PYTHON" -c "import virtualenvwrapper.hook_loader" >/dev/null 2>&1
+    if [ $? -ne 0 ]
+    then
+        echo "virtualenvwrapper.sh: Could not find Python module virtualenvwrapper.hook_loader using VIRTUALENVWRAPPER_PYTHON=$VIRTUALENVWRAPPER_PYTHON. Is the PATH set properly?" 1>&2
+        return 1
+    fi
     virtualenvwrapper_run_hook "initialize"
 }
 
-virtualenvwrapper_initialize
-
 # Verify that virtualenv is installed and visible
 virtualenvwrapper_verify_virtualenv () {
     venv=$(which virtualenv | grep -v "not found")
@@ -426,3 +432,8 @@ cpvirtualenv() {
     echo "Created $new_env virtualenv"
     workon "$new_env"
 }
+
+#
+# Invoke the initialization hooks
+#
+virtualenvwrapper_initialize