Provide an option to force pip --upgrade

Make it possible for someone to config

  PIP_UPGRADE=True

in local.conf and thus force pip_install calls to upgrade. In
automated testing this is probably a bad idea, but in manual testing
or situations where devstack is being used to spin up proof of
concepts having the option to use the latest and greatest Python
modules is a useful way of exploring the health of the ecosystem.

To help with visibility of the setting, and section has been added
in configuration.rst near other similar settings.

Change-Id: I484c954f1e1f05ed02c0b08e8e4a9c18558c05ef

doc/source/configuration.rst

@@ -247,6 +247,21 @@ A clean install every time
 
         RECLONE=yes
 
+Upgrade packages installed by pip
+---------------------------------
+
+    | *Default: ``PIP_UPGRADE=""``*
+    |  By default ``stack.sh`` only installs Python packages if no version
+       is currently installed or the current version does not match a specified
+       requirement. If ``PIP_UPGRADE`` is set to ``True`` then existing required
+       Python packages will be upgraded to the most recent version that
+       matches requirements.
+    |
+
+    ::
+
+        PIP_UPGRADE=True
+
 Swift
 -----
 

inc/python

@@ -54,17 +54,23 @@ function get_python_exec_prefix {
 
 # Wrapper for ``pip install`` to set cache and proxy environment variables
 # Uses globals ``INSTALL_TESTONLY_PACKAGES``, ``OFFLINE``, ``PIP_VIRTUAL_ENV``,
-# ``TRACK_DEPENDS``, ``*_proxy``
+# ``PIP_UPGRADE``, ``TRACK_DEPENDS``, ``*_proxy``
 # pip_install package [package ...]
 function pip_install {
     local xtrace=$(set +o | grep xtrace)
     set +o xtrace
+    local upgrade=""
     local offline=${OFFLINE:-False}
     if [[ "$offline" == "True" || -z "$@" ]]; then
         $xtrace
         return
     fi
 
+    PIP_UPGRADE=$(trueorfalse False PIP_UPGRADE)
+    if [[ "$PIP_UPGRADE" = "True" ]] ; then
+        upgrade="--upgrade"
+    fi
+
     if [[ -z "$os_PACKAGE" ]]; then
         GetOSVersion
     fi
@@ -98,7 +104,7 @@ function pip_install {
         https_proxy="${https_proxy:-}" \
         no_proxy="${no_proxy:-}" \
         PIP_FIND_LINKS=$PIP_FIND_LINKS \
-        $cmd_pip install \
+        $cmd_pip install $upgrade \
         $@
 
     # Also install test requirements
@@ -110,7 +116,7 @@ function pip_install {
             https_proxy=${https_proxy:-} \
             no_proxy=${no_proxy:-} \
             PIP_FIND_LINKS=$PIP_FIND_LINKS \
-            $cmd_pip install \
+            $cmd_pip install $upgrade \
             -r $test_req
     fi
 }