Support for generative section names (#2557)

Resolves #2362

Author: gaborbernat

docs/changelog/2362.feature.rst

@@ -0,0 +1 @@
+Add support for generative section headers - by :user:`gaborbernat`.

docs/user_guide.rst

@@ -10,7 +10,7 @@ tool can be:
 - a test runner (such as :pypi:`pytest`),
 - a linter (e.g., :pypi:`flake8`),
 - a formatter (for example :pypi:`black` or :pypi:`isort`),
-- a documentation generator (e.g., :pypi:`sphinx`),
+- a documentation generator (e.g., :pypi:`Sphinx`),
 - library builder and publisher (e.g., :pypi:`build` with :pypi:`twine`),
 - or anything else you may need to execute.
 
@@ -176,10 +176,10 @@ Related projects
 tox has influenced several other projects in the Python test automation space. If tox doesn't quite fit your needs or
 you want to do more research, we recommend taking a look at these projects:
 
-- `nox <https://nox.thea.codes>`__ is a project similar in spirit to tox but different in approach. The primary key
-  difference is that it uses Python scripts instead of a configuration file. It might be useful if you find tox
-  configuration too limiting but aren't looking to move to something as general-purpose as ``Invoke`` or ``make``.
-  Please note that tox will support defining configuration in a Python file soon, too.
+- `nox <https://nox.thea.codes/en/stable/>`__ is a project similar in spirit to tox but different in approach. The
+  primary key difference is that it uses Python scripts instead of a configuration file. It might be useful if you
+  find tox configuration too limiting but aren't looking to move to something as general-purpose as ``Invoke`` or
+  ``make``. Please note that tox will support defining configuration in a Python file soon, too.
 - `Invoke <https://www.pyinvoke.org/>`__ is a general-purpose task execution library, similar to Make. Invoke is far
   more general-purpose than tox but it does not contain the Python testing-specific features that tox specializes in.
 
@@ -364,4 +364,74 @@ tox supports these features that 90 percent of the time you'll not need, but are
 Generative environments
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Django.
+Generative environment list
++++++++++++++++++++++++++++
+
+If you have a large matrix of dependencies, python versions and/or environments you can use a generative
+:ref:`env_list` and conditional settings to express that in a concise form:
+
+.. code-block:: ini
+
+    [tox]
+    env_list = py{311,310,39}-django{41,40}-{sqlite,mysql}
+
+    [testenv]
+    deps =
+        django41: Django>=4.1,<4.2
+        django40: Django>=4.0,<4.1
+        # use PyMySQL if factors "py311" and "mysql" are present in env name
+        py311-mysql: PyMySQL
+        # use urllib3 if any of "py311" or "py310" are present in env name
+        py311,py310: urllib3
+        # mocking sqlite on 3.11 and 3.10 if factor "sqlite" is present
+        py{311,310}-sqlite: mock
+
+This will generate the following tox environments:
+
+.. code-block:: shell
+
+    > tox l
+    default environments:
+    py311-django41-sqlite -> [no description]
+    py311-django41-mysql  -> [no description]
+    py311-django40-sqlite -> [no description]
+    py311-django40-mysql  -> [no description]
+    py310-django41-sqlite -> [no description]
+    py310-django41-mysql  -> [no description]
+    py310-django40-sqlite -> [no description]
+    py310-django40-mysql  -> [no description]
+    py39-django41-sqlite  -> [no description]
+    py39-django41-mysql   -> [no description]
+    py39-django40-sqlite  -> [no description]
+    py39-django40-mysql   -> [no description]
+
+Generative section names
+++++++++++++++++++++++++
+
+Suppose you have some binary packages, and need to run tests both in 32 and 64 bits. You also want an environment to
+create your virtual env for the developers.
+
+.. code-block:: ini
+
+    [testenv]
+    base_python =
+        py311-x86: python3.11-32
+        py311-x64: python3.11-64
+    commands = pytest
+
+    [testenv:py311-{x86,x64}-venv]
+    envdir =
+        x86: .venv-x86
+        x64: .venv-x64
+
+.. code-block:: shell
+
+    > tox l
+    default environments:
+    py          -> [no description]
+
+    additional environments:
+    py310-black -> [no description]
+    py310-lint  -> [no description]
+    py311-black -> [no description]
+    py311-lint  -> [no description]

src/tox/config/loader/ini/__init__.py

@@ -31,8 +31,9 @@ def __init__(
         parser: ConfigParser,
         overrides: list[Override],
         core_section: Section,
+        section_key: str | None = None,
     ) -> None:
-        self._section_proxy: SectionProxy = parser[section.key]
+        self._section_proxy: SectionProxy = parser[section_key or section.key]
         self._parser = parser
         self.core_section = core_section
         super().__init__(section, overrides)

src/tox/config/source/ini.py

@@ -1,10 +1,11 @@
 """Load """
 from __future__ import annotations
 
+from collections import defaultdict
 from configparser import ConfigParser
 from itertools import chain
 from pathlib import Path
-from typing import Iterator
+from typing import DefaultDict, Iterable, Iterator
 
 from tox.config.loader.ini.factor import find_envs
 
@@ -29,7 +30,7 @@ def __init__(self, path: Path, content: str | None = None) -> None:
                 raise ValueError
             content = path.read_text()
         self._parser.read_string(content, str(path))
-        self._sections: dict[str, list[IniLoader]] = {}
+        self._section_mapping: DefaultDict[str, list[str]] = defaultdict(list)
 
     def transform_section(self, section: Section) -> Section:
         return IniSection(section.prefix, section.name)
@@ -39,14 +40,17 @@ def sections(self) -> Iterator[IniSection]:
             yield IniSection.from_key(section)
 
     def get_loader(self, section: Section, override_map: OverrideMap) -> IniLoader | None:
-        if not self._parser.has_section(section.key):
-            return None
-        return IniLoader(
-            section=section,
-            parser=self._parser,
-            overrides=override_map.get(section.key, []),
-            core_section=self.CORE_SECTION,
-        )
+        sections = self._section_mapping.get(section.name)
+        key = sections[0] if sections else section.key
+        if self._parser.has_section(key):
+            return IniLoader(
+                section=section,
+                parser=self._parser,
+                overrides=override_map.get(section.key, []),
+                core_section=self.CORE_SECTION,
+                section_key=key,
+            )
+        return None
 
     def get_core_section(self) -> Section:
         return self.CORE_SECTION
@@ -69,20 +73,29 @@ def envs(self, core_config: ConfigSet) -> Iterator[str]:
                 yield name
 
     def _discover_tox_envs(self, core_config: ConfigSet) -> Iterator[str]:
+        def register_factors(envs: Iterable[str]) -> None:
+            known_factors.update(chain.from_iterable(e.split("-") for e in envs))
+
         explicit = list(core_config["env_list"])
         yield from explicit
-        known_factors = None
+        known_factors: set[str] = set()
+        register_factors(explicit)
+
+        # discover all additional defined environments, including generative section headers
+        for section in self.sections():
+            register_factors(section.names)
+            for name in section.names:
+                self._section_mapping[name].append(section.key)
+                if section.is_test_env:
+                    yield name
+        # add all conditional markers that are not part of the explicitly defined sections
         for section in self.sections():
-            if section.is_test_env:
-                yield section.name
-            if known_factors is None:
-                known_factors = set(chain.from_iterable(e.split("-") for e in explicit))
             yield from self._discover_from_section(section, known_factors)
 
     def _discover_from_section(self, section: IniSection, known_factors: set[str]) -> Iterator[str]:
         for value in self._parser[section.key].values():
             for env in find_envs(value):
-                if env not in known_factors:
+                if set(env.split("-")) - known_factors:
                     yield env
 
     def __repr__(self) -> str:

src/tox/config/source/ini_section.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from tox.config.loader.ini.factor import extend_factors
 from tox.config.loader.section import Section
 
 
@@ -12,6 +13,11 @@ def test_env(cls, name: str) -> IniSection:
     def is_test_env(self) -> bool:
         return self.prefix == TEST_ENV_PREFIX
 
+    @property
+    def names(self) -> list[str]:
+        elements = list(extend_factors(self.name))
+        return elements
+
 
 TEST_ENV_PREFIX = "testenv"
 CORE = IniSection(None, "tox")

tests/config/loader/ini/test_factor.py

@@ -176,3 +176,25 @@ def test_ini_loader_raw_with_factors(
     )
     outcome = loader.load_raw(key="commands", conf=empty_config, env_name=env)
     assert outcome == result
+
+
+def test_generative_section_name(tox_ini_conf: ToxIniCreator) -> None:
+    config = tox_ini_conf(
+        """
+        [testenv:{py311,py310}-{black,lint}]
+        deps-x =
+            black: black
+            lint: flake8
+        """,
+    )
+    assert list(config) == ["py311-black", "py311-lint", "py310-black", "py310-lint"]
+
+    env_config = config.get_env("py311-black")
+    env_config.add_config(keys="deps-x", of_type=List[str], default=[], desc="deps")
+    deps = env_config["deps-x"]
+    assert deps == ["black"]
+
+    env_config = config.get_env("py311-lint")
+    env_config.add_config(keys="deps-x", of_type=List[str], default=[], desc="deps")
+    deps = env_config["deps-x"]
+    assert deps == ["flake8"]

tests/config/test_main.py

@@ -39,7 +39,7 @@ def test_config_some_envs(tox_ini_conf: ToxIniCreator) -> None:
     """
     config = tox_ini_conf(example)
     tox_env_keys = list(config)
-    assert tox_env_keys == ["py38", "py37", "other", "magic"]
+    assert tox_env_keys == ["py38", "py37", "magic", "other"]
 
     config_set = config.get_env("py38")
     assert repr(config_set)

tests/plugin/test_plugin.py

@@ -102,7 +102,7 @@ def tox_add_core_config(core_conf: CoreConfigSet, state: State) -> None:  # noqa
     """
     project = tox_project({"tox.ini": ini})
     result = project.run()
-    assert "ROOT: All envs: explicit, implicit, section" in result.out
+    assert "ROOT: All envs: explicit, section, implicit" in result.out
     assert "ROOT: Default envs: explicit" in result.out