Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/ext/autosummary/generate.py

@@ -18,14 +18,12 @@ import argparse
 import importlib
 import inspect
 import locale
-import os
 import pkgutil
 import pydoc
 import re
 import sys
-from os import path
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -38,7 +36,7 @@ from sphinx.errors import PycodeError
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autosummary import (
     ImportExceptionGroup,
-    get_documenter,
+    _get_documenter,
     import_by_name,
     import_ivar_by_name,
 )
@@ -46,28 +44,38 @@ from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import logging, rst
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
 if TYPE_CHECKING:
+    import os
     from collections.abc import Sequence, Set
     from gettext import NullTranslations
+    from typing import Any
 
     from sphinx.application import Sphinx
+    from sphinx.events import EventManager
     from sphinx.ext.autodoc import Documenter
 
 logger = logging.getLogger(__name__)
 
 
+class _DummyEvents:
+    def emit_firstresult(self, *args: Any) -> None:
+        pass
+
+
 class DummyApplication:
     """Dummy Application class for sphinx-autogen command."""
 
     def __init__(self, translator: NullTranslations) -> None:
         self.config = Config()
+        self.events = _DummyEvents()
         self.registry = SphinxComponentRegistry()
         self.messagelog: list[str] = []
-        self.srcdir = '/'
+        self.srcdir = _StrPath('/')
         self.translator = translator
         self.verbosity = 0
         self._warncount = 0
@@ -88,7 +96,7 @@ class AutosummaryEntry(NamedTuple):
     recursive: bool
 
 
-def setup_documenters(app: Any) -> None:
+def setup_documenters(app: Sphinx) -> None:
     from sphinx.ext.autodoc import (
         AttributeDocumenter,
         ClassDocumenter,
@@ -129,10 +137,10 @@ class AutosummaryRenderer:
     def __init__(self, app: Sphinx) -> None:
         if isinstance(app, Builder):
             msg = 'Expected a Sphinx application object!'
-            raise ValueError(msg)
+            raise TypeError(msg)
 
         system_templates_path = [
-            os.path.join(package_dir, 'ext', 'autosummary', 'templates')
+            package_dir.joinpath('ext', 'autosummary', 'templates')
         ]
         loader = SphinxTemplateLoader(
             app.srcdir, app.config.templates_path, system_templates_path
@@ -197,16 +205,25 @@ def _split_full_qualified_name(name: str) -> tuple[str | None, str]:
 
 
 class ModuleScanner:
-    def __init__(self, app: Any, obj: Any) -> None:
-        self.app = app
+    def __init__(
+        self,
+        obj: Any,
+        *,
+        config: Config,
+        events: EventManager,
+        registry: SphinxComponentRegistry,
+    ) -> None:
+        self.config = config
+        self.events = events
+        self.registry = registry
         self.object = obj
 
     def get_object_type(self, name: str, value: Any) -> str:
-        return get_documenter(self.app, value, self.object).objtype
+        return _get_documenter(value, self.object, registry=self.registry).objtype
 
     def is_skipped(self, name: str, value: Any, objtype: str) -> bool:
         try:
-            return self.app.emit_firstresult(
+            return self.events.emit_firstresult(
                 'autodoc-skip-member', objtype, name, value, False, {}
             )
         except Exception as exc:
@@ -229,7 +246,7 @@ class ModuleScanner:
         except PycodeError:
             attr_docs = {}
 
-        for name in members_of(self.object, self.app.config):
+        for name in members_of(self.object, config=self.config):
             try:
                 value = safe_getattr(self.object, name)
             except AttributeError:
@@ -251,7 +268,7 @@ class ModuleScanner:
             except AttributeError:
                 imported = False
 
-            respect_module_all = not self.app.config.autosummary_ignore_module_all
+            respect_module_all = not self.config.autosummary_ignore_module_all
             if (
                 # list all members up
                 imported_members
@@ -265,15 +282,19 @@ class ModuleScanner:
         return members
 
 
-def members_of(obj: Any, conf: Config) -> Sequence[str]:
+def members_of(obj: Any, *, config: Config) -> Sequence[str]:
     """Get the members of ``obj``, possibly ignoring the ``__all__`` module attribute
 
-    Follows the ``conf.autosummary_ignore_module_all`` setting.
+    Follows the ``config.autosummary_ignore_module_all`` setting.
     """
-    if conf.autosummary_ignore_module_all:
+    if config.autosummary_ignore_module_all:
         return dir(obj)
     else:
-        return getall(obj) or dir(obj)
+        if (obj___all__ := getall(obj)) is not None:
+            # return __all__, even if empty.
+            return obj___all__
+        # if __all__ is not set, return dir(obj)
+        return dir(obj)
 
 
 def generate_autosummary_content(
@@ -283,34 +304,55 @@ def generate_autosummary_content(
     template: AutosummaryRenderer,
     template_name: str,
     imported_members: bool,
-    app: Any,
     recursive: bool,
     context: dict[str, Any],
     modname: str | None = None,
     qualname: str | None = None,
+    *,
+    config: Config,
+    events: EventManager,
+    registry: SphinxComponentRegistry,
 ) -> str:
-    doc = get_documenter(app, obj, parent)
+    doc = _get_documenter(obj, parent, registry=registry)
 
     ns: dict[str, Any] = {}
     ns.update(context)
 
     if doc.objtype == 'module':
-        scanner = ModuleScanner(app, obj)
+        scanner = ModuleScanner(obj, config=config, events=events, registry=registry)
         ns['members'] = scanner.scan(imported_members)
 
-        respect_module_all = not app.config.autosummary_ignore_module_all
+        respect_module_all = not config.autosummary_ignore_module_all
         imported_members = imported_members or (
             '__all__' in dir(obj) and respect_module_all
         )
 
         ns['functions'], ns['all_functions'] = _get_members(
-            doc, app, obj, {'function'}, imported=imported_members
+            doc,
+            obj,
+            {'function'},
+            config=config,
+            events=events,
+            registry=registry,
+            imported=imported_members,
         )
         ns['classes'], ns['all_classes'] = _get_members(
-            doc, app, obj, {'class'}, imported=imported_members
+            doc,
+            obj,
+            {'class'},
+            config=config,
+            events=events,
+            registry=registry,
+            imported=imported_members,
         )
         ns['exceptions'], ns['all_exceptions'] = _get_members(
-            doc, app, obj, {'exception'}, imported=imported_members
+            doc,
+            obj,
+            {'exception'},
+            config=config,
+            events=events,
+            registry=registry,
+            imported=imported_members,
         )
         ns['attributes'], ns['all_attributes'] = _get_module_attrs(name, ns['members'])
         ispackage = hasattr(obj, '__path__')
@@ -332,7 +374,13 @@ def generate_autosummary_content(
             # Otherwise, use get_modules method normally
             if respect_module_all and '__all__' in dir(obj):
                 imported_modules, all_imported_modules = _get_members(
-                    doc, app, obj, {'module'}, imported=True
+                    doc,
+                    obj,
+                    {'module'},
+                    config=config,
+                    events=events,
+                    registry=registry,
+                    imported=True,
                 )
                 skip += all_imported_modules
                 public_members = getall(obj)
@@ -349,16 +397,27 @@ def generate_autosummary_content(
         ns['members'] = dir(obj)
         ns['inherited_members'] = set(dir(obj)) - set(obj.__dict__.keys())
         ns['methods'], ns['all_methods'] = _get_members(
-            doc, app, obj, {'method'}, include_public={'__init__'}
+            doc,
+            obj,
+            {'method'},
+            config=config,
+            events=events,
+            registry=registry,
+            include_public={'__init__'},
         )
         ns['attributes'], ns['all_attributes'] = _get_members(
-            doc, app, obj, {'attribute', 'property'}
+            doc,
+            obj,
+            {'attribute', 'property'},
+            config=config,
+            events=events,
+            registry=registry,
         )
 
     if modname is None or qualname is None:
         modname, qualname = _split_full_qualified_name(name)
 
-    if doc.objtype in ('method', 'attribute', 'property'):
+    if doc.objtype in {'method', 'attribute', 'property'}:
         ns['class'] = qualname.rsplit('.', 1)[0]
 
     if doc.objtype == 'class':
@@ -380,9 +439,9 @@ def generate_autosummary_content(
         return template.render(doc.objtype, ns)
 
 
-def _skip_member(app: Sphinx, obj: Any, name: str, objtype: str) -> bool:
+def _skip_member(obj: Any, name: str, objtype: str, *, events: EventManager) -> bool:
     try:
-        return app.emit_firstresult(
+        return events.emit_firstresult(
             'autodoc-skip-member', objtype, name, obj, False, {}
         )
     except Exception as exc:
@@ -403,9 +462,9 @@ def _get_class_members(obj: Any) -> dict[str, Any]:
     return {name: member.object for name, member in members.items()}
 
 
-def _get_module_members(app: Sphinx, obj: Any) -> dict[str, Any]:
+def _get_module_members(obj: Any, *, config: Config) -> dict[str, Any]:
     members = {}
-    for name in members_of(obj, app.config):
+    for name in members_of(obj, config=config):
         try:
             members[name] = safe_getattr(obj, name)
         except AttributeError:
@@ -413,9 +472,11 @@ def _get_module_members(app: Sphinx, obj: Any) -> dict[str, Any]:
     return members
 
 
-def _get_all_members(doc: type[Documenter], app: Sphinx, obj: Any) -> dict[str, Any]:
+def _get_all_members(
+    doc: type[Documenter], obj: Any, *, config: Config
+) -> dict[str, Any]:
     if doc.objtype == 'module':
-        return _get_module_members(app, obj)
+        return _get_module_members(obj, config=config)
     elif doc.objtype == 'class':
         return _get_class_members(obj)
     return {}
@@ -423,23 +484,25 @@ def _get_all_members(doc: type[Documenter], app: Sphinx, obj: Any) -> dict[str,
 
 def _get_members(
     doc: type[Documenter],
-    app: Sphinx,
     obj: Any,
     types: set[str],
     *,
+    config: Config,
+    events: EventManager,
+    registry: SphinxComponentRegistry,
     include_public: Set[str] = frozenset(),
     imported: bool = True,
 ) -> tuple[list[str], list[str]]:
     items: list[str] = []
     public: list[str] = []
 
-    all_members = _get_all_members(doc, app, obj)
+    all_members = _get_all_members(doc, obj, config=config)
     for name, value in all_members.items():
-        documenter = get_documenter(app, value, obj)
+        documenter = _get_documenter(value, obj, registry=registry)
         if documenter.objtype in types:
             # skip imported members if expected
             if imported or getattr(value, '__module__', None) == obj.__name__:
-                skipped = _skip_member(app, value, name, documenter.objtype)
+                skipped = _skip_member(value, name, documenter.objtype, events=events)
                 if skipped is True:
                     pass
                 elif skipped is False:
@@ -461,7 +524,7 @@ def _get_module_attrs(name: str, members: Any) -> tuple[list[str], list[str]]:
         analyzer = ModuleAnalyzer.for_module(name)
         attr_docs = analyzer.find_attr_docs()
         for namespace, attr_name in attr_docs:
-            if namespace == '' and attr_name in members:
+            if not namespace and attr_name in members:
                 attrs.append(attr_name)
                 if not attr_name.startswith('_'):
                     public.append(attr_name)
@@ -529,12 +592,15 @@ def generate_autosummary_docs(
         logger.info(__('[autosummary] writing to %s'), output_dir)
 
     if base_path is not None:
-        sources = [os.path.join(base_path, filename) for filename in sources]
+        base_path = Path(base_path)
+        source_paths = [base_path / filename for filename in sources]
+    else:
+        source_paths = list(map(Path, sources))
 
     template = AutosummaryRenderer(app)
 
     # read
-    items = find_autosummary_in_files(sources)
+    items = find_autosummary_in_files(source_paths)
 
     # keep track of new files
     new_files: list[Path] = []
@@ -549,7 +615,7 @@ def generate_autosummary_docs(
             # a :toctree: option
             continue
 
-        path = output_dir or os.path.abspath(entry.path)
+        path = output_dir or Path(entry.path).resolve()
         ensuredir(path)
 
         try:
@@ -583,11 +649,13 @@ def generate_autosummary_docs(
             template,
             entry.template,
             imported_members,
-            app,
             entry.recursive,
             context,
             modname,
             qualname,
+            config=app.config,
+            events=app.events,
+            registry=app.registry,
         )
 
         file_path = Path(path, filename_map.get(name, name) + suffix)
@@ -627,7 +695,9 @@ def generate_autosummary_docs(
 # -- Finding documented entries in files ---------------------------------------
 
 
-def find_autosummary_in_files(filenames: list[str]) -> list[AutosummaryEntry]:
+def find_autosummary_in_files(
+    filenames: Sequence[str | os.PathLike[str]],
+) -> list[AutosummaryEntry]:
     """Find out what items are documented in source/*.rst.
 
     See `find_autosummary_in_lines`.
@@ -636,13 +706,13 @@ def find_autosummary_in_files(filenames: list[str]) -> list[AutosummaryEntry]:
     for filename in filenames:
         with open(filename, encoding='utf-8', errors='ignore') as f:
             lines = f.read().splitlines()
-            documented.extend(find_autosummary_in_lines(lines, filename=filename))
+        documented.extend(find_autosummary_in_lines(lines, filename=filename))
     return documented
 
 
 def find_autosummary_in_docstring(
     name: str,
-    filename: str | None = None,
+    filename: str | os.PathLike[str] | None = None,
 ) -> list[AutosummaryEntry]:
     """Find out what items are documented in the given object's docstring.
 
@@ -669,7 +739,7 @@ def find_autosummary_in_docstring(
 def find_autosummary_in_lines(
     lines: list[str],
     module: str | None = None,
-    filename: str | None = None,
+    filename: str | os.PathLike[str] | None = None,
 ) -> list[AutosummaryEntry]:
     """Find out what items appear in autosummary:: directives in the
     given lines.
@@ -709,7 +779,7 @@ def find_autosummary_in_lines(
             if m:
                 toctree = m.group(1)
                 if filename:
-                    toctree = os.path.join(os.path.dirname(filename), toctree)
+                    toctree = str(Path(filename).parent / toctree)
                 continue
 
             m = template_arg_re.match(line)
@@ -849,11 +919,11 @@ def main(argv: Sequence[str] = (), /) -> None:
 
     app = DummyApplication(sphinx.locale.get_translator())
     logging.setup(app, sys.stdout, sys.stderr)  # type: ignore[arg-type]
-    setup_documenters(app)
+    setup_documenters(app)  # type: ignore[arg-type]
     args = get_parser().parse_args(argv or sys.argv[1:])
 
     if args.templates:
-        app.config.templates_path.append(path.abspath(args.templates))
+        app.config.templates_path.append(str(Path(args.templates).resolve()))
     app.config.autosummary_ignore_module_all = not args.respect_module_all
 
     written_files = generate_autosummary_docs(