Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/ext/imgconverter.py

@@ -14,6 +14,8 @@ from sphinx.transforms.post_transforms.images import ImageConverter
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    import os
+
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
 
@@ -37,42 +39,57 @@ class ImagemagickConverter(ImageConverter):
             subprocess.run(args, capture_output=True, check=True)
             return True
         except OSError as exc:
-            logger.warning(__(
-                "Unable to run the image conversion command %r. "
-                "'sphinx.ext.imgconverter' requires ImageMagick by default. "
-                "Ensure it is installed, or set the 'image_converter' option "
-                "to a custom conversion command.\n\n"
-                "Traceback: %s",
-            ), self.config.image_converter, exc)
+            logger.warning(
+                __(
+                    'Unable to run the image conversion command %r. '
+                    "'sphinx.ext.imgconverter' requires ImageMagick by default. "
+                    "Ensure it is installed, or set the 'image_converter' option "
+                    'to a custom conversion command.\n\n'
+                    'Traceback: %s',
+                ),
+                self.config.image_converter,
+                exc,
+            )
             return False
         except CalledProcessError as exc:
-            logger.warning(__('convert exited with error:\n'
-                              '[stderr]\n%r\n[stdout]\n%r'),
-                           exc.stderr, exc.stdout)
+            logger.warning(
+                __('convert exited with error:\n[stderr]\n%r\n[stdout]\n%r'),
+                exc.stderr,
+                exc.stdout,
+            )
             return False
 
-    def convert(self, _from: str, _to: str) -> bool:
+    def convert(
+        self, _from: str | os.PathLike[str], _to: str | os.PathLike[str]
+    ) -> bool:
         """Converts the image to expected one."""
         try:
             # append an index 0 to source filename to pick up the first frame
             # (or first page) of image (ex. Animation GIF, PDF)
-            _from += '[0]'
+            from_ = f'{_from}[0]'
 
-            args = ([
-                self.config.image_converter, *self.config.image_converter_args, _from, _to,
-            ])
+            args = [
+                self.config.image_converter,
+                *self.config.image_converter_args,
+                from_,
+                _to,
+            ]
             logger.debug('Invoking %r ...', args)
             subprocess.run(args, capture_output=True, check=True)
             return True
         except OSError:
-            logger.warning(__('convert command %r cannot be run, '
-                              'check the image_converter setting'),
-                           self.config.image_converter)
+            logger.warning(
+                __(
+                    'convert command %r cannot be run, check the image_converter setting'
+                ),
+                self.config.image_converter,
+            )
             return False
         except CalledProcessError as exc:
-            raise ExtensionError(__('convert exited with error:\n'
-                                    '[stderr]\n%r\n[stdout]\n%r') %
-                                 (exc.stderr, exc.stdout)) from exc
+            raise ExtensionError(
+                __('convert exited with error:\n[stderr]\n%r\n[stdout]\n%r')
+                % (exc.stderr, exc.stdout)
+            ) from exc
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
@@ -80,14 +97,20 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     if sys.platform == 'win32':
         # On Windows, we use Imagemagik v7 by default to avoid the trouble for
         # convert.exe bundled with Windows.
-        app.add_config_value('image_converter', 'magick', 'env')
-        app.add_config_value('image_converter_args', ['convert'], 'env')
+        app.add_config_value('image_converter', 'magick', 'env', types=frozenset({str}))
+        app.add_config_value(
+            'image_converter_args', ['convert'], 'env', types=frozenset({list, tuple})
+        )
     else:
         # On other platform, we use Imagemagick v6 by default.  Especially,
         # Debian/Ubuntu are still based of v6.  So we can't use "magick" command
         # for these platforms.
-        app.add_config_value('image_converter', 'convert', 'env')
-        app.add_config_value('image_converter_args', [], 'env')
+        app.add_config_value(
+            'image_converter', 'convert', 'env', types=frozenset({str})
+        )
+        app.add_config_value(
+            'image_converter_args', [], 'env', types=frozenset({list, tuple})
+        )
 
     return {
         'version': sphinx.__display_version__,

sphinx/ext/imgmath.py

@@ -6,12 +6,14 @@ __all__ = ()
 
 import base64
 import contextlib
+import os
+import os.path
 import re
 import shutil
 import subprocess
 import tempfile
 from hashlib import sha1
-from os import path
+from pathlib import Path
 from subprocess import CalledProcessError
 from typing import TYPE_CHECKING
 
@@ -23,31 +25,29 @@ from sphinx.errors import SphinxError
 from sphinx.locale import _, __
 from sphinx.util import logging
 from sphinx.util.math import get_node_equation_number, wrap_displaymath
-from sphinx.util.osutil import ensuredir
 from sphinx.util.png import read_png_depth, write_png_depth
 from sphinx.util.template import LaTeXRenderer
 
 if TYPE_CHECKING:
-    import os
-
     from docutils.nodes import Element
 
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
     from sphinx.config import Config
+    from sphinx.util._pathlib import _StrPath
     from sphinx.util.typing import ExtensionMetadata
     from sphinx.writers.html5 import HTML5Translator
 
 logger = logging.getLogger(__name__)
 
-templates_path = path.join(package_dir, 'templates', 'imgmath')
+templates_path = package_dir.joinpath('templates', 'imgmath')
 
 
 class MathExtError(SphinxError):
     category = 'Math extension error'
 
     def __init__(
-        self, msg: str, stderr: str | None = None, stdout: str | None = None,
+        self, msg: str, stderr: str | None = None, stdout: str | None = None
     ) -> None:
         if stderr:
             msg += '\n[stderr]\n' + stderr
@@ -67,10 +67,9 @@ depthsvg_re = re.compile(r'.*, depth=(.*)pt')
 depthsvgcomment_re = re.compile(r'<!-- DEPTH=(-?\d+) -->')
 
 
-def read_svg_depth(filename: str) -> int | None:
-    """Read the depth from comment at last line of SVG file
-    """
-    with open(filename, encoding="utf-8") as f:
+def read_svg_depth(filename: str | os.PathLike[str]) -> int | None:
+    """Read the depth from comment at last line of SVG file"""
+    with open(filename, encoding='utf-8') as f:
         for line in f:  # NoQA: B007
             pass
         # Only last line is checked
@@ -80,23 +79,24 @@ def read_svg_depth(filename: str) -> int | None:
         return None
 
 
-def write_svg_depth(filename: str, depth: int) -> None:
-    """Write the depth to SVG file as a comment at end of file
-    """
-    with open(filename, 'a', encoding="utf-8") as f:
+def write_svg_depth(filename: Path, depth: int) -> None:
+    """Write the depth to SVG file as a comment at end of file"""
+    with open(filename, 'a', encoding='utf-8') as f:
         f.write('\n<!-- DEPTH=%s -->' % depth)
 
 
-def generate_latex_macro(image_format: str,
-                         math: str,
-                         config: Config,
-                         confdir: str | os.PathLike[str] = '') -> str:
+def generate_latex_macro(
+    image_format: str,
+    math: str,
+    config: Config,
+    confdir: _StrPath,
+) -> str:
     """Generate LaTeX macro."""
     variables = {
         'fontsize': config.imgmath_font_size,
-        'baselineskip': int(round(config.imgmath_font_size * 1.2)),
+        'baselineskip': round(config.imgmath_font_size * 1.2),
         'preamble': config.imgmath_latex_preamble,
-        # the dvips option is important when imgmath_latex in ["xelatex", "tectonic"],
+        # the dvips option is important when imgmath_latex in {"xelatex", "tectonic"},
         # it has no impact when imgmath_latex="latex"
         'tightpage': '' if image_format == 'png' else ',dvips,tightpage',
         'math': math,
@@ -109,14 +109,14 @@ def generate_latex_macro(image_format: str,
 
     for template_dir in config.templates_path:
         for template_suffix in ('.jinja', '_t'):
-            template = path.join(confdir, template_dir, template_name + template_suffix)
-            if path.exists(template):
+            template = confdir / template_dir / (template_name + template_suffix)
+            if template.exists():
                 return LaTeXRenderer().render(template, variables)
 
-    return LaTeXRenderer(templates_path).render(template_name + '.jinja', variables)
+    return LaTeXRenderer([templates_path]).render(template_name + '.jinja', variables)
 
 
-def ensure_tempdir(builder: Builder) -> str:
+def ensure_tempdir(builder: Builder) -> Path:
     """Create temporary directory.
 
     use only one tempdir per build -- the use of a directory is cleaner
@@ -124,19 +124,19 @@ def ensure_tempdir(builder: Builder) -> str:
     just removing the whole directory (see cleanup_tempdir)
     """
     if not hasattr(builder, '_imgmath_tempdir'):
-        builder._imgmath_tempdir = tempfile.mkdtemp()  # type: ignore[attr-defined]
+        builder._imgmath_tempdir = Path(tempfile.mkdtemp())  # type: ignore[attr-defined]
 
     return builder._imgmath_tempdir  # type: ignore[attr-defined]
 
 
-def compile_math(latex: str, builder: Builder) -> str:
+def compile_math(latex: str, builder: Builder) -> Path:
     """Compile LaTeX macros for math to DVI."""
     tempdir = ensure_tempdir(builder)
-    filename = path.join(tempdir, 'math.tex')
+    filename = tempdir / 'math.tex'
     with open(filename, 'w', encoding='utf-8') as f:
         f.write(latex)
 
-    imgmath_latex_name = path.basename(builder.config.imgmath_latex)
+    imgmath_latex_name = os.path.basename(builder.config.imgmath_latex)
 
     # build latex command; old versions of latex don't have the
     # --output-directory option, so we have to manually chdir to the
@@ -149,16 +149,21 @@ def compile_math(latex: str, builder: Builder) -> str:
     command.append('math.tex')
 
     try:
-        subprocess.run(command, capture_output=True, cwd=tempdir, check=True,
-                       encoding='ascii')
+        subprocess.run(
+            command, capture_output=True, cwd=tempdir, check=True, encoding='ascii'
+        )
         if imgmath_latex_name in {'xelatex', 'tectonic'}:
-            return path.join(tempdir, 'math.xdv')
+            return tempdir / 'math.xdv'
         else:
-            return path.join(tempdir, 'math.dvi')
+            return tempdir / 'math.dvi'
     except OSError as exc:
-        logger.warning(__('LaTeX command %r cannot be run (needed for math '
-                          'display), check the imgmath_latex setting'),
-                       builder.config.imgmath_latex)
+        logger.warning(
+            __(
+                'LaTeX command %r cannot be run (needed for math '
+                'display), check the imgmath_latex setting'
+            ),
+            builder.config.imgmath_latex,
+        )
         raise InvokeError from exc
     except CalledProcessError as exc:
         msg = 'latex exited with error'
@@ -171,15 +176,22 @@ def convert_dvi_to_image(command: list[str], name: str) -> tuple[str, str]:
         ret = subprocess.run(command, capture_output=True, check=True, encoding='ascii')
         return ret.stdout, ret.stderr
     except OSError as exc:
-        logger.warning(__('%s command %r cannot be run (needed for math '
-                          'display), check the imgmath_%s setting'),
-                       name, command[0], name)
+        logger.warning(
+            __(
+                '%s command %r cannot be run (needed for math '
+                'display), check the imgmath_%s setting'
+            ),
+            name,
+            command[0],
+            name,
+        )
         raise InvokeError from exc
     except CalledProcessError as exc:
-        raise MathExtError('%s exited with error' % name, exc.stderr, exc.stdout) from exc
+        msg = f'{name} exited with error'
+        raise MathExtError(msg, exc.stderr, exc.stdout) from exc
 
 
-def convert_dvi_to_png(dvipath: str, builder: Builder, out_path: str) -> int | None:
+def convert_dvi_to_png(dvipath: Path, builder: Builder, out_path: Path) -> int | None:
     """Convert DVI file to PNG image."""
     name = 'dvipng'
     command = [builder.config.imgmath_dvipng, '-o', out_path, '-T', 'tight', '-z9']
@@ -202,7 +214,7 @@ def convert_dvi_to_png(dvipath: str, builder: Builder, out_path: str) -> int | N
     return depth
 
 
-def convert_dvi_to_svg(dvipath: str, builder: Builder, out_path: str) -> int | None:
+def convert_dvi_to_svg(dvipath: Path, builder: Builder, out_path: Path) -> int | None:
     """Convert DVI file to SVG image."""
     name = 'dvisvgm'
     command = [builder.config.imgmath_dvisvgm, '-o', out_path]
@@ -226,7 +238,7 @@ def convert_dvi_to_svg(dvipath: str, builder: Builder, out_path: str) -> int | N
 def render_math(
     self: HTML5Translator,
     math: str,
-) -> tuple[str | None, int | None]:
+) -> tuple[_StrPath | None, int | None]:
     """Render the LaTeX math expression *math* using latex and dvipng or
     dvisvgm.
 
@@ -245,15 +257,16 @@ def render_math(
         unsupported_format_msg = 'imgmath_image_format must be either "png" or "svg"'
         raise MathExtError(unsupported_format_msg)
 
-    latex = generate_latex_macro(image_format,
-                                 math,
-                                 self.builder.config,
-                                 self.builder.confdir)
+    latex = generate_latex_macro(
+        image_format, math, self.builder.config, self.builder.confdir
+    )
 
-    filename = f"{sha1(latex.encode(), usedforsecurity=False).hexdigest()}.{image_format}"
-    generated_path = path.join(self.builder.outdir, self.builder.imagedir, 'math', filename)
-    ensuredir(path.dirname(generated_path))
-    if path.isfile(generated_path):
+    filename = (
+        f'{sha1(latex.encode(), usedforsecurity=False).hexdigest()}.{image_format}'
+    )
+    generated_path = self.builder.outdir / self.builder.imagedir / 'math' / filename
+    generated_path.parent.mkdir(parents=True, exist_ok=True)
+    if generated_path.is_file():
         if image_format == 'png':
             depth = read_png_depth(generated_path)
         elif image_format == 'svg':
@@ -261,8 +274,9 @@ def render_math(
         return generated_path, depth
 
     # if latex or dvipng (dvisvgm) has failed once, don't bother to try again
-    if hasattr(self.builder, '_imgmath_warned_latex') or \
-       hasattr(self.builder, '_imgmath_warned_image_translator'):
+    latex_failed = hasattr(self.builder, '_imgmath_warned_latex')
+    trans_failed = hasattr(self.builder, '_imgmath_warned_image_translator')
+    if latex_failed or trans_failed:
         return None, None
 
     # .tex -> .dvi
@@ -285,9 +299,10 @@ def render_math(
     return generated_path, depth
 
 
-def render_maths_to_base64(image_format: str, generated_path: str) -> str:
-    with open(generated_path, "rb") as f:
-        encoded = base64.b64encode(f.read()).decode(encoding='utf-8')
+def render_maths_to_base64(image_format: str, generated_path: Path) -> str:
+    with open(generated_path, 'rb') as f:
+        content = f.read()
+    encoded = base64.b64encode(content).decode(encoding='utf-8')
     if image_format == 'png':
         return f'data:image/png;base64,{encoded}'
     if image_format == 'svg':
@@ -308,12 +323,12 @@ def clean_up_files(app: Sphinx, exc: Exception) -> None:
         # in embed mode, the images are still generated in the math output dir
         # to be shared across workers, but are not useful to the final document
         with contextlib.suppress(Exception):
-            shutil.rmtree(path.join(app.builder.outdir, app.builder.imagedir, 'math'))
+            shutil.rmtree(app.builder.outdir / app.builder.imagedir / 'math')
 
 
 def get_tooltip(self: HTML5Translator, node: Element) -> str:
     if self.builder.config.imgmath_add_tooltips:
-        return ' alt="%s"' % self.encode(node.astext()).strip()
+        return f' alt="{self.encode(node.astext()).strip()}"'
     return ''
 
 
@@ -322,33 +337,35 @@ def html_visit_math(self: HTML5Translator, node: nodes.math) -> None:
         rendered_path, depth = render_math(self, '$' + node.astext() + '$')
     except MathExtError as exc:
         msg = str(exc)
-        sm = nodes.system_message(msg, type='WARNING', level=2,
-                                  backrefs=[], source=node.astext())
+        sm = nodes.system_message(
+            msg, type='WARNING', level=2, backrefs=[], source=node.astext()
+        )
         sm.walkabout(self)
         logger.warning(__('display latex %r: %s'), node.astext(), msg)
         raise nodes.SkipNode from exc
 
     if rendered_path is None:
         # something failed -- use text-only as a bad substitute
-        self.body.append('<span class="math">%s</span>' %
-                         self.encode(node.astext()).strip())
+        self.body.append(
+            f'<span class="math">{self.encode(node.astext()).strip()}</span>'
+        )
     else:
         if self.builder.config.imgmath_embed:
             image_format = self.builder.config.imgmath_image_format.lower()
             img_src = render_maths_to_base64(image_format, rendered_path)
         else:
-            bname = path.basename(rendered_path)
-            relative_path = path.join(self.builder.imgpath, 'math', bname)
-            img_src = relative_path.replace(path.sep, '/')
-        c = f'<img class="math" src="{img_src}"' + get_tooltip(self, node)
-        if depth is not None:
-            c += f' style="vertical-align: {-depth:d}px"'
-        self.body.append(c + '/>')
+            bname = os.path.basename(rendered_path)
+            relative_path = Path(self.builder.imgpath, 'math', bname)
+            img_src = relative_path.as_posix()
+        align = f' style="vertical-align: {-depth:d}px"' if depth is not None else ''
+        self.body.append(
+            f'<img class="math" src="{img_src}"{get_tooltip(self, node)}{align}/>'
+        )
     raise nodes.SkipNode
 
 
 def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> None:
-    if node['nowrap']:
+    if node.get('no-wrap', node.get('nowrap', False)):
         latex = node.astext()
     else:
         latex = wrap_displaymath(node.astext(), None, False)
@@ -356,8 +373,9 @@ def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> Non
         rendered_path, depth = render_math(self, latex)
     except MathExtError as exc:
         msg = str(exc)
-        sm = nodes.system_message(msg, type='WARNING', level=2,
-                                  backrefs=[], source=node.astext())
+        sm = nodes.system_message(
+            msg, type='WARNING', level=2, backrefs=[], source=node.astext()
+        )
         sm.walkabout(self)
         logger.warning(__('inline latex %r: %s'), node.astext(), msg)
         raise nodes.SkipNode from exc
@@ -371,39 +389,51 @@ def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> Non
 
     if rendered_path is None:
         # something failed -- use text-only as a bad substitute
-        self.body.append('<span class="math">%s</span></p>\n</div>' %
-                         self.encode(node.astext()).strip())
+        self.body.append(
+            f'<span class="math">{self.encode(node.astext()).strip()}</span></p>\n</div>'
+        )
     else:
         if self.builder.config.imgmath_embed:
             image_format = self.builder.config.imgmath_image_format.lower()
             img_src = render_maths_to_base64(image_format, rendered_path)
         else:
-            bname = path.basename(rendered_path)
-            relative_path = path.join(self.builder.imgpath, 'math', bname)
-            img_src = relative_path.replace(path.sep, '/')
-        self.body.append(f'<img src="{img_src}"' + get_tooltip(self, node) +
-                         '/></p>\n</div>')
+            bname = os.path.basename(rendered_path)
+            relative_path = Path(self.builder.imgpath, 'math', bname)
+            img_src = relative_path.as_posix()
+        self.body.append(f'<img src="{img_src}"{get_tooltip(self, node)}/></p>\n</div>')
     raise nodes.SkipNode
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_html_math_renderer('imgmath',
-                               (html_visit_math, None),
-                               (html_visit_displaymath, None))
-
-    app.add_config_value('imgmath_image_format', 'png', 'html')
-    app.add_config_value('imgmath_dvipng', 'dvipng', 'html')
-    app.add_config_value('imgmath_dvisvgm', 'dvisvgm', 'html')
-    app.add_config_value('imgmath_latex', 'latex', 'html')
-    app.add_config_value('imgmath_use_preview', False, 'html')
-    app.add_config_value('imgmath_dvipng_args',
-                         ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'],
-                         'html')
-    app.add_config_value('imgmath_dvisvgm_args', ['--no-fonts'], 'html')
-    app.add_config_value('imgmath_latex_args', [], 'html')
-    app.add_config_value('imgmath_latex_preamble', '', 'html')
-    app.add_config_value('imgmath_add_tooltips', True, 'html')
-    app.add_config_value('imgmath_font_size', 12, 'html')
-    app.add_config_value('imgmath_embed', False, 'html', bool)
+    app.add_html_math_renderer(
+        'imgmath',
+        inline_renderers=(html_visit_math, None),
+        block_renderers=(html_visit_displaymath, None),
+    )
+
+    app.add_config_value('imgmath_image_format', 'png', 'html', types=frozenset({str}))
+    app.add_config_value('imgmath_dvipng', 'dvipng', 'html', types=frozenset({str}))
+    app.add_config_value('imgmath_dvisvgm', 'dvisvgm', 'html', types=frozenset({str}))
+    app.add_config_value('imgmath_latex', 'latex', 'html', types=frozenset({str}))
+    app.add_config_value('imgmath_use_preview', False, 'html', types=frozenset({bool}))
+    app.add_config_value(
+        'imgmath_dvipng_args',
+        ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'],
+        'html',
+        types=frozenset({list}),
+    )
+    app.add_config_value(
+        'imgmath_dvisvgm_args', ['--no-fonts'], 'html', types=frozenset({list, tuple})
+    )
+    app.add_config_value(
+        'imgmath_latex_args', [], 'html', types=frozenset({list, tuple})
+    )
+    app.add_config_value('imgmath_latex_preamble', '', 'html', types=frozenset({str}))
+    app.add_config_value('imgmath_add_tooltips', True, 'html', types=frozenset({bool}))
+    app.add_config_value('imgmath_font_size', 12, 'html', types=frozenset({int}))
+    app.add_config_value('imgmath_embed', False, 'html', types=frozenset({bool}))
     app.connect('build-finished', clean_up_files)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }