Split out _parse_name()

Author: AA-Turner

sphinx/ext/autodoc/importer.py

@@ -770,77 +770,15 @@ def _load_object_by_name(
     get_attr: _AttrGetter,
 ) -> tuple[_ItemProperties, str | None, str | None, ModuleType | None, Any] | None:
     """Import and load the object given by *name*."""
-    from sphinx.ext.autodoc._documenters import py_ext_sig_re
-
-    # Parse the definition in *name*.
-    # autodoc directives for classes and functions can contain a signature,
-    # which overrides the autogenerated one.
-    matched = py_ext_sig_re.match(name)
-    if matched is None:
-        logger.warning(
-            __('invalid signature for auto%s (%r)'),
-            objtype,
-            name,
-            type='autodoc',
-        )
-        # need a module to import
-        logger.warning(
-            __(
-                "don't know which module to import for autodocumenting "
-                '%r (try placing a "module" or "currentmodule" directive '
-                'in the document, or giving an explicit module name)'
-            ),
-            name,
-            type='autodoc',
-        )
-        return None
-
-    explicit_modname, path, base, _tp_list, args, retann = matched.groups()
-
-    # Support explicit module and class name separation via ``::``
-    if explicit_modname is not None:
-        module_name = explicit_modname.removesuffix('::')
-        parents = path.rstrip('.').split('.') if path else ()
-    else:
-        module_name = None
-        parents = ()
-
-    resolved = _resolve_name(
+    parsed = _parse_name(
+        name=name,
         objtype=objtype,
-        module_name=module_name,
-        path=path,
-        base=base,
-        parents=parents,
         current_document=current_document,
-        ref_context_py_module=env.ref_context.get('py:module'),
-        ref_context_py_class=env.ref_context.get('py:class', ''),
+        env=env,
     )
-    if resolved is None:
-        msg = 'must be implemented in subclasses'
-        raise NotImplementedError(msg)
-    module_name, parts = resolved
-
-    if objtype == 'module' and args:
-        msg = __("signature arguments given for automodule: '%s'")
-        logger.warning(msg, name, type='autodoc')
-        return None
-    if objtype == 'module' and retann:
-        msg = __("return annotation given for automodule: '%s'")
-        logger.warning(msg, name, type='autodoc')
-        return None
-
-    if not module_name:
-        # Could not resolve a module to import
-        logger.warning(
-            __(
-                "don't know which module to import for autodocumenting "
-                '%r (try placing a "module" or "currentmodule" directive '
-                'in the document, or giving an explicit module name)'
-            ),
-            name,
-            type='autodoc',
-        )
+    if parsed is None:
         return None
+    module_name, parts, args, retann = parsed
 
     # Import the module and get the object to document
     try:
@@ -1052,6 +990,89 @@ def _load_object_by_name(
     return props, args, retann, module, parent
 
 
+def _parse_name(
+    *,
+    name: str,
+    objtype: _AutodocObjType,
+    current_document: _CurrentDocument,
+    env: BuildEnvironment,
+) -> tuple[str, tuple[str, ...], str | None, str | None] | None:
+    """Parse *name* into module name, path, arguments, and return annotation."""
+    from sphinx.ext.autodoc._documenters import py_ext_sig_re
+
+    # Parse the definition in *name*.
+    # autodoc directives for classes and functions can contain a signature,
+    # which overrides the autogenerated one.
+    matched = py_ext_sig_re.match(name)
+    if matched is None:
+        logger.warning(
+            __('invalid signature for auto%s (%r)'),
+            objtype,
+            name,
+            type='autodoc',
+        )
+        # need a module to import
+        logger.warning(
+            __(
+                "don't know which module to import for autodocumenting "
+                '%r (try placing a "module" or "currentmodule" directive '
+                'in the document, or giving an explicit module name)'
+            ),
+            name,
+            type='autodoc',
+        )
+        return None
+
+    explicit_modname, path, base, _tp_list, args, retann = matched.groups()
+
+    # Support explicit module and class name separation via ``::``
+    if explicit_modname is not None:
+        module_name = explicit_modname.removesuffix('::')
+        parents = path.rstrip('.').split('.') if path else ()
+    else:
+        module_name = None
+        parents = ()
+
+    resolved = _resolve_name(
+        objtype=objtype,
+        module_name=module_name,
+        path=path,
+        base=base,
+        parents=parents,
+        current_document=current_document,
+        ref_context_py_module=env.ref_context.get('py:module'),
+        ref_context_py_class=env.ref_context.get('py:class', ''),
+    )
+    if resolved is None:
+        msg = 'must be implemented in subclasses'
+        raise NotImplementedError(msg)
+    module_name, parts = resolved
+
+    if objtype == 'module' and args:
+        msg = __("signature arguments given for automodule: '%s'")
+        logger.warning(msg, name, type='autodoc')
+        return None
+    if objtype == 'module' and retann:
+        msg = __("return annotation given for automodule: '%s'")
+        logger.warning(msg, name, type='autodoc')
+        return None
+
+    if not module_name:
+        # Could not resolve a module to import
+        logger.warning(
+            __(
+                "don't know which module to import for autodocumenting "
+                '%r (try placing a "module" or "currentmodule" directive '
+                'in the document, or giving an explicit module name)'
+            ),
+            name,
+            type='autodoc',
+        )
+        return None
+
+    return module_name, parts, args, retann
+
+
 def _resolve_name(
     *,
     objtype: str,