config: deprecate config.inicfg

As a private attribute, we broke it in pytest 9.0.0, but since it's not
using a `_` prefix and has some external usage, let's keep it working
until pytest 10 and deprecate it instead.

Fix #13946.

Author: bluetech

changelog/13946.deprecation.rst

@@ -0,0 +1,4 @@
+The private ``config.inicfg`` attribute is now deprecated.
+Use :meth:`config.getini() <pytest.Config.getini>` to access configuration values instead.
+
+See :ref:`config-inicfg` for more details.

doc/en/deprecations.rst

@@ -15,6 +15,43 @@ Below is a complete list of all pytest features which are considered deprecated.
 :class:`~pytest.PytestWarning` or subclasses, which can be filtered using :ref:`standard warning filters <warnings>`.
 
 
+.. _config-inicfg:
+
+``config.inicfg``
+~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 9.0
+
+The private ``config.inicfg`` attribute is deprecated.
+Use :meth:`config.getini() <pytest.Config.getini>` to access configuration values instead.
+
+``config.inicfg`` was never documented and it should have had a ``_`` prefix from the start.
+Pytest performs caching, transformation and aliasing on configuration options which make direct access to the raw ``config.inicfg`` untenable.
+
+**Reading configuration values:**
+
+Instead of accessing ``config.inicfg`` directly, use :meth:`config.getini() <pytest.Config.getini>`:
+
+.. code-block:: python
+
+    # Deprecated
+    value = config.inicfg["some_option"]
+
+    # Use this instead
+    value = config.getini("some_option")
+
+**Setting configuration values:**
+
+Setting or deleting configuration values after initialization is not supported.
+If you need to override configuration values, use the ``-o`` command line option:
+
+.. code-block:: bash
+
+    pytest -o some_option=value
+
+or set them in your configuration file instead.
+
+
 .. _parametrize-iterators:
 
 Non-Collection iterables in ``@pytest.mark.parametrize``

src/_pytest/config/__init__.py

@@ -59,6 +59,7 @@
 from _pytest._code.code import TracebackStyle
 from _pytest._io import TerminalWriter
 from _pytest.compat import assert_never
+from _pytest.compat import deprecated
 from _pytest.compat import NOTSET
 from _pytest.config.argparsing import Argument
 from _pytest.config.argparsing import FILE_OR_DIR
@@ -1126,9 +1127,23 @@ def __init__(
         self.args_source = Config.ArgsSource.ARGS
         self.args: list[str] = []
 
-    @property
-    def inicfg(self) -> _DeprecatedInicfgProxy:
-        return _DeprecatedInicfgProxy(self)
+    if TYPE_CHECKING:
+
+        @deprecated(
+            "config.inicfg is deprecated, use config.getini() to access configuration values instead.",
+        )
+        @property
+        def inicfg(self) -> _DeprecatedInicfgProxy:
+            raise NotImplementedError()
+    else:
+
+        @property
+        def inicfg(self) -> _DeprecatedInicfgProxy:
+            warnings.warn(
+                _pytest.deprecated.CONFIG_INICFG,
+                stacklevel=2,
+            )
+            return _DeprecatedInicfgProxy(self)
 
     @property
     def rootpath(self) -> pathlib.Path:

src/_pytest/deprecated.py

@@ -83,6 +83,11 @@
     "See https://docs.pytest.org/en/stable/deprecations.html#parametrize-iterators",
 )
 
+CONFIG_INICFG = PytestRemovedIn10Warning(
+    "config.inicfg is deprecated, use config.getini() to access configuration values instead.\n"
+    "See https://docs.pytest.org/en/stable/deprecations.html#config-inicfg"
+)
+
 # You want to make some `__init__` or function "private".
 #
 #   def my_private_function(some, args):

testing/test_config.py

@@ -30,6 +30,7 @@
 from _pytest.monkeypatch import MonkeyPatch
 from _pytest.pathlib import absolutepath
 from _pytest.pytester import Pytester
+from _pytest.warning_types import PytestDeprecationWarning
 import pytest
 
 
@@ -3001,10 +3002,10 @@ def pytest_addoption(parser):
 
 
 class TestInicfgDeprecation:
-    """Tests for the upcoming deprecation of config.inicfg."""
+    """Tests for the deprecation of config.inicfg."""
 
     def test_inicfg_deprecated(self, pytester: Pytester) -> None:
-        """Test that accessing config.inicfg issues a deprecation warning (not yet)."""
+        """Test that accessing config.inicfg issues a deprecation warning."""
         pytester.makeini(
             """
             [pytest]
@@ -3013,7 +3014,10 @@ def test_inicfg_deprecated(self, pytester: Pytester) -> None:
         )
         config = pytester.parseconfig()
 
-        inicfg = config.inicfg
+        with pytest.warns(
+            PytestDeprecationWarning, match=r"config\.inicfg is deprecated"
+        ):
+            inicfg = config.inicfg  # type: ignore[deprecated]
 
         assert config.getini("minversion") == "3.0"
         assert inicfg["minversion"] == "3.0"