Sphinx 7.1.2__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/ext/autosummary/generate.py

@@ -15,6 +15,7 @@ Example Makefile rule::
 from __future__ import annotations
 
 import argparse
+import importlib
 import inspect
 import locale
 import os
@@ -23,17 +24,15 @@ import pydoc
 import re
 import sys
 from os import path
-from typing import TYPE_CHECKING, Any, NamedTuple, Sequence
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
 
 import sphinx.locale
 from sphinx import __display_version__, package_dir
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
-from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autosummary import (
     ImportExceptionGroup,
@@ -44,14 +43,18 @@ from sphinx.ext.autosummary import (
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.registry import SphinxComponentRegistry
-from sphinx.util import logging, rst, split_full_qualified_name
+from sphinx.util import logging, rst
 from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence, Set
     from gettext import NullTranslations
 
+    from sphinx.application import Sphinx
+    from sphinx.ext.autodoc import Documenter
+
 logger = logging.getLogger(__name__)
 
 
@@ -79,7 +82,7 @@ class DummyApplication:
 
 class AutosummaryEntry(NamedTuple):
     name: str
-    path: str
+    path: str | None
     template: str
     recursive: bool
 
@@ -107,7 +110,8 @@ def setup_documenters(app: Any) -> None:
 
 def _underline(title: str, line: str = '=') -> str:
     if '\n' in title:
-        raise ValueError('Can only underline single lines')
+        msg = 'Can only underline single lines'
+        raise ValueError(msg)
     return title + '\n' + line * len(title)
 
 
@@ -116,7 +120,8 @@ class AutosummaryRenderer:
 
     def __init__(self, app: Sphinx) -> None:
         if isinstance(app, Builder):
-            raise ValueError('Expected a Sphinx application object!')
+            msg = 'Expected a Sphinx application object!'
+            raise ValueError(msg)
 
         system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
         loader = SphinxTemplateLoader(app.srcdir, app.config.templates_path,
@@ -146,6 +151,36 @@ class AutosummaryRenderer:
         return template.render(context)
 
 
+def _split_full_qualified_name(name: str) -> tuple[str | None, str]:
+    """Split full qualified name to a pair of modname and qualname.
+
+    A qualname is an abbreviation for "Qualified name" introduced at PEP-3155
+    (https://peps.python.org/pep-3155/).  It is a dotted path name
+    from the module top-level.
+
+    A "full" qualified name means a string containing both module name and
+    qualified name.
+
+    .. note:: This function actually imports the module to check its existence.
+              Therefore you need to mock 3rd party modules if needed before
+              calling this function.
+    """
+    parts = name.split('.')
+    for i, _part in enumerate(parts, 1):
+        try:
+            modname = ".".join(parts[:i])
+            importlib.import_module(modname)
+        except ImportError:
+            if parts[:i - 1]:
+                return ".".join(parts[:i - 1]), ".".join(parts[i - 1:])
+            else:
+                return None, ".".join(parts)
+        except IndexError:
+            pass
+
+    return name, ""
+
+
 # -- Generating output ---------------------------------------------------------
 
 
@@ -230,104 +265,6 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                                  qualname: str | None = None) -> str:
     doc = get_documenter(app, obj, parent)
 
-    def skip_member(obj: Any, name: str, objtype: str) -> bool:
-        try:
-            return app.emit_firstresult('autodoc-skip-member', objtype, name,
-                                        obj, False, {})
-        except Exception as exc:
-            logger.warning(__('autosummary: failed to determine %r to be documented, '
-                              'the following exception was raised:\n%s'),
-                           name, exc, type='autosummary')
-            return False
-
-    def get_class_members(obj: Any) -> dict[str, Any]:
-        members = sphinx.ext.autodoc.get_class_members(obj, [qualname], safe_getattr)
-        return {name: member.object for name, member in members.items()}
-
-    def get_module_members(obj: Any) -> dict[str, Any]:
-        members = {}
-        for name in members_of(obj, app.config):
-            try:
-                members[name] = safe_getattr(obj, name)
-            except AttributeError:
-                continue
-        return members
-
-    def get_all_members(obj: Any) -> dict[str, Any]:
-        if doc.objtype == "module":
-            return get_module_members(obj)
-        elif doc.objtype == "class":
-            return get_class_members(obj)
-        return {}
-
-    def get_members(obj: Any, types: set[str], include_public: list[str] = [],
-                    imported: bool = True) -> tuple[list[str], list[str]]:
-        items: list[str] = []
-        public: list[str] = []
-
-        all_members = get_all_members(obj)
-        for name, value in all_members.items():
-            documenter = get_documenter(app, value, obj)
-            if documenter.objtype in types:
-                # skip imported members if expected
-                if imported or getattr(value, '__module__', None) == obj.__name__:
-                    skipped = skip_member(value, name, documenter.objtype)
-                    if skipped is True:
-                        pass
-                    elif skipped is False:
-                        # show the member forcedly
-                        items.append(name)
-                        public.append(name)
-                    else:
-                        items.append(name)
-                        if name in include_public or not name.startswith('_'):
-                            # considers member as public
-                            public.append(name)
-        return public, items
-
-    def get_module_attrs(members: Any) -> tuple[list[str], list[str]]:
-        """Find module attributes with docstrings."""
-        attrs, public = [], []
-        try:
-            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:
-                    attrs.append(attr_name)
-                    if not attr_name.startswith('_'):
-                        public.append(attr_name)
-        except PycodeError:
-            pass    # give up if ModuleAnalyzer fails to parse code
-        return public, attrs
-
-    def get_modules(
-            obj: Any,
-            skip: Sequence[str],
-            public_members: Sequence[str] | None = None) -> tuple[list[str], list[str]]:
-        items: list[str] = []
-        public: list[str] = []
-        for _, modname, _ispkg in pkgutil.iter_modules(obj.__path__):
-
-            if modname in skip:
-                # module was overwritten in __init__.py, so not accessible
-                continue
-            fullname = name + '.' + modname
-            try:
-                module = import_module(fullname)
-                if module and hasattr(module, '__sphinx_mock__'):
-                    continue
-            except ImportError:
-                pass
-
-            items.append(fullname)
-            if public_members is not None:
-                if modname in public_members:
-                    public.append(fullname)
-            else:
-                if not modname.startswith('_'):
-                    public.append(fullname)
-        return public, items
-
     ns: dict[str, Any] = {}
     ns.update(context)
 
@@ -339,13 +276,13 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
 
         ns['functions'], ns['all_functions'] = \
-            get_members(obj, {'function'}, imported=imported_members)
+            _get_members(doc, app, obj, {'function'}, imported=imported_members)
         ns['classes'], ns['all_classes'] = \
-            get_members(obj, {'class'}, imported=imported_members)
+            _get_members(doc, app, obj, {'class'}, imported=imported_members)
         ns['exceptions'], ns['all_exceptions'] = \
-            get_members(obj, {'exception'}, imported=imported_members)
+            _get_members(doc, app, obj, {'exception'}, imported=imported_members)
         ns['attributes'], ns['all_attributes'] = \
-            get_module_attrs(ns['members'])
+            _get_module_attrs(name, ns['members'])
         ispackage = hasattr(obj, '__path__')
         if ispackage and recursive:
             # Use members that are not modules as skip list, because it would then mean
@@ -365,7 +302,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             # Otherwise, use get_modules method normally
             if respect_module_all and '__all__' in dir(obj):
                 imported_modules, all_imported_modules = \
-                    get_members(obj, {'module'}, imported=True)
+                    _get_members(doc, app, obj, {'module'}, imported=True)
                 skip += all_imported_modules
                 imported_modules = [name + '.' + modname for modname in imported_modules]
                 all_imported_modules = \
@@ -375,7 +312,8 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 imported_modules, all_imported_modules = [], []
                 public_members = None
 
-            modules, all_modules = get_modules(obj, skip=skip, public_members=public_members)
+            modules, all_modules = _get_modules(obj, skip=skip, name=name,
+                                                public_members=public_members)
             ns['modules'] = imported_modules + modules
             ns["all_modules"] = all_imported_modules + all_modules
     elif doc.objtype == 'class':
@@ -383,12 +321,12 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         ns['inherited_members'] = \
             set(dir(obj)) - set(obj.__dict__.keys())
         ns['methods'], ns['all_methods'] = \
-            get_members(obj, {'method'}, ['__init__'])
+            _get_members(doc, app, obj, {'method'}, include_public={'__init__'})
         ns['attributes'], ns['all_attributes'] = \
-            get_members(obj, {'attribute', 'property'})
+            _get_members(doc, app, obj, {'attribute', 'property'})
 
     if modname is None or qualname is None:
-        modname, qualname = split_full_qualified_name(name)
+        modname, qualname = _split_full_qualified_name(name)
 
     if doc.objtype in ('method', 'attribute', 'property'):
         ns['class'] = qualname.rsplit(".", 1)[0]
@@ -412,8 +350,118 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         return template.render(doc.objtype, ns)
 
 
-def generate_autosummary_docs(sources: list[str], output_dir: str | None = None,
-                              suffix: str = '.rst', base_path: str | None = None,
+def _skip_member(app: Sphinx, obj: Any, name: str, objtype: str) -> bool:
+    try:
+        return app.emit_firstresult('autodoc-skip-member', objtype, name,
+                                    obj, False, {})
+    except Exception as exc:
+        logger.warning(__('autosummary: failed to determine %r to be documented, '
+                          'the following exception was raised:\n%s'),
+                       name, exc, type='autosummary')
+        return False
+
+
+def _get_class_members(obj: Any) -> dict[str, Any]:
+    members = sphinx.ext.autodoc.get_class_members(obj, None, safe_getattr)
+    return {name: member.object for name, member in members.items()}
+
+
+def _get_module_members(app: Sphinx, obj: Any) -> dict[str, Any]:
+    members = {}
+    for name in members_of(obj, app.config):
+        try:
+            members[name] = safe_getattr(obj, name)
+        except AttributeError:
+            continue
+    return members
+
+
+def _get_all_members(doc: type[Documenter], app: Sphinx, obj: Any) -> dict[str, Any]:
+    if doc.objtype == 'module':
+        return _get_module_members(app, obj)
+    elif doc.objtype == 'class':
+        return _get_class_members(obj)
+    return {}
+
+
+def _get_members(doc: type[Documenter], app: Sphinx, obj: Any, types: set[str], *,
+                 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)
+    for name, value in all_members.items():
+        documenter = get_documenter(app, value, obj)
+        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)
+                if skipped is True:
+                    pass
+                elif skipped is False:
+                    # show the member forcedly
+                    items.append(name)
+                    public.append(name)
+                else:
+                    items.append(name)
+                    if name in include_public or not name.startswith('_'):
+                        # considers member as public
+                        public.append(name)
+    return public, items
+
+
+def _get_module_attrs(name: str, members: Any) -> tuple[list[str], list[str]]:
+    """Find module attributes with docstrings."""
+    attrs, public = [], []
+    try:
+        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:
+                attrs.append(attr_name)
+                if not attr_name.startswith('_'):
+                    public.append(attr_name)
+    except PycodeError:
+        pass    # give up if ModuleAnalyzer fails to parse code
+    return public, attrs
+
+
+def _get_modules(
+        obj: Any,
+        *,
+        skip: Sequence[str],
+        name: str,
+        public_members: Sequence[str] | None = None) -> tuple[list[str], list[str]]:
+    items: list[str] = []
+    public: list[str] = []
+    for _, modname, _ispkg in pkgutil.iter_modules(obj.__path__):
+
+        if modname in skip:
+            # module was overwritten in __init__.py, so not accessible
+            continue
+        fullname = name + '.' + modname
+        try:
+            module = import_module(fullname)
+            if module and hasattr(module, '__sphinx_mock__'):
+                continue
+        except ImportError:
+            pass
+
+        items.append(fullname)
+        if public_members is not None:
+            if modname in public_members:
+                public.append(fullname)
+        else:
+            if not modname.startswith('_'):
+                public.append(fullname)
+    return public, items
+
+
+def generate_autosummary_docs(sources: list[str],
+                              output_dir: str | os.PathLike[str] | None = None,
+                              suffix: str = '.rst',
+                              base_path: str | os.PathLike[str] | None = None,
                               imported_members: bool = False, app: Any = None,
                               overwrite: bool = True, encoding: str = 'utf-8') -> None:
     showed_sources = sorted(sources)
@@ -532,10 +580,10 @@ def find_autosummary_in_docstring(
         pass
     except ImportExceptionGroup as exc:
         errors = '\n'.join({f"* {type(e).__name__}: {e}" for e in exc.exceptions})
-        print(f'Failed to import {name}.\nPossible hints:\n{errors}')
+        logger.warning(f'Failed to import {name}.\nPossible hints:\n{errors}')  # NoQA: G004
     except SystemExit:
-        print("Failed to import '%s'; the module executes module level "
-              "statement and it might call sys.exit()." % name)
+        logger.warning("Failed to import '%s'; the module executes module level "
+                       'statement and it might call sys.exit().', name)
     return []
 
 
@@ -566,7 +614,7 @@ def find_autosummary_in_lines(
 
     recursive = False
     toctree: str | None = None
-    template = None
+    template = ''
     current_module = module
     in_autosummary = False
     base_indent = ""
@@ -616,7 +664,7 @@ def find_autosummary_in_lines(
             base_indent = m.group(1)
             recursive = False
             toctree = None
-            template = None
+            template = ''
             continue
 
         m = automodule_re.search(line)
@@ -681,18 +729,20 @@ The format of the autosummary directive is documented in the
     return parser
 
 
-def main(argv: list[str] = sys.argv[1:]) -> None:
+def main(argv: Sequence[str] = (), /) -> None:
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console()
 
     app = DummyApplication(sphinx.locale.get_translator())
-    logging.setup(app, sys.stdout, sys.stderr)  # type: ignore
+    logging.setup(app, sys.stdout, sys.stderr)  # type: ignore[arg-type]
     setup_documenters(app)
-    args = get_parser().parse_args(argv)
+    args = get_parser().parse_args(argv or sys.argv[1:])
 
     if args.templates:
         app.config.templates_path.append(path.abspath(args.templates))
-    app.config.autosummary_ignore_module_all = not args.respect_module_all  # type: ignore
+    app.config.autosummary_ignore_module_all = (  # type: ignore[attr-defined]
+        not args.respect_module_all
+    )
 
     generate_autosummary_docs(args.source_file, args.output_dir,
                               '.' + args.suffix,
@@ -701,4 +751,4 @@ def main(argv: list[str] = sys.argv[1:]) -> None:
 
 
 if __name__ == '__main__':
-    main()
+    main(sys.argv[1:])

sphinx/ext/coverage.py

@@ -10,25 +10,30 @@ import glob
 import inspect
 import pickle
 import re
+import sys
 from importlib import import_module
 from os import path
-from typing import IO, Any
+from typing import IO, TYPE_CHECKING, Any, TextIO
 
 import sphinx
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import red  # type: ignore
+from sphinx.util.console import red  # type: ignore[attr-defined]
 from sphinx.util.inspect import safe_getattr
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 
 # utility
 def write_header(f: IO[str], text: str, char: str = '-') -> None:
     f.write(text + '\n')
-    f.write(char * len(text) + '\n')
+    f.write(char * len(text) + '\n\n')
 
 
 def compile_regex_list(name: str, exps: str) -> list[re.Pattern[str]]:
@@ -41,6 +46,25 @@ def compile_regex_list(name: str, exps: str) -> list[re.Pattern[str]]:
     return lst
 
 
+def _write_table(table: list[list[str]]) -> Iterator[str]:
+    sizes = [max(len(x[column]) for x in table) + 1 for column in range(len(table[0]))]
+
+    yield _add_line(sizes, '-')
+    yield from _add_row(sizes, table[0], '=')
+
+    for row in table[1:]:
+        yield from _add_row(sizes, row, '-')
+
+
+def _add_line(sizes: list[int], separator: str) -> str:
+    return '+' + ''.join((separator * (size + 1)) + '+' for size in sizes)
+
+
+def _add_row(col_widths: list[int], columns: list[str], separator: str) -> Iterator[str]:
+    yield ''.join(f'| {column: <{col_widths[i]}}' for i, column in enumerate(columns)) + '|'
+    yield _add_line(col_widths, separator)
+
+
 class CoverageBuilder(Builder):
     """
     Evaluates coverage of code in the documentation.
@@ -80,6 +104,8 @@ class CoverageBuilder(Builder):
 
     def write(self, *ignored: Any) -> None:
         self.py_undoc: dict[str, dict[str, Any]] = {}
+        self.py_undocumented: dict[str, set[str]] = {}
+        self.py_documented: dict[str, set[str]] = {}
         self.build_py_coverage()
         self.write_py_coverage()
 
@@ -88,8 +114,9 @@ class CoverageBuilder(Builder):
         self.write_c_coverage()
 
     def build_c_coverage(self) -> None:
-        # Fetch all the info from the header files
-        c_objects = self.env.domaindata['c']['objects']
+        c_objects = {}
+        for obj in self.env.domains['c'].get_objects():
+            c_objects[obj[2]] = obj[1]
         for filename in self.c_sourcefiles:
             undoc: set[tuple[str, str]] = set()
             with open(filename, encoding="utf-8") as f:
@@ -98,7 +125,11 @@ class CoverageBuilder(Builder):
                         match = regex.match(line)
                         if match:
                             name = match.groups()[0]
-                            if name not in c_objects:
+                            if key not in c_objects:
+                                undoc.add((key, name))
+                                continue
+
+                            if name not in c_objects[key]:
                                 for exp in self.c_ignorexps.get(key, []):
                                     if exp.match(name):
                                         break
@@ -157,6 +188,9 @@ class CoverageBuilder(Builder):
                 self.py_undoc[mod_name] = {'error': err}
                 continue
 
+            documented_objects: set[str] = set()
+            undocumented_objects: set[str] = set()
+
             funcs = []
             classes: dict[str, list[str]] = {}
 
@@ -185,6 +219,9 @@ class CoverageBuilder(Builder):
                             if skip_undoc and not obj.__doc__:
                                 continue
                             funcs.append(name)
+                            undocumented_objects.add(full_name)
+                    else:
+                        documented_objects.add(full_name)
                 elif inspect.isclass(obj):
                     for exp in self.cls_ignorexps:
                         if exp.match(name):
@@ -220,11 +257,47 @@ class CoverageBuilder(Builder):
                                 continue
                             if full_attr_name not in objects:
                                 attrs.append(attr_name)
+                                undocumented_objects.add(full_attr_name)
+                            else:
+                                documented_objects.add(full_attr_name)
+
                         if attrs:
                             # some attributes are undocumented
                             classes[name] = attrs
 
             self.py_undoc[mod_name] = {'funcs': funcs, 'classes': classes}
+            self.py_undocumented[mod_name] = undocumented_objects
+            self.py_documented[mod_name] = documented_objects
+
+    def _write_py_statistics(self, op: TextIO) -> None:
+        """ Outputs the table of ``op``."""
+        all_modules = set(self.py_documented.keys()).union(
+            set(self.py_undocumented.keys()))
+        all_objects: set[str] = set()
+        all_documented_objects: set[str] = set()
+        for module in all_modules:
+            all_module_objects = self.py_documented[module].union(self.py_undocumented[module])
+            all_objects = all_objects.union(all_module_objects)
+            all_documented_objects = all_documented_objects.union(self.py_documented[module])
+
+        # prepare tabular
+        table = [['Module', 'Coverage', 'Undocumented']]
+        for module in all_modules:
+            module_objects = self.py_documented[module].union(self.py_undocumented[module])
+            if len(module_objects):
+                value = 100.0 * len(self.py_documented[module]) / len(module_objects)
+            else:
+                value = 100.0
+
+            table.append([module, '%.2f%%' % value, '%d' % len(self.py_undocumented[module])])
+        table.append([
+            'TOTAL',
+            f'{100 * len(all_documented_objects) / len(all_objects):.2f}%',
+            f'{len(all_objects) - len(all_documented_objects)}',
+        ])
+
+        for line in _write_table(table):
+            op.write(f'{line}\n')
 
     def write_py_coverage(self) -> None:
         output_file = path.join(self.outdir, 'python.txt')
@@ -232,6 +305,15 @@ class CoverageBuilder(Builder):
         with open(output_file, 'w', encoding="utf-8") as op:
             if self.config.coverage_write_headline:
                 write_header(op, 'Undocumented Python objects', '=')
+
+            if self.config.coverage_statistics_to_stdout:
+                self._write_py_statistics(sys.stdout)
+
+            if self.config.coverage_statistics_to_report:
+                write_header(op, 'Statistics')
+                self._write_py_statistics(op)
+                op.write('\n')
+
             keys = sorted(self.py_undoc.keys())
             for name in keys:
                 undoc = self.py_undoc[name]
@@ -297,7 +379,8 @@ class CoverageBuilder(Builder):
         # dump the coverage data to a pickle file too
         picklepath = path.join(self.outdir, 'undoc.pickle')
         with open(picklepath, 'wb') as dumpfile:
-            pickle.dump((self.py_undoc, self.c_undoc), dumpfile)
+            pickle.dump((self.py_undoc, self.c_undoc,
+                         self.py_undocumented, self.py_documented), dumpfile)
 
 
 def setup(app: Sphinx) -> dict[str, Any]:
@@ -310,6 +393,8 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('coverage_c_regexes', {}, False)
     app.add_config_value('coverage_ignore_c_items', {}, False)
     app.add_config_value('coverage_write_headline', True, False)
+    app.add_config_value('coverage_statistics_to_report', True, False, (bool,))
+    app.add_config_value('coverage_statistics_to_stdout', True, False, (bool,))
     app.add_config_value('coverage_skip_undoc_in_source', False, False)
     app.add_config_value('coverage_show_missing_items', False, False)
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}