Ignore basepython for default factors (tox-dev#477)

tox provides a number of default factors - py27, py34, py35 etc. - that
are tied to particular interpreter versions. It is possible to override
these through individual sections or the global [testenv] section. For
example, consider the following 'tox.ini' file:

  [tox]
  skipsdist = True
  minversion = 2.0
  distribute = False
  envlist = py35,py27,pep8,py34-test

  [testenv]
  basepython = python3
  install_command = pip install {opts} {packages}
  commands =
    python --version

  [testenv:py27]
  basepython = python2.7

Running any target except for 'py27' will result in the same interpreter
being used. On Fedora 28 with the 'python3-tox' package:

  $ tox -qq -e py27
  Python 2.7.15
  $ tox -qq -e py35
  Python 3.6.5
  $ tox -qq -e py34-test
  Python 3.6.5

This is broken by design. Overriding these makes no sense and is a
source of common misconfigurations, as noted in tox-dev#477. The only sane
thing to do here is ignore the request and use the correct interpreter
so this is what's done.

Signed-off-by: Stephen Finucane <[email protected]>
Closes: tox-dev#477

Author: stephenfin

changelog/477.bugfix.rst

@@ -0,0 +1,3 @@
+Ignore ``basepython`` for environments containing default factors, such as
+``py27`` or ``django18-py35``. This was a common source of misconfiguration and
+is rarely, if ever, desirable from a user perspective - by @stephenfin

doc/config.rst

@@ -81,8 +81,15 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
 .. confval:: basepython=NAME-OR-PATH
 
-    name or path to a Python interpreter which will be used for creating
-    the virtual environment. **default**: interpreter used for tox invocation.
+    Name or path to a Python interpreter which will be used for creating
+    the virtual environment; if the environment name contains a :ref:`default
+    factor <factors>`, this value will be ignored. **default**: interpreter
+    used for tox invocation.
+
+    .. versionchanged:: 3.1
+
+       Environments that use a :ref:`default factor <factors>` now ignore this
+       value, defaulting to the interpreter defined for that factor.
 
 .. confval:: commands=ARGVLIST
 
@@ -540,9 +547,6 @@ However, a better approach looks like this:
     envlist = {py27,py36}-django{15,16}
 
     [testenv]
-    basepython =
-        py27: python2.7
-        py36: python3.6
     deps =
         pytest
         django15: Django>=1.5,<1.6
@@ -606,23 +610,12 @@ Factors and factor-conditional settings
 ++++++++++++++++++++++++++++++++++++++++
 
 Parts of an environment name delimited by hyphens are called factors and can
-be used to set values conditionally:
-
-.. code-block:: ini
-
-    basepython =
-        py27: python2.7
-        py36: python3.6
-
-This conditional setting will lead to either ``python3.6`` or
-``python2.7`` used as base python, e.g. ``python3.6`` is selected if current
-environment contains ``py36`` factor.
-
-In list settings such as ``deps`` or ``commands`` you can freely intermix
-optional lines with unconditional ones:
+be used to set values conditionally. In list settings such as ``deps`` or
+``commands`` you can freely intermix optional lines with unconditional ones:
 
 .. code-block:: ini
 
+    [testenv]
     deps =
         pytest
         django15: Django>=1.5,<1.6
@@ -632,16 +625,20 @@ optional lines with unconditional ones:
 Reading it line by line:
 
 - ``pytest`` will be included unconditionally,
-- ``Django>=1.5,<1.6`` will be included for environments containing ``django15`` factor,
+- ``Django>=1.5,<1.6`` will be included for environments containing
+  ``django15`` factor,
 - ``Django>=1.6,<1.7`` similarly depends on ``django16`` factor,
 - ``unittest`` will be loaded for Python 3.6 environments.
 
-.. note::
+tox provides a number of default factors corresponding to Python interpreter
+versions. The conditional setting above will lead to either ``python3.6`` or
+``python2.7`` used as base python, e.g. ``python3.6`` is selected if current
+environment contains ``py36`` factor.
 
-    tox provides good defaults for basepython setting, so the above
-    ini-file can be further reduced by omitting the ``basepython``
-    setting.
+.. note::
 
+    It is not possible to override the ``basepython`` value for environments
+    using default factors. If defined, this value will be ignored.
 
 Complex factor conditions
 +++++++++++++++++++++++++

doc/example/general.rst

@@ -49,7 +49,6 @@ a tox test run.  Here is an example ``tox.ini`` configuration:
 .. code-block:: ini
 
     [testenv:docs]
-    basepython = python
     changedir = doc
     deps = sphinx
     commands = sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
@@ -142,26 +141,23 @@ If you want to use this with Jenkins_, also checkout the :ref:`jenkins artifact
 .. _verlib: https://bitbucket.org/tarek/distutilsversion/
 
 basepython defaults, overriding
-++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++
 
-By default, for any ``pyXY`` test environment name
-the underlying "pythonX.Y" executable will be searched in
-your system ``PATH``. It must exist in order to successfully create
-virtualenv environments.  On Windows a ``pythonX.Y`` named executable
-will be searched in typical default locations using the
-``C:\PythonX.Y\python.exe`` pattern.
+For any ``pyXY`` test environment name the underlying ``pythonX.Y`` executable
+will be searched in your system ``PATH``. Similarly, for ``jython`` and
+``pypy`` the respective ``jython`` and ``pypy-c`` names will be looked for.
+The executable must exist in order to successfully create *virtualenv*
+environments. On Windows a ``pythonX.Y`` named executable will be searched in
+typical default locations using the ``C:\PythonX.Y\python.exe`` pattern.
 
-For ``jython`` and ``pypy`` the respective ``jython``
-and ``pypy-c`` names will be looked for.
-
-You can override any of the default settings by defining
-the ``basepython`` variable in a specific test environment
-section, for example:
+All other targets will use the system ``python`` instead. You can override any
+of the default settings by defining the :confval:`basepython` variable in a
+specific test environment section, for example:
 
 .. code-block:: ini
 
-    [testenv:py27]
-    basepython=/my/path/to/python2.7
+    [testenv:docs]
+    basepython = python2.7
 
 Avoiding expensive sdist
 ------------------------

tests/test_config.py

@@ -1005,6 +1005,19 @@ def test_envbindir_jython(self, newconfig, bp):
         if bp == "jython":
             assert envconfig.envpython == envconfig.envbindir.join(bp)
 
+    def test_envbindir_override_ignored(self, newconfig):
+        config = newconfig(
+            """
+            [testenv]
+            basepython=python3
+            [testenv:py27]
+            commands = python --version
+        """
+        )
+        assert len(config.envconfigs) == 1
+        envconfig = config.envconfigs["py27"]
+        assert envconfig.basepython == "python2.7"
+
     @pytest.mark.parametrize("plat", ["win32", "linux2"])
     def test_passenv_as_multiline_list(self, newconfig, monkeypatch, plat):
         monkeypatch.setattr(tox.INFO, "IS_WIN", plat == "win32")

tox/config.py

@@ -505,11 +505,19 @@ def setenv(testenv_config, value):
     )
 
     def basepython_default(testenv_config, value):
+        """Configure a sane interpreter for the environment.
+
+        If the environment contains a default factor, this will always be the
+        interpreter associated with that factor overriding anything manually
+        set.
+        """
+        for factor in testenv_config.factors:
+            if factor in tox.PYTHON.DEFAULT_FACTORS:
+                return tox.PYTHON.DEFAULT_FACTORS[factor]
+
         if value is None:
-            for factor in testenv_config.factors:
-                if factor in tox.PYTHON.DEFAULT_FACTORS:
-                    return tox.PYTHON.DEFAULT_FACTORS[factor]
             return sys.executable
+
         return str(value)
 
     parser.add_testenv_attribute(