usse/scrape/venv/lib/python3.10/site-packages/sphinx/util/nodes.py
2023-12-22 15:26:01 +01:00

673 lines
24 KiB
Python

"""Docutils node-related utility functions for Sphinx."""
from __future__ import annotations
import contextlib
import re
import unicodedata
from typing import TYPE_CHECKING, Any, Callable
from docutils import nodes
from sphinx import addnodes
from sphinx.locale import __
from sphinx.util import logging
if TYPE_CHECKING:
from collections.abc import Iterable
from docutils.nodes import Element, Node
from docutils.parsers.rst import Directive
from docutils.parsers.rst.states import Inliner
from docutils.statemachine import StringList
from sphinx.builders import Builder
from sphinx.environment import BuildEnvironment
from sphinx.util.tags import Tags
logger = logging.getLogger(__name__)
# \x00 means the "<" was backslash-escaped
explicit_title_re = re.compile(r'^(.+?)\s*(?<!\x00)<([^<]*?)>$', re.DOTALL)
caption_ref_re = explicit_title_re # b/w compat alias
class NodeMatcher:
"""A helper class for Node.findall().
It checks that the given node is an instance of the specified node-classes and
has the specified node-attributes.
For example, following example searches ``reference`` node having ``refdomain``
and ``reftype`` attributes::
matcher = NodeMatcher(nodes.reference, refdomain='std', reftype='citation')
doctree.findall(matcher)
# => [<reference ...>, <reference ...>, ...]
A special value ``typing.Any`` matches any kind of node-attributes. For example,
following example searches ``reference`` node having ``refdomain`` attributes::
from __future__ import annotations
from typing import TYPE_CHECKING, Any
matcher = NodeMatcher(nodes.reference, refdomain=Any)
doctree.findall(matcher)
# => [<reference ...>, <reference ...>, ...]
"""
def __init__(self, *node_classes: type[Node], **attrs: Any) -> None:
self.classes = node_classes
self.attrs = attrs
def match(self, node: Node) -> bool:
try:
if self.classes and not isinstance(node, self.classes):
return False
if self.attrs:
if not isinstance(node, nodes.Element):
return False
for key, value in self.attrs.items():
if key not in node:
return False
elif value is Any:
continue
elif node.get(key) != value:
return False
return True
except Exception:
# for non-Element nodes
return False
def __call__(self, node: Node) -> bool:
return self.match(node)
def get_full_module_name(node: Node) -> str:
"""
Return full module dotted path like: 'docutils.nodes.paragraph'
:param nodes.Node node: target node
:return: full module dotted path
"""
return f'{node.__module__}.{node.__class__.__name__}'
def repr_domxml(node: Node, length: int = 80) -> str:
"""
return DOM XML representation of the specified node like:
'<paragraph translatable="False"><inline classes="versionmodified">New in version...'
:param nodes.Node node: target node
:param int length:
length of return value to be striped. if false-value is specified, repr_domxml
returns full of DOM XML representation.
:return: DOM XML representation
"""
try:
text = node.asdom().toxml()
except Exception:
text = str(node)
if length and len(text) > length:
text = text[:length] + '...'
return text
def apply_source_workaround(node: Element) -> None:
# workaround: nodes.term have wrong rawsource if classifier is specified.
# The behavior of docutils-0.11, 0.12 is:
# * when ``term text : classifier1 : classifier2`` is specified,
# * rawsource of term node will have: ``term text : classifier1 : classifier2``
# * rawsource of classifier node will be None
if isinstance(node, nodes.classifier) and not node.rawsource:
logger.debug('[i18n] PATCH: %r to have source, line and rawsource: %s',
get_full_module_name(node), repr_domxml(node))
definition_list_item = node.parent
node.source = definition_list_item.source
node.line = definition_list_item.line - 1
node.rawsource = node.astext() # set 'classifier1' (or 'classifier2')
elif isinstance(node, nodes.classifier) and not node.source:
# docutils-0.15 fills in rawsource attribute, but not in source.
node.source = node.parent.source
if isinstance(node, nodes.image) and node.source is None:
logger.debug('[i18n] PATCH: %r to have source, line: %s',
get_full_module_name(node), repr_domxml(node))
node.source, node.line = node.parent.source, node.parent.line
if isinstance(node, nodes.title) and node.source is None:
logger.debug('[i18n] PATCH: %r to have source: %s',
get_full_module_name(node), repr_domxml(node))
node.source, node.line = node.parent.source, node.parent.line
if isinstance(node, nodes.term):
logger.debug('[i18n] PATCH: %r to have rawsource: %s',
get_full_module_name(node), repr_domxml(node))
# strip classifier from rawsource of term
for classifier in reversed(list(node.parent.findall(nodes.classifier))):
node.rawsource = re.sub(r'\s*:\s*%s' % re.escape(classifier.astext()),
'', node.rawsource)
if isinstance(node, nodes.topic) and node.source is None:
# docutils-0.18 does not fill the source attribute of topic
logger.debug('[i18n] PATCH: %r to have source, line: %s',
get_full_module_name(node), repr_domxml(node))
node.source, node.line = node.parent.source, node.parent.line
# workaround: literal_block under bullet list (#4913)
if isinstance(node, nodes.literal_block) and node.source is None:
with contextlib.suppress(ValueError):
node.source = get_node_source(node)
# workaround: recommonmark-0.2.0 doesn't set rawsource attribute
if not node.rawsource:
node.rawsource = node.astext()
if node.source and node.rawsource:
return
# workaround: some docutils nodes doesn't have source, line.
if (isinstance(node, (
nodes.rubric, # #1305 rubric directive
nodes.line, # #1477 line node
nodes.image, # #3093 image directive in substitution
nodes.field_name, # #3335 field list syntax
))):
logger.debug('[i18n] PATCH: %r to have source and line: %s',
get_full_module_name(node), repr_domxml(node))
try:
node.source = get_node_source(node)
except ValueError:
node.source = ''
node.line = 0 # need fix docutils to get `node.line`
return
IGNORED_NODES = (
nodes.Invisible,
nodes.literal_block,
nodes.doctest_block,
addnodes.versionmodified,
# XXX there are probably more
)
def is_translatable(node: Node) -> bool:
if isinstance(node, addnodes.translatable):
return True
# image node marked as translatable or having alt text
if isinstance(node, nodes.image) and (node.get('translatable') or node.get('alt')):
return True
if isinstance(node, nodes.Inline) and 'translatable' not in node: # type: ignore[operator]
# inline node must not be translated if 'translatable' is not set
return False
if isinstance(node, nodes.TextElement):
if not node.source:
logger.debug('[i18n] SKIP %r because no node.source: %s',
get_full_module_name(node), repr_domxml(node))
return False # built-in message
if isinstance(node, IGNORED_NODES) and 'translatable' not in node:
logger.debug("[i18n] SKIP %r because node is in IGNORED_NODES "
"and no node['translatable']: %s",
get_full_module_name(node), repr_domxml(node))
return False
if not node.get('translatable', True):
# not(node['translatable'] == True or node['translatable'] is None)
logger.debug("[i18n] SKIP %r because not node['translatable']: %s",
get_full_module_name(node), repr_domxml(node))
return False
# <field_name>orphan</field_name>
# XXX ignore all metadata (== docinfo)
if isinstance(node, nodes.field_name) and node.children[0] == 'orphan':
logger.debug('[i18n] SKIP %r because orphan node: %s',
get_full_module_name(node), repr_domxml(node))
return False
return True
if isinstance(node, nodes.meta): # type: ignore[attr-defined]
return True
return False
LITERAL_TYPE_NODES = (
nodes.literal_block,
nodes.doctest_block,
nodes.math_block,
nodes.raw,
)
IMAGE_TYPE_NODES = (
nodes.image,
)
def extract_messages(doctree: Element) -> Iterable[tuple[Element, str]]:
"""Extract translatable messages from a document tree."""
for node in doctree.findall(is_translatable): # type: Element
if isinstance(node, addnodes.translatable):
for msg in node.extract_original_messages():
yield node, msg
continue
if isinstance(node, LITERAL_TYPE_NODES):
msg = node.rawsource
if not msg:
msg = node.astext()
elif isinstance(node, nodes.image):
if node.get('alt'):
yield node, node['alt']
if node.get('translatable'):
image_uri = node.get('original_uri', node['uri'])
msg = f'.. image:: {image_uri}'
else:
msg = ''
elif isinstance(node, nodes.meta): # type: ignore[attr-defined]
msg = node["content"]
else:
msg = node.rawsource.replace('\n', ' ').strip()
# XXX nodes rendering empty are likely a bug in sphinx.addnodes
if msg:
yield node, msg
def get_node_source(node: Element) -> str:
for pnode in traverse_parent(node):
if pnode.source:
return pnode.source
msg = 'node source not found'
raise ValueError(msg)
def get_node_line(node: Element) -> int:
for pnode in traverse_parent(node):
if pnode.line:
return pnode.line
msg = 'node line not found'
raise ValueError(msg)
def traverse_parent(node: Element, cls: Any = None) -> Iterable[Element]:
while node:
if cls is None or isinstance(node, cls):
yield node
node = node.parent
def get_prev_node(node: Node) -> Node | None:
pos = node.parent.index(node)
if pos > 0:
return node.parent[pos - 1]
else:
return None
def traverse_translatable_index(
doctree: Element,
) -> Iterable[tuple[Element, list[tuple[str, str, str, str, str | None]]]]:
"""Traverse translatable index node from a document tree."""
matcher = NodeMatcher(addnodes.index, inline=False)
for node in doctree.findall(matcher): # type: addnodes.index
if 'raw_entries' in node:
entries = node['raw_entries']
else:
entries = node['entries']
yield node, entries
def nested_parse_with_titles(state: Any, content: StringList, node: Node,
content_offset: int = 0) -> str:
"""Version of state.nested_parse() that allows titles and does not require
titles to have the same decoration as the calling document.
This is useful when the parsed content comes from a completely different
context, such as docstrings.
"""
# hack around title style bookkeeping
surrounding_title_styles = state.memo.title_styles
surrounding_section_level = state.memo.section_level
state.memo.title_styles = []
state.memo.section_level = 0
try:
return state.nested_parse(content, content_offset, node, match_titles=1)
finally:
state.memo.title_styles = surrounding_title_styles
state.memo.section_level = surrounding_section_level
def clean_astext(node: Element) -> str:
"""Like node.astext(), but ignore images."""
node = node.deepcopy()
for img in node.findall(nodes.image):
img['alt'] = ''
for raw in list(node.findall(nodes.raw)):
raw.parent.remove(raw)
return node.astext()
def split_explicit_title(text: str) -> tuple[bool, str, str]:
"""Split role content into title and target, if given."""
match = explicit_title_re.match(text)
if match:
return True, match.group(1), match.group(2)
return False, text, text
indextypes = [
'single', 'pair', 'double', 'triple', 'see', 'seealso',
]
def process_index_entry(entry: str, targetid: str,
) -> list[tuple[str, str, str, str, str | None]]:
from sphinx.domains.python import pairindextypes
indexentries: list[tuple[str, str, str, str, str | None]] = []
entry = entry.strip()
oentry = entry
main = ''
if entry.startswith('!'):
main = 'main'
entry = entry[1:].lstrip()
for index_type in pairindextypes:
if entry.startswith(f'{index_type}:'):
value = entry[len(index_type) + 1:].strip()
value = f'{pairindextypes[index_type]}; {value}'
# xref RemovedInSphinx90Warning
logger.warning(__('%r is deprecated for index entries (from entry %r). '
"Use 'pair: %s' instead."),
index_type, entry, value, type='index')
indexentries.append(('pair', value, targetid, main, None))
break
else:
for index_type in indextypes:
if entry.startswith(f'{index_type}:'):
value = entry[len(index_type) + 1:].strip()
if index_type == 'double':
index_type = 'pair'
indexentries.append((index_type, value, targetid, main, None))
break
# shorthand notation for single entries
else:
for value in oentry.split(','):
value = value.strip()
main = ''
if value.startswith('!'):
main = 'main'
value = value[1:].lstrip()
if not value:
continue
indexentries.append(('single', value, targetid, main, None))
return indexentries
def inline_all_toctrees(builder: Builder, docnameset: set[str], docname: str,
tree: nodes.document, colorfunc: Callable, traversed: list[str],
) -> nodes.document:
"""Inline all toctrees in the *tree*.
Record all docnames in *docnameset*, and output docnames with *colorfunc*.
"""
tree = tree.deepcopy()
for toctreenode in list(tree.findall(addnodes.toctree)):
newnodes = []
includefiles = map(str, toctreenode['includefiles'])
for includefile in includefiles:
if includefile not in traversed:
try:
traversed.append(includefile)
logger.info(colorfunc(includefile) + " ", nonl=True)
subtree = inline_all_toctrees(builder, docnameset, includefile,
builder.env.get_doctree(includefile),
colorfunc, traversed)
docnameset.add(includefile)
except Exception:
logger.warning(__('toctree contains ref to nonexisting file %r'),
includefile, location=docname)
else:
sof = addnodes.start_of_file(docname=includefile)
sof.children = subtree.children
for sectionnode in sof.findall(nodes.section):
if 'docname' not in sectionnode:
sectionnode['docname'] = includefile
newnodes.append(sof)
toctreenode.parent.replace(toctreenode, newnodes)
return tree
def _make_id(string: str) -> str:
"""Convert `string` into an identifier and return it.
This function is a modified version of ``docutils.nodes.make_id()`` of
docutils-0.16.
Changes:
* Allow to use capital alphabet characters
* Allow to use dots (".") and underscores ("_") for an identifier
without a leading character.
# Author: David Goodger <goodger@python.org>
# Maintainer: docutils-develop@lists.sourceforge.net
# Copyright: This module has been placed in the public domain.
"""
id = string.translate(_non_id_translate_digraphs)
id = id.translate(_non_id_translate)
# get rid of non-ascii characters.
# 'ascii' lowercase to prevent problems with turkish locale.
id = unicodedata.normalize('NFKD', id).encode('ascii', 'ignore').decode('ascii')
# shrink runs of whitespace and replace by hyphen
id = _non_id_chars.sub('-', ' '.join(id.split()))
id = _non_id_at_ends.sub('', id)
return str(id)
_non_id_chars = re.compile('[^a-zA-Z0-9._]+')
_non_id_at_ends = re.compile('^[-0-9._]+|-+$')
_non_id_translate = {
0x00f8: 'o', # o with stroke
0x0111: 'd', # d with stroke
0x0127: 'h', # h with stroke
0x0131: 'i', # dotless i
0x0142: 'l', # l with stroke
0x0167: 't', # t with stroke
0x0180: 'b', # b with stroke
0x0183: 'b', # b with topbar
0x0188: 'c', # c with hook
0x018c: 'd', # d with topbar
0x0192: 'f', # f with hook
0x0199: 'k', # k with hook
0x019a: 'l', # l with bar
0x019e: 'n', # n with long right leg
0x01a5: 'p', # p with hook
0x01ab: 't', # t with palatal hook
0x01ad: 't', # t with hook
0x01b4: 'y', # y with hook
0x01b6: 'z', # z with stroke
0x01e5: 'g', # g with stroke
0x0225: 'z', # z with hook
0x0234: 'l', # l with curl
0x0235: 'n', # n with curl
0x0236: 't', # t with curl
0x0237: 'j', # dotless j
0x023c: 'c', # c with stroke
0x023f: 's', # s with swash tail
0x0240: 'z', # z with swash tail
0x0247: 'e', # e with stroke
0x0249: 'j', # j with stroke
0x024b: 'q', # q with hook tail
0x024d: 'r', # r with stroke
0x024f: 'y', # y with stroke
}
_non_id_translate_digraphs = {
0x00df: 'sz', # ligature sz
0x00e6: 'ae', # ae
0x0153: 'oe', # ligature oe
0x0238: 'db', # db digraph
0x0239: 'qp', # qp digraph
}
def make_id(env: BuildEnvironment, document: nodes.document,
prefix: str = '', term: str | None = None) -> str:
"""Generate an appropriate node_id for given *prefix* and *term*."""
node_id = None
if prefix:
idformat = prefix + "-%s"
else:
idformat = (document.settings.id_prefix or "id") + "%s"
# try to generate node_id by *term*
if prefix and term:
node_id = _make_id(idformat % term)
if node_id == prefix:
# *term* is not good to generate a node_id.
node_id = None
elif term:
node_id = _make_id(term)
if node_id == '':
node_id = None # fallback to None
while node_id is None or node_id in document.ids:
node_id = idformat % env.new_serialno(prefix)
return node_id
def find_pending_xref_condition(node: addnodes.pending_xref, condition: str,
) -> Element | None:
"""Pick matched pending_xref_condition node up from the pending_xref."""
for subnode in node:
if (isinstance(subnode, addnodes.pending_xref_condition) and
subnode.get('condition') == condition):
return subnode
return None
def make_refnode(builder: Builder, fromdocname: str, todocname: str, targetid: str | None,
child: Node | list[Node], title: str | None = None,
) -> nodes.reference:
"""Shortcut to create a reference node."""
node = nodes.reference('', '', internal=True)
if fromdocname == todocname and targetid:
node['refid'] = targetid
else:
if targetid:
node['refuri'] = (builder.get_relative_uri(fromdocname, todocname) +
'#' + targetid)
else:
node['refuri'] = builder.get_relative_uri(fromdocname, todocname)
if title:
node['reftitle'] = title
node += child
return node
def set_source_info(directive: Directive, node: Node) -> None:
node.source, node.line = \
directive.state_machine.get_source_and_line(directive.lineno)
def set_role_source_info(inliner: Inliner, lineno: int, node: Node) -> None:
gsal = inliner.reporter.get_source_and_line # type: ignore[attr-defined]
node.source, node.line = gsal(lineno)
def copy_source_info(src: Element, dst: Element) -> None:
with contextlib.suppress(ValueError):
dst.source = get_node_source(src)
dst.line = get_node_line(src)
NON_SMARTQUOTABLE_PARENT_NODES = (
nodes.FixedTextElement,
nodes.literal,
nodes.math,
nodes.image,
nodes.raw,
nodes.problematic,
addnodes.not_smartquotable,
)
def is_smartquotable(node: Node) -> bool:
"""Check whether the node is smart-quotable or not."""
for pnode in traverse_parent(node.parent):
if isinstance(pnode, NON_SMARTQUOTABLE_PARENT_NODES):
return False
if pnode.get('support_smartquotes', None) is False:
return False
if getattr(node, 'support_smartquotes', None) is False:
return False
return True
def process_only_nodes(document: Node, tags: Tags) -> None:
"""Filter ``only`` nodes which do not match *tags*."""
for node in document.findall(addnodes.only):
if _only_node_keep_children(node, tags):
node.replace_self(node.children or nodes.comment())
else:
# A comment on the comment() nodes being inserted: replacing by [] would
# 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...
node.replace_self(nodes.comment())
def _only_node_keep_children(node: addnodes.only, tags: Tags) -> bool:
"""Keep children if tags match or error."""
try:
return tags.eval_condition(node['expr'])
except Exception as err:
logger.warning(
__('exception while evaluating only directive expression: %s'),
err,
location=node)
return True
def _copy_except__document(el: Element) -> Element:
"""Monkey-patch ```nodes.Element.copy``` to not copy the ``_document``
attribute.
xref: https://github.com/sphinx-doc/sphinx/issues/11116#issuecomment-1376767086
"""
newnode = object.__new__(el.__class__)
# set in Element.__init__()
newnode.children = []
newnode.rawsource = el.rawsource
newnode.tagname = el.tagname
# copied in Element.copy()
newnode.attributes = {k: (v
if k not in {'ids', 'classes', 'names', 'dupnames', 'backrefs'}
else v[:])
for k, v in el.attributes.items()}
newnode.line = el.line
newnode.source = el.source
return newnode
nodes.Element.copy = _copy_except__document # type: ignore[assignment]
def _deepcopy(el: Element) -> Element:
"""Monkey-patch ```nodes.Element.deepcopy``` for speed."""
newnode = el.copy()
newnode.children = [child.deepcopy() for child in el.children]
for child in newnode.children:
child.parent = newnode
if el.document:
child.document = el.document
if child.source is None:
child.source = el.document.current_source
if child.line is None:
child.line = el.document.current_line
return newnode
nodes.Element.deepcopy = _deepcopy # type: ignore[assignment]