prevent machine ISA from overriding explicit env factors (#3904)

- Machine ISA (e.g., arm64 from sysconfig.get_platform()) is no longer
unconditionally added as an implicit factor, preventing it from
conflicting with explicit ISA factors in the env name
- When the env name contains an explicit ISA (e.g., py39-x86_64), only
that ISA's factor conditions match — the machine's ISA is excluded
- When no env factor conflicts (e.g., env is just py39), the machine ISA
still works as an implicit factor
- Fix applied to both INI (filter_for_env) and TOML (_replace_if_toml)
config paths

<!-- Thank you for your contribution!

Please, make sure you address all the checklists (for details on how see
[development
documentation](http://tox.readthedocs.org/en/latest/development.html#development))!
-->

- [ ] ran the linter to address style issues (`tox -e fix`)
- [ ] wrote descriptive pull request text
- [ ] ensured there are test(s) validating the fix
- [ ] added news fragment in `docs/changelog` folder
- [ ] updated/extended the documentation

---------

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

Author: rahuldevikar

docs/changelog/3903.bugfix.rst

@@ -0,0 +1,2 @@
+Prevent implicit machine ISA (e.g. ``arm64``, ``x86_64``) from overriding explicit architecture factors in environment
+names, fixing cross-architecture conflicts in multiline factor conditionals - by :user:`rahuldevikar`.

pyproject.toml

@@ -56,6 +56,7 @@ dependencies = [
   "platformdirs>=4.9.4",
   "pluggy>=1.6",
   "pyproject-api>=1.10",
+  "python-discovery>=1.2.1",
   "tomli>=2.4; python_version<'3.11'",
   "tomli-w>=1.2",
   "typing-extensions>=4.15; python_version<'3.11'",

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

@@ -8,6 +8,8 @@
 from itertools import chain, groupby, product
 from typing import TYPE_CHECKING
 
+from python_discovery import KNOWN_ARCHITECTURES
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
@@ -16,13 +18,19 @@
 
 
 def filter_for_env(value: str, name: str | None) -> str:
-    current = (
+    env_factors = (
         set(chain.from_iterable([(i for i, _ in a) for a in find_factor_groups(name)])) if name is not None else set()
     )
+    current = set(env_factors)
     current.add(sys.platform)
     parts = sysconfig.get_platform().rsplit("-", 1)
     if len(parts) > 1:
-        current.add(parts[-1])
+        machine = parts[-1]
+        # Add machine ISA implicitly only when the env name does not already contain
+        # an architecture factor; when it does the explicit ISA takes precedence and
+        # adding the machine ISA would cause cross-architecture conflicts (#3903).
+        if not (env_factors & KNOWN_ARCHITECTURES):
+            current.add(machine)
     overall: list[str] = []
     active_continuation = False
     pending_skip = False

src/tox/config/loader/toml/_replace.py

@@ -10,6 +10,8 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
+from python_discovery import KNOWN_ARCHITECTURES
+
 from tox.config.loader.ini.factor import find_factor_groups
 from tox.config.loader.replacer import (
     MatchError,
@@ -42,18 +44,19 @@ def __init__(self, conf: Config | None, loader: TomlLoader, args: ConfigLoadArgs
         self.loader = loader
         self.args = args
         self.factors = self._extract_factors(args.env_name)
+        self.factors.add(sys.platform)
 
     @staticmethod
     def _extract_factors(env_name: str | None) -> set[str]:
-        """Extract factors from environment name and add platform."""
         if env_name is None:
-            factors = set()
+            factors: set[str] = set()
         else:
             factors = set(chain.from_iterable([(i for i, _ in a) for a in find_factor_groups(env_name)]))
-        factors.add(sys.platform)
         parts = sysconfig.get_platform().rsplit("-", 1)
         if len(parts) > 1:
-            factors.add(parts[-1])
+            machine = parts[-1]
+            if not (factors & KNOWN_ARCHITECTURES):
+                factors.add(machine)
         return factors
 
     def __call__(  # noqa: C901, PLR0912

tests/config/loader/ini/test_factor.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import sys
+import sysconfig
 from textwrap import dedent
 from typing import TYPE_CHECKING
 
@@ -511,3 +512,33 @@ def test_platform_factor(tox_ini_conf: ToxIniCreator) -> None:
         assert 'print("Windows")' in str(commands)
         assert 'print("Linux")' not in str(commands)
         assert 'print("Darwin")' not in str(commands)
+
+
+def test_machine_isa_does_not_override_explicit_env_factor() -> None:
+    """Regression test for #3903: explicit ISA in env name takes precedence over machine ISA."""
+    parts = sysconfig.get_platform().rsplit("-", 1)
+    if len(parts) < 2:
+        pytest.skip("sysconfig.get_platform() has no machine component")
+    machine = parts[-1]
+    other_isa = "x86_64" if machine != "x86_64" else "arm64"
+
+    value = f"{other_isa}: {other_isa}_value\n{machine}: {machine}_value"
+    # When the env name explicitly contains an ISA factor different from the machine,
+    # only the env factor's condition should match, not the machine ISA.
+    result = filter_for_env(value, name=f"py39-{other_isa}")
+    assert f"{other_isa}_value" in result
+    assert f"{machine}_value" not in result
+
+
+def test_machine_isa_implicit_when_no_env_isa() -> None:
+    """Machine ISA is added implicitly when no ISA factor is in the env name."""
+    parts = sysconfig.get_platform().rsplit("-", 1)
+    if len(parts) < 2:
+        pytest.skip("sysconfig.get_platform() has no machine component")
+    machine = parts[-1]
+
+    value = f"{machine}: {machine}_value\nother: other_value"
+    # No ISA in the env name, so machine ISA should be added implicitly.
+    result = filter_for_env(value, name="py39")
+    assert f"{machine}_value" in result
+    assert "other_value" not in result

tests/config/source/test_toml_pyproject.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import sys
+import sysconfig
 from textwrap import dedent
 from typing import TYPE_CHECKING
 
@@ -1070,3 +1071,50 @@ def test_config_in_toml_replace_ref_command(tox_project: ToxProjectCreator) -> N
     assert "python" in outcome.out
     assert "pip" in outcome.out
     assert "freeze" in outcome.out
+
+
+def test_toml_machine_isa_does_not_override_explicit_env_factor(tox_project: ToxProjectCreator) -> None:
+    """Regression test for #3903: explicit ISA in env name takes precedence over machine ISA in TOML."""
+    parts = sysconfig.get_platform().rsplit("-", 1)
+    if len(parts) < 2:
+        pytest.skip("sysconfig.get_platform() has no machine component")
+    machine = parts[-1]
+    other_isa = "x86_64" if machine != "x86_64" else "arm64"
+
+    project = tox_project({
+        "pyproject.toml": dedent(f"""
+        [tool.tox.env_run_base]
+        package = "skip"
+        description = {{ replace = "if", condition = "factor.{machine}", then = "{machine}_val", \
+else = {{ replace = "if", condition = "factor.{other_isa}", then = "{other_isa}_val", else = "unknown" }} }}
+
+        [tool.tox.env.py39-{other_isa}]
+        """),
+    })
+    # Env name contains other_isa, so only other_isa condition should match, not machine ISA.
+    outcome = project.run("c", "-e", f"py39-{other_isa}", "-k", "description")
+    outcome.assert_success()
+    assert f"{other_isa}_val" in outcome.out
+    assert f"{machine}_val" not in outcome.out
+
+
+def test_toml_machine_isa_implicit_when_no_env_isa(tox_project: ToxProjectCreator) -> None:
+    """Machine ISA is added implicitly to TOML factors when no ISA factor is in the env name."""
+    parts = sysconfig.get_platform().rsplit("-", 1)
+    if len(parts) < 2:
+        pytest.skip("sysconfig.get_platform() has no machine component")
+    machine = parts[-1]
+
+    project = tox_project({
+        "pyproject.toml": dedent(f"""
+        [tool.tox.env_run_base]
+        package = "skip"
+        description = {{ replace = "if", condition = "factor.{machine}", then = "matched", else = "no-match" }}
+
+        [tool.tox.env.py39]
+        """),
+    })
+    # No ISA in env name, so machine ISA should be added implicitly.
+    outcome = project.run("c", "-e", "py39", "-k", "description")
+    outcome.assert_success()
+    assert "matched" in outcome.out