Add a shared utilities module for autodoc

sphinx/ext/autodoc/_docstrings.py

@@ -25,8 +25,8 @@
 
     from sphinx.events import EventManager
     from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
-    from sphinx.ext.autodoc._importer import _AttrGetter
     from sphinx.ext.autodoc._property_types import _ItemProperties
+    from sphinx.ext.autodoc._shared import _AttrGetter
 
 logger = logging.getLogger('sphinx.ext.autodoc')
 

sphinx/ext/autodoc/_generate.py

@@ -9,6 +9,7 @@
 from sphinx.ext.autodoc._member_finder import _gather_members
 from sphinx.ext.autodoc._renderer import _add_content, _directive_header_lines
 from sphinx.ext.autodoc._sentinels import ALL
+from sphinx.ext.autodoc._shared import _get_render_mode
 from sphinx.ext.autodoc.mock import ismock
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
@@ -17,14 +18,12 @@
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Mapping, MutableSet
-    from typing import Literal
 
-    from sphinx.config import Config
     from sphinx.environment import _CurrentDocument
     from sphinx.events import EventManager
     from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
-    from sphinx.ext.autodoc._importer import _AttrGetter
     from sphinx.ext.autodoc._property_types import _ItemProperties
+    from sphinx.ext.autodoc._shared import _AttrGetter, _AutodocConfig
     from sphinx.util.typing import _RestifyMode
 
 logger = logging.getLogger('sphinx.ext.autodoc')
@@ -36,7 +35,7 @@ def _generate_directives(
     check_module: bool = False,
     all_members: bool = False,
     *,
-    config: Config,
+    config: _AutodocConfig,
     current_document: _CurrentDocument,
     events: EventManager,
     get_attr: _AttrGetter,
@@ -154,7 +153,7 @@ def _add_directive_lines(
     *,
     more_content: StringList | None,
     is_final: bool,
-    config: Config,
+    config: _AutodocConfig,
     indent: str,
     options: _AutoDocumenterOptions,
     props: _ItemProperties,
@@ -180,8 +179,8 @@ def _add_directive_lines(
 
     # add alias information, if applicable
     lines = _body_alias_lines(
-        typehints_format=config.autodoc_typehints_format,
-        python_display_short_literal_types=config.python_display_short_literal_types,
+        render_mode=_get_render_mode(config.autodoc_typehints_format),
+        short_literals=config.python_display_short_literal_types,
         props=props,
     )
     alias_lines = StringList(list(lines), source='')
@@ -204,7 +203,7 @@ def _document_members(
     all_members: bool,
     analyzer_order: dict[str, int],
     attr_docs: dict[tuple[str, str], list[str]],
-    config: Config,
+    config: _AutodocConfig,
     current_document: _CurrentDocument,
     events: EventManager,
     get_attr: _AttrGetter,
@@ -276,22 +275,17 @@ def _document_members(
 
 
 def _body_alias_lines(
-    *,
-    props: _ItemProperties,
-    typehints_format: Literal['fully-qualified', 'short'],
-    python_display_short_literal_types: bool,
+    *, props: _ItemProperties, render_mode: _RestifyMode, short_literals: bool
 ) -> Iterator[str]:
     """Add content from docstrings, attribute documentation and user."""
     if props.obj_type in {'data', 'attribute'}:
         from sphinx.ext.autodoc._property_types import _AssignStatementProperties
 
         assert isinstance(props, _AssignStatementProperties)
 
-        mode = _get_render_mode(typehints_format)
-
         # Support for documenting GenericAliases
         if props._obj_is_generic_alias:
-            alias = restify(props._obj, mode=mode)
+            alias = restify(props._obj, mode=render_mode)
             yield _('alias of %s') % alias
             yield ''
             return
@@ -303,27 +297,25 @@ def _body_alias_lines(
         assert isinstance(props, _ClassDefProperties)
 
         obj = props._obj
-        mode = _get_render_mode(typehints_format)
 
         if props._obj_is_new_type:
-            supertype = restify(obj.__supertype__, mode=mode)
+            supertype = restify(obj.__supertype__, mode=render_mode)
             yield _('alias of %s') % supertype
             yield ''
             return
 
         if props._obj_is_typevar:
-            short_literals = python_display_short_literal_types
             attrs = [
                 repr(obj.__name__),
                 *(
                     stringify_annotation(
-                        constraint, mode, short_literals=short_literals
+                        constraint, render_mode, short_literals=short_literals
                     )
                     for constraint in obj.__constraints__
                 ),
             ]
             if obj.__bound__:
-                attrs.append(rf'bound=\ {restify(obj.__bound__, mode=mode)}')
+                attrs.append(rf'bound=\ {restify(obj.__bound__, mode=render_mode)}')
             if obj.__covariant__:
                 attrs.append('covariant=True')
             if obj.__contravariant__:
@@ -345,7 +337,7 @@ def _body_alias_lines(
 
             if class_var_doc_comment:
                 return
-            alias = restify(obj, mode=mode)
+            alias = restify(obj, mode=render_mode)
             yield _('alias of %s') % alias
             return
 
@@ -367,11 +359,3 @@ def _docstring_source_name(*, props: _ItemProperties, source: str) -> str:
     if source:
         return f'{source}:docstring of {fullname}'
     return f'docstring of {fullname}'
-
-
-def _get_render_mode(
-    typehints_format: Literal['fully-qualified', 'short'],
-) -> _RestifyMode:
-    if typehints_format == 'short':
-        return 'smart'
-    return 'fully-qualified-except-typing'

sphinx/ext/autodoc/_importer.py

@@ -23,7 +23,7 @@
 from sphinx.util.typing import get_type_hints
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Mapping, Sequence
     from importlib.machinery import ModuleSpec
     from types import ModuleType
     from typing import Any, Protocol
@@ -71,11 +71,11 @@ def __repr__(self) -> str:
 def _import_object(
     *,
     get_attr: _AttrGetter = safe_getattr,
-    mock_imports: list[str],
+    mock_imports: Sequence[str],
     module_name: str,
     obj_path: Sequence[str],
     obj_type: _AutodocObjType,
-    type_aliases: dict[str, Any] | None,
+    type_aliases: Mapping[str, str] | None,
 ) -> _ImportedObject | None:
     """Import the module and get the object to document."""
     try:
@@ -310,8 +310,8 @@ def _import_data_declaration(
     *,
     module_name: str,
     obj_path: Sequence[str],
-    mock_imports: list[str],
-    type_aliases: dict[str, Any] | None,
+    mock_imports: Sequence[str],
+    type_aliases: Mapping[str, str] | None,
 ) -> _ImportedObject | None:
     # annotation only instance variable (PEP-526)
     try:
@@ -333,8 +333,8 @@ def _import_attribute_declaration(
     *,
     module_name: str,
     obj_path: Sequence[str],
-    mock_imports: list[str],
-    type_aliases: dict[str, Any] | None,
+    mock_imports: Sequence[str],
+    type_aliases: Mapping[str, str] | None,
     get_attr: _AttrGetter = safe_getattr,
 ) -> _ImportedObject | None:
     # Support runtime & uninitialized instance attributes.
@@ -424,7 +424,7 @@ def _get_attribute_comment(
 
 
 def _is_uninitialized_instance_attribute(
-    *, parent: Any, obj_path: Sequence[str], type_aliases: dict[str, Any] | None
+    *, parent: Any, obj_path: Sequence[str], type_aliases: Mapping[str, str] | None
 ) -> bool:
     """Check the subject is an annotation only attribute."""
     annotations = get_type_hints(parent, None, type_aliases, include_extras=True)

sphinx/ext/autodoc/_loader.py

@@ -27,6 +27,7 @@
     SLOTS_ATTR,
     UNINITIALIZED_ATTR,
 )
+from sphinx.ext.autodoc._shared import _get_render_mode
 from sphinx.ext.autodoc._signatures import _format_signatures
 from sphinx.ext.autodoc._type_comments import (
     _ensure_annotations_from_type_comments,
@@ -42,12 +43,12 @@
     from collections.abc import Mapping, MutableSet, Sequence
     from typing import Any
 
-    from sphinx.config import Config
     from sphinx.environment import _CurrentDocument
     from sphinx.events import EventManager
     from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
-    from sphinx.ext.autodoc._importer import _AttrGetter, _ImportedObject
+    from sphinx.ext.autodoc._importer import _ImportedObject
     from sphinx.ext.autodoc._property_types import _AutodocFuncProperty, _AutodocObjType
+    from sphinx.ext.autodoc._shared import _AttrGetter, _AutodocConfig
 
 logger = logging.getLogger(__name__)
 
@@ -58,10 +59,8 @@ def _load_object_by_name(
     *,
     name: str,
     objtype: _AutodocObjType,
-    mock_imports: list[str],
-    type_aliases: dict[str, Any] | None,
     current_document: _CurrentDocument,
-    config: Config,
+    config: _AutodocConfig,
     events: EventManager,
     get_attr: _AttrGetter,
     options: _AutoDocumenterOptions,
@@ -84,10 +83,10 @@ def _load_object_by_name(
     im = _import_object(
         module_name=module_name,
         obj_path=parts,
-        mock_imports=mock_imports,
+        mock_imports=config.autodoc_mock_imports,
         get_attr=get_attr,
         obj_type=objtype,
-        type_aliases=type_aliases,
+        type_aliases=config.autodoc_type_aliases,
     )
     if im is None:
         # See BuildEnvironment.note_reread()
@@ -164,7 +163,7 @@ def _load_object_by_name(
 def _make_props_from_imported_object(
     im: _ImportedObject,
     *,
-    config: Config,
+    config: _AutodocConfig,
     events: EventManager,
     get_attr: _AttrGetter,
     module_name: str,
@@ -175,6 +174,7 @@ def _make_props_from_imported_object(
     object_name = im.object_name
     obj = im.obj
     obj_properties: set[_AutodocFuncProperty] = set()
+    render_mode = _get_render_mode(config.autodoc_typehints_format)
 
     if objtype == 'module':
         try:
@@ -232,11 +232,7 @@ def _make_props_from_imported_object(
             SimpleNamespace(),
             obj_bases,
         )
-        if config.autodoc_typehints_format == 'short':
-            mode = 'smart'
-        else:
-            mode = 'fully-qualified-except-typing'
-        base_classes = tuple(restify(cls, mode=mode) for cls in obj_bases)  # type: ignore[arg-type]
+        base_classes = tuple(restify(cls, mode=render_mode) for cls in obj_bases)
 
         return _ClassDefProperties(
             obj_type=objtype,  # type: ignore[arg-type]
@@ -342,15 +338,11 @@ def _make_props_from_imported_object(
             except ValueError:
                 pass
             else:
-                if config.autodoc_typehints_format == 'short':
-                    mode = 'smart'
-                else:
-                    mode = 'fully-qualified-except-typing'
                 if signature.return_annotation is not Parameter.empty:
                     short_literals = config.python_display_short_literal_types
                     obj_property_type_annotation = stringify_annotation(
                         signature.return_annotation,
-                        mode,  # type: ignore[arg-type]
+                        render_mode,
                         short_literals=short_literals,
                     )
 
@@ -378,16 +370,10 @@ def _make_props_from_imported_object(
             config.autodoc_type_aliases,
             include_extras=True,
         )
-        if config.autodoc_typehints_format == 'short':
-            mode = 'smart'
-        else:
-            mode = 'fully-qualified-except-typing'
         if parts[-1] in annotations:
             short_literals = config.python_display_short_literal_types
             type_annotation = stringify_annotation(
-                annotations[parts[-1]],
-                mode,  # type: ignore[arg-type]
-                short_literals=short_literals,
+                annotations[parts[-1]], render_mode, short_literals=short_literals
             )
         else:
             type_annotation = None
@@ -436,16 +422,10 @@ def _make_props_from_imported_object(
             config.autodoc_type_aliases,
             include_extras=True,
         )
-        if config.autodoc_typehints_format == 'short':
-            mode = 'smart'
-        else:
-            mode = 'fully-qualified-except-typing'
         if parts[-1] in annotations:
             short_literals = config.python_display_short_literal_types
             type_annotation = stringify_annotation(
-                annotations[parts[-1]],
-                mode,  # type: ignore[arg-type]
-                short_literals=short_literals,
+                annotations[parts[-1]], render_mode, short_literals=short_literals
             )
         else:
             type_annotation = None
@@ -485,15 +465,9 @@ def _make_props_from_imported_object(
             parts = tuple(bases) + parts
             module_name = obj_module_name
 
-        if config.autodoc_typehints_format == 'short':
-            mode = 'smart'
-        else:
-            mode = 'fully-qualified-except-typing'
         short_literals = config.python_display_short_literal_types
         ann = stringify_annotation(
-            obj.__value__,
-            mode,  # type: ignore[arg-type]
-            short_literals=short_literals,
+            obj.__value__, render_mode, short_literals=short_literals
         )
         return _TypeStatementProperties(
             obj_type=objtype,

sphinx/ext/autodoc/_member_finder.py

@@ -32,18 +32,17 @@
     from collections.abc import Iterable, Iterator, Mapping, MutableSet, Sequence, Set
     from typing import Any, Literal
 
-    from sphinx.config import Config
     from sphinx.environment import _CurrentDocument
     from sphinx.events import EventManager
     from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
-    from sphinx.ext.autodoc._importer import _AttrGetter
     from sphinx.ext.autodoc._property_types import _AutodocObjType, _ItemProperties
     from sphinx.ext.autodoc._sentinels import (
         ALL_T,
         EMPTY_T,
         INSTANCE_ATTR_T,
         SLOTS_ATTR_T,
     )
+    from sphinx.ext.autodoc._shared import _AttrGetter, _AutodocConfig
 
 logger = logging.getLogger('sphinx.ext.autodoc')
 special_member_re = re.compile(r'^__\S+__$')
@@ -94,7 +93,7 @@ def _gather_members(
     indent: str,
     analyzer_order: dict[str, int],
     attr_docs: dict[tuple[str, str], list[str]],
-    config: Config,
+    config: _AutodocConfig,
     current_document: _CurrentDocument,
     events: EventManager,
     get_attr: _AttrGetter,
@@ -176,8 +175,6 @@ def _gather_members(
         member_props = _load_object_by_name(
             name=full_name,
             objtype=obj_type,
-            mock_imports=config.autodoc_mock_imports,
-            type_aliases=config.autodoc_type_aliases,
             current_document=current_document,
             config=config,
             events=events,