Sphinx 7.2.6__py3-none-any.whl → 7.3.0__py3-none-any.whl

sphinx/ext/viewcode.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import operator
 import posixpath
 import traceback
 from importlib import import_module
@@ -22,11 +23,12 @@ from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterable
+    from collections.abc import Iterable, Iterator
 
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -79,9 +81,7 @@ def is_supported_builder(builder: Builder) -> bool:
         return False
     if builder.name == 'singlehtml':
         return False
-    if builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
-        return False
-    return True
+    return not (builder.name.startswith('epub') and not builder.config.viewcode_enable_epub)
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
@@ -185,6 +185,7 @@ def env_purge_doc(app: Sphinx, env: BuildEnvironment, docname: str) -> None:
 
 class ViewcodeAnchorTransform(SphinxPostTransform):
     """Convert or remove viewcode_anchor nodes depends on builder."""
+
     default_priority = 100
 
     def run(self, **kwargs: Any) -> None:
@@ -239,7 +240,7 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Iterator[tuple[str, dict[str, Any], str]]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return
@@ -254,7 +255,7 @@ def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], Non
             sorted(env._viewcode_modules.items()),
             __('highlighting module code... '), "blue",
             len(env._viewcode_modules),
-            app.verbosity, lambda x: x[0]):
+            app.verbosity, operator.itemgetter(0)):
         if not entry:
             continue
         if not should_generate_module_page(app, modname):
@@ -340,11 +341,11 @@ def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], Non
     yield (posixpath.join(OUTPUT_DIRNAME, 'index'), context, 'page.html')
 
 
-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,))
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_config_value('viewcode_import', None, '')
+    app.add_config_value('viewcode_enable_epub', False, '')
+    app.add_config_value('viewcode_follow_imported_members', True, '')
+    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

@@ -13,6 +13,7 @@ from sphinx.util import logging
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.config import Config
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -21,7 +22,7 @@ class Extension:
     def __init__(self, name: str, module: Any, **kwargs: Any) -> None:
         self.name = name
         self.module = module
-        self.metadata = kwargs
+        self.metadata: ExtensionMetadata = kwargs  # type: ignore[assignment]
         self.version = kwargs.pop('version', 'unknown version')
 
         # The extension supports parallel read or not.  The default value
@@ -50,8 +51,13 @@ def verify_needs_extensions(app: Sphinx, config: Config) -> None:
     for extname, reqversion in config.needs_extensions.items():
         extension = app.extensions.get(extname)
         if extension is None:
-            logger.warning(__('The %s extension is required by needs_extensions settings, '
-                              'but it is not loaded.'), extname)
+            logger.warning(
+                __(
+                    'The %s extension is required by needs_extensions settings, '
+                    'but it is not loaded.'
+                ),
+                extname,
+            )
             continue
 
         fulfilled = True
@@ -66,13 +72,17 @@ def verify_needs_extensions(app: Sphinx, config: Config) -> None:
                     fulfilled = False
 
         if not fulfilled:
-            raise VersionRequirementError(__('This project needs the extension %s at least in '
-                                             'version %s and therefore cannot be built with '
-                                             'the loaded version (%s).') %
-                                          (extname, reqversion, extension.version))
+            raise VersionRequirementError(
+                __(
+                    'This project needs the extension %s at least in '
+                    'version %s and therefore cannot be built with '
+                    'the loaded version (%s).'
+                )
+                % (extname, reqversion, extension.version)
+            )
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('config-inited', verify_needs_extensions, priority=800)
 
     return {

sphinx/highlighting.py

@@ -42,9 +42,7 @@ lexer_classes: dict[str, type[Lexer] | partial[Lexer]] = {
 }
 
 
-escape_hl_chars = {ord('\\'): '\\PYGZbs{}',
-                   ord('{'): '\\PYGZob{}',
-                   ord('}'): '\\PYGZcb{}'}
+escape_hl_chars = {ord('\\'): '\\PYGZbs{}', ord('{'): '\\PYGZob{}', ord('}'): '\\PYGZcb{}'}
 
 # used if Pygments is available
 # MEMO: no use of \protected here to avoid having to do hyperref extras,
@@ -57,7 +55,7 @@ escape_hl_chars = {ord('\\'): '\\PYGZbs{}',
 # MEMO: the Pygments escapes with \char`\<char> syntax, if the document
 # uses old OT1 font encoding, work correctly only in monospace font.
 # MEMO: the Pygmentize output mark-up is always with a {} after.
-_LATEX_ADD_STYLES = r'''
+_LATEX_ADD_STYLES = r"""
 % Sphinx redefinitions
 % Originally to obtain a straight single quote via package textcomp, then
 % to fix problems for the 5.0.0 inline code highlighting (captions!).
@@ -82,7 +80,7 @@ _LATEX_ADD_STYLES = r'''
 % use \protected to allow syntax highlighting in captions
 \protected\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+{\PYG@do{#2}}}
 \makeatother
-'''
+"""
 
 
 class PygmentsBridge:
@@ -91,8 +89,9 @@ class PygmentsBridge:
     html_formatter = HtmlFormatter
     latex_formatter = LatexFormatter
 
-    def __init__(self, dest: str = 'html', stylename: str = 'sphinx',
-                 latex_engine: str | None = None) -> None:
+    def __init__(
+        self, dest: str = 'html', stylename: str = 'sphinx', latex_engine: str | None = None
+    ) -> None:
         self.dest = dest
         self.latex_engine = latex_engine
 
@@ -104,8 +103,8 @@ class PygmentsBridge:
             self.formatter = self.latex_formatter
             self.formatter_args['commandprefix'] = 'PYG'
 
-    def get_style(self, stylename: str) -> Style:
-        if stylename is None or stylename == 'sphinx':
+    def get_style(self, stylename: str) -> type[Style]:
+        if not stylename or stylename == 'sphinx':
             return SphinxStyle
         elif stylename == 'none':
             return NoneStyle
@@ -119,8 +118,14 @@ class PygmentsBridge:
         kwargs.update(self.formatter_args)
         return self.formatter(**kwargs)
 
-    def get_lexer(self, source: str, lang: str, opts: dict | None = None,
-                  force: bool = False, location: Any = None) -> Lexer:
+    def get_lexer(
+        self,
+        source: str,
+        lang: str,
+        opts: dict | None = None,
+        force: bool = False,
+        location: Any = None,
+    ) -> Lexer:
         if not opts:
             opts = {}
 
@@ -146,8 +151,9 @@ class PygmentsBridge:
                 else:
                     lexer = get_lexer_by_name(lang, **opts)
             except ClassNotFound:
-                logger.warning(__('Pygments lexer name %r is not known'), lang,
-                               location=location)
+                logger.warning(
+                    __('Pygments lexer name %r is not known'), lang, location=location
+                )
                 lexer = lexer_classes['none'](**opts)
 
         if not force:
@@ -155,8 +161,15 @@ class PygmentsBridge:
 
         return lexer
 
-    def highlight_block(self, source: str, lang: str, opts: dict | None = None,
-                        force: bool = False, location: Any = None, **kwargs: Any) -> str:
+    def highlight_block(
+        self,
+        source: str,
+        lang: str,
+        opts: dict | None = None,
+        force: bool = False,
+        location: Any = None,
+        **kwargs: Any,
+    ) -> str:
         if not isinstance(source, str):
             source = source.decode()
 
@@ -173,11 +186,17 @@ class PygmentsBridge:
                 lang = 'none'  # automatic highlighting failed.
             else:
                 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)
+                    __(
+                        '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:

sphinx/io.py

@@ -1,4 +1,5 @@
 """Input/Output files"""
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
@@ -46,6 +47,7 @@ class SphinxBaseReader(standalone.Reader):
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         from sphinx.application import Sphinx
+
         if len(args) > 0 and isinstance(args[0], Sphinx):
             self._app = args[0]
             self._env = self._app.env
@@ -54,7 +56,7 @@ class SphinxBaseReader(standalone.Reader):
         super().__init__(*args, **kwargs)
 
     def setup(self, app: Sphinx) -> None:
-        self._app = app      # hold application object only for compatibility
+        self._app = app  # hold application object only for compatibility
         self._env = app.env
 
     def get_transforms(self) -> list[type[Transform]]:
@@ -96,9 +98,9 @@ class SphinxStandaloneReader(SphinxBaseReader):
         self.transforms = self.transforms + app.registry.get_transforms()
         super().setup(app)
 
-    def read(self, source: Input, parser: Parser, settings: Values) -> nodes.document:
+    def read(self, source: Input, parser: Parser, settings: Values) -> nodes.document:  # type: ignore[type-arg]
         self.source = source
-        if not self.parser:
+        if not self.parser:  # type: ignore[has-type]
             self.parser = parser
         self.settings = settings
         self.input = self.read_source(settings.env)
@@ -128,9 +130,15 @@ class SphinxI18nReader(SphinxBaseReader):
         super().setup(app)
 
         self.transforms = self.transforms + app.registry.get_transforms()
-        unused = [PreserveTranslatableMessages, Locale, RemoveTranslatableInline,
-                  AutoIndexUpgrader, SphinxDomains, DoctreeReadEvent,
-                  UIDTransform]
+        unused = [
+            PreserveTranslatableMessages,
+            Locale,
+            RemoveTranslatableInline,
+            AutoIndexUpgrader,
+            SphinxDomains,
+            DoctreeReadEvent,
+            UIDTransform,
+        ]
         for transform in unused:
             if transform in self.transforms:
                 self.transforms.remove(transform)
@@ -152,6 +160,7 @@ def SphinxDummySourceClass(source: Any, *args: Any, **kwargs: Any) -> Any:
 
 class SphinxFileInput(FileInput):
     """A basic FileInput for Sphinx."""
+
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         kwargs['error_handler'] = 'sphinx'
         super().__init__(*args, **kwargs)
@@ -170,7 +179,7 @@ def create_publisher(app: Sphinx, filetype: str) -> Publisher:
         #   CommonMarkParser.
         from docutils.parsers.rst import Parser as RSTParser
 
-        parser.settings_spec = RSTParser.settings_spec
+        parser.settings_spec = RSTParser.settings_spec  # type: ignore[misc]
 
     pub = Publisher(
         reader=reader,
@@ -180,7 +189,7 @@ def create_publisher(app: Sphinx, filetype: str) -> Publisher:
         destination=NullOutput(),
     )
     # Propagate exceptions by default when used programmatically:
-    defaults = {"traceback": True, **app.env.settings}
+    defaults = {'traceback': True, **app.env.settings}
     # Set default settings
     if docutils.__version_info__[:2] >= (0, 19):
         pub.get_settings(**defaults)

sphinx/jinja2glue.py

@@ -8,17 +8,12 @@ from typing import TYPE_CHECKING, Any, Callable
 
 from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
-from jinja2.utils import open_if_exists
+from jinja2.utils import open_if_exists, pass_context
 
 from sphinx.application import TemplateBridge
 from sphinx.util import logging
 from sphinx.util.osutil import mtimes_of_files
 
-try:
-    from jinja2.utils import pass_context
-except ImportError:
-    from jinja2 import contextfunction as pass_context
-
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
@@ -60,7 +55,7 @@ def _todim(val: int | str) -> str:
 
 
 def _slice_index(values: list, slices: int) -> Iterator[list]:
-    seq = list(values)
+    seq = values.copy()
     length = 0
     for value in values:
         length += 1 + len(value[1][1])  # count includes subitems
@@ -70,7 +65,7 @@ def _slice_index(values: list, slices: int) -> Iterator[list]:
         count = 0
         start = offset
         if slices == slice_number + 1:  # last column
-            offset = len(seq)  # noqa: SIM113
+            offset = len(seq)  # NoQA: SIM113
         else:
             for value in values[offset:]:
                 count += 1 + len(value[1][1])
@@ -100,6 +95,7 @@ class idgen:
     def __next__(self) -> int:
         self.id += 1
         return self.id
+
     next = __next__  # Python 2/Jinja compatibility
 
 
@@ -138,6 +134,7 @@ class SphinxFileSystemLoader(FileSystemLoader):
                 return path.getmtime(filename) == mtime
             except OSError:
                 return False
+
         return contents, filename, uptodate
 
 
@@ -170,8 +167,9 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         # prepend explicit template paths
         self.templatepathlen = len(builder.config.templates_path)
         if builder.config.templates_path:
-            cfg_templates_path = [path.join(builder.confdir, tp)
-                                  for tp in builder.config.templates_path]
+            cfg_templates_path = [
+                path.join(builder.confdir, tp) for tp in builder.config.templates_path
+            ]
             pathchain[0:0] = cfg_templates_path
             loaderchain[0:0] = cfg_templates_path
 
@@ -183,8 +181,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
 
         use_i18n = builder.app.translator is not None
         extensions = ['jinja2.ext.i18n'] if use_i18n else []
-        self.environment = SandboxedEnvironment(loader=self,
-                                                extensions=extensions)
+        self.environment = SandboxedEnvironment(loader=self, extensions=extensions)
         self.environment.filters['tobool'] = _tobool
         self.environment.filters['toint'] = _toint
         self.environment.filters['todim'] = _todim
@@ -194,7 +191,10 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         self.environment.globals['accesskey'] = pass_context(accesskey)
         self.environment.globals['idgen'] = idgen
         if use_i18n:
-            self.environment.install_gettext_translations(builder.app.translator)
+            # ``install_gettext_translations`` is injected by the ``jinja2.ext.i18n`` extension
+            self.environment.install_gettext_translations(  # type: ignore[attr-defined]
+                builder.app.translator
+            )
 
     def render(self, template: str, context: dict) -> str:  # type: ignore[override]
         return self.environment.get_template(template).render(context)
@@ -211,11 +211,12 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         loaders = self.loaders
         # exclamation mark starts search from theme
         if template.startswith('!'):
-            loaders = loaders[self.templatepathlen:]
+            loaders = loaders[self.templatepathlen :]
             template = template[1:]
         for loader in loaders:
             try:
                 return loader.get_source(environment, template)
             except TemplateNotFound:
                 pass
-        raise TemplateNotFound(template)
+        msg = f'{template!r} not found in {self.environment.loader.pathchain}'  # type: ignore[union-attr]
+        raise TemplateNotFound(msg)

sphinx/locale/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import locale
+import sys
 from gettext import NullTranslations, translation
 from os import path
 from typing import TYPE_CHECKING
@@ -17,6 +18,7 @@ class _TranslationProxy:
     The proxy implementation attempts to be as complete as possible, so that
     the lazy objects should mostly work as expected, for example for sorting.
     """
+
     __slots__ = '_catalogue', '_namespace', '_message'
 
     def __init__(self, catalogue: str, namespace: str, message: str) -> None:
@@ -50,8 +52,10 @@ class _TranslationProxy:
         try:
             return f'i{self.__str__()!r}'
         except Exception:
-            return (self.__class__.__name__
-                    + f'({self._catalogue}, {self._namespace}, {self._message})')
+            return (
+                self.__class__.__name__
+                + f'({self._catalogue}, {self._namespace}, {self._message})'
+            )
 
     def __add__(self, other: str) -> str:
         return self.__str__() + other
@@ -71,22 +75,22 @@ class _TranslationProxy:
     def __rmul__(self, other: Any) -> str:
         return other * self.__str__()
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.__str__())
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return self.__str__() == other
 
-    def __lt__(self, string):
+    def __lt__(self, string: str) -> bool:
         return self.__str__() < string
 
-    def __contains__(self, char):
+    def __contains__(self, char: str) -> bool:
         return char in self.__str__()
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.__str__())
 
-    def __getitem__(self, index):
+    def __getitem__(self, index: int | slice) -> str:
         return self.__str__()[index]
 
 
@@ -153,13 +157,15 @@ def init_console(
     """
     if locale_dir is None:
         locale_dir = _LOCALE_DIR
-    try:
-        # encoding is ignored
-        language, _ = locale.getlocale(locale.LC_MESSAGES)
-    except AttributeError:
-        # LC_MESSAGES is not always defined. Fallback to the default language
-        # in case it is not.
+    if sys.platform == 'win32':
         language = None
+    else:
+        try:
+            # encoding is ignored
+            language, _ = locale.getlocale(locale.LC_MESSAGES)
+        except AttributeError:
+            # Fallback to the default language in case LC_MESSAGES is not defined.
+            language = None
     return init([locale_dir], language, catalog, 'console')
 
 
@@ -196,10 +202,11 @@ def get_translation(catalog: str, namespace: str = 'general') -> Callable[[str],
 
     .. versionadded:: 1.8
     """
+
     def gettext(message: str) -> str:
         if not is_translator_registered(catalog, namespace):
             # not initialized yet
-            return _TranslationProxy(catalog, namespace, message)  # type: ignore[return-value]  # noqa: E501
+            return _TranslationProxy(catalog, namespace, message)  # type: ignore[return-value]  # NoQA: E501
         else:
             translator = get_translator(catalog, namespace)
             return translator.gettext(message)
@@ -219,13 +226,13 @@ __ = get_translation('sphinx', 'console')
 # labels
 admonitionlabels = {
     'attention': _('Attention'),
-    'caution':   _('Caution'),
-    'danger':    _('Danger'),
-    'error':     _('Error'),
-    'hint':      _('Hint'),
+    'caution': _('Caution'),
+    'danger': _('Danger'),
+    'error': _('Error'),
+    'hint': _('Hint'),
     'important': _('Important'),
-    'note':      _('Note'),
-    'seealso':   _('See also'),
-    'tip':       _('Tip'),
-    'warning':   _('Warning'),
+    'note': _('Note'),
+    'seealso': _('See also'),
+    'tip': _('Tip'),
+    'warning': _('Warning'),
 }