WIP: Allow ensure-tox to upgrade tox version

Adds new variable `tox_upgrade: false` which can be used to change
behavior of ensure-tox role. By default old bahaviour is maintained.

This fixes failure to run "Run tox without tests" on some platform which
already have an ancient version (like 1.6) on the system. Users
encountering this can easily set tox_upgrade to true.

Such old versions of tox are not able to upgrade itself and not even
able to parse the tox.ini file.

The only way to avoid this is to assure that the system has a recent
enough version of tox.

Tox ability to boostrap itself was added only in 3.8.0 which is
not present in most distributions.

This change also switches the default tox executable to use python
module calling method in order to avoid calling /usr/bin/tox file
which could be broken after the upgrade.

Change-Id: I27950691a815bbb458952b585084f2fa1158661f
Needed-By: https://review.rdoproject.org/r/#/c/21594/

roles/ensure-tox/README.rst

@@ -2,3 +2,26 @@ Ensure tox is installed
 
 If tox is not already installed, it will be installed via pip in the
 user install directory (i.e., "pip install --user").
+
+If tox is already installed and working and user does not specify a
+``tox_condition`` or enable `tox_upgrade`, this task will not need network
+access.
+
+**Role Variables**
+
+.. zuul:rolevar:: tox_upgrade
+   :default: false
+
+   If you want the installation of latest tox, regardless of presence on the
+   system, define `tox_upgrade: true`.
+
+.. zuul:rolevar:: tox_condition
+   :default: tox
+
+   Python requirements condition to be used when installing tox. You can define
+   it to "tox>=3.8.0" to force a minimal version.
+
+.. zuul:rolevar:: tox_executable
+   :default: {{ ansible_python.executable }} -m tox
+
+   Location of the tox executable.

roles/ensure-tox/defaults/main.yaml

@@ -0,0 +1,5 @@
+# when set, it will always install latest version of tox using --user
+# be aware that this may break /usr/bin/tox executable due to changed internals
+tox_upgrade: false
+tox_condition: tox
+tox_executable: "{{ ansible_python.executable }} -m tox"

roles/ensure-tox/tasks/main.yaml

@@ -1,2 +1,53 @@
-- name: Ensure tox is installed
-  shell: type tox || pip install --user tox
+- name: Check if tox is accesiblsexx  # noqa 305
+  shell: |
+    set -eux
+    tox --version
+    {{ tox_executable }} --version
+  register: result
+  ignore_errors: true
+  changed_when: false
+
+# installing tox with --user will create tox script inside ~/.local/bin but
+# this folder is *not* included PATH in all distros. If you want to call it as
+# a script you may need to add it to the path like example below. Still calling
+# it as a python module works in all cases.
+#
+# if [[ ":$PATH:" != *":${HOME}/.local/bin:"* ]] && [ -d "${HOME}/.local/bin" ]; then
+#   export PATH=${HOME}/.local/bin:$PATH
+# fi
+- name: install tox
+  when: result is failed or tox_upgrade or tox_condition != 'tox'
+  block:
+
+    - name: Ensure tox is installed  # noqa 305
+      environment:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_WARN_SCRIPT_LOCATION: "1"
+      vars:
+        upgrade: "{% if result is failed or tox_upgrade %}--upgrade{% endif %}"
+      shell: |
+        set -eu
+        {{ ansible_python.executable }} -m pip install --user {{ upgrade }} '{{ tox_condition }}'
+        {{ tox_executable }} --version
+      args:
+        executable: /bin/bash
+      register: result
+      changed_when: result.stdout.find('Successfully installed') != -1
+
+    # We want to be sure that if someone calls 'tox' without having `~/.local/bin`
+    # in PATH, they still get a *working* copy of it.
+    - name: Ensure a system tox is also available
+      when: result is changed
+      become: true
+      environment:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_WARN_SCRIPT_LOCATION: "1"
+      shell: |
+        set -eu
+        type tox >/dev/null || {
+          {# -s is key here to prevent it from finding tox from userdir #}
+          {{ ansible_python.executable }} -s -m pip install '{{ tox_condition }}'
+        }
+        {{ tox_executable }} --version
+      args:
+        executable: /bin/bash

roles/tox/README.rst

@@ -12,7 +12,7 @@ Runs tox for a project
    Which tox environment to run.
 
 .. zuul:rolevar:: tox_executable
-   :default: tox
+   :default: {{ ansible_python.executable }} -m tox
 
    Location of the tox executable.
 

roles/tox/defaults/main.yaml

@@ -1,7 +1,9 @@
 ---
 tox_environment: {}
 tox_envlist: venv
-tox_executable: tox
+# Calling tox as a module in order to avoid case where tox script gets broken
+# because user installed newer version of tox into user packages.
+tox_executable: "{{ ansible_python.executable }} -m tox"
 tox_extra_args: -vv
 tox_install_siblings: true