config: add support for ini option aliases

Fix #13829.

Author: bluetech

changelog/13829.feature.rst

@@ -0,0 +1,5 @@
+Added support for ini option aliases via the ``aliases`` parameter in :meth:`Parser.addini() <pytest.Parser.addini>`.
+
+Plugins can now register alternative names for ini options,
+allowing for more flexibility in configuration naming and supporting backward compatibility when renaming options.
+The canonical name always takes precedence if both the canonical name and an alias are specified in the configuration file.

src/_pytest/config/__init__.py

@@ -1519,9 +1519,9 @@ def _warn_or_fail_if_strict(self, message: str) -> None:
 
         self.issue_config_time_warning(PytestConfigWarning(message), stacklevel=3)
 
-    def _get_unknown_ini_keys(self) -> list[str]:
-        parser_inicfg = self._parser._inidict
-        return [name for name in self.inicfg if name not in parser_inicfg]
+    def _get_unknown_ini_keys(self) -> set[str]:
+        known_keys = self._parser._inidict.keys() | self._parser._ini_aliases.keys()
+        return self.inicfg.keys() - known_keys
 
     def parse(self, args: list[str], addopts: bool = True) -> None:
         # Parse given cmdline arguments into this config object.
@@ -1621,10 +1621,11 @@ def getini(self, name: str) -> Any:
         :func:`parser.addini <pytest.Parser.addini>` call (usually from a
         plugin), a ValueError is raised.
         """
+        canonical_name = self._parser._ini_aliases.get(name, name)
         try:
-            return self._inicache[name]
+            return self._inicache[canonical_name]
         except KeyError:
-            self._inicache[name] = val = self._getini(name)
+            self._inicache[canonical_name] = val = self._getini(canonical_name)
             return val
 
     # Meant for easy monkeypatching by legacypath plugin.
@@ -1636,14 +1637,29 @@ def _getini_unknown_type(self, name: str, type: str, value: object):
         raise ValueError(msg)  # pragma: no cover
 
     def _getini(self, name: str):
+        # If this is an alias, resolve to canonical name.
+        canonical_name = self._parser._ini_aliases.get(name, name)
+
         try:
-            _description, type, default = self._parser._inidict[name]
+            _description, type, default = self._parser._inidict[canonical_name]
         except KeyError as e:
             raise ValueError(f"unknown configuration value: {name!r}") from e
-        try:
-            value = self.inicfg[name]
-        except KeyError:
+
+        # Try to get value from inicfg, checking canonical name first, then aliases.
+        # Canonical name takes precedence over any aliases.
+        value = None
+        if canonical_name in self.inicfg:
+            value = self.inicfg[canonical_name]
+        else:
+            # Check if any alias for this canonical name exists in inicfg.
+            for alias, target in self._parser._ini_aliases.items():
+                if target == canonical_name and alias in self.inicfg:
+                    value = self.inicfg[alias]
+                    break
+
+        if value is None:
             return default
+
         # Coerce the values based on types.
         #
         # Note: some coercions are only required if we are reading from .ini files, because

src/_pytest/config/argparsing.py

@@ -52,6 +52,8 @@ def __init__(
         self._usage = usage
         self._inidict: dict[str, tuple[str, str | None, Any]] = {}
         self._ininames: list[str] = []
+        # Maps alias -> canonical name.
+        self._ini_aliases: dict[str, str] = {}
         self.extra_info: dict[str, Any] = {}
 
     def processoption(self, option: Argument) -> None:
@@ -179,6 +181,8 @@ def addini(
         ]
         | None = None,
         default: Any = NOT_SET,
+        *,
+        aliases: Sequence[str] = (),
     ) -> None:
         """Register an ini-file option.
 
@@ -213,6 +217,12 @@ def addini(
             Defaults to ``string`` if ``None`` or not passed.
         :param default:
             Default value if no ini-file option exists but is queried.
+        :param aliases:
+            Additional names by which this option can be referenced.
+            Aliases resolve to the canonical name.
+
+            .. versionadded:: 9.0
+                The ``aliases`` parameter.
 
         The value of ini-variables can be retrieved via a call to
         :py:func:`config.getini(name) <pytest.Config.getini>`.
@@ -234,6 +244,13 @@ def addini(
         self._inidict[name] = (help, type, default)
         self._ininames.append(name)
 
+        for alias in aliases:
+            if alias in self._inidict:
+                raise ValueError(f"alias {alias!r} conflicts with existing ini option")
+            if (already := self._ini_aliases.get(alias)) is not None:
+                raise ValueError(f"{alias!r} is already an alias of {already!r}")
+            self._ini_aliases[alias] = name
+
 
 def get_ini_default_for_type(
     type: Literal[

testing/test_config.py

@@ -1005,6 +1005,143 @@ def pytest_addoption(parser):
         value = config.getini("no_type")
         assert value == ""
 
+    def test_addini_with_aliases(self, pytester: Pytester) -> None:
+        """Test that ini options can have aliases."""
+        pytester.makeconftest(
+            """
+            def pytest_addoption(parser):
+                parser.addini("new_name", "my option", aliases=["old_name"])
+            """
+        )
+        pytester.makeini(
+            """
+            [pytest]
+            old_name = hello
+            """
+        )
+        config = pytester.parseconfig()
+        # Should be able to access via canonical name.
+        assert config.getini("new_name") == "hello"
+        # Should also be able to access via alias.
+        assert config.getini("old_name") == "hello"
+
+    def test_addini_aliases_with_canonical_in_file(self, pytester: Pytester) -> None:
+        """Test that canonical name takes precedence over alias in ini file."""
+        pytester.makeconftest(
+            """
+            def pytest_addoption(parser):
+                parser.addini("new_name", "my option", aliases=["old_name"])
+            """
+        )
+        pytester.makeini(
+            """
+            [pytest]
+            old_name = from_alias
+            new_name = from_canonical
+            """
+        )
+        config = pytester.parseconfig()
+        # Canonical name should take precedence.
+        assert config.getini("new_name") == "from_canonical"
+        assert config.getini("old_name") == "from_canonical"
+
+    def test_addini_aliases_multiple(self, pytester: Pytester) -> None:
+        """Test that ini option can have multiple aliases."""
+        pytester.makeconftest(
+            """
+            def pytest_addoption(parser):
+                parser.addini("current_name", "my option", aliases=["old_name", "legacy_name"])
+            """
+        )
+        pytester.makeini(
+            """
+            [pytest]
+            old_name = value1
+            """
+        )
+        config = pytester.parseconfig()
+        assert config.getini("current_name") == "value1"
+        assert config.getini("old_name") == "value1"
+        assert config.getini("legacy_name") == "value1"
+
+    def test_addini_aliases_with_override(self, pytester: Pytester) -> None:
+        """Test that aliases work with --override-ini."""
+        pytester.makeconftest(
+            """
+            def pytest_addoption(parser):
+                parser.addini("new_name", "my option", aliases=["old_name"])
+            """
+        )
+        pytester.makeini(
+            """
+            [pytest]
+            old_name = from_file
+            """
+        )
+        # Override using alias.
+        config = pytester.parseconfig("-o", "old_name=overridden")
+        assert config.getini("new_name") == "overridden"
+        assert config.getini("old_name") == "overridden"
+
+        # Override using canonical name.
+        config = pytester.parseconfig("-o", "new_name=overridden2")
+        assert config.getini("new_name") == "overridden2"
+
+    def test_addini_aliases_with_types(self, pytester: Pytester) -> None:
+        """Test that aliases work with different types."""
+        pytester.makeconftest(
+            """
+            def pytest_addoption(parser):
+                parser.addini("mylist", "list option", type="linelist", aliases=["oldlist"])
+                parser.addini("mybool", "bool option", type="bool", aliases=["oldbool"])
+            """
+        )
+        pytester.makeini(
+            """
+            [pytest]
+            oldlist = line1
+                line2
+            oldbool = true
+        """
+        )
+        config = pytester.parseconfig()
+        assert config.getini("mylist") == ["line1", "line2"]
+        assert config.getini("oldlist") == ["line1", "line2"]
+        assert config.getini("mybool") is True
+        assert config.getini("oldbool") is True
+
+    def test_addini_aliases_conflict_error(self, pytester: Pytester) -> None:
+        """Test that registering an alias that conflicts with an existing option raises an error."""
+        pytester.makeconftest(
+            """
+            def pytest_addoption(parser):
+                parser.addini("existing", "first option")
+
+                try:
+                    parser.addini("new_option", "second option", aliases=["existing"])
+                except ValueError as e:
+                    assert "alias 'existing' conflicts with existing ini option" in str(e)
+                else:
+                    assert False, "Should have raised ValueError"
+            """
+        )
+        pytester.parseconfig()
+
+    def test_addini_aliases_duplicate_error(self, pytester: Pytester) -> None:
+        """Test that registering the same alias twice raises an error."""
+        pytester.makeconftest(
+            """
+            def pytest_addoption(parser):
+                parser.addini("option1", "first option", aliases=["shared_alias"])
+                try:
+                    parser.addini("option2", "second option", aliases=["shared_alias"])
+                    raise AssertionError("Should have raised ValueError")
+                except ValueError as e:
+                    assert "'shared_alias' is already an alias of 'option1'" in str(e)
+            """
+        )
+        pytester.parseconfig()
+
     @pytest.mark.parametrize(
         "type, expected",
         [