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

sphinx/ext/napoleon/docstring.py

@@ -3,17 +3,20 @@
 from __future__ import annotations
 
 import collections
+import contextlib
 import inspect
 import re
 from functools import partial
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Any, Callable
 
-from sphinx.application import Sphinx
-from sphinx.config import Config as SphinxConfig
 from sphinx.locale import _, __
 from sphinx.util import logging
 from sphinx.util.typing import get_type_hints, stringify_annotation
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config as SphinxConfig
+
 logger = logging.getLogger(__name__)
 
 _directive_regex = re.compile(r'\.\. \S+::')
@@ -23,7 +26,9 @@ _numpy_section_regex = re.compile(r'^[=\-`:\'"~^_*+#<>]{2,}\s*$')
 _single_colon_regex = re.compile(r'(?<!:):(?!:)')
 _xref_or_code_regex = re.compile(
     r'((?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:`.+?`)|'
-    r'(?:``.+?``))')
+    r'(?:``.+?``)|'
+    r'(?::meta .+:.*)|'
+    r'(?:`.+?\s*(?<!\x00)<.*?>`))')
 _xref_regex = re.compile(
     r'(?:(?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:)?`.+?`)',
 )
@@ -67,17 +72,13 @@ class Deque(collections.deque):
             raise StopIteration
 
 
-def _convert_type_spec(_type: str, translations: dict[str, str] = {}) -> str:
+def _convert_type_spec(_type: str, translations: dict[str, str] | None = None) -> str:
     """Convert type specification to reference in reST."""
-    if _type in translations:
+    if translations is not None and _type in translations:
         return translations[_type]
-    else:
-        if _type == 'None':
-            return ':obj:`None`'
-        else:
-            return ':class:`%s`' % _type
-
-    return _type
+    if _type == 'None':
+        return ':py:obj:`None`'
+    return f':py:class:`{_type}`'
 
 
 class GoogleDocstring:
@@ -108,7 +109,7 @@ class GoogleDocstring:
         The object to which the docstring belongs.
     options : :class:`sphinx.ext.autodoc.Options`, optional
         The options given to the directive: an object with attributes
-        inherited_members, undoc_members, show_inheritance and noindex that
+        inherited_members, undoc_members, show_inheritance and no_index that
         are True if the flag option of same name was given to the auto
         directive.
 
@@ -156,12 +157,15 @@ class GoogleDocstring:
         obj: Any = None,
         options: Any = None,
     ) -> None:
-        self._config = config
         self._app = app
-
-        if not self._config:
+        if config:
+            self._config = config
+        elif app:
+            self._config = app.config
+        else:
             from sphinx.ext.napoleon import Config
-            self._config = self._app.config if self._app else Config()  # type: ignore
+
+            self._config = Config()  # type: ignore[assignment]
 
         if not what:
             if inspect.isclass(obj):
@@ -314,7 +318,7 @@ class GoogleDocstring:
                 for name in _name.split(","):
                     fields.append((name.strip(), _type, _desc))
             elif _name or _type or _desc:
-                fields.append((_name, _type, _desc,))
+                fields.append((_name, _type, _desc))
         return fields
 
     def _consume_inline_attribute(self) -> tuple[str, list[str]]:
@@ -347,7 +351,7 @@ class GoogleDocstring:
                 _type = _convert_type_spec(_type, self._config.napoleon_type_aliases or {})
 
             _desc = self.__class__(_desc, self._config).lines()
-            return [(_name, _type, _desc,)]
+            return [(_name, _type, _desc)]
         else:
             return []
 
@@ -606,10 +610,9 @@ class GoogleDocstring:
 
         if self._name and self._what in ('attribute', 'data', 'property'):
             res: list[str] = []
-            try:
+            with contextlib.suppress(StopIteration):
                 res = self._parse_attribute_docstring()
-            except StopIteration:
-                pass
+
             self._parsed_lines.extend(res)
             return
 
@@ -657,8 +660,9 @@ class GoogleDocstring:
                     lines.append(f':vartype {_name}: {_type}')
             else:
                 lines.append('.. attribute:: ' + _name)
-                if self._opt and 'noindex' in self._opt:
-                    lines.append('   :noindex:')
+                if self._opt:
+                    if 'no-index' in self._opt or 'noindex' in self._opt:
+                        lines.append('   :no-index:')
                 lines.append('')
 
                 fields = self._format_field('', '', _desc)
@@ -725,8 +729,9 @@ class GoogleDocstring:
         lines: list[str] = []
         for _name, _type, _desc in self._consume_fields(parse_type=False):
             lines.append('.. method:: %s' % _name)
-            if self._opt and 'noindex' in self._opt:
-                lines.append('   :noindex:')
+            if self._opt:
+                if 'no-index' in self._opt or 'noindex' in self._opt:
+                    lines.append('   :no-index:')
             if _desc:
                 lines.extend([''] + self._indent(_desc, 3))
             lines.append('')
@@ -1016,8 +1021,11 @@ def _token_type(token: str, location: str | None = None) -> str:
 
 
 def _convert_numpy_type_spec(
-    _type: str, location: str | None = None, translations: dict = {},
+    _type: str, location: str | None = None, translations: dict | None = None,
 ) -> str:
+    if translations is None:
+        translations = {}
+
     def convert_obj(obj, translations, default_translation):
         translation = translations.get(obj, obj)
 
@@ -1048,7 +1056,8 @@ def _convert_numpy_type_spec(
         "reference": lambda x: x,
     }
 
-    converted = "".join(converters.get(type_)(token) for token, type_ in types)
+    converted = "".join(converters.get(type_)(token)  # type: ignore[misc]
+                        for token, type_ in types)
 
     return converted
 
@@ -1081,7 +1090,7 @@ class NumpyDocstring(GoogleDocstring):
         The object to which the docstring belongs.
     options : :class:`sphinx.ext.autodoc.Options`, optional
         The options given to the directive: an object with attributes
-        inherited_members, undoc_members, show_inheritance and noindex that
+        inherited_members, undoc_members, show_inheritance and no_index that
         are True if the flag option of same name was given to the auto
         directive.
 
@@ -1273,7 +1282,7 @@ class NumpyDocstring(GoogleDocstring):
                     return g[2], g[1]
             raise ValueError("%s is not a item name" % text)
 
-        def push_item(name: str, rest: list[str]) -> None:
+        def push_item(name: str | None, rest: list[str]) -> None:
             if not name:
                 return
             name, role = parse_item_name(name)

sphinx/ext/todo.py

@@ -7,25 +7,28 @@ with a backlink to the original location.
 
 from __future__ import annotations
 
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Element, Node
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.admonitions import BaseAdmonition
 
 import sphinx
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.domains import Domain
-from sphinx.environment import BuildEnvironment
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
 from sphinx.util import logging, texescape
 from sphinx.util.docutils import SphinxDirective, new_document
-from sphinx.util.typing import OptionSpec
-from sphinx.writers.html import HTML5Translator
-from sphinx.writers.latex import LaTeXTranslator
+
+if TYPE_CHECKING:
+    from docutils.nodes import Element, Node
+
+    from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
+    from sphinx.util.typing import OptionSpec
+    from sphinx.writers.html import HTML5Translator
+    from sphinx.writers.latex import LaTeXTranslator
 
 logger = logging.getLogger(__name__)
 

sphinx/ext/viewcode.py

@@ -4,25 +4,30 @@ from __future__ import annotations
 
 import posixpath
 import traceback
+from importlib import import_module
 from os import path
-from typing import Any, Generator, Iterable, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
 
 import sphinx
 from sphinx import addnodes
-from sphinx.application import Sphinx
-from sphinx.builders import Builder
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import get_full_modname, logging
+from sphinx.util import logging
 from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterable
+
+    from sphinx.application import Sphinx
+    from sphinx.builders import Builder
+    from sphinx.environment import BuildEnvironment
+
 logger = logging.getLogger(__name__)
 
 
@@ -38,9 +43,22 @@ class viewcode_anchor(Element):
     """
 
 
-def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> str | None:
+def _get_full_modname(modname: str, attribute: str) -> str | None:
     try:
-        return get_full_modname(modname, attribute)
+        if modname is None:
+            # Prevents a TypeError: if the last getattr() call will return None
+            # then it's better to return it directly
+            return None
+        module = import_module(modname)
+
+        # Allow an attribute to have multiple parts and incidentally allow
+        # repeated .s in the attribute.
+        value = module
+        for attr in attribute.split('.'):
+            if attr:
+                value = getattr(value, attr)
+
+        return getattr(value, '__module__', None)
     except AttributeError:
         # sphinx.ext.viewcode can't follow class instance attribute
         # then AttributeError logging output only verbose mode.
@@ -69,10 +87,10 @@ def is_supported_builder(builder: Builder) -> bool:
 def doctree_read(app: Sphinx, doctree: Node) -> None:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
-        env._viewcode_modules = {}  # type: ignore
+        env._viewcode_modules = {}  # type: ignore[attr-defined]
 
     def has_tag(modname: str, fullname: str, docname: str, refname: str) -> bool:
-        entry = env._viewcode_modules.get(modname, None)  # type: ignore
+        entry = env._viewcode_modules.get(modname, None)  # type: ignore[attr-defined]
         if entry is False:
             return False
 
@@ -82,7 +100,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
                 analyzer = ModuleAnalyzer.for_module(modname)
                 analyzer.find_tags()
             except Exception:
-                env._viewcode_modules[modname] = False  # type: ignore
+                env._viewcode_modules[modname] = False  # type: ignore[attr-defined]
                 return False
 
             code = analyzer.code
@@ -92,7 +110,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
 
         if entry is None or entry[0] != code:
             entry = code, tags, {}, refname
-            env._viewcode_modules[modname] = entry  # type: ignore
+            env._viewcode_modules[modname] = entry  # type: ignore[attr-defined]
         _, tags, used, _ = entry
         if fullname in tags:
             used[fullname] = docname
@@ -115,7 +133,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
                     'viewcode-follow-imported', modname, fullname,
                 )
                 if not new_modname:
-                    new_modname = _get_full_modname(app, modname, fullname)
+                    new_modname = _get_full_modname(modname, fullname)
                 modname = new_modname
             if not modname:
                 continue
@@ -136,14 +154,14 @@ def env_merge_info(app: Sphinx, env: BuildEnvironment, docnames: Iterable[str],
         return
     # create a _viewcode_modules dict on the main environment
     if not hasattr(env, '_viewcode_modules'):
-        env._viewcode_modules = {}  # type: ignore
+        env._viewcode_modules = {}  # type: ignore[attr-defined]
     # now merge in the information from the subprocess
     for modname, entry in other._viewcode_modules.items():
-        if modname not in env._viewcode_modules:  # type: ignore
-            env._viewcode_modules[modname] = entry  # type: ignore
+        if modname not in env._viewcode_modules:  # type: ignore[attr-defined]
+            env._viewcode_modules[modname] = entry  # type: ignore[attr-defined]
         else:
-            if env._viewcode_modules[modname]:  # type: ignore
-                used = env._viewcode_modules[modname][2]  # type: ignore
+            if env._viewcode_modules[modname]:  # type: ignore[attr-defined]
+                used = env._viewcode_modules[modname][2]  # type: ignore[attr-defined]
                 for fullname, docname in entry[2].items():
                     if fullname not in used:
                         used[fullname] = docname
@@ -227,7 +245,7 @@ def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], Non
         return
     if not is_supported_builder(app.builder):
         return
-    highlighter = app.builder.highlighter  # type: ignore
+    highlighter = app.builder.highlighter  # type: ignore[attr-defined]
     urito = app.builder.get_relative_uri
 
     modnames = set(env._viewcode_modules)
@@ -250,7 +268,8 @@ def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], Non
             lexer = env.config.highlight_language
         else:
             lexer = 'python'
-        highlighted = highlighter.highlight_block(code, lexer, linenos=False)
+        linenos = 'inline' * env.config.viewcode_line_numbers
+        highlighted = highlighter.highlight_block(code, lexer, linenos=linenos)
         # split the code into lines
         lines = highlighted.splitlines()
         # split off wrap markup from the first line of the actual code
@@ -260,15 +279,16 @@ def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], Non
         # now that we have code lines (starting at index 1), insert anchors for
         # the collected tags (HACK: this only works if the tag boundaries are
         # properly nested!)
-        maxindex = len(lines) - 1
+        max_index = len(lines) - 1
+        link_text = _('[docs]')
         for name, docname in used.items():
             type, start, end = tags[name]
             backlink = urito(pagename, docname) + '#' + refname + '.' + name
-            lines[start] = (
-                '<div class="viewcode-block" id="%s"><a class="viewcode-back" '
-                'href="%s">%s</a>' % (name, backlink, _('[docs]')) +
-                lines[start])
-            lines[min(end, maxindex)] += '</div>'
+            lines[start] = (f'<div class="viewcode-block" id="{name}">\n'
+                            f'<a class="viewcode-back" href="{backlink}">{link_text}</a>\n'
+                            + lines[start])
+            lines[min(end, max_index)] += '</div>\n'
+
         # try to find parents (for submodules)
         parents = []
         parent = modname
@@ -324,6 +344,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('viewcode_import', None, False)
     app.add_config_value('viewcode_enable_epub', False, False)
     app.add_config_value('viewcode_follow_imported_members', True, False)
+    app.add_config_value('viewcode_line_numbers', False, 'env', (bool,))
     app.connect('doctree-read', doctree_read)
     app.connect('env-merge-info', env_merge_info)
     app.connect('env-purge-doc', env_purge_doc)

sphinx/extension.py

@@ -6,13 +6,13 @@ from typing import TYPE_CHECKING, Any
 
 from packaging.version import InvalidVersion, Version
 
-from sphinx.config import Config
 from sphinx.errors import VersionRequirementError
 from sphinx.locale import __
 from sphinx.util import logging
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.config import Config
 
 logger = logging.getLogger(__name__)
 

sphinx/highlighting.py

@@ -4,13 +4,11 @@ from __future__ import annotations
 
 from functools import partial
 from importlib import import_module
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from pygments import highlight
 from pygments.filters import ErrorToken
-from pygments.formatter import Formatter
 from pygments.formatters import HtmlFormatter, LatexFormatter
-from pygments.lexer import Lexer
 from pygments.lexers import (
     CLexer,
     PythonConsoleLexer,
@@ -20,7 +18,6 @@ from pygments.lexers import (
     get_lexer_by_name,
     guess_lexer,
 )
-from pygments.style import Style
 from pygments.styles import get_style_by_name
 from pygments.util import ClassNotFound
 
@@ -28,6 +25,11 @@ from sphinx.locale import __
 from sphinx.pygments_styles import NoneStyle, SphinxStyle
 from sphinx.util import logging, texescape
 
+if TYPE_CHECKING:
+    from pygments.formatter import Formatter
+    from pygments.lexer import Lexer
+    from pygments.style import Style
+
 logger = logging.getLogger(__name__)
 
 lexers: dict[str, Lexer] = {}
@@ -164,17 +166,23 @@ class PygmentsBridge:
         formatter = self.get_formatter(**kwargs)
         try:
             hlsource = highlight(source, lexer, formatter)
-        except ErrorToken:
+        except ErrorToken as err:
             # this is most probably not the selected language,
-            # so let it pass unhighlighted
+            # so let it pass un highlighted
             if lang == 'default':
-                pass  # automatic highlighting failed.
+                lang = 'none'  # automatic highlighting failed.
             else:
-                logger.warning(__('Could not lex literal_block %r as "%s". '
-                                  'Highlighting skipped.'), source, lang,
-                               type='misc', subtype='highlighting_failure',
-                               location=location)
-            lexer = self.get_lexer(source, 'none', opts, force, location)
+                logger.warning(
+                    __('Lexing literal_block %r as "%s" resulted in an error at token: %r. '
+                       'Retrying in relaxed mode.'),
+                    source, lang, str(err),
+                    type='misc', subtype='highlighting_failure',
+                    location=location)
+                if force:
+                    lang = 'none'
+                else:
+                    force = True
+            lexer = self.get_lexer(source, lang, opts, force, location)
             hlsource = highlight(source, lexer, formatter)
 
         if self.dest == 'html':

sphinx/io.py

@@ -6,16 +6,12 @@ from typing import TYPE_CHECKING, Any
 import docutils
 from docutils import nodes
 from docutils.core import Publisher
-from docutils.frontend import Values
 from docutils.io import FileInput, Input, NullOutput
-from docutils.parsers import Parser
 from docutils.readers import standalone
-from docutils.transforms import Transform
 from docutils.transforms.references import DanglingReferences
 from docutils.writers import UnfilteredWriter
 
 from sphinx import addnodes
-from sphinx.environment import BuildEnvironment
 from sphinx.transforms import AutoIndexUpgrader, DoctreeReadEvent, SphinxTransformer
 from sphinx.transforms.i18n import (
     Locale,
@@ -28,7 +24,12 @@ from sphinx.util.docutils import LoggingReporter
 from sphinx.versioning import UIDTransform
 
 if TYPE_CHECKING:
+    from docutils.frontend import Values
+    from docutils.parsers import Parser
+    from docutils.transforms import Transform
+
     from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
 
 
 logger = logging.getLogger(__name__)

sphinx/jinja2glue.py

@@ -5,15 +5,13 @@ from __future__ import annotations
 import pathlib
 from os import path
 from pprint import pformat
-from typing import TYPE_CHECKING, Any, Callable, Iterator
+from typing import TYPE_CHECKING, Any, Callable
 
 from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound
-from jinja2.environment import Environment
 from jinja2.sandbox import SandboxedEnvironment
 from jinja2.utils import open_if_exists
 
 from sphinx.application import TemplateBridge
-from sphinx.theming import Theme
 from sphinx.util import logging
 from sphinx.util.osutil import mtimes_of_files
 
@@ -23,7 +21,12 @@ except ImportError:
     from jinja2 import contextfunction as pass_context
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from jinja2.environment import Environment
+
     from sphinx.builders import Builder
+    from sphinx.theming import Theme
 
 
 def _tobool(val: str) -> bool:
@@ -54,7 +57,7 @@ def _todim(val: int | str) -> str:
         return 'initial'
     elif str(val).isdigit():
         return '0' if int(val) == 0 else '%spx' % val
-    return val  # type: ignore
+    return val  # type: ignore[return-value]
 
 
 def _slice_index(values: list, slices: int) -> Iterator[list]:
@@ -121,20 +124,22 @@ class SphinxFileSystemLoader(FileSystemLoader):
         for searchpath in self.searchpath:
             filename = str(pathlib.Path(searchpath, template))
             f = open_if_exists(filename)
-            if f is None:
-                continue
-            with f:
-                contents = f.read().decode(self.encoding)
-
-            mtime = path.getmtime(filename)
-
-            def uptodate() -> bool:
-                try:
-                    return path.getmtime(filename) == mtime
-                except OSError:
-                    return False
-            return contents, filename, uptodate
-        raise TemplateNotFound(template)
+            if f is not None:
+                break
+        else:
+            raise TemplateNotFound(template)
+
+        with f:
+            contents = f.read().decode(self.encoding)
+
+        mtime = path.getmtime(filename)
+
+        def uptodate() -> bool:
+            try:
+                return path.getmtime(filename) == mtime
+            except OSError:
+                return False
+        return contents, filename, uptodate
 
 
 class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
@@ -192,7 +197,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         if use_i18n:
             self.environment.install_gettext_translations(builder.app.translator)
 
-    def render(self, template: str, context: dict) -> str:  # type: ignore
+    def render(self, template: str, context: dict) -> str:  # type: ignore[override]
         return self.environment.get_template(template).render(context)
 
     def render_string(self, source: str, context: dict) -> str:

sphinx/locale/__init__.py

@@ -5,7 +5,11 @@ from __future__ import annotations
 import locale
 from gettext import NullTranslations, translation
 from os import path
-from typing import Any, Callable, Iterable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from typing import Any, Callable
 
 
 class _TranslationProxy:
@@ -140,13 +144,15 @@ _LOCALE_DIR = path.abspath(path.dirname(__file__))
 
 
 def init_console(
-    locale_dir: str = _LOCALE_DIR,
+    locale_dir: str | None = None,
     catalog: str = 'sphinx',
 ) -> tuple[NullTranslations, bool]:
     """Initialize locale for console.
 
     .. versionadded:: 1.8
     """
+    if locale_dir is None:
+        locale_dir = _LOCALE_DIR
     try:
         # encoding is ignored
         language, _ = locale.getlocale(locale.LC_MESSAGES)