Better selection support (#2290)

Author: gaborbernat

.github/workflows/check.yml

@@ -15,11 +15,11 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-      - uses: pre-commit/[email protected].0
+      - uses: pre-commit/[email protected].3
 
   test:
-    name: test ${{ matrix.py }} - ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}-latest
+    name: test ${{ matrix.py }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
@@ -29,9 +29,9 @@ jobs:
           - "3.8"
           - "3.7"
         os:
-          - Ubuntu
-          - Windows
-          - MacOs
+          - ubuntu-20.04
+          - windows-2022
+          - macos-11
     steps:
       - name: Setup python for tox
         uses: actions/setup-python@v2
@@ -78,21 +78,21 @@ jobs:
           name: ${{ matrix.py }} - ${{ matrix.os }}
 
   check:
-    name: check ${{ matrix.tox_env }} - ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}-latest
+    name: tox env ${{ matrix.tox_env }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        os:
-          - Windows
-          - Ubuntu
         tox_env:
           - type
           - dev
           - docs
           - pkg_meta
+        os:
+          - ubuntu-20.04
+          - windows-2022
         exclude:
-          - { os: windows, tox_env: pkg_meta }
+          - { os: windows-2022, tox_env: pkg_meta }
     steps:
       - uses: actions/checkout@v2
         with:
@@ -111,7 +111,7 @@ jobs:
   publish:
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
     needs: [check, test, pre_commit]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     steps:
       - name: Setup python to build package
         uses: actions/setup-python@v2

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
+    rev: v4.1.0
     hooks:
       - id: check-builtin-literals
       - id: check-docstring-first
@@ -17,7 +17,7 @@ repos:
       - id: add-trailing-comma
         args: [--py36-plus]
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.29.1
+    rev: v2.30.1
     hooks:
       - id: pyupgrade
         args: ["--py37-plus"]
@@ -43,7 +43,7 @@ repos:
       - id: prettier
         additional_dependencies:
           - [email protected]
-          - "@prettier/plugin-xml@1.1.0"
+          - "@prettier/plugin-xml@1.2.0"
         args: ["--print-width=120", "--prose-wrap=always"]
   - repo: https://github.com/asottile/blacken-docs
     rev: v1.12.0
@@ -55,7 +55,7 @@ repos:
     hooks:
       - id: setup-cfg-fmt
   - repo: https://github.com/tox-dev/tox-ini-fmt
-    rev: "0.5.1"
+    rev: "0.5.2"
     hooks:
       - id: tox-ini-fmt
         args: ["-p", "fix"]

docs/changelog/2275.removal.rst

@@ -0,0 +1,3 @@
+``tox_add_core_config`` and ``tox_add_env_config`` now take a ``state: State`` argument instead of a configuration one,
+and ``Config`` not longer provides the ``envs`` property (instead users should migrate to ``State.envs``) - by
+:user:`gaborbernat`.

docs/changelog/2290.feature.rst

@@ -0,0 +1,2 @@
+Support for selecting target environments with a given factor via the :ref:`-m <tox-run--f>` CLI environment flag - by
+:user:`gaborbernat`.

docs/changelog/238.feature.rst

@@ -0,0 +1,3 @@
+Support for grouping environment values together by applying labels to them either at :ref:`core <labels>` and
+:ref:`environment <labels-env>` level, and allow selecting them via the :ref:`-m <tox-run--m>` flag from the CLI - by
+:user:`gaborbernat`.

docs/conf.py

@@ -142,13 +142,16 @@ def resolve_xref(
                 "tox.tox_env.installer.T": "typing.TypeVar",
                 "ToxParserT": "typing.TypeVar",
                 "_Section": "Section",
+                "ArgumentParser": "argparse.ArgumentParser",
+                "Factory": "tox.config.loader.convert.Factory",
             }
             if target in mapping:
+                if target == "Factory":
+                    type = "attr"
                 node["reftarget"] = mapping[target]
-            if target == "_Section":
-                target = "Section"
-                contnode = Text(target, target)
-
+                if target == "_Section":
+                    target = "Section"
+                    contnode = Text(target, target)
             return super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)
 
     app.connect("autodoc-skip-member", skip_member)

docs/config.rst

@@ -195,6 +195,19 @@ Core
 
     Indicates where the packaging root file exists (historically setup.py file or pyproject.toml now).
 
+.. conf::
+   :keys: labels
+   :default: <empty dictionary>
+
+   A mapping of label names to environments it applies too. For example:
+
+   .. code-block:: ini
+
+      [tox]
+      labels =
+           test = py310, py39
+           static = flake8, mypy
+
 Python language core options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -304,6 +317,20 @@ Base options
    ``allowlist_externals=make`` or ``allowlist_externals=/usr/bin/make``. If you want to allow all external commands
    you can use ``allowlist_externals=*`` which will match all commands (not recommended).
 
+.. conf::
+   :keys: labels
+   :default: <empty list>
+   :ref_suffix: env
+
+   A list of labels to apply for this environment. For example:
+
+   .. code-block:: ini
+
+      [testenv]
+      labels = test, core
+      [testenv:flake8]
+      labels = mypy
+
 Execute
 ~~~~~~~
 

docs/plugins_api.rst

@@ -73,6 +73,9 @@ config
 .. autoclass:: tox.config.types.Command
    :members:
 
+.. autoclass:: tox.config.loader.convert.Factory
+   :members:
+
 environments
 ------------
 .. autoclass:: tox.tox_env.api.ToxEnv
@@ -128,3 +131,14 @@ installer
 
 .. autoclass:: tox.tox_env.installer.Installer
    :members:
+
+session
+-------
+.. autoclass:: tox.session.state.State
+   :members:
+
+.. autoclass:: tox.session.env_select.EnvSelector
+   :members:
+
+.. autoclass:: tox.tox_env.info.Info
+   :members:

src/tox/config/cli/parse.py

@@ -3,17 +3,26 @@
 """
 from __future__ import annotations
 
-from typing import Dict, Sequence, cast
+from typing import TYPE_CHECKING, Callable, NamedTuple, Sequence, cast
 
 from tox.config.source import Source, discover_source
 from tox.report import ToxHandler, setup_report
 
-from .parser import Handler, Parsed, ToxParser
+from .parser import Parsed, ToxParser
 
-Handlers = Dict[str, Handler]
+if TYPE_CHECKING:
+    from tox.session.state import State
 
 
-def get_options(*args: str) -> tuple[Parsed, Handlers, Sequence[str] | None, ToxHandler, Source]:
+class Options(NamedTuple):
+    parsed: Parsed
+    pos_args: Sequence[str] | None
+    source: Source
+    cmd_handlers: dict[str, Callable[[State], int]]
+    log_handler: ToxHandler
+
+
+def get_options(*args: str) -> Options:
     pos_args: tuple[str, ...] | None = None
     try:  # remove positional arguments passed to parser if specified, they are pulled directly from sys.argv
         pos_arg_at = args.index("--")
@@ -27,7 +36,7 @@ def get_options(*args: str) -> tuple[Parsed, Handlers, Sequence[str] | None, Tox
     parsed, cmd_handlers = _get_all(args)
     if guess_verbosity != parsed.verbosity:
         setup_report(parsed.verbosity, parsed.is_colored)  # pragma: no cover
-    return parsed, cmd_handlers, pos_args, log_handler, source
+    return Options(parsed, pos_args, source, cmd_handlers, log_handler)
 
 
 def _get_base(args: Sequence[str]) -> tuple[int, ToxHandler, Source]:
@@ -45,7 +54,7 @@ def _get_base(args: Sequence[str]) -> tuple[int, ToxHandler, Source]:
     return guess_verbosity, handler, source
 
 
-def _get_all(args: Sequence[str]) -> tuple[Parsed, Handlers]:
+def _get_all(args: Sequence[str]) -> tuple[Parsed, dict[str, Callable[[State], int]]]:
     """Parse all the options."""
     tox_parser = _get_parser()
     parsed = cast(Parsed, tox_parser.parse_args(args))
@@ -75,5 +84,5 @@ def _get_parser_doc() -> ToxParser:
 
 __all__ = (
     "get_options",
-    "Handlers",
+    "Options",
 )

src/tox/config/cli/parser.py

@@ -9,11 +9,10 @@
 import sys
 from argparse import SUPPRESS, Action, ArgumentDefaultsHelpFormatter, ArgumentParser, Namespace
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Type, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Sequence, Tuple, Type, TypeVar, cast
 
 from tox.config.loader.str_convert import StrConvert
 from tox.plugin import NAME
-from tox.session.state import State
 
 from .env_var import get_env_var
 from .ini import IniConfig
@@ -23,6 +22,9 @@
 else:  # pragma: no cover (py38+)
     from typing_extensions import Literal
 
+if TYPE_CHECKING:
+    from tox.session.state import State
+
 
 class ArgumentParserWithEnvAndConfig(ArgumentParser):
     """
@@ -93,8 +95,6 @@ def _get_help_string(self, action: Action) -> str | None:
         return text
 
 
-Handler = Callable[[State], int]
-
 ToxParserT = TypeVar("ToxParserT", bound="ToxParser")
 DEFAULT_VERBOSITY = 2
 
@@ -122,7 +122,7 @@ class ToxParser(ArgumentParserWithEnvAndConfig):
 
     def __init__(self, *args: Any, root: bool = False, add_cmd: bool = False, **kwargs: Any) -> None:
         self.of_cmd: str | None = None
-        self.handlers: dict[str, tuple[Any, Handler]] = {}
+        self.handlers: dict[str, tuple[Any, Callable[[State], int]]] = {}
         self._arguments: list[ArgumentArgs] = []
         self._groups: list[tuple[Any, dict[str, Any], list[tuple[dict[str, Any], list[ArgumentArgs]]]]] = []
         super().__init__(*args, **kwargs)
@@ -136,7 +136,13 @@ def __init__(self, *args: Any, root: bool = False, add_cmd: bool = False, **kwar
         else:
             self._cmd = None
 
-    def add_command(self, cmd: str, aliases: Sequence[str], help_msg: str, handler: Handler) -> ArgumentParser:
+    def add_command(
+        self,
+        cmd: str,
+        aliases: Sequence[str],
+        help_msg: str,
+        handler: Callable[[State], int],
+    ) -> ArgumentParser:
         if self._cmd is None:
             raise RuntimeError("no sub-command group allowed")
         sub_parser: ToxParser = self._cmd.add_parser(
@@ -217,7 +223,7 @@ def _add_base_options(self) -> None:
 
     def parse_known_args(  # type: ignore[override]
         self,
-        args: Sequence[str] | None,
+        args: Sequence[str] | None = None,
         namespace: Parsed | None = None,
     ) -> tuple[Parsed, list[str]]:
         if args is None:
@@ -315,5 +321,4 @@ def add_core_arguments(parser: ArgumentParser) -> None:
     "DEFAULT_VERBOSITY",
     "Parsed",
     "ToxParser",
-    "Handler",
 )