🐛 fix(env): suggest normalized env name for dotted Python versions (#3888)

Users typing `tox -e py3.10-lint` when their envlist defined
`py310-lint` saw the command silently fall back to the base `[testenv]`
configuration, running the wrong environment without warning or error.
This became increasingly problematic with Python 3.10+ where dotted
version notation (py3.10, py3.11) is common, creating easy-to-miss typos
that produce confusing results.

Python version factors can be written with or without dots: `py3.10` vs
`py310`, `3.10` vs `310`. The validation logic treated dotted versions
as valid dynamic factors even when a normalized equivalent existed in
the config. 🔍 Since `py3.10` matched the Python version regex and `lint`
was a valid factor, `py3.10-lint` passed validation and created an
ad-hoc environment using `[testenv]` instead of the intended
`[testenv:py310-lint]`.

The fix normalizes environment names by removing dots from Python
version factors, then checks if the normalized name exists in known
environments. When found, tox errors with `py3.10-lint - did you mean
py310-lint?` instead of silently proceeding. ✨ If the normalized name
doesn't exist (e.g., `py3.15` when only `py310` and `py311` are
defined), the dotted version is allowed as an ad-hoc environment,
preserving the flexibility of tox's dynamic environment creation.

This catches typos while maintaining backward compatibility for
intentional ad-hoc environments.

Fixes #3877

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: gaborbernat

docs/changelog/3877.bugfix.rst

@@ -0,0 +1,3 @@
+Detect and suggest normalized environment names when users specify dotted Python versions (e.g., ``py3.10-lint``) that
+match existing environments with compact notation (e.g., ``py310-lint``), preventing silent fallback to base
+``[testenv]`` configuration - by :user:`gaborbernat`.

docs/how-to/usage.rst

@@ -276,6 +276,11 @@ For example, given:
 Running ``tox -e unt`` or ``tox -e unti`` would succeed without running any tests. An exception is made for environments
 that look like Python version specifiers -- ``tox -e 3.13`` or ``tox -e py313`` would still work as intended.
 
+Note that Python versions can be written with or without dots (``py3.10`` vs ``py310``). If you define ``py310-lint`` in
+your configuration and accidentally run ``tox -e py3.10-lint``, tox will detect the mismatch and suggest the correct
+environment name with a ``did you mean py310-lint?`` message rather than silently falling back to the base test
+environment.
+
 .. _platform-specification:
 
 **************************************

src/tox/session/env_select.py

@@ -294,6 +294,10 @@ def _ensure_envs_valid(self) -> None:
         for env in self._cli_envs or []:
             if env.startswith(".pkg_external") or env in known_envs:
                 continue
+            normalized_env = self._normalize_env_name(env)
+            if normalized_env != env and normalized_env in known_envs:
+                invalid_envs[env] = normalized_env
+                continue
             factors: dict[str, str | None] = dict.fromkeys(env.split("-"))
             found_factors: set[str] = set()
             for factor in factors:
@@ -314,16 +318,31 @@ def _ensure_envs_valid(self) -> None:
                     else "-".join(cast("Iterable[str]", factors.values()))
                 )
         if invalid_envs:
-            msg = "provided environments not found in configuration file:\n"
-            first = True
-            for env, suggestion in invalid_envs.items():
-                if not first:
-                    msg += "\n"
-                first = False
-                msg += env
-                if suggestion:
-                    msg += f" - did you mean {suggestion}?"
-            raise HandledError(msg)
+            self._raise_invalid_envs(invalid_envs)
+
+    @staticmethod
+    def _normalize_env_name(env_name: str) -> str:
+        factors = env_name.split("-")
+        normalized_factors = []
+        for factor in factors:
+            if _DYNAMIC_ENV_FACTORS.fullmatch(factor):
+                normalized_factors.append(factor.replace(".", ""))
+            else:
+                normalized_factors.append(factor)
+        return "-".join(normalized_factors)
+
+    @staticmethod
+    def _raise_invalid_envs(invalid_envs: dict[str, str | None]) -> None:
+        msg = "provided environments not found in configuration file:\n"
+        first = True
+        for env, suggestion in invalid_envs.items():
+            if not first:
+                msg += "\n"
+            first = False
+            msg += env
+            if suggestion:
+                msg += f" - did you mean {suggestion}?"
+        raise HandledError(msg)
 
     def _env_name_to_active(self) -> dict[str, bool]:
         env_name_to_active_map = {}

tests/session/test_env_select.py

@@ -487,3 +487,86 @@ def test_multiple_unavailable_runners_implicit(tox_project: ToxProjectCreator) -
     assert "available: OK" in outcome.out
     assert "unavailable1: NOT AVAILABLE" in outcome.out
     assert "unavailable2: NOT AVAILABLE" in outcome.out
+
+
+@pytest.mark.parametrize(
+    ("env_list", "env_sections", "cli_env", "expected_suggestion"),
+    [
+        pytest.param(
+            '["py310-lint", "py310-test", "py311-lint", "py311-test"]',
+            ['[tool.tox.env."py310-lint"]', '[tool.tox.env."py311-lint"]'],
+            "py3.10-lint",
+            "py310-lint",
+            id="dotted_py_version_with_factor",
+        ),
+        pytest.param(
+            '["py310", "py311"]',
+            ['[tool.tox.env."py310-cov"]', '[tool.tox.env."py311-cov"]'],
+            "py3.10-cov",
+            "py310-cov",
+            id="dotted_py_version_single",
+        ),
+        pytest.param(
+            '["310", "311"]',
+            ['[tool.tox.env."310-lint"]', '[tool.tox.env."311-lint"]'],
+            "3.10-lint",
+            "310-lint",
+            id="explicit_version_format",
+        ),
+    ],
+)
+def test_dotted_env_name_suggests_normalized(
+    tox_project: ToxProjectCreator, env_list: str, env_sections: list[str], cli_env: str, expected_suggestion: str
+) -> None:
+    sections_text = "\n    ".join(f'{sec}\n    commands = [["echo", "specialized"]]' for sec in env_sections)
+    toml = f"""
+    [tool.tox]
+    env_list = {env_list}
+
+    [tool.tox.env_run_base]
+    package = "skip"
+    commands = [["echo", "testenv"]]
+
+    {sections_text}
+    """
+    proj = tox_project({"pyproject.toml": toml})
+    outcome = proj.run("r", "-e", cli_env)
+    outcome.assert_failed(code=-2)
+    assert f"{cli_env} - did you mean {expected_suggestion}?" in outcome.out
+
+
+def test_dotted_env_no_normalized_match_allows_adhoc(tox_project: ToxProjectCreator) -> None:
+    toml = """
+    [tool.tox]
+    env_list = ["lint"]
+
+    [tool.tox.env_run_base]
+    package = "skip"
+    commands = [["python", "-c", "print('adhoc')"]]
+    """
+    proj = tox_project({"pyproject.toml": toml})
+    outcome = proj.run("r", "-e", f"py{sys.version_info[0]}.{sys.version_info[1]}-lint")
+    outcome.assert_success()
+    assert "adhoc" in outcome.out
+
+
+def test_dotted_env_multiple_suggestions(tox_project: ToxProjectCreator) -> None:
+    toml = """
+    [tool.tox]
+    env_list = ["py310-lint", "py311-cov"]
+
+    [tool.tox.env_run_base]
+    package = "skip"
+    commands = [["echo", "testenv"]]
+
+    [tool.tox.env."py310-lint"]
+    commands = [["echo", "lint"]]
+
+    [tool.tox.env."py311-cov"]
+    commands = [["echo", "coverage"]]
+    """
+    proj = tox_project({"pyproject.toml": toml})
+    outcome = proj.run("r", "-e", "py3.10-lint,py3.11-cov")
+    outcome.assert_failed(code=-2)
+    assert "py3.10-lint - did you mean py310-lint?" in outcome.out
+    assert "py3.11-cov - did you mean py311-cov?" in outcome.out