Add UPPER_CONSTRAINTS_FILE file if it exists

Create a parameter called tox_upper_constraints. The parameter points
to a file on the system. If the file exists, it will be passed to the
tox invocation in the UPPER_CONSTRAINTS_FILE environment variable.

This allows a global setting in a base job of a known file to be the
UPPER_CONSTRAINTS_FILE file, or for that to be overridden on a per-job
basis. For people who do not know or care what an
UPPER_CONSTRAINTS_FILE file is, the behavior should be a no-op.

Also, collapse tox_environment and tox_environment_defaults.
zuul already does variable merging on parent and child jobs, so we don't
need to do it in the playbook.

While we're in there, clean up a few small things in the yaml. Notably,
jlk says we should not put variables in task names, and we don't need
quotes around strings if they don't have special characters.

Change-Id: Ibede59ca6f85914952da175c77ea29391ef9a88c

roles/tox/README.rst

@@ -6,12 +6,6 @@ Runs tox for a project
 
    Environment variables to pass in to the tox run.
 
-.. zuul:rolevar:: tox_environment_defaults
-
-   Default environment variables to pass in to the tox run. Intended
-   to allow setting a set of environment variables in a base job but
-   to still allow specific settings on a per-job or per-variant basis.
-
 .. zuul:rolevar:: tox_envlist
    :default: venv
 
@@ -27,7 +21,12 @@ Runs tox for a project
 
    String of extra command line options to pass to tox.
 
+.. zuul:rolevar:: tox_upper_constraints_file
+
+   Path to an upper constraints file. Will be provided to tox via
+   UPPER_CONSTRAINTS_FILE environment variable if it exists.
+
 .. zuul:rolevar:: zuul_work_dir
-   :default: src/{{ zuul.project.canonical_name }}
+   :default: {{ zuul.project.src_dir }}
 
    Directory to run tox in.

roles/tox/defaults/main.yaml

@@ -1,8 +1,7 @@
 ---
 tox_environment: {}
-tox_environment_defaults: {}
 tox_envlist: venv
 tox_executable: tox
 tox_extra_args: -vv
 
-zuul_work_dir: "src/{{ zuul.project.canonical_name }}"
+zuul_work_dir: "{{ zuul.project.src_dir }}"

roles/tox/tasks/main.yaml

@@ -1,14 +1,25 @@
-- name: Require tox_envlist variable - {{ tox_envlist }}
+- name: Require tox_envlist variable
   fail:
-    msg: "tox_envlist is required for this role"
+    msg: tox_envlist is required for this role
   when: tox_envlist is not defined
 
-- name: Create my_tox_environment variable
+- name: Check to see if the constraints file exists
+  stat:
+    path: "{{ tox_upper_constraints_file }}"
+    get_checksum: false
+    get_mime: false
+    get_md5: false
+  register: stat_results
+  when: tox_upper_constraints_file is defined
+
+- name: Record file location
   set_fact:
-    my_tox_environment: "{{ tox_environment_defaults | combine(tox_environment) }}"
+    tox_upper_constraints_env:
+      UPPER_CONSTRAINTS_FILE: "{{ tox_upper_constraints_file }}"
+  when: not stat_results|skipped and stat_results.stat.exists
 
 - name: Run tox
   args:
-    chdir: "{{ zuul_work_dir | default(omit) }}"
-  environment: "{{ my_tox_environment }}"
+    chdir: "{{ zuul_work_dir }}"
+  environment: "{{ tox_environment|combine(tox_upper_constraints_env|default({})) }}"
   command: "{{ tox_executable }} -e{{ tox_envlist }} {{ tox_extra_args }}"

zuul.yaml

@@ -34,11 +34,16 @@
       .. zuul:jobvar:: tox_extra_args
 
          String containing extra arguments to append to the tox command line.
+
+      .. zuul:jobvar: tox_upper_constraints_file
+
+         Path to an upper constraints file. Will be provided to tox via
+         UPPER_CONSTRAINTS_FILE environment variable if it exists.
     run: playbooks/tox/run
     pre-run: playbooks/tox/pre
     post-run: playbooks/tox/post
     vars:
-      tox_environment_defaults:
+      tox_environment:
         NOSE_WITH_HTML_OUTPUT: 1
         NOSE_HTML_OUT_FILE: nose_results.html
         NOSE_WITH_XUNIT: 1