autodoc: Deprecate mapping interface for options (#14140)

Author: AA-Turner

CHANGES.rst

@@ -4,6 +4,10 @@ Release 9.0.1 (in development)
 Bugs fixed
 ----------
 
+* #13942: autodoc: Restore the mapping interface for options objects.
+  Patch by Adam Turner.
+* #13942: autodoc: Deprecate the mapping interface for options objects.
+  Patch by Adam Turner.
 
 Release 9.0.0 (released Nov 30, 2025)
 =====================================

doc/usage/extensions/autodoc.rst

@@ -1393,9 +1393,8 @@ autodoc provides the following additional events:
    :param name: the fully qualified name of the object
    :param obj: the object itself
    :param options: the options given to the directive: an object with attributes
-      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
-      ``no-index`` that are true if the flag option of same name was given to the
-      auto directive
+      corresponding to the options used in the auto directive, e.g.
+      ``inherited_members``, ``undoc_members``, or ``show_inheritance``.
    :param lines: the lines of the docstring, see above
 
 .. event:: autodoc-before-process-signature (app, obj, bound_method)
@@ -1424,9 +1423,8 @@ autodoc provides the following additional events:
    :param name: the fully qualified name of the object
    :param obj: the object itself
    :param options: the options given to the directive: an object with attributes
-      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
-      ``no-index`` that are true if the flag option of same name was given to the
-      auto directive
+      corresponding to the options used in the auto directive, e.g.
+      ``inherited_members``, ``undoc_members``, or ``show_inheritance``.
    :param signature: function signature, as a string of the form
       ``'(parameter_1, parameter_2)'``, or ``None`` if introspection didn't
       succeed and signature wasn't specified in the directive.
@@ -1487,6 +1485,5 @@ member should be included in the documentation by using the following event:
    :param skip: a boolean indicating if autodoc will skip this member if the
       user handler does not override the decision
    :param options: the options given to the directive: an object with attributes
-      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
-      ``no-index`` that are true if the flag option of same name was given to the
-      auto directive
+      corresponding to the options used in the auto directive, e.g.
+      ``inherited_members``, ``undoc_members``, or ``show_inheritance``.

sphinx/ext/autodoc/_directive_options.py

@@ -1,14 +1,16 @@
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING
 
 from docutils.utils import assemble_option_dict
 
+from sphinx.deprecation import RemovedInSphinx11Warning
 from sphinx.ext.autodoc._sentinels import ALL, EMPTY, SUPPRESS
 from sphinx.locale import __
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping, Set
+    from collections.abc import Iterable, Iterator, Mapping, Set
     from typing import Any, Final, Literal, Self
 
     from sphinx.ext.autodoc._property_types import _AutodocObjType
@@ -90,6 +92,99 @@ def copy(self) -> Self:
     def from_directive_options(cls, opts: Mapping[str, Any], /) -> Self:
         return cls(**{k.replace('-', '_'): v for k, v in opts.items() if v is not None})
 
+    # Mapping interface:
+
+    def __getitem__(self, item: str) -> Any:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        try:
+            return getattr(self, item)
+        except AttributeError:
+            raise KeyError(item) from None
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        msg = f'{self.__class__.__name__!r} object does not support indexed assignment'
+        raise TypeError(msg)
+
+    def __delitem__(self, key: str) -> None:
+        msg = f'{self.__class__.__name__!r} object does not support indexed deletion'
+        raise TypeError(msg)
+
+    def __contains__(self, item: str) -> bool:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        return hasattr(self, item)
+
+    def __keys(self) -> list[str]:
+        return [key for key in dir(self) if not key.startswith('_')]
+
+    def __iter__(self) -> Iterator[str]:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        yield from self.__keys()
+
+    def __len__(self) -> int:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        return len(self.__keys())
+
+    def keys(self) -> Iterable[str]:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        yield from self.__keys()
+
+    def items(self) -> Iterable[tuple[str, Any]]:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        for key in self.__keys():
+            yield key, getattr(self, key)
+
+    def values(self) -> Iterable[Any]:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        for key in self.__keys():
+            yield getattr(self, key)
+
+    def get(self, key: str, default: Any | None = None) -> Any | None:
+        warnings.warn(
+            'The mapping interface for autodoc options objects is deprecated, '
+            'and will be removed in Sphinx 11. Use attribute access instead.',
+            RemovedInSphinx11Warning,
+            stacklevel=2,
+        )
+        try:
+            return getattr(self, key)
+        except AttributeError:
+            return default
+
 
 def identity(x: Any) -> Any:
     return x