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

sphinx/ext/githubpages.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-import contextlib
-import os
 import urllib.parse
 from typing import TYPE_CHECKING
 
@@ -39,20 +37,22 @@ def create_nojekyll_and_cname(app: Sphinx, env: BuildEnvironment) -> None:
         return
 
     app.builder.outdir.joinpath('.nojekyll').touch()
-    cname_path = os.path.join(app.builder.outdir, 'CNAME')
+    cname_path = app.builder.outdir / 'CNAME'
 
     domain = _get_domain_from_url(app.config.html_baseurl)
     # Filter out GitHub Pages domains, as they do not require CNAME files.
-    if domain and not domain.endswith(".github.io"):
-        with open(cname_path, 'w', encoding="utf-8") as f:
+    if domain and not domain.endswith('.github.io'):
+        with open(cname_path, 'w', encoding='utf-8') as f:
             # NOTE: don't write a trailing newline. The `CNAME` file that's
             # auto-generated by the GitHub UI doesn't have one.
             f.write(domain)
     else:
-        with contextlib.suppress(FileNotFoundError):
-            os.unlink(cname_path)
+        cname_path.unlink(missing_ok=True)
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('env-updated', create_nojekyll_and_cname)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }

sphinx/ext/graphviz.py

@@ -1,17 +1,15 @@
-"""Allow graphviz-formatted graphs to be included inline in generated documents.
-"""
+"""Allow graphviz-formatted graphs to be included inline in generated documents."""
 
 from __future__ import annotations
 
-import posixpath
+import os.path
 import re
 import subprocess
 import xml.etree.ElementTree as ET
 from hashlib import sha1
 from itertools import chain
-from os import path
 from subprocess import CalledProcessError
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING
 from urllib.parse import urlsplit, urlunsplit
 
 from docutils import nodes
@@ -21,12 +19,14 @@ import sphinx
 from sphinx.errors import SphinxError
 from sphinx.locale import _, __
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.i18n import search_image_for_language
 from sphinx.util.nodes import set_source_info
-from sphinx.util.osutil import ensuredir
 
 if TYPE_CHECKING:
+    from typing import Any, ClassVar
+
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
@@ -62,14 +62,15 @@ class ClickableMapDefinition:
     def parse(self, dot: str) -> None:
         matched = self.maptag_re.match(self.content[0])
         if not matched:
-            raise GraphvizError('Invalid clickable map file found: %s' % self.filename)
+            msg = f'Invalid clickable map file found: {self.filename}'
+            raise GraphvizError(msg)
 
         self.id = matched.group(1)
         if self.id == '%3':
             # graphviz generates wrong ID if graph name not specified
             # https://gitlab.com/graphviz/graphviz/issues/1327
             hashed = sha1(dot.encode(), usedforsecurity=False).hexdigest()
-            self.id = 'grapviz%s' % hashed[-10:]
+            self.id = f'grapviz{hashed[-10:]}'
             self.content[0] = self.content[0].replace('%3', self.id)
 
         for line in self.content:
@@ -91,7 +92,9 @@ class graphviz(nodes.General, nodes.Inline, nodes.Element):
     pass
 
 
-def figure_wrapper(directive: SphinxDirective, node: graphviz, caption: str) -> nodes.figure:
+def figure_wrapper(
+    directive: SphinxDirective, node: graphviz, caption: str
+) -> nodes.figure:
     figure_node = nodes.figure('', node)
     if 'align' in node:
         figure_node['align'] = node.attributes.pop('align')
@@ -109,9 +112,7 @@ def align_spec(argument: Any) -> str:
 
 
 class Graphviz(SphinxDirective):
-    """
-    Directive to insert arbitrary dot markup.
-    """
+    """Directive to insert arbitrary dot markup."""
 
     has_content = True
     required_arguments = 0
@@ -131,9 +132,15 @@ class Graphviz(SphinxDirective):
         if self.arguments:
             document = self.state.document
             if self.content:
-                return [document.reporter.warning(
-                    __('Graphviz directive cannot have both content and '
-                       'a filename argument'), line=self.lineno)]
+                return [
+                    document.reporter.warning(
+                        __(
+                            'Graphviz directive cannot have both content and '
+                            'a filename argument'
+                        ),
+                        line=self.lineno,
+                    )
+                ]
             argument = search_image_for_language(self.arguments[0], self.env)
             rel_filename, filename = self.env.relfn2path(argument)
             self.env.note_dependency(rel_filename)
@@ -141,16 +148,23 @@ class Graphviz(SphinxDirective):
                 with open(filename, encoding='utf-8') as fp:
                     dotcode = fp.read()
             except OSError:
-                return [document.reporter.warning(
-                    __('External Graphviz file %r not found or reading '
-                       'it failed') % filename, line=self.lineno)]
+                return [
+                    document.reporter.warning(
+                        __('External Graphviz file %r not found or reading it failed')
+                        % filename,
+                        line=self.lineno,
+                    )
+                ]
         else:
             dotcode = '\n'.join(self.content)
             rel_filename = None
             if not dotcode.strip():
-                return [self.state_machine.reporter.warning(
-                    __('Ignoring "graphviz" directive without content.'),
-                    line=self.lineno)]
+                return [
+                    self.state_machine.reporter.warning(
+                        __('Ignoring "graphviz" directive without content.'),
+                        line=self.lineno,
+                    )
+                ]
         node = graphviz()
         node['code'] = dotcode
         node['options'] = {'docname': self.env.docname}
@@ -178,9 +192,7 @@ class Graphviz(SphinxDirective):
 
 
 class GraphvizSimple(SphinxDirective):
-    """
-    Directive to insert arbitrary dot markup.
-    """
+    """Directive to insert arbitrary dot markup."""
 
     has_content = True
     required_arguments = 1
@@ -198,8 +210,8 @@ class GraphvizSimple(SphinxDirective):
 
     def run(self) -> list[Node]:
         node = graphviz()
-        node['code'] = '%s %s {\n%s\n}\n' % \
-                       (self.name, self.arguments[0], '\n'.join(self.content))
+        dot_code = '\n'.join(self.content)
+        node['code'] = f'{self.name} {self.arguments[0]} {{\n{dot_code}\n}}\n'
         node['options'] = {'docname': self.env.docname}
         if 'graphviz_dot' in self.options:
             node['options']['graphviz_dot'] = self.options['graphviz_dot']
@@ -221,9 +233,12 @@ class GraphvizSimple(SphinxDirective):
             return [figure]
 
 
-def fix_svg_relative_paths(self: HTML5Translator | LaTeXTranslator | TexinfoTranslator,
-                           filepath: str) -> None:
+def fix_svg_relative_paths(
+    self: HTML5Translator | LaTeXTranslator | TexinfoTranslator,
+    filepath: str | os.PathLike[str],
+) -> None:
     """Change relative links in generated svg files to be relative to imgpath."""
+    env = self.builder.env
     tree = ET.parse(filepath)  # NoQA: S314
     root = tree.getroot()
     ns = {'svg': 'http://www.w3.org/2000/svg', 'xlink': 'http://www.w3.org/1999/xlink'}
@@ -239,15 +254,15 @@ def fix_svg_relative_paths(self: HTML5Translator | LaTeXTranslator | TexinfoTran
             # not a relative link
             continue
 
-        docname = self.builder.env.path2doc(self.document["source"])
+        docname = env.path2doc(self.document['source'])
         if docname is None:
             # This shouldn't happen!
             continue
-        doc_dir = self.builder.app.outdir.joinpath(docname).resolve().parent
+        doc_dir = self.builder.outdir.joinpath(docname).resolve().parent
 
         old_path = doc_dir / rel_uri
         img_path = doc_dir / self.builder.imgpath
-        new_path = path.relpath(old_path, start=img_path)
+        new_path = os.path.relpath(old_path, start=img_path)
         modified_url = urlunsplit((scheme, hostname, new_path, query, fragment))
 
         element.set(href_name, modified_url)
@@ -257,61 +272,78 @@ def fix_svg_relative_paths(self: HTML5Translator | LaTeXTranslator | TexinfoTran
         tree.write(filepath)
 
 
-def render_dot(self: HTML5Translator | LaTeXTranslator | TexinfoTranslator,
-               code: str, options: dict, format: str,
-               prefix: str = 'graphviz', filename: str | None = None,
-               ) -> tuple[str | None, str | None]:
+def render_dot(
+    self: HTML5Translator | LaTeXTranslator | TexinfoTranslator,
+    code: str,
+    options: dict[str, Any],
+    format: str,
+    prefix: str = 'graphviz',
+    filename: str | None = None,
+) -> tuple[_StrPath | None, _StrPath | None]:
     """Render graphviz code into a PNG or PDF output file."""
     graphviz_dot = options.get('graphviz_dot', self.builder.config.graphviz_dot)
     if not graphviz_dot:
         raise GraphvizError(
             __('graphviz_dot executable path must be set! %r') % graphviz_dot,
         )
-    hashkey = (code + str(options) + str(graphviz_dot) +
-               str(self.builder.config.graphviz_dot_args)).encode()
+    hashkey = ''.join((
+        code,
+        str(options),
+        str(graphviz_dot),
+        str(self.builder.config.graphviz_dot_args),
+    )).encode()
 
     fname = f'{prefix}-{sha1(hashkey, usedforsecurity=False).hexdigest()}.{format}'
-    relfn = posixpath.join(self.builder.imgpath, fname)
-    outfn = path.join(self.builder.outdir, self.builder.imagedir, fname)
+    relfn = _StrPath(self.builder.imgpath, fname)
+    outfn = self.builder.outdir / self.builder.imagedir / fname
 
-    if path.isfile(outfn):
+    if outfn.is_file():
         return relfn, outfn
 
-    if (hasattr(self.builder, '_graphviz_warned_dot') and
-       self.builder._graphviz_warned_dot.get(graphviz_dot)):
+    if getattr(self.builder, '_graphviz_warned_dot', {}).get(graphviz_dot):
         return None, None
 
-    ensuredir(path.dirname(outfn))
+    outfn.parent.mkdir(parents=True, exist_ok=True)
 
     dot_args = [graphviz_dot]
     dot_args.extend(self.builder.config.graphviz_dot_args)
-    dot_args.extend(['-T' + format, '-o' + outfn])
+    dot_args.extend([f'-T{format}', f'-o{outfn}'])
 
     docname = options.get('docname', 'index')
     if filename:
-        cwd = path.dirname(path.join(self.builder.srcdir, filename))
+        cwd = (self.builder.srcdir / filename).parent
     else:
-        cwd = path.dirname(path.join(self.builder.srcdir, docname))
+        cwd = (self.builder.srcdir / docname).parent
 
     if format == 'png':
-        dot_args.extend(['-Tcmapx', '-o%s.map' % outfn])
+        dot_args.extend(['-Tcmapx', f'-o{outfn}.map'])
 
     try:
-        ret = subprocess.run(dot_args, input=code.encode(), capture_output=True,
-                             cwd=cwd, check=True)
+        ret = subprocess.run(
+            dot_args, input=code.encode(), capture_output=True, cwd=cwd, check=True
+        )
     except OSError:
-        logger.warning(__('dot command %r cannot be run (needed for graphviz '
-                          'output), check the graphviz_dot setting'), graphviz_dot)
+        logger.warning(
+            __(
+                'dot command %r cannot be run (needed for graphviz '
+                'output), check the graphviz_dot setting'
+            ),
+            graphviz_dot,
+        )
         if not hasattr(self.builder, '_graphviz_warned_dot'):
             self.builder._graphviz_warned_dot = {}  # type: ignore[union-attr]
-        self.builder._graphviz_warned_dot[graphviz_dot] = True
+        self.builder._graphviz_warned_dot[graphviz_dot] = True  # type: ignore[union-attr]
         return None, None
     except CalledProcessError as exc:
-        raise GraphvizError(__('dot exited with error:\n[stderr]\n%r\n'
-                               '[stdout]\n%r') % (exc.stderr, exc.stdout)) from exc
-    if not path.isfile(outfn):
-        raise GraphvizError(__('dot did not produce an output file:\n[stderr]\n%r\n'
-                               '[stdout]\n%r') % (ret.stderr, ret.stdout))
+        raise GraphvizError(
+            __('dot exited with error:\n[stderr]\n%r\n[stdout]\n%r')
+            % (exc.stderr, exc.stdout)
+        ) from exc
+    if not outfn.is_file():
+        raise GraphvizError(
+            __('dot did not produce an output file:\n[stderr]\n%r\n[stdout]\n%r')
+            % (ret.stderr, ret.stdout)
+        )
 
     if format == 'svg':
         fix_svg_relative_paths(self, outfn)
@@ -319,15 +351,23 @@ def render_dot(self: HTML5Translator | LaTeXTranslator | TexinfoTranslator,
     return relfn, outfn
 
 
-def render_dot_html(self: HTML5Translator, node: graphviz, code: str, options: dict,
-                    prefix: str = 'graphviz', imgcls: str | None = None,
-                    alt: str | None = None, filename: str | None = None,
-                    ) -> tuple[str, str]:
+def render_dot_html(
+    self: HTML5Translator,
+    node: graphviz,
+    code: str,
+    options: dict[str, Any],
+    prefix: str = 'graphviz',
+    imgcls: str | None = None,
+    alt: str | None = None,
+    filename: str | None = None,
+) -> tuple[str, str]:
     format = self.builder.config.graphviz_output_format
+    if format not in {'png', 'svg'}:
+        logger.warning(
+            __("graphviz_output_format must be either 'png' or 'svg', but is %r"),
+            format,
+        )
     try:
-        if format not in ('png', 'svg'):
-            raise GraphvizError(__("graphviz_output_format must be one of 'png', "
-                                   "'svg', but is %r") % format)
         fname, outfn = render_dot(self, code, options, format, prefix, filename)
     except GraphvizError as exc:
         logger.warning(__('dot code %r: %s'), code, exc)
@@ -339,34 +379,37 @@ def render_dot_html(self: HTML5Translator, node: graphviz, code: str, options: d
     if fname is None:
         self.body.append(self.encode(code))
     else:
+        src = fname.as_posix()
         if alt is None:
             alt = node.get('alt', self.encode(code).strip())
         if 'align' in node:
-            self.body.append('<div align="%s" class="align-%s">' %
-                             (node['align'], node['align']))
+            align = node['align']
+            self.body.append(f'<div align="{align}" class="align-{align}">')
         if format == 'svg':
             self.body.append('<div class="graphviz">')
-            self.body.append('<object data="%s" type="image/svg+xml" class="%s">\n' %
-                             (fname, imgcls))
-            self.body.append('<p class="warning">%s</p>' % alt)
+            self.body.append(
+                f'<object data="{src}" type="image/svg+xml" class="{imgcls}">\n'
+            )
+            self.body.append(f'<p class="warning">{alt}</p>')
             self.body.append('</object></div>\n')
         else:
             assert outfn is not None
-            with open(outfn + '.map', encoding='utf-8') as mapfile:
-                imgmap = ClickableMapDefinition(outfn + '.map', mapfile.read(), dot=code)
-                if imgmap.clickable:
-                    # has a map
-                    self.body.append('<div class="graphviz">')
-                    self.body.append('<img src="%s" alt="%s" usemap="#%s" class="%s" />' %
-                                     (fname, alt, imgmap.id, imgcls))
-                    self.body.append('</div>\n')
-                    self.body.append(imgmap.generate_clickable_map())
-                else:
-                    # nothing in image map
-                    self.body.append('<div class="graphviz">')
-                    self.body.append('<img src="%s" alt="%s" class="%s" />' %
-                                     (fname, alt, imgcls))
-                    self.body.append('</div>\n')
+            with open(f'{outfn}.map', encoding='utf-8') as mapfile:
+                map_content = mapfile.read()
+            imgmap = ClickableMapDefinition(f'{outfn}.map', map_content, dot=code)
+            if imgmap.clickable:
+                # has a map
+                self.body.append('<div class="graphviz">')
+                self.body.append(
+                    f'<img src="{src}" alt="{alt}" usemap="#{imgmap.id}" class="{imgcls}" />'
+                )
+                self.body.append('</div>\n')
+                self.body.append(imgmap.generate_clickable_map())
+            else:
+                # nothing in image map
+                self.body.append('<div class="graphviz">')
+                self.body.append(f'<img src="{src}" alt="{alt}" class="{imgcls}" />')
+                self.body.append('</div>\n')
         if 'align' in node:
             self.body.append('</div>\n')
 
@@ -374,12 +417,19 @@ def render_dot_html(self: HTML5Translator, node: graphviz, code: str, options: d
 
 
 def html_visit_graphviz(self: HTML5Translator, node: graphviz) -> None:
-    render_dot_html(self, node, node['code'], node['options'], filename=node.get('filename'))
-
-
-def render_dot_latex(self: LaTeXTranslator, node: graphviz, code: str,
-                     options: dict, prefix: str = 'graphviz', filename: str | None = None,
-                     ) -> None:
+    render_dot_html(
+        self, node, node['code'], node['options'], filename=node.get('filename')
+    )
+
+
+def render_dot_latex(
+    self: LaTeXTranslator,
+    node: graphviz,
+    code: str,
+    options: dict[str, Any],
+    prefix: str = 'graphviz',
+    filename: str | None = None,
+) -> None:
     try:
         fname, outfn = render_dot(self, code, options, 'pdf', prefix, filename)
     except GraphvizError as exc:
@@ -401,22 +451,29 @@ def render_dot_latex(self: LaTeXTranslator, node: graphviz, code: str,
             elif node['align'] == 'center':
                 pre = r'{\hfill'
                 post = r'\hspace*{\fill}}'
-        self.body.append('\n%s' % pre)
+        self.body.append(f'\n{pre}')
 
     self.body.append(r'\sphinxincludegraphics[]{%s}' % fname)
 
     if not is_inline:
-        self.body.append('%s\n' % post)
+        self.body.append(f'{post}\n')
 
     raise nodes.SkipNode
 
 
 def latex_visit_graphviz(self: LaTeXTranslator, node: graphviz) -> None:
-    render_dot_latex(self, node, node['code'], node['options'], filename=node.get('filename'))
-
-
-def render_dot_texinfo(self: TexinfoTranslator, node: graphviz, code: str,
-                       options: dict, prefix: str = 'graphviz') -> None:
+    render_dot_latex(
+        self, node, node['code'], node['options'], filename=node.get('filename')
+    )
+
+
+def render_dot_texinfo(
+    self: TexinfoTranslator,
+    node: graphviz,
+    code: str,
+    options: dict[str, Any],
+    prefix: str = 'graphviz',
+) -> None:
     try:
         fname, outfn = render_dot(self, code, options, 'png', prefix)
     except GraphvizError as exc:
@@ -448,23 +505,32 @@ def man_visit_graphviz(self: ManualPageTranslator, node: graphviz) -> None:
 
 
 def on_config_inited(_app: Sphinx, config: Config) -> None:
-    css_path = path.join(sphinx.package_dir, 'templates', 'graphviz', 'graphviz.css')
-    config.html_static_path.append(css_path)
+    css_path = sphinx.package_dir.joinpath('templates', 'graphviz', 'graphviz.css')
+    config.html_static_path.append(str(css_path))
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_node(graphviz,
-                 html=(html_visit_graphviz, None),
-                 latex=(latex_visit_graphviz, None),
-                 texinfo=(texinfo_visit_graphviz, None),
-                 text=(text_visit_graphviz, None),
-                 man=(man_visit_graphviz, None))
+    app.add_node(
+        graphviz,
+        html=(html_visit_graphviz, None),
+        latex=(latex_visit_graphviz, None),
+        texinfo=(texinfo_visit_graphviz, None),
+        text=(text_visit_graphviz, None),
+        man=(man_visit_graphviz, None),
+    )
     app.add_directive('graphviz', Graphviz)
     app.add_directive('graph', GraphvizSimple)
     app.add_directive('digraph', GraphvizSimple)
-    app.add_config_value('graphviz_dot', 'dot', 'html')
-    app.add_config_value('graphviz_dot_args', [], 'html')
-    app.add_config_value('graphviz_output_format', 'png', 'html')
+    app.add_config_value('graphviz_dot', 'dot', 'html', types=frozenset({str}))
+    app.add_config_value(
+        'graphviz_dot_args', (), 'html', types=frozenset({list, tuple})
+    )
+    app.add_config_value(
+        'graphviz_output_format', 'png', 'html', types=frozenset({str})
+    )
     app.add_css_file('graphviz.css')
     app.connect('config-inited', on_config_inited)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }

sphinx/ext/ifconfig.py

@@ -16,7 +16,7 @@ namespace of the project configuration (that is, all variables from
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 
@@ -24,6 +24,8 @@ import sphinx
 from sphinx.util.docutils import SphinxDirective
 
 if TYPE_CHECKING:
+    from typing import ClassVar
+
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
@@ -35,7 +37,6 @@ class ifconfig(nodes.Element):
 
 
 class IfConfig(SphinxDirective):
-
     has_content = True
     required_arguments = 1
     optional_arguments = 0
@@ -61,10 +62,11 @@ def process_ifconfig_nodes(app: Sphinx, doctree: nodes.document, docname: str) -
         except Exception as err:
             # handle exceptions in a clean fashion
             from traceback import format_exception_only
+
             msg = ''.join(format_exception_only(err.__class__, err))
-            newnode = doctree.reporter.error('Exception occurred in '
-                                             'ifconfig expression: \n%s' %
-                                             msg, base_node=node)
+            newnode = doctree.reporter.error(
+                f'Exception occurred in ifconfig expression: \n{msg}', base_node=node
+            )
             node.replace_self(newnode)
         else:
             if not res:
@@ -77,4 +79,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_node(ifconfig)
     app.add_directive('ifconfig', IfConfig)
     app.connect('doctree-resolved', process_ifconfig_nodes)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }