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

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#425. The only sane
thing to do here is ignore the request and use the correct interpreter
so this is what's done. A log is included to alert people to their
potential misconfigurations.

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

Author: stephenfin

changelog/425.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

@@ -82,7 +82,9 @@ 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.
+    the virtual environment; if the environment name contains a :ref:`default
+    factor <factors>`, this value will be ignored. **default**: interpreter
+    used for tox invocation.
 
 .. confval:: commands=ARGVLIST
 
@@ -540,9 +542,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 +605,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 +620,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
 +++++++++++++++++++++++++

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(