Inject TOX_PARALLEL_ENV environment variables (#1139)

* Inject TOX_PARALLEL_ENV environment variables

To allow other libraries, or projects, to know if Tox is running in
parallel mode, add the `TOX_PARALLEL_ENV` environment variable to the
list of injected variables.

Particularly, this is useful for `pytest-django` to know if Tox is
running in parallel mode, to rename test databases [0].

[0] pytest-dev/pytest-django#680

* Use strings (bytestrings in Python 2) in passenv whitelist

CONTRIBUTORS

@@ -50,6 +50,7 @@ Mark Hirota
 Matt Good
 Matt Jeffery
 Mattieu Agopian
+Michael Manganiello
 Mikhail Kyshtymov
 Monty Taylor
 Morgan Fainberg

docs/changelog/1139.feature.rst

@@ -0,0 +1 @@
+tox will inject the ``TOX_PARALLEL_ENV`` environment variable, set to the current running tox environment name, only when running in parallel mode.

docs/config.rst

@@ -932,6 +932,7 @@ tox will inject the following environment variables that you can use to test tha
 - ``TOX_ENV_NAME`` is set to the current running tox environment name
 - ``TOX_ENV_DIR`` is set to the current tox environments working dir.
 - ``TOX_PACKAGE`` the packaging phases outcome path (useful to inspect and make assertion of the built package itself).
+- ``TOX_PARALLEL_ENV`` is set to the current running tox environment name, only when running in parallel mode.
 
 :note: this applies for all tox envs (isolated packaging too) and all external
  commands called (e.g. install command - pip).

src/tox/config/__init__.py

@@ -659,7 +659,15 @@ def passenv(testenv_config, value):
         # Flatten the list to deal with space-separated values.
         value = list(itertools.chain.from_iterable([x.split(" ") for x in value]))
 
-        passenv = {"PATH", "PIP_INDEX_URL", "LANG", "LANGUAGE", "LD_LIBRARY_PATH", "TOX_WORK_DIR"}
+        passenv = {
+            "PATH",
+            "PIP_INDEX_URL",
+            "LANG",
+            "LANGUAGE",
+            "LD_LIBRARY_PATH",
+            "TOX_WORK_DIR",
+            str(PARALLEL_ENV_VAR_KEY),
+        }
 
         # read in global passenv settings
         p = os.environ.get("TOX_TESTENV_PASSENV", None)

tests/unit/config/test_config.py

@@ -19,6 +19,7 @@
     is_section_substitution,
     parseconfig,
 )
+from tox.config.parallel import ENV_VAR_KEY as PARALLEL_ENV_VAR_KEY
 from tox.venv import VirtualEnv
 
 
@@ -1047,6 +1048,7 @@ def test_passenv_as_multiline_list(self, newconfig, monkeypatch, plat):
         assert "LANG" in envconfig.passenv
         assert "LANGUAGE" in envconfig.passenv
         assert "LD_LIBRARY_PATH" in envconfig.passenv
+        assert PARALLEL_ENV_VAR_KEY in envconfig.passenv
         assert "A123A" in envconfig.passenv
         assert "A123B" in envconfig.passenv