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

sphinx/builders/html/_assets.py

@@ -3,13 +3,15 @@ from __future__ import annotations
 import os
 import warnings
 import zlib
-from typing import TYPE_CHECKING, Any, NoReturn
+from functools import cache
+from typing import TYPE_CHECKING
 
 from sphinx.deprecation import RemovedInSphinx90Warning
 from sphinx.errors import ThemeError
 
 if TYPE_CHECKING:
     from pathlib import Path
+    from typing import Any, NoReturn
 
 
 class _CascadingStyleSheet:
@@ -172,9 +174,14 @@ def _file_checksum(outdir: Path, filename: str | os.PathLike[str]) -> str:
     if '?' in filename:
         msg = f'Local asset file paths must not contain query strings: {filename!r}'
         raise ThemeError(msg)
+    return _file_checksum_inner(outdir.joinpath(filename).resolve())
+
+
+@cache
+def _file_checksum_inner(file: Path) -> str:
     try:
         # Remove all carriage returns to avoid checksum differences
-        content = outdir.joinpath(filename).read_bytes().translate(None, b'\r')
+        content = file.read_bytes().translate(None, b'\r')
     except FileNotFoundError:
         return ''
     if not content:

sphinx/builders/html/_build_info.py

@@ -65,6 +65,9 @@ class BuildInfo:
             self.config_hash == other.config_hash and self.tags_hash == other.tags_hash
         )
 
+    def __hash__(self) -> int:
+        return hash((self.config_hash, self.tags_hash))
+
     def dump(self, filename: Path, /) -> None:
         build_info = (
             '# Sphinx build info version 1\n'

sphinx/builders/latex/__init__.py

@@ -3,14 +3,16 @@
 from __future__ import annotations
 
 import os
+import os.path
 import warnings
-from os import path
-from typing import TYPE_CHECKING, Any
+from pathlib import Path
+from typing import TYPE_CHECKING
 
 from docutils.frontend import OptionParser
 
-import sphinx.builders.latex.nodes  # NoQA: F401,E501  # Workaround: import this before writer to avoid ImportError
+import sphinx.builders.latex.nodes  # NoQA: F401  # Workaround: import this before writer to avoid ImportError
 from sphinx import addnodes, highlighting, package_dir
+from sphinx._cli.util.colour import darkgreen
 from sphinx.builders import Builder
 from sphinx.builders.latex.constants import (
     ADDITIONAL_SETTINGS,
@@ -19,12 +21,11 @@ from sphinx.builders.latex.constants import (
 )
 from sphinx.builders.latex.theming import Theme, ThemeFactory
 from sphinx.builders.latex.util import ExtBabel
-from sphinx.config import ENUM, Config
+from sphinx.config import ENUM
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import NoUri, SphinxError
 from sphinx.locale import _, __
 from sphinx.util import logging, texescape
-from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import SphinxFileOutput, new_document
 from sphinx.util.fileutil import copy_asset_file
@@ -39,10 +40,12 @@ from docutils import nodes  # isort:skip
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Set
+    from typing import Any
 
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
+    from sphinx.config import Config
     from sphinx.util.typing import ExtensionMetadata
 
 XINDY_LANG_OPTIONS = {
@@ -102,15 +105,13 @@ XINDY_LANG_OPTIONS = {
     'el-polyton': '-L greek-polytonic -C utf8 ',
 }  # fmt: skip
 
-XINDY_CYRILLIC_SCRIPTS = ['be', 'bg', 'mk', 'mn', 'ru', 'sr', 'sh', 'uk']
+XINDY_CYRILLIC_SCRIPTS = frozenset({'be', 'bg', 'mk', 'mn', 'ru', 'sr', 'sh', 'uk'})
 
 logger = logging.getLogger(__name__)
 
 
 class LaTeXBuilder(Builder):
-    """
-    Builds LaTeX output to create PDF.
-    """
+    """Builds LaTeX output to create PDF."""
 
     name = 'latex'
     format = 'latex'
@@ -166,10 +167,7 @@ class LaTeXBuilder(Builder):
             docname = entry[0]
             if docname not in self.env.all_docs:
                 logger.warning(
-                    __(
-                        '"latex_documents" config value references unknown '
-                        'document %s'
-                    ),
+                    __('"latex_documents" config value references unknown document %s'),
                     docname,
                 )
                 continue
@@ -202,7 +200,7 @@ class LaTeXBuilder(Builder):
             self.context['date'] = format_date(today_fmt, language=self.config.language)
 
         if self.config.latex_logo:
-            self.context['logofilename'] = path.basename(self.config.latex_logo)
+            self.context['logofilename'] = os.path.basename(self.config.latex_logo)
 
         # for compatibilities
         self.context['indexname'] = _('Index')
@@ -213,7 +211,7 @@ class LaTeXBuilder(Builder):
     def update_context(self) -> None:
         """Update template variables for .tex file just before writing."""
         # Apply extension settings to context
-        registry = self.app.registry
+        registry = self.env._registry
         self.context['packages'] = registry.latex_packages
         self.context['packages_after_hyperref'] = registry.latex_packages_after_hyperref
 
@@ -249,7 +247,7 @@ class LaTeXBuilder(Builder):
                 )
             else:
                 self.context['textgreek'] = ''
-            if self.context['substitutefont'] == '':
+            if not self.context['substitutefont']:
                 self.context['fontsubstitution'] = ''
 
         # 'babel' key is public and user setting must be obeyed
@@ -279,7 +277,7 @@ class LaTeXBuilder(Builder):
 
     def write_stylesheet(self) -> None:
         highlighter = highlighting.PygmentsBridge('latex', self.config.pygments_style)
-        stylesheet = path.join(self.outdir, 'sphinxhighlight.sty')
+        stylesheet = self.outdir / 'sphinxhighlight.sty'
         with open(stylesheet, 'w', encoding='utf-8') as f:
             f.write('\\NeedsTeXFormat{LaTeX2e}[1995/12/01]\n')
             f.write(
@@ -320,7 +318,7 @@ class LaTeXBuilder(Builder):
             if len(entry) > 5:
                 toctree_only = entry[5]
             destination = SphinxFileOutput(
-                destination_path=path.join(self.outdir, targetname),
+                destination_path=self.outdir / targetname,
                 encoding='utf-8',
                 overwrite_if_changed=True,
             )
@@ -420,8 +418,6 @@ class LaTeXBuilder(Builder):
                         nodes.Text(')'),
                     ))
                     break
-            else:
-                pass
             pendingnode.replace_self(newnodes)
         return largetree
 
@@ -446,11 +442,11 @@ class LaTeXBuilder(Builder):
             'xindy_lang_option': xindy_lang_option,
             'xindy_cyrillic': xindy_cyrillic,
         }
-        staticdirname = path.join(package_dir, 'texinputs')
-        for filename in os.listdir(staticdirname):
-            if not filename.startswith('.'):
+        static_dir_name = package_dir / 'texinputs'
+        for filename in Path(static_dir_name).iterdir():
+            if not filename.name.startswith('.'):
                 copy_asset_file(
-                    path.join(staticdirname, filename),
+                    static_dir_name / filename,
                     self.outdir,
                     context=context,
                     force=True,
@@ -458,9 +454,9 @@ class LaTeXBuilder(Builder):
 
         # use pre-1.6.x Makefile for make latexpdf on Windows
         if os.name == 'nt':
-            staticdirname = path.join(package_dir, 'texinputs_win')
+            static_dir_name = package_dir / 'texinputs_win'
             copy_asset_file(
-                path.join(staticdirname, 'Makefile.jinja'),
+                static_dir_name / 'Makefile.jinja',
                 self.outdir,
                 context=context,
                 force=True,
@@ -469,7 +465,7 @@ class LaTeXBuilder(Builder):
     @progress_message(__('copying additional files'))
     def copy_latex_additional_files(self) -> None:
         for filename in self.config.latex_additional_files:
-            logger.info(' ' + filename, nonl=True)
+            logger.info(' %s', filename, nonl=True)
             source = self.confdir / filename
             copyfile(
                 source,
@@ -479,7 +475,7 @@ class LaTeXBuilder(Builder):
 
     def copy_image_files(self) -> None:
         if self.images:
-            stringify_func = ImageAdapter(self.app.env).get_original_image_uri
+            stringify_func = ImageAdapter(self.env).get_original_image_uri
             for src in status_iterator(
                 self.images,
                 __('copying images... '),
@@ -498,15 +494,15 @@ class LaTeXBuilder(Builder):
                 except Exception as err:
                     logger.warning(
                         __('cannot copy image file %r: %s'),
-                        path.join(self.srcdir, src),
+                        self.srcdir / src,
                         err,
                     )
         if self.config.latex_logo:
-            if not path.isfile(path.join(self.confdir, self.config.latex_logo)):
+            source = self.confdir / self.config.latex_logo
+            if not source.is_file():
                 raise SphinxError(
                     __('logo file %r does not exist') % self.config.latex_logo
                 )
-            source = self.confdir / self.config.latex_logo
             copyfile(
                 source,
                 self.outdir / source.name,
@@ -525,11 +521,8 @@ class LaTeXBuilder(Builder):
         if self.context['babel'] or self.context['polyglossia']:
             context['addtocaptions'] = r'\addto\captions%s' % self.babel.get_language()
 
-        filename = path.join(
-            package_dir, 'templates', 'latex', 'sphinxmessages.sty.jinja'
-        )
         copy_asset_file(
-            filename,
+            package_dir.joinpath('templates', 'latex', 'sphinxmessages.sty.jinja'),
             self.outdir,
             context=context,
             renderer=LaTeXRenderer(),
@@ -555,7 +548,7 @@ def validate_latex_theme_options(app: Sphinx, config: Config) -> None:
 
 def install_packages_for_ja(app: Sphinx) -> None:
     """Install packages for Japanese."""
-    if app.config.language == 'ja' and app.config.latex_engine in ('platex', 'uplatex'):
+    if app.config.language == 'ja' and app.config.latex_engine in {'platex', 'uplatex'}:
         app.add_latex_package('pxjahyper', after_hyperref=True)
 
 
@@ -613,27 +606,44 @@ def setup(app: Sphinx) -> ExtensionMetadata:
         'latex_engine',
         default_latex_engine,
         '',
-        ENUM('pdflatex', 'xelatex', 'lualatex', 'platex', 'uplatex'),
+        types=ENUM('pdflatex', 'xelatex', 'lualatex', 'platex', 'uplatex'),
+    )
+    app.add_config_value(
+        'latex_documents', default_latex_documents, '', types=frozenset({list, tuple})
+    )
+    app.add_config_value('latex_logo', None, '', types=frozenset({str}))
+    app.add_config_value('latex_appendices', [], '', types=frozenset({list, tuple}))
+    app.add_config_value(
+        'latex_use_latex_multicolumn', False, '', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'latex_use_xindy', default_latex_use_xindy, '', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'latex_toplevel_sectioning',
+        None,
+        '',
+        types=ENUM(None, 'part', 'chapter', 'section'),
+    )
+    app.add_config_value(
+        'latex_domain_indices', True, '', types=frozenset({frozenset, list, set, tuple})
     )
-    app.add_config_value('latex_documents', default_latex_documents, '')
-    app.add_config_value('latex_logo', None, '', str)
-    app.add_config_value('latex_appendices', [], '')
-    app.add_config_value('latex_use_latex_multicolumn', False, '')
-    app.add_config_value('latex_use_xindy', default_latex_use_xindy, '', bool)
+    app.add_config_value('latex_show_urls', 'no', '', types=frozenset({str}))
+    app.add_config_value('latex_show_pagerefs', False, '', types=frozenset({bool}))
+    app.add_config_value('latex_elements', {}, '', types=frozenset({dict}))
+    app.add_config_value(
+        'latex_additional_files', [], '', types=frozenset({list, tuple})
+    )
+    app.add_config_value(
+        'latex_table_style', ['booktabs', 'colorrows'], '', types=frozenset({list})
+    )
+    app.add_config_value('latex_theme', 'manual', '', types=frozenset({str}))
+    app.add_config_value('latex_theme_options', {}, '', types=frozenset({dict}))
+    app.add_config_value('latex_theme_path', [], '', types=frozenset({list}))
+
     app.add_config_value(
-        'latex_toplevel_sectioning', None, '', ENUM(None, 'part', 'chapter', 'section')
+        'latex_docclass', default_latex_docclass, '', types=frozenset({dict})
     )
-    app.add_config_value('latex_domain_indices', True, '', types={set, list})
-    app.add_config_value('latex_show_urls', 'no', '')
-    app.add_config_value('latex_show_pagerefs', False, '')
-    app.add_config_value('latex_elements', {}, '')
-    app.add_config_value('latex_additional_files', [], '')
-    app.add_config_value('latex_table_style', ['booktabs', 'colorrows'], '', list)
-    app.add_config_value('latex_theme', 'manual', '', str)
-    app.add_config_value('latex_theme_options', {}, '')
-    app.add_config_value('latex_theme_path', [], '', list)
-
-    app.add_config_value('latex_docclass', default_latex_docclass, '')
 
     return {
         'version': 'builtin',

sphinx/builders/latex/constants.py

@@ -2,15 +2,18 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING
 
-PDFLATEX_DEFAULT_FONTPKG = r'''
+if TYPE_CHECKING:
+    from typing import Any
+
+PDFLATEX_DEFAULT_FONTPKG = r"""
 \usepackage{tgtermes}
 \usepackage{tgheros}
 \renewcommand{\ttdefault}{txtt}
-'''
+"""
 
-PDFLATEX_DEFAULT_FONTSUBSTITUTION = r'''
+PDFLATEX_DEFAULT_FONTSUBSTITUTION = r"""
 \expandafter\ifx\csname T@LGR\endcsname\relax
 \else
 % LGR was declared as font encoding
@@ -32,9 +35,9 @@ PDFLATEX_DEFAULT_FONTSUBSTITUTION = r'''
   \substitutefont{X2}{\sfdefault}{cmss}
   \substitutefont{X2}{\ttdefault}{cmtt}
 \fi
-'''
+"""
 
-XELATEX_DEFAULT_FONTPKG = r'''
+XELATEX_DEFAULT_FONTPKG = r"""
 \setmainfont{FreeSerif}[
   Extension      = .otf,
   UprightFont    = *,
@@ -56,7 +59,7 @@ XELATEX_DEFAULT_FONTPKG = r'''
   BoldFont       = *Bold,
   BoldItalicFont = *BoldOblique,
 ]
-'''
+"""
 
 XELATEX_GREEK_DEFAULT_FONTPKG = (
     XELATEX_DEFAULT_FONTPKG
@@ -117,7 +120,7 @@ DEFAULT_SETTINGS: dict[str, Any] = {
     'figure_align':    'htbp',
     'tocdepth':        '',
     'secnumdepth':     '',
-}
+}  # fmt: skip
 
 ADDITIONAL_SETTINGS: dict[Any, dict[str, Any]] = {
     'pdflatex': {
@@ -204,12 +207,12 @@ ADDITIONAL_SETTINGS: dict[Any, dict[str, Any]] = {
     ('xelatex', 'el'): {
         'fontpkg':      XELATEX_GREEK_DEFAULT_FONTPKG,
     },
-}
+}  # fmt: skip
 
 
-SHORTHANDOFF = r'''
+SHORTHANDOFF = r"""
 \ifdefined\shorthandoff
   \ifnum\catcode`\=\string=\active\shorthandoff{=}\fi
   \ifnum\catcode`\"=\active\shorthandoff{"}\fi
 \fi
-'''
+"""

sphinx/builders/latex/nodes.py

@@ -1,5 +1,7 @@
 """Additional nodes for LaTeX writer."""
 
+from __future__ import annotations
+
 from docutils import nodes
 
 

sphinx/builders/latex/theming.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import configparser
-from os import path
 from typing import TYPE_CHECKING
 
 from sphinx.errors import ThemeError
@@ -11,6 +10,8 @@ from sphinx.locale import __
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    from pathlib import Path
+
     from sphinx.application import Sphinx
     from sphinx.config import Config
 
@@ -55,7 +56,7 @@ class BuiltInTheme(Theme):
         else:
             self.docclass = config.latex_docclass.get('manual', 'report')
 
-        if name in ('manual', 'howto'):
+        if name in {'manual', 'howto'}:
             self.wrapperclass = 'sphinx' + name
         else:
             self.wrapperclass = name
@@ -74,10 +75,10 @@ class UserTheme(Theme):
     REQUIRED_CONFIG_KEYS = ['docclass', 'wrapperclass']
     OPTIONAL_CONFIG_KEYS = ['papersize', 'pointsize', 'toplevel_sectioning']
 
-    def __init__(self, name: str, filename: str) -> None:
+    def __init__(self, name: str, filename: Path) -> None:
         super().__init__(name)
         self.config = configparser.RawConfigParser()
-        self.config.read(path.join(filename), encoding='utf-8')
+        self.config.read(filename, encoding='utf-8')
 
         for key in self.REQUIRED_CONFIG_KEYS:
             try:
@@ -103,9 +104,7 @@ class ThemeFactory:
 
     def __init__(self, app: Sphinx) -> None:
         self.themes: dict[str, Theme] = {}
-        self.theme_paths = [
-            path.join(app.srcdir, p) for p in app.config.latex_theme_path
-        ]
+        self.theme_paths = [app.srcdir / p for p in app.config.latex_theme_path]
         self.config = app.config
         self.load_builtin_themes(app.config)
 
@@ -127,8 +126,8 @@ class ThemeFactory:
     def find_user_theme(self, name: str) -> Theme | None:
         """Find a theme named as *name* from latex_theme_path."""
         for theme_path in self.theme_paths:
-            config_path = path.join(theme_path, name, 'theme.conf')
-            if path.isfile(config_path):
+            config_path = theme_path / name / 'theme.conf'
+            if config_path.is_file():
                 try:
                     return UserTheme(name, config_path)
                 except ThemeError as exc:

sphinx/builders/latex/transforms.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
 from docutils.transforms.references import Substitutions
@@ -21,6 +21,8 @@ from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util.nodes import NodeMatcher
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from docutils.nodes import Element, Node
 
     from sphinx.application import Sphinx
@@ -151,7 +153,7 @@ class ShowUrlsTransform(SphinxPostTransform):
                     break
 
             # assign new footnote number
-            old_label = cast(nodes.label, footnote[0])
+            old_label = cast('nodes.label', footnote[0])
             old_label.replace_self(nodes.label('', str(num)))
             if old_label in footnote['names']:
                 footnote['names'].remove(old_label.astext())
@@ -455,7 +457,7 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor):
         number = node.astext().strip()
         docname = node['docname']
         if (docname, number) in self.appeared:
-            footnote = self.appeared[(docname, number)]
+            footnote = self.appeared[docname, number]
             footnote['referred'] = True
 
             mark = footnotemark('', number, refid=node['refid'])
@@ -471,7 +473,7 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor):
                 node.replace_self(footnote)
                 footnote.walkabout(self)
 
-            self.appeared[(docname, number)] = footnote
+            self.appeared[docname, number] = footnote
         raise nodes.SkipNode
 
     def get_footnote_by_reference(
@@ -566,7 +568,7 @@ class MathReferenceTransform(SphinxPostTransform):
     def run(self, **kwargs: Any) -> None:
         equations = self.env.domains.math_domain.data['objects']
         for node in self.document.findall(addnodes.pending_xref):
-            if node['refdomain'] == 'math' and node['reftype'] in ('eq', 'numref'):
+            if node['refdomain'] == 'math' and node['reftype'] in {'eq', 'numref'}:
                 docname, _ = equations.get(node['reftarget'], (None, None))
                 if docname:
                     refnode = math_reference(