Sphinx 8.0.2__py3-none-any.whl → 8.1.1__py3-none-any.whl

sphinx/transforms/post_transforms/__init__.py

@@ -66,7 +66,7 @@ class ReferencesResolver(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         for node in self.document.findall(addnodes.pending_xref):
-            content = self.find_pending_xref_condition(node, ("resolved", "*"))
+            content = self.find_pending_xref_condition(node, ('resolved', '*'))
             if content:
                 contnode = cast(Element, content[0].deepcopy())
             else:
@@ -87,16 +87,21 @@ class ReferencesResolver(SphinxPostTransform):
                         domain = self.env.domains[node['refdomain']]
                     except KeyError as exc:
                         raise NoUri(target, typ) from exc
-                    newnode = domain.resolve_xref(self.env, refdoc, self.app.builder,
-                                                  typ, target, node, contnode)
+                    newnode = domain.resolve_xref(
+                        self.env, refdoc, self.app.builder, typ, target, node, contnode
+                    )
                 # really hardwired reference types
                 elif typ == 'any':
                     newnode = self.resolve_anyref(refdoc, node, contnode)
                 # no new node found? try the missing-reference event
                 if newnode is None:
-                    newnode = self.app.emit_firstresult('missing-reference', self.env,
-                                                        node, contnode,
-                                                        allowed_exceptions=(NoUri,))
+                    newnode = self.app.emit_firstresult(
+                        'missing-reference',
+                        self.env,
+                        node,
+                        contnode,
+                        allowed_exceptions=(NoUri,),
+                    )
                     # still not found? warn if node wishes to be warned about or
                     # we are in nitpicky mode
                     if newnode is None:
@@ -108,69 +113,103 @@ class ReferencesResolver(SphinxPostTransform):
                 newnodes: list[Node] = [newnode]
             else:
                 newnodes = [contnode]
-                if newnode is None and isinstance(node[0], addnodes.pending_xref_condition):
-                    matched = self.find_pending_xref_condition(node, ("*",))
+                if newnode is None and isinstance(
+                    node[0], addnodes.pending_xref_condition
+                ):
+                    matched = self.find_pending_xref_condition(node, ('*',))
                     if matched:
                         newnodes = matched
                     else:
-                        logger.warning(__('Could not determine the fallback text for the '
-                                          'cross-reference. Might be a bug.'), location=node)
+                        logger.warning(
+                            __(
+                                'Could not determine the fallback text for the '
+                                'cross-reference. Might be a bug.'
+                            ),
+                            location=node,
+                        )
 
             node.replace_self(newnodes)
 
     def resolve_anyref(
-        self, refdoc: str, node: pending_xref, contnode: Element,
+        self,
+        refdoc: str,
+        node: pending_xref,
+        contnode: Element,
     ) -> Element | None:
         """Resolve reference generated by the "any" role."""
-        stddomain = self.env.get_domain('std')
+        stddomain = self.env.domains.standard_domain
         target = node['reftarget']
         results: list[tuple[str, Element]] = []
         # first, try resolving as :doc:
-        doc_ref = stddomain.resolve_xref(self.env, refdoc, self.app.builder,
-                                         'doc', target, node, contnode)
+        doc_ref = stddomain.resolve_xref(
+            self.env, refdoc, self.app.builder, 'doc', target, node, contnode
+        )
         if doc_ref:
             results.append(('doc', doc_ref))
         # next, do the standard domain (makes this a priority)
-        results.extend(stddomain.resolve_any_xref(self.env, refdoc, self.app.builder,
-                                                  target, node, contnode))
-        for domain in self.env.domains.values():
+        results.extend(
+            stddomain.resolve_any_xref(
+                self.env, refdoc, self.app.builder, target, node, contnode
+            )
+        )
+        for domain in self.env.domains.sorted():
             if domain.name == 'std':
                 continue  # we did this one already
             try:
-                results.extend(domain.resolve_any_xref(self.env, refdoc, self.app.builder,
-                                                       target, node, contnode))
+                results.extend(
+                    domain.resolve_any_xref(
+                        self.env, refdoc, self.app.builder, target, node, contnode
+                    )
+                )
             except NotImplementedError:
                 # the domain doesn't yet support the new interface
                 # we have to manually collect possible references (SLOW)
                 for role in domain.roles:
-                    res = domain.resolve_xref(self.env, refdoc, self.app.builder,
-                                              role, target, node, contnode)
+                    res = domain.resolve_xref(
+                        self.env, refdoc, self.app.builder, role, target, node, contnode
+                    )
                     if res and len(res) > 0 and isinstance(res[0], nodes.Element):
                         results.append((f'{domain.name}:{role}', res))
         # now, see how many matches we got...
         if not results:
             return None
         if len(results) > 1:
+
             def stringify(name: str, node: Element) -> str:
                 reftitle = node.get('reftitle', node.astext())
                 return f':{name}:`{reftitle}`'
+
             candidates = ' or '.join(starmap(stringify, results))
-            logger.warning(__("more than one target found for 'any' cross-"
-                              'reference %r: could be %s'), target, candidates,
-                           location=node)
+            logger.warning(
+                __(
+                    "more than one target found for 'any' cross-"
+                    'reference %r: could be %s'
+                ),
+                target,
+                candidates,
+                location=node,
+            )
         res_role, newnode = results[0]
         # Override "any" class with the actual role type to get the styling
         # approximately correct.
         res_domain = res_role.split(':')[0]
-        if (len(newnode) > 0 and
-                isinstance(newnode[0], nodes.Element) and
-                newnode[0].get('classes')):
+        if (
+            len(newnode) > 0
+            and isinstance(newnode[0], nodes.Element)
+            and newnode[0].get('classes')
+        ):
             newnode[0]['classes'].append(res_domain)
             newnode[0]['classes'].append(res_role.replace(':', '-'))
         return newnode
 
-    def warn_missing_reference(self, refdoc: str, typ: str, target: str,
-                               node: pending_xref, domain: Domain | None) -> None:
+    def warn_missing_reference(
+        self,
+        refdoc: str,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        domain: Domain | None,
+    ) -> None:
         warn = node.get('refwarn')
         if self.config.nitpicky:
             warn = True
@@ -179,24 +218,26 @@ class ReferencesResolver(SphinxPostTransform):
                 if (dtype, target) in self.config.nitpick_ignore:
                     warn = False
                 # for "std" types also try without domain name
-                if (not domain or domain.name == 'std') and \
-                   (typ, target) in self.config.nitpick_ignore:
+                if (
+                    (not domain or domain.name == 'std')
+                    and (typ, target) in self.config.nitpick_ignore
+                ):  # fmt: skip
                     warn = False
             if self.config.nitpick_ignore_regex:
+
                 def matches_ignore(entry_type: str, entry_target: str) -> bool:
                     return any(
                         (
                             re.fullmatch(ignore_type, entry_type)
                             and re.fullmatch(ignore_target, entry_target)
                         )
-                        for ignore_type, ignore_target
-                        in self.config.nitpick_ignore_regex
+                        for ignore_type, ignore_target in self.config.nitpick_ignore_regex
                     )
+
                 if matches_ignore(dtype, target):
                     warn = False
                 # for "std" types also try without domain name
-                if (not domain or domain.name == 'std') and \
-                   matches_ignore(typ, target):
+                if (not domain or domain.name == 'std') and matches_ignore(typ, target):
                     warn = False
         if not warn:
             return
@@ -206,14 +247,20 @@ class ReferencesResolver(SphinxPostTransform):
         elif domain and typ in domain.dangling_warnings:
             msg = domain.dangling_warnings[typ] % {'target': target}
         elif node.get('refdomain', 'std') not in ('', 'std'):
-            msg = (__('%s:%s reference target not found: %s') %
-                   (node['refdomain'], typ, target))
+            msg = __('%s:%s reference target not found: %s') % (
+                node['refdomain'],
+                typ,
+                target,
+            )
         else:
             msg = __('%r reference target not found: %s') % (typ, target)
         logger.warning(msg, location=node, type='ref', subtype=typ)
 
-    def find_pending_xref_condition(self, node: pending_xref, conditions: Sequence[str],
-                                    ) -> list[Node] | None:
+    def find_pending_xref_condition(
+        self,
+        node: pending_xref,
+        conditions: Sequence[str],
+    ) -> list[Node] | None:
         for condition in conditions:
             matched = find_pending_xref_condition(node, condition)
             if matched:
@@ -238,8 +285,10 @@ class SigElementFallbackTransform(SphinxPostTransform):
     default_priority = 200
 
     def run(self, **kwargs: Any) -> None:
-        def has_visitor(translator: type[nodes.NodeVisitor], node: type[Element]) -> bool:
-            return hasattr(translator, "visit_%s" % node.__name__)
+        def has_visitor(
+            translator: type[nodes.NodeVisitor], node: type[Element]
+        ) -> bool:
+            return hasattr(translator, 'visit_%s' % node.__name__)
 
         try:
             translator = self.app.builder.get_translator_class()
@@ -253,8 +302,10 @@ class SigElementFallbackTransform(SphinxPostTransform):
 
         # for the leaf elements (desc_sig_element), the translator should support _all_,
         # unless there exists a generic visit_desc_sig_element default visitor
-        if (not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS)
-                and not has_visitor(translator, addnodes.desc_sig_element)):
+        if (
+            not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS)
+            and not has_visitor(translator, addnodes.desc_sig_element)
+        ):  # fmt: skip
             self.fallback(addnodes.desc_sig_element)
 
         if not has_visitor(translator, addnodes.desc_inline):

sphinx/transforms/post_transforms/code.py

@@ -37,8 +37,9 @@ class HighlightLanguageTransform(SphinxTransform):
     default_priority = 400
 
     def apply(self, **kwargs: Any) -> None:
-        visitor = HighlightLanguageVisitor(self.document,
-                                           self.config.highlight_language)
+        visitor = HighlightLanguageVisitor(
+            self.document, self.config.highlight_language
+        )
         self.document.walkabout(visitor)
 
         for node in list(self.document.findall(addnodes.highlightlang)):
@@ -70,9 +71,9 @@ class HighlightLanguageVisitor(nodes.NodeVisitor):
         self.settings.pop()
 
     def visit_highlightlang(self, node: addnodes.highlightlang) -> None:
-        self.settings[-1] = HighlightSetting(node['lang'],
-                                             node['force'],
-                                             node['linenothreshold'])
+        self.settings[-1] = HighlightSetting(
+            node['lang'], node['force'], node['linenothreshold']
+        )
 
     def visit_literal_block(self, node: nodes.literal_block) -> None:
         setting = self.settings[-1]
@@ -81,7 +82,7 @@ class HighlightLanguageVisitor(nodes.NodeVisitor):
             node['force'] = setting.force
         if 'linenos' not in node:
             lines = node.astext().count('\n')
-            node['linenos'] = (lines >= setting.lineno_threshold - 1)
+            node['linenos'] = lines >= setting.lineno_threshold - 1
 
 
 class TrimDoctestFlagsTransform(SphinxTransform):

sphinx/transforms/post_transforms/images.py

@@ -6,6 +6,7 @@ import os
 import re
 from hashlib import sha1
 from math import ceil
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
@@ -13,6 +14,7 @@ from docutils import nodes
 from sphinx.locale import __
 from sphinx.transforms import SphinxTransform
 from sphinx.util import logging, requests
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.http_date import epoch_to_rfc1123, rfc1123_to_epoch
 from sphinx.util.images import get_image_extension, guess_mimetype, parse_data_uri
 from sphinx.util.osutil import ensuredir
@@ -61,54 +63,65 @@ class ImageDownloader(BaseImageConverter):
                 basename = basename.split('?')[0]
             if basename == '' or len(basename) > MAX_FILENAME_LEN:
                 filename, ext = os.path.splitext(node['uri'])
-                basename = sha1(filename.encode(), usedforsecurity=False).hexdigest() + ext
-            basename = CRITICAL_PATH_CHAR_RE.sub("_", basename)
+                basename = (
+                    sha1(filename.encode(), usedforsecurity=False).hexdigest() + ext
+                )
+            basename = CRITICAL_PATH_CHAR_RE.sub('_', basename)
 
             uri_hash = sha1(node['uri'].encode(), usedforsecurity=False).hexdigest()
-            ensuredir(os.path.join(self.imagedir, uri_hash))
-            path = os.path.join(self.imagedir, uri_hash, basename)
-
-            headers = {}
-            if os.path.exists(path):
-                timestamp: float = ceil(os.stat(path).st_mtime)
-                headers['If-Modified-Since'] = epoch_to_rfc1123(timestamp)
-
-            config = self.app.config
-            r = requests.get(
-                node['uri'], headers=headers,
-                _user_agent=config.user_agent,
-                _tls_info=(config.tls_verify, config.tls_cacerts),
-            )
-            if r.status_code >= 400:
-                logger.warning(__('Could not fetch remote image: %s [%d]'),
-                               node['uri'], r.status_code)
-            else:
-                self.app.env.original_image_uri[path] = node['uri']
-
-                if r.status_code == 200:
-                    with open(path, 'wb') as f:
-                        f.write(r.content)
-
-                last_modified = r.headers.get('last-modified')
-                if last_modified:
-                    timestamp = rfc1123_to_epoch(last_modified)
-                    os.utime(path, (timestamp, timestamp))
-
-                mimetype = guess_mimetype(path, default='*')
-                if mimetype != '*' and os.path.splitext(basename)[1] == '':
-                    # append a suffix if URI does not contain suffix
-                    ext = get_image_extension(mimetype)
-                    newpath = os.path.join(self.imagedir, uri_hash, basename + ext)
-                    os.replace(path, newpath)
-                    self.app.env.original_image_uri.pop(path)
-                    self.app.env.original_image_uri[newpath] = node['uri']
-                    path = newpath
-                node['candidates'].pop('?')
-                node['candidates'][mimetype] = path
-                node['uri'] = path
-                self.app.env.images.add_file(self.env.docname, path)
+            path = Path(self.imagedir, uri_hash, basename)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            self._download_image(node, path)
+
         except Exception as exc:
-            logger.warning(__('Could not fetch remote image: %s [%s]'), node['uri'], exc)
+            msg = __('Could not fetch remote image: %s [%s]')
+            logger.warning(msg, node['uri'], exc)
+
+    def _download_image(self, node: nodes.image, path: Path) -> None:
+        headers = {}
+        if path.exists():
+            timestamp: float = ceil(path.stat().st_mtime)
+            headers['If-Modified-Since'] = epoch_to_rfc1123(timestamp)
+
+        config = self.app.config
+        r = requests.get(
+            node['uri'],
+            headers=headers,
+            _user_agent=config.user_agent,
+            _tls_info=(config.tls_verify, config.tls_cacerts),
+        )
+        if r.status_code >= 400:
+            msg = __('Could not fetch remote image: %s [%d]')
+            logger.warning(msg, node['uri'], r.status_code)
+        else:
+            self.app.env.original_image_uri[_StrPath(path)] = node['uri']
+
+            if r.status_code == 200:
+                path.write_bytes(r.content)
+            if last_modified := r.headers.get('Last-Modified'):
+                timestamp = rfc1123_to_epoch(last_modified)
+                os.utime(path, (timestamp, timestamp))
+
+            self._process_image(node, path)
+
+    def _process_image(self, node: nodes.image, path: Path) -> None:
+        str_path = _StrPath(path)
+        self.app.env.original_image_uri[str_path] = node['uri']
+
+        mimetype = guess_mimetype(path, default='*')
+        if mimetype != '*' and path.suffix == '':
+            # append a suffix if URI does not contain suffix
+            ext = get_image_extension(mimetype) or ''
+            with_ext = path.with_name(path.name + ext)
+            os.replace(path, with_ext)
+            self.app.env.original_image_uri.pop(str_path)
+            self.app.env.original_image_uri[_StrPath(with_ext)] = node['uri']
+            path = with_ext
+        path_str = str(path)
+        node['candidates'].pop('?')
+        node['candidates'][mimetype] = path_str
+        node['uri'] = path_str
+        self.app.env.images.add_file(self.env.docname, path_str)
 
 
 class DataURIExtractor(BaseImageConverter):
@@ -124,27 +137,29 @@ class DataURIExtractor(BaseImageConverter):
         assert image is not None
         ext = get_image_extension(image.mimetype)
         if ext is None:
-            logger.warning(__('Unknown image format: %s...'), node['uri'][:32],
-                           location=node)
+            logger.warning(
+                __('Unknown image format: %s...'), node['uri'][:32], location=node
+            )
             return
 
         ensuredir(os.path.join(self.imagedir, 'embeded'))
         digest = sha1(image.data, usedforsecurity=False).hexdigest()
-        path = os.path.join(self.imagedir, 'embeded', digest + ext)
+        path = _StrPath(self.imagedir, 'embeded', digest + ext)
         self.app.env.original_image_uri[path] = node['uri']
 
         with open(path, 'wb') as f:
             f.write(image.data)
 
+        path_str = str(path)
         node['candidates'].pop('?')
-        node['candidates'][image.mimetype] = path
-        node['uri'] = path
-        self.app.env.images.add_file(self.env.docname, path)
+        node['candidates'][image.mimetype] = path_str
+        node['uri'] = path_str
+        self.app.env.images.add_file(self.env.docname, path_str)
 
 
 def get_filename_for(filename: str, mimetype: str) -> str:
     basename = os.path.basename(filename)
-    basename = CRITICAL_PATH_CHAR_RE.sub("_", basename)
+    basename = CRITICAL_PATH_CHAR_RE.sub('_', basename)
     return os.path.splitext(basename)[0] + (get_image_extension(mimetype) or '')
 
 
@@ -195,7 +210,9 @@ class ImageConverter(BaseImageConverter):
             return False
         if '?' in node['candidates']:
             return False
-        if set(self.guess_mimetypes(node)) & set(self.app.builder.supported_image_types):
+        node_mime_types = set(self.guess_mimetypes(node))
+        supported_image_types = set(self.app.builder.supported_image_types)
+        if node_mime_types & supported_image_types:
             # builder supports the image; no need to convert
             return False
         if self.available is None:
@@ -258,7 +275,7 @@ class ImageConverter(BaseImageConverter):
                 node['candidates'][_to] = destpath
             node['uri'] = destpath
 
-            self.env.original_image_uri[destpath] = srcpath
+            self.env.original_image_uri[_StrPath(destpath)] = srcpath
             self.env.images.add_file(self.env.docname, destpath)
 
     def convert(self, _from: str, _to: str) -> bool:

sphinx/transforms/references.py

@@ -34,8 +34,7 @@ class SphinxDomains(SphinxTransform):
     default_priority = 850
 
     def apply(self, **kwargs: Any) -> None:
-        for domain in self.env.domains.values():
-            domain.process_doc(self.env, self.env.docname, self.document)
+        self.env.domains._process_doc(self.env, self.env.docname, self.document)
 
 
 def setup(app: Sphinx) -> ExtensionMetadata: