Introduce a new type for documenter options (sphinx-doc#13783)

Author: AA-Turner

sphinx/ext/autodoc/_directive_options.py

@@ -8,9 +8,11 @@
 from sphinx.locale import __
 
 if TYPE_CHECKING:
-    from typing import Any
+    from collections.abc import Mapping, Set
+    from typing import Any, Literal, Self
 
-    from sphinx.ext.autodoc._documenters import Documenter
+    from sphinx.ext.autodoc._sentinels import ALL_T, EMPTY_T, SUPPRESS_T
+    from sphinx.util.typing import OptionSpec
 
 
 # common option names for autodoc directives
@@ -39,64 +41,123 @@
 })
 
 
+class _AutoDocumenterOptions:
+    # TODO: make immutable.
+
+    no_index: Literal[True] | None = None
+    no_index_entry: Literal[True] | None = None
+
+    # module-like options
+    members: ALL_T | list[str] | None = None
+    undoc_members: Literal[True] | None = None
+    inherited_members: Set[str] | None = None
+    show_inheritance: Literal[True] | None = None
+    synopsis: str | None = None
+    platform: str | None = None
+    deprecated: Literal[True] | None = None
+    member_order: Literal['alphabetical', 'bysource', 'groupwise'] | None = None
+    exclude_members: EMPTY_T | set[str] | None = None
+    private_members: ALL_T | list[str] | None = None
+    special_members: ALL_T | list[str] | None = None
+    imported_members: Literal[True] | None = None
+    ignore_module_all: Literal[True] | None = None
+    no_value: Literal[True] | None = None
+
+    # class-like options (class, exception)
+    class_doc_from: Literal['both', 'class', 'init'] | None = None
+
+    # assignment-like (data, attribute)
+    annotation: SUPPRESS_T | str | None = None
+
+    noindex: Literal[True] | None = None
+
+    def __init__(self, **kwargs: Any) -> None:
+        vars(self).update(kwargs)
+
+    def __repr__(self) -> str:
+        args = ', '.join(f'{k}={v!r}' for k, v in vars(self).items())
+        return f'_AutoDocumenterOptions({args})'
+
+    def __getattr__(self, name: str) -> object:
+        return None  # return None for missing attributes
+
+    def copy(self) -> Self:
+        return self.__class__(**vars(self))
+
+    @classmethod
+    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})
+
+    def merge_member_options(self) -> Self:
+        """Merge :private-members: and :special-members: into :members:"""
+        if self.members is ALL:
+            # merging is not needed when members: ALL
+            return self
+
+        members = self.members or []
+        for others in self.private_members, self.special_members:
+            if others is not None and others is not ALL:
+                members.extend(others)
+        new = self.copy()
+        new.members = list(dict.fromkeys(members))  # deduplicate; preserve order
+        return new
+
+
 def identity(x: Any) -> Any:
     return x
 
 
-def members_option(arg: Any) -> object | list[str]:
+def members_option(arg: str | None) -> ALL_T | list[str] | None:
     """Used to convert the :members: option to auto directives."""
-    if arg in {None, True}:
+    if arg is None or arg is True:
         return ALL
-    elif arg is False:
+    if arg is False:
         return None
-    else:
-        return [x.strip() for x in arg.split(',') if x.strip()]
+    return [stripped for x in arg.split(',') if (stripped := x.strip())]
 
 
-def exclude_members_option(arg: Any) -> object | set[str]:
+def exclude_members_option(arg: str | None) -> EMPTY_T | set[str]:
     """Used to convert the :exclude-members: option."""
-    if arg in {None, True}:
+    if arg is None or arg is True:
         return EMPTY
-    return {x.strip() for x in arg.split(',') if x.strip()}
+    return {stripped for x in arg.split(',') if (stripped := x.strip())}
 
 
-def inherited_members_option(arg: Any) -> set[str]:
+def inherited_members_option(arg: str | None) -> set[str]:
     """Used to convert the :inherited-members: option to auto directives."""
-    if arg in {None, True}:
+    if arg is None or arg is True:
         return {'object'}
-    elif arg:
+    if arg:
         return {x.strip() for x in arg.split(',')}
-    else:
-        return set()
+    return set()
 
 
-def member_order_option(arg: Any) -> str | None:
+def member_order_option(
+    arg: str | None,
+) -> Literal['alphabetical', 'bysource', 'groupwise'] | None:
     """Used to convert the :member-order: option to auto directives."""
-    if arg in {None, True}:
+    if arg is None or arg is True:
         return None
-    elif arg in {'alphabetical', 'bysource', 'groupwise'}:
-        return arg
-    else:
-        raise ValueError(__('invalid value for member-order option: %s') % arg)
+    if arg in {'alphabetical', 'bysource', 'groupwise'}:
+        return arg  # type: ignore[return-value]
+    raise ValueError(__('invalid value for member-order option: %s') % arg)
 
 
-def class_doc_from_option(arg: Any) -> str | None:
+def class_doc_from_option(arg: str | None) -> Literal['both', 'class', 'init']:
     """Used to convert the :class-doc-from: option to autoclass directives."""
     if arg in {'both', 'class', 'init'}:
-        return arg
-    else:
-        raise ValueError(__('invalid value for class-doc-from option: %s') % arg)
+        return arg  # type: ignore[return-value]
+    raise ValueError(__('invalid value for class-doc-from option: %s') % arg)
 
 
-def annotation_option(arg: Any) -> Any:
-    if arg in {None, True}:
+def annotation_option(arg: str | None) -> SUPPRESS_T | str | Literal[False]:
+    if arg is None or arg is True:
         # suppress showing the representation of the object
         return SUPPRESS
-    else:
-        return arg
+    return arg
 
 
-def bool_option(arg: Any) -> bool:
+def bool_option(arg: str | None) -> bool:
     """Used to convert flag options to auto directives.  (Instead of
     directives.flag(), which returns None).
     """
@@ -137,14 +198,14 @@ def __getattr__(self, name: str) -> Any:
 
 
 def _process_documenter_options(
-    documenter: type[Documenter],
     *,
+    option_spec: OptionSpec,
     default_options: dict[str, str | bool],
-    options: dict[str, str],
-) -> Options:
+    options: dict[str, str | None],
+) -> dict[str, object]:
     """Recognize options of Documenter from user input."""
     for name in AUTODOC_DEFAULT_OPTIONS:
-        if name not in documenter.option_spec:
+        if name not in option_spec:
             continue
 
         negated = options.pop(f'no-{name}', True) is None
@@ -153,13 +214,13 @@ def _process_documenter_options(
                 # take value from options if present or extend it
                 # with autodoc_default_options if necessary
                 if name in AUTODOC_EXTENDABLE_OPTIONS:
-                    if options[name] is not None and options[name].startswith('+'):
-                        options[name] = f'{default_options[name]},{options[name][1:]}'
+                    opt_value = options[name]
+                    if opt_value is not None and opt_value.startswith('+'):
+                        options[name] = f'{default_options[name]},{opt_value[1:]}'
             else:
                 options[name] = default_options[name]  # type: ignore[assignment]
-        elif options.get(name) is not None:
+        elif (opt_value := options.get(name)) is not None:
             # remove '+' from option argument if there's nothing to merge it with
-            options[name] = options[name].removeprefix('+')
+            options[name] = opt_value.removeprefix('+')
 
-    opts = assemble_option_dict(options.items(), documenter.option_spec)
-    return Options(opts)
+    return assemble_option_dict(options.items(), option_spec)  # type: ignore[arg-type]

sphinx/ext/autodoc/_documenters.py

@@ -19,7 +19,6 @@
     inherited_members_option,
     member_order_option,
     members_option,
-    merge_members_option,
 )
 from sphinx.ext.autodoc._sentinels import (
     ALL,
@@ -62,6 +61,7 @@
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment, _CurrentDocument
     from sphinx.events import EventManager
+    from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
     from sphinx.ext.autodoc.directive import DocumenterBridge
     from sphinx.registry import SphinxComponentRegistry
     from sphinx.util.typing import OptionSpec, _RestifyMode
@@ -198,7 +198,7 @@ def __init__(
         self.env: BuildEnvironment = directive.env
         self._current_document: _CurrentDocument = directive.env.current_document
         self._events: EventManager = directive.env.events
-        self.options = directive.genopt
+        self.options: _AutoDocumenterOptions = directive.genopt
         self.name = name
         self.indent = indent
         # the module and object path within the module, and the fully
@@ -794,7 +794,7 @@ def is_filtered_inherited_member(name: str, obj: Any) -> bool:
                         elif is_filtered_inherited_member(membername, obj):
                             keep = False
                         else:
-                            keep = has_doc or self.options.undoc_members
+                            keep = has_doc or self.options.undoc_members  # type: ignore[assignment]
                     else:
                         keep = False
                 elif (namespace, membername) in attr_docs:
@@ -823,7 +823,7 @@ def is_filtered_inherited_member(name: str, obj: Any) -> bool:
                         keep = False
                     else:
                         # ignore undocumented members if :undoc-members: is not given
-                        keep = has_doc or self.options.undoc_members
+                        keep = has_doc or self.options.undoc_members  # type: ignore[assignment]
 
                 if isinstance(obj, ObjectMember) and obj.skipped:
                     # forcedly skipped member (ex. a module attribute not defined in __all__)
@@ -873,7 +873,7 @@ def document_members(self, all_members: bool = False) -> None:
         if self.objpath:
             self._current_document.autodoc_class = self.objpath[0]
 
-        want_all = (
+        want_all = bool(
             all_members or self.options.inherited_members or self.options.members is ALL
         )
         # find out which members are documentable
@@ -1101,7 +1101,7 @@ class ModuleDocumenter(Documenter):
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
-        merge_members_option(self.options)
+        self.options = self.options.merge_member_options()
         self.__all__: Sequence[str] | None = None
 
     def add_content(self, more_content: StringList | None) -> None:
@@ -1210,6 +1210,7 @@ def get_object_members(self, want_all: bool) -> tuple[bool, list[ObjectMember]]:
 
                 return False, list(members.values())
         else:
+            assert self.options.members is not ALL
             memberlist = self.options.members or []
             ret = []
             for name in memberlist:
@@ -1469,12 +1470,12 @@ def __init__(self, *args: Any) -> None:
 
             # show __init__() method
             if self.options.special_members is None:
-                self.options['special-members'] = ['__new__', '__init__']
+                self.options.special_members = ['__new__', '__init__']
             else:
                 self.options.special_members.append('__new__')
                 self.options.special_members.append('__init__')
 
-        merge_members_option(self.options)
+        self.options = self.options.merge_member_options()
 
     @classmethod
     def can_document_member(
@@ -1769,6 +1770,7 @@ def get_object_members(self, want_all: bool) -> tuple[bool, list[ObjectMember]]:
                 return False, []
             # specific members given
             selected = []
+            assert self.options.members is not ALL
             for name in self.options.members:
                 if name in members:
                     selected.append(members[name])
@@ -1800,9 +1802,10 @@ def get_doc(self) -> list[list[str]] | None:
         if lines is not None:
             return lines
 
-        classdoc_from = self.options.get(
-            'class-doc-from', self.config.autoclass_content
-        )
+        if self.options.class_doc_from is not None:
+            classdoc_from = self.options.class_doc_from
+        else:
+            classdoc_from = self.config.autoclass_content
 
         docstrings = []
         attrdocstring = getdoc(self.object, self.get_attr)

sphinx/ext/autodoc/_sentinels.py

@@ -2,7 +2,7 @@
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import NoReturn, Self, _SpecialForm
+    from typing import Final, Literal, NoReturn, Self, TypeAlias, _SpecialForm
 
 
 class _Sentinel:
@@ -42,7 +42,7 @@ def __getstate__(self) -> NoReturn:
 class _All(_Sentinel):
     """A special value for :*-members: that matches to any member."""
 
-    def __contains__(self, item: object) -> bool:
+    def __contains__(self, item: object) -> Literal[True]:
         return True
 
     def append(self, item: object) -> None:
@@ -52,20 +52,49 @@ def append(self, item: object) -> None:
 class _Empty(_Sentinel):
     """A special value for :exclude-members: that never matches to any member."""
 
-    def __contains__(self, item: object) -> bool:
+    def __contains__(self, item: object) -> Literal[False]:
         return False
 
 
 if TYPE_CHECKING:
     # For the sole purpose of satisfying the type checker.
     # fmt: off
-    class ALL: ...
-    class EMPTY: ...
-    class INSTANCE_ATTR: ...
-    class RUNTIME_INSTANCE_ATTRIBUTE: ...
-    class SLOTS_ATTR: ...
-    class SUPPRESS: ...
-    class UNINITIALIZED_ATTR: ...
+    import enum
+    class _AllTC(enum.Enum):
+        ALL = enum.auto()
+
+        def __contains__(self, item: object) -> Literal[True]: return True
+        def append(self, item: object) -> None: pass
+    ALL_T: TypeAlias = Literal[_AllTC.ALL]
+    ALL: Final[ALL_T] = _AllTC.ALL
+
+    class _EmptyTC(enum.Enum):
+        EMPTY = enum.auto()
+
+        def __contains__(self, item: object) -> Literal[False]: return False
+    EMPTY_T: TypeAlias = Literal[_EmptyTC.EMPTY]
+    EMPTY: Final[EMPTY_T] = _EmptyTC.EMPTY
+
+    class _SentinelTC(enum.Enum):
+        INSTANCE_ATTR = enum.auto()
+        RUNTIME_INSTANCE_ATTRIBUTE = enum.auto()
+        SLOTS_ATTR = enum.auto()
+        SUPPRESS = enum.auto()
+        UNINITIALIZED_ATTR = enum.auto()
+    INSTANCE_ATTR_T: TypeAlias = Literal[_SentinelTC.INSTANCE_ATTR]
+    RUNTIME_INSTANCE_ATTRIBUTE_T: TypeAlias = Literal[
+        _SentinelTC.RUNTIME_INSTANCE_ATTRIBUTE
+    ]
+    SLOTS_ATTR_T: TypeAlias = Literal[_SentinelTC.SLOTS_ATTR]
+    SUPPRESS_T: TypeAlias = Literal[_SentinelTC.SUPPRESS]
+    UNINITIALIZED_ATTR_T: TypeAlias = Literal[_SentinelTC.UNINITIALIZED_ATTR]
+    INSTANCE_ATTR: Final[INSTANCE_ATTR_T] = _SentinelTC.INSTANCE_ATTR
+    RUNTIME_INSTANCE_ATTRIBUTE: Final[RUNTIME_INSTANCE_ATTRIBUTE_T] = (
+        _SentinelTC.RUNTIME_INSTANCE_ATTRIBUTE
+    )
+    SLOTS_ATTR: Final[SLOTS_ATTR_T] = _SentinelTC.SLOTS_ATTR
+    SUPPRESS: Final[SUPPRESS_T] = _SentinelTC.SUPPRESS
+    UNINITIALIZED_ATTR: Final[UNINITIALIZED_ATTR_T] = _SentinelTC.UNINITIALIZED_ATTR
     # fmt: on
 else:
     ALL = _All('ALL')