Improved factor selection to allow multiple uses of `-f` for "OR" and to allow hyphenated factors (#2786)

* Enable multiple uses of '-f' meaning 'OR'

Previously, when `-f` was passed, it overwrote the last value. The
result was that `-f foo -f bar` was equivalent to only passing
`-f bar`. Under the new behavior, `-f foo -f bar` combines `foo` and
`bar` as selection criteria, using OR-semantics. Envs matching
`foo OR bar` will be selected.

The existing multi-value argument behavior for `-f` is retained, in
which `-f foo bar` means `foo AND bar`. The behaviors can be combined
to express a variety of environment selections which were not
previously possible in a single invocation. e.g. `-f foo bar -f baz`
meaning `(foo AND bar) OR baz`.

No existing tests fail, and the new behavior is checked by a new test.
The help message for `-f` is updated.

* Allow factors to be passed hyphenated

The existing parsing of factors allows multiple factors to be selected
by passing them as multiple arguments to the `-f` flag. For example,
`-f foo bar` to pass both `foo` and `bar` as factors. This can now be
passed equivalently using `-f foo-bar`. The meaning of this
usage is identical to `-f foo bar`.

A new test checks the behavior, and very closely mirrors the existing
`-f` selection test so that their outputs are exactly equivalent.

* Make factor tests parametrized & apply pre-commit

These three tests are nearly identical in structure, and rely upon the
same project configuration. Convert from three distinct test cases to
a single parametrized test.

Also apply pre-commit, which does some mild reformatting.

* Add changelog entry for #2766

* Fix missing annotation in tests

* Fix changelog entry for #2766

* Improve env selection with factors: perf and types

- use tuple instead of list for immutable data
- use `continue` and `break` to skip unnecessary loop iterations

* Cleanup factor selection tests

- convert args from list[str] to tuple[str, ...]
- reformat str concat into a `.format()` usage

* Remove unreachable factor selection check

This check cannot be reached because it relies on an impossible
combination of factors and labels.

1 files changed, 26 insertions, 3 deletions

diff --git a/tests/session/test_env_select.py b/tests/session/test_env_select.py
index b6683541..496107a3 100644
--- a/tests/session/test_env_select.py
+++ b/tests/session/test_env_select.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import pytest
+
 from tox.pytest import MonkeyPatch, ToxProjectCreator
 
 
@@ -61,15 +63,36 @@ def test_label_core_and_trait(tox_project: ToxProjectCreator) -> None:
     outcome.assert_out_err("py310\npy39\nflake8\ntype\n", "")
 
 
-def test_factor_select(tox_project: ToxProjectCreator) -> None:
+@pytest.mark.parametrize(
+    ("selection_arguments", "expect_envs"),
+    [
+        (
+            ("-f", "cov", "django20"),
+            ("py310-django20-cov", "py39-django20-cov"),
+        ),
+        (
+            ("-f", "cov-django20"),
+            ("py310-django20-cov", "py39-django20-cov"),
+        ),
+        (
+            ("-f", "py39", "django20", "-f", "py310", "django21"),
+            ("py310-django21-cov", "py310-django21", "py39-django20-cov", "py39-django20"),
+        ),
+    ],
+)
+def test_factor_select(
+    tox_project: ToxProjectCreator,
+    selection_arguments: tuple[str, ...],
+    expect_envs: tuple[str, ...],
+) -> None:
     ini = """
         [tox]
         env_list = py3{10,9}-{django20,django21}{-cov,}
         """
     project = tox_project({"tox.ini": ini})
-    outcome = project.run("l", "--no-desc", "-f", "cov", "django20")
+    outcome = project.run("l", "--no-desc", *selection_arguments)
     outcome.assert_success()
-    outcome.assert_out_err("py310-django20-cov\npy39-django20-cov\n", "")
+    outcome.assert_out_err("{}\n".format("\n".join(expect_envs)), "")
 
 
 def test_tox_skip_env(tox_project: ToxProjectCreator, monkeypatch: MonkeyPatch) -> None: