From 42a3d5e185a182035e7b5392b4824b5235292800 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 1 Dec 2025 15:48:35 +0000 Subject: [PATCH] autodoc: Deprecate mapping interface for options --- CHANGES.rst | 4 + doc/usage/extensions/autodoc.rst | 15 ++-- sphinx/ext/autodoc/_directive_options.py | 97 +++++++++++++++++++++++- 3 files changed, 106 insertions(+), 10 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 229fe99d999..7413557f61a 100644 --- a/CHANGES.rst +++ b/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) ===================================== diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 45bd8a6d5de..17445b19635 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/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``. diff --git a/sphinx/ext/autodoc/_directive_options.py b/sphinx/ext/autodoc/_directive_options.py index cfd505c25f9..7eeed79287c 100644 --- a/sphinx/ext/autodoc/_directive_options.py +++ b/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