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

sphinx/transforms/post_transforms/__init__.py

@@ -4,10 +4,9 @@ from __future__ import annotations
 
 import re
 from itertools import starmap
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
-from docutils.nodes import Element, Node
 
 from sphinx import addnodes
 from sphinx.errors import NoUri
@@ -19,6 +18,9 @@ from sphinx.util.nodes import find_pending_xref_condition, process_only_nodes
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+    from typing import Any
+
+    from docutils.nodes import Element, Node
 
     from sphinx.addnodes import pending_xref
     from sphinx.application import Sphinx
@@ -58,9 +60,7 @@ class SphinxPostTransform(SphinxTransform):
 
 
 class ReferencesResolver(SphinxPostTransform):
-    """
-    Resolves cross-references on doctrees.
-    """
+    """Resolves cross-references on doctrees."""
 
     default_priority = 10
 
@@ -68,105 +68,158 @@ class ReferencesResolver(SphinxPostTransform):
         for node in self.document.findall(addnodes.pending_xref):
             content = self.find_pending_xref_condition(node, ('resolved', '*'))
             if content:
-                contnode = cast(Element, content[0].deepcopy())
+                contnode = cast('Element', content[0].deepcopy())
             else:
-                contnode = cast(Element, node[0].deepcopy())
-
-            newnode = None
+                contnode = cast('Element', node[0].deepcopy())
 
-            typ = node['reftype']
-            target = node['reftarget']
-            node.setdefault('refdoc', self.env.docname)
-            refdoc = node.get('refdoc')
-            domain = None
-
-            try:
-                if node.get('refdomain', False):
-                    # let the domain try to resolve the reference
-                    try:
-                        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
-                    )
-                # 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,),
-                    )
-                    # still not found? warn if node wishes to be warned about or
-                    # we are in nitpicky mode
-                    if newnode is None:
-                        self.warn_missing_reference(refdoc, typ, target, node, domain)
-            except NoUri:
-                newnode = None
-
-            if newnode:
-                newnodes: list[Node] = [newnode]
+            new_node = self._resolve_pending_xref(node, contnode)
+            if new_node:
+                new_nodes: list[Node] = [new_node]
             else:
-                newnodes = [contnode]
-                if newnode is None and isinstance(
+                new_nodes = [contnode]
+                if new_node is None and isinstance(
                     node[0], addnodes.pending_xref_condition
                 ):
                     matched = self.find_pending_xref_condition(node, ('*',))
                     if matched:
-                        newnodes = matched
+                        new_nodes = matched
                     else:
-                        logger.warning(
-                            __(
-                                'Could not determine the fallback text for the '
-                                'cross-reference. Might be a bug.'
-                            ),
-                            location=node,
+                        msg = __(
+                            'Could not determine the fallback text for the '
+                            'cross-reference. Might be a bug.'
                         )
+                        logger.warning(msg, location=node)
+
+            node.replace_self(new_nodes)
+
+    def _resolve_pending_xref(
+        self, node: addnodes.pending_xref, contnode: Element
+    ) -> nodes.reference | None:
+        new_node: nodes.reference | None
+        typ = node['reftype']
+        target = node['reftarget']
+        ref_doc = node.setdefault('refdoc', self.env.docname)
+        ref_domain = node.get('refdomain', '')
+        domain: Domain | None
+        if ref_domain:
+            try:
+                domain = self.env.domains[ref_domain]
+            except KeyError:
+                return None
+        else:
+            domain = None
+
+        try:
+            new_node = self._resolve_pending_xref_in_domain(
+                domain=domain,
+                node=node,
+                contnode=contnode,
+                ref_doc=ref_doc,
+                typ=typ,
+                target=target,
+            )
+        except NoUri:
+            return None
+        if new_node is not None:
+            return new_node
+
+        try:
+            # no new node found? try the missing-reference event
+            new_node = self.app.events.emit_firstresult(
+                'missing-reference',
+                self.env,
+                node,
+                contnode,
+                allowed_exceptions=(NoUri,),
+            )
+        except NoUri:
+            return None
+        if new_node is not None:
+            return new_node
 
-            node.replace_self(newnodes)
+        # Is this a self-referential intersphinx reference?
+        if 'intersphinx_self_referential' in node:
+            del node.attributes['intersphinx_self_referential']
+            try:
+                new_node = self._resolve_pending_xref_in_domain(
+                    domain=domain,
+                    node=node,
+                    contnode=contnode,
+                    ref_doc=ref_doc,
+                    typ=typ,
+                    target=node['reftarget'],
+                )
+            except NoUri:
+                return None
+            if new_node is not None:
+                return new_node
 
-    def resolve_anyref(
+        # Still not found? Emit a warning if we are in nitpicky mode
+        # or if the node wishes to be warned about.
+        self.warn_missing_reference(ref_doc, typ, target, node, domain)
+        return None
+
+    def _resolve_pending_xref_in_domain(
         self,
-        refdoc: str,
-        node: pending_xref,
+        *,
+        domain: Domain | None,
+        node: addnodes.pending_xref,
         contnode: Element,
-    ) -> Element | None:
+        ref_doc: str,
+        typ: str,
+        target: str,
+    ) -> nodes.reference | None:
+        # let the domain try to resolve the reference
+        if domain is not None:
+            return domain.resolve_xref(
+                self.env, ref_doc, self.app.builder, typ, target, node, contnode
+            )
+
+        # really hardwired reference types
+        if typ == 'any':
+            return self._resolve_pending_any_xref(
+                node=node, contnode=contnode, ref_doc=ref_doc, target=target
+            )
+
+        return None
+
+    def _resolve_pending_any_xref(
+        self,
+        *,
+        node: addnodes.pending_xref,
+        contnode: Element,
+        ref_doc: str,
+        target: str,
+    ) -> nodes.reference | None:
         """Resolve reference generated by the "any" role."""
-        stddomain = self.env.domains.standard_domain
-        target = node['reftarget']
-        results: list[tuple[str, Element]] = []
+        env = self.env
+        builder = self.app.builder
+        domains = env.domains
+
+        results: list[tuple[str, nodes.reference]] = []
         # first, try resolving as :doc:
-        doc_ref = stddomain.resolve_xref(
-            self.env, refdoc, self.app.builder, 'doc', target, node, contnode
+        doc_ref = domains.standard_domain.resolve_xref(
+            env, ref_doc, 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
-            )
+        results += domains.standard_domain.resolve_any_xref(
+            env, ref_doc, builder, target, node, contnode
         )
-        for domain in self.env.domains.sorted():
+        for domain in 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 += domain.resolve_any_xref(
+                    env, ref_doc, 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
+                        env, ref_doc, builder, role, target, node, contnode
                     )
                     if res and len(res) > 0 and isinstance(res[0], nodes.Element):
                         results.append((f'{domain.name}:{role}', res))
@@ -180,27 +233,23 @@ class ReferencesResolver(SphinxPostTransform):
                 return f':{name}:`{reftitle}`'
 
             candidates = ' or '.join(starmap(stringify, results))
+            msg = __(
+                "more than one target found for 'any' cross-reference %r: could be %s"
+            )
             logger.warning(
-                __(
-                    "more than one target found for 'any' cross-"
-                    'reference %r: could be %s'
-                ),
-                target,
-                candidates,
-                location=node,
+                msg, target, candidates, location=node, type='ref', subtype='any'
             )
-        res_role, newnode = results[0]
+        res_role, new_node = results[0]
         # Override "any" class with the actual role type to get the styling
         # approximately correct.
-        res_domain = res_role.split(':')[0]
+        res_domain = res_role.partition(':')[0]
         if (
-            len(newnode) > 0
-            and isinstance(newnode[0], nodes.Element)
-            and newnode[0].get('classes')
+            len(new_node) > 0
+            and isinstance(new_node[0], nodes.Element)
+            and new_node[0].get('classes')
         ):
-            newnode[0]['classes'].append(res_domain)
-            newnode[0]['classes'].append(res_role.replace(':', '-'))
-        return newnode
+            new_node[0]['classes'].extend((res_domain, res_role.replace(':', '-')))
+        return new_node
 
     def warn_missing_reference(
         self,
@@ -242,11 +291,11 @@ class ReferencesResolver(SphinxPostTransform):
         if not warn:
             return
 
-        if self.app.emit_firstresult('warn-missing-reference', domain, node):
+        if self.app.events.emit_firstresult('warn-missing-reference', domain, node):
             return
         elif domain and typ in domain.dangling_warnings:
             msg = domain.dangling_warnings[typ] % {'target': target}
-        elif node.get('refdomain', 'std') not in ('', 'std'):
+        elif node.get('refdomain', 'std') not in {'', 'std'}:
             msg = __('%s:%s reference target not found: %s') % (
                 node['refdomain'],
                 typ,
@@ -276,7 +325,7 @@ class OnlyNodeTransform(SphinxPostTransform):
         # result in a "Losing ids" exception if there is a target node before
         # the only node, so we make sure docutils can transfer the id to
         # something, even if it's just a comment and will lose the id anyway...
-        process_only_nodes(self.document, self.app.builder.tags)
+        process_only_nodes(self.document, self.app.tags)
 
 
 class SigElementFallbackTransform(SphinxPostTransform):

sphinx/transforms/post_transforms/code.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import sys
-from typing import TYPE_CHECKING, Any, NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
 
 from docutils import nodes
 from pygments.lexers import PythonConsoleLexer, guess_lexer
@@ -13,6 +13,8 @@ from sphinx.ext import doctest
 from sphinx.transforms import SphinxTransform
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from docutils.nodes import Node, TextElement
 
     from sphinx.application import Sphinx
@@ -26,8 +28,7 @@ class HighlightSetting(NamedTuple):
 
 
 class HighlightLanguageTransform(SphinxTransform):
-    """
-    Apply highlight_language to all literal_block nodes.
+    """Apply highlight_language to all literal_block nodes.
 
     This refers both :confval:`highlight_language` setting and
     :rst:dir:`highlight` directive.  After processing, this transform
@@ -86,8 +87,7 @@ class HighlightLanguageVisitor(nodes.NodeVisitor):
 
 
 class TrimDoctestFlagsTransform(SphinxTransform):
-    """
-    Trim doctest flags like ``# doctest: +FLAG`` from python code-blocks.
+    """Trim doctest flags like ``# doctest: +FLAG`` from python code-blocks.
 
     see :confval:`trim_doctest_flags` for more information.
     """

sphinx/transforms/post_transforms/images.py

@@ -7,7 +7,7 @@ import re
 from hashlib import sha1
 from math import ceil
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 
@@ -20,6 +20,8 @@ from sphinx.util.images import get_image_extension, guess_mimetype, parse_data_u
 from sphinx.util.osutil import ensuredir
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
 
@@ -42,8 +44,8 @@ class BaseImageConverter(SphinxTransform):
         pass
 
     @property
-    def imagedir(self) -> str:
-        return os.path.join(self.app.doctreedir, 'images')
+    def imagedir(self) -> _StrPath:
+        return self.app.doctreedir / 'images'
 
 
 class ImageDownloader(BaseImageConverter):
@@ -61,7 +63,7 @@ class ImageDownloader(BaseImageConverter):
             basename = os.path.basename(node['uri'])
             if '?' in basename:
                 basename = basename.split('?')[0]
-            if basename == '' or len(basename) > MAX_FILENAME_LEN:
+            if not basename or len(basename) > MAX_FILENAME_LEN:
                 filename, ext = os.path.splitext(node['uri'])
                 basename = (
                     sha1(filename.encode(), usedforsecurity=False).hexdigest() + ext
@@ -83,7 +85,7 @@ class ImageDownloader(BaseImageConverter):
             timestamp: float = ceil(path.stat().st_mtime)
             headers['If-Modified-Since'] = epoch_to_rfc1123(timestamp)
 
-        config = self.app.config
+        config = self.config
         r = requests.get(
             node['uri'],
             headers=headers,
@@ -94,7 +96,7 @@ class ImageDownloader(BaseImageConverter):
             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']
+            self.env.original_image_uri[_StrPath(path)] = node['uri']
 
             if r.status_code == 200:
                 path.write_bytes(r.content)
@@ -106,22 +108,22 @@ class ImageDownloader(BaseImageConverter):
 
     def _process_image(self, node: nodes.image, path: Path) -> None:
         str_path = _StrPath(path)
-        self.app.env.original_image_uri[str_path] = node['uri']
+        self.env.original_image_uri[str_path] = node['uri']
 
         mimetype = guess_mimetype(path, default='*')
-        if mimetype != '*' and path.suffix == '':
+        if mimetype != '*' and not 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.replace(with_ext)
+            self.env.original_image_uri.pop(str_path)
+            self.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)
+        self.env.images.add_file(self.env.docname, path_str)
 
 
 class DataURIExtractor(BaseImageConverter):
@@ -142,10 +144,10 @@ class DataURIExtractor(BaseImageConverter):
             )
             return
 
-        ensuredir(os.path.join(self.imagedir, 'embeded'))
+        ensuredir(self.imagedir / 'embeded')
         digest = sha1(image.data, usedforsecurity=False).hexdigest()
-        path = _StrPath(self.imagedir, 'embeded', digest + ext)
-        self.app.env.original_image_uri[path] = node['uri']
+        path = self.imagedir / 'embeded' / (digest + ext)
+        self.env.original_image_uri[path] = node['uri']
 
         with open(path, 'wb') as f:
             f.write(image.data)
@@ -154,7 +156,7 @@ class DataURIExtractor(BaseImageConverter):
         node['candidates'].pop('?')
         node['candidates'][image.mimetype] = path_str
         node['uri'] = path_str
-        self.app.env.images.add_file(self.env.docname, path_str)
+        self.env.images.add_file(self.env.docname, path_str)
 
 
 def get_filename_for(filename: str, mimetype: str) -> str:
@@ -248,7 +250,7 @@ class ImageConverter(BaseImageConverter):
         if '?' in node['candidates']:
             return []
         elif '*' in node['candidates']:
-            path = os.path.join(self.app.srcdir, node['uri'])
+            path = self.app.srcdir / node['uri']
             guessed = guess_mimetype(path)
             return [guessed] if guessed is not None else []
         else:
@@ -265,20 +267,22 @@ class ImageConverter(BaseImageConverter):
         filename = self.env.images[srcpath][1]
         filename = get_filename_for(filename, _to)
         ensuredir(self.imagedir)
-        destpath = os.path.join(self.imagedir, filename)
+        destpath = self.imagedir / filename
 
-        abs_srcpath = os.path.join(self.app.srcdir, srcpath)
+        abs_srcpath = self.app.srcdir / srcpath
         if self.convert(abs_srcpath, destpath):
             if '*' in node['candidates']:
-                node['candidates']['*'] = destpath
+                node['candidates']['*'] = str(destpath)
             else:
-                node['candidates'][_to] = destpath
-            node['uri'] = destpath
+                node['candidates'][_to] = str(destpath)
+            node['uri'] = str(destpath)
 
-            self.env.original_image_uri[_StrPath(destpath)] = srcpath
+            self.env.original_image_uri[destpath] = srcpath
             self.env.images.add_file(self.env.docname, destpath)
 
-    def convert(self, _from: str, _to: str) -> bool:
+    def convert(
+        self, _from: str | os.PathLike[str], _to: str | os.PathLike[str]
+    ) -> bool:
         """Convert an image file to the expected format.
 
         *_from* is a path of the source image file, and *_to* is a path

sphinx/transforms/references.py

@@ -2,13 +2,15 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils.transforms.references import DanglingReferences
 
 from sphinx.transforms import SphinxTransform
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata