"""The Python domain.""" from __future__ import annotations import ast import builtins import contextlib import inspect import re import token import typing from inspect import Parameter from typing import TYPE_CHECKING, Any, NamedTuple, cast from docutils import nodes from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.addnodes import desc_signature, pending_xref, pending_xref_condition from sphinx.directives import ObjectDescription from sphinx.domains import Domain, Index, IndexEntry, ObjType from sphinx.locale import _, __ from sphinx.pycode.parser import Token, TokenProcessor from sphinx.roles import XRefRole from sphinx.util import logging from sphinx.util.docfields import Field, GroupedField, TypedField from sphinx.util.docutils import SphinxDirective from sphinx.util.inspect import signature_from_str from sphinx.util.nodes import ( find_pending_xref_condition, make_id, make_refnode, nested_parse_with_titles, ) if TYPE_CHECKING: from collections.abc import Iterable, Iterator from docutils.nodes import Element, Node from docutils.parsers.rst.states import Inliner from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.environment import BuildEnvironment from sphinx.util.typing import OptionSpec, TextlikeNode logger = logging.getLogger(__name__) # REs for Python signatures py_sig_re = re.compile( r'''^ ([\w.]*\.)? # class name(s) (\w+) \s* # thing name (?: \[\s*(.*)\s*])? # optional: type parameters list (?: \(\s*(.*)\s*\) # optional: arguments (?:\s* -> \s* (.*))? # return annotation )? $ # and nothing more ''', re.VERBOSE) pairindextypes = { 'module': 'module', 'keyword': 'keyword', 'operator': 'operator', 'object': 'object', 'exception': 'exception', 'statement': 'statement', 'builtin': 'built-in function', } class ObjectEntry(NamedTuple): docname: str node_id: str objtype: str aliased: bool class ModuleEntry(NamedTuple): docname: str node_id: str synopsis: str platform: str deprecated: bool def parse_reftarget(reftarget: str, suppress_prefix: bool = False, ) -> tuple[str, str, str, bool]: """Parse a type string and return (reftype, reftarget, title, refspecific flag)""" refspecific = False if reftarget.startswith('.'): reftarget = reftarget[1:] title = reftarget refspecific = True elif reftarget.startswith('~'): reftarget = reftarget[1:] title = reftarget.split('.')[-1] elif suppress_prefix: title = reftarget.split('.')[-1] elif reftarget.startswith('typing.'): title = reftarget[7:] else: title = reftarget if reftarget == 'None' or reftarget.startswith('typing.'): # typing module provides non-class types. Obj reference is good to refer them. reftype = 'obj' else: reftype = 'class' return reftype, reftarget, title, refspecific def type_to_xref(target: str, env: BuildEnvironment, *, suppress_prefix: bool = False) -> addnodes.pending_xref: """Convert a type string to a cross reference node.""" if env: kwargs = {'py:module': env.ref_context.get('py:module'), 'py:class': env.ref_context.get('py:class')} else: kwargs = {} reftype, target, title, refspecific = parse_reftarget(target, suppress_prefix) if env.config.python_use_unqualified_type_names: # Note: It would be better to use qualname to describe the object to support support # nested classes. But python domain can't access the real python object because this # module should work not-dynamically. shortname = title.split('.')[-1] contnodes: list[Node] = [pending_xref_condition('', shortname, condition='resolved'), pending_xref_condition('', title, condition='*')] else: contnodes = [nodes.Text(title)] return pending_xref('', *contnodes, refdomain='py', reftype=reftype, reftarget=target, refspecific=refspecific, **kwargs) def _parse_annotation(annotation: str, env: BuildEnvironment) -> list[Node]: """Parse type annotation.""" short_literals = env.config.python_display_short_literal_types def unparse(node: ast.AST) -> list[Node]: if isinstance(node, ast.Attribute): return [nodes.Text(f"{unparse(node.value)[0]}.{node.attr}")] if isinstance(node, ast.BinOp): result: list[Node] = unparse(node.left) result.extend(unparse(node.op)) result.extend(unparse(node.right)) return result if isinstance(node, ast.BitOr): return [addnodes.desc_sig_space(), addnodes.desc_sig_punctuation('', '|'), addnodes.desc_sig_space()] if isinstance(node, ast.Constant): if node.value is Ellipsis: return [addnodes.desc_sig_punctuation('', "...")] if isinstance(node.value, bool): return [addnodes.desc_sig_keyword('', repr(node.value))] if isinstance(node.value, int): return [addnodes.desc_sig_literal_number('', repr(node.value))] if isinstance(node.value, str): return [addnodes.desc_sig_literal_string('', repr(node.value))] else: # handles None, which is further handled by type_to_xref later # and fallback for other types that should be converted return [nodes.Text(repr(node.value))] if isinstance(node, ast.Expr): return unparse(node.value) if isinstance(node, ast.Invert): return [addnodes.desc_sig_punctuation('', '~')] if isinstance(node, ast.List): result = [addnodes.desc_sig_punctuation('', '[')] if node.elts: # check if there are elements in node.elts to only pop the # last element of result if the for-loop was run at least # once for elem in node.elts: result.extend(unparse(elem)) result.append(addnodes.desc_sig_punctuation('', ',')) result.append(addnodes.desc_sig_space()) result.pop() result.pop() result.append(addnodes.desc_sig_punctuation('', ']')) return result if isinstance(node, ast.Module): return sum((unparse(e) for e in node.body), []) if isinstance(node, ast.Name): return [nodes.Text(node.id)] if isinstance(node, ast.Subscript): if getattr(node.value, 'id', '') in {'Optional', 'Union'}: return _unparse_pep_604_annotation(node) if short_literals and getattr(node.value, 'id', '') == 'Literal': return _unparse_pep_604_annotation(node) result = unparse(node.value) result.append(addnodes.desc_sig_punctuation('', '[')) result.extend(unparse(node.slice)) result.append(addnodes.desc_sig_punctuation('', ']')) # Wrap the Text nodes inside brackets by literal node if the subscript is a Literal if result[0] in ('Literal', 'typing.Literal'): for i, subnode in enumerate(result[1:], start=1): if isinstance(subnode, nodes.Text): result[i] = nodes.literal('', '', subnode) return result if isinstance(node, ast.UnaryOp): return unparse(node.op) + unparse(node.operand) if isinstance(node, ast.Tuple): if node.elts: result = [] for elem in node.elts: result.extend(unparse(elem)) result.append(addnodes.desc_sig_punctuation('', ',')) result.append(addnodes.desc_sig_space()) result.pop() result.pop() else: result = [addnodes.desc_sig_punctuation('', '('), addnodes.desc_sig_punctuation('', ')')] return result raise SyntaxError # unsupported syntax def _unparse_pep_604_annotation(node: ast.Subscript) -> list[Node]: subscript = node.slice flattened: list[Node] = [] if isinstance(subscript, ast.Tuple): flattened.extend(unparse(subscript.elts[0])) for elt in subscript.elts[1:]: flattened.extend(unparse(ast.BitOr())) flattened.extend(unparse(elt)) else: # e.g. a Union[] inside an Optional[] flattened.extend(unparse(subscript)) if getattr(node.value, 'id', '') == 'Optional': flattened.extend(unparse(ast.BitOr())) flattened.append(nodes.Text('None')) return flattened try: tree = ast.parse(annotation, type_comments=True) result: list[Node] = [] for node in unparse(tree): if isinstance(node, nodes.literal): result.append(node[0]) elif isinstance(node, nodes.Text) and node.strip(): if (result and isinstance(result[-1], addnodes.desc_sig_punctuation) and result[-1].astext() == '~'): result.pop() result.append(type_to_xref(str(node), env, suppress_prefix=True)) else: result.append(type_to_xref(str(node), env)) else: result.append(node) return result except SyntaxError: return [type_to_xref(annotation, env)] class _TypeParameterListParser(TokenProcessor): def __init__(self, sig: str) -> None: signature = sig.replace('\n', '').strip() super().__init__([signature]) # Each item is a tuple (name, kind, default, annotation) mimicking # ``inspect.Parameter`` to allow default values on VAR_POSITIONAL # or VAR_KEYWORD parameters. self.type_params: list[tuple[str, int, Any, Any]] = [] def fetch_type_param_spec(self) -> list[Token]: tokens = [] while current := self.fetch_token(): tokens.append(current) for ldelim, rdelim in ('(', ')'), ('{', '}'), ('[', ']'): if current == [token.OP, ldelim]: tokens += self.fetch_until([token.OP, rdelim]) break else: if current == token.INDENT: tokens += self.fetch_until(token.DEDENT) elif current.match( [token.OP, ':'], [token.OP, '='], [token.OP, ',']): tokens.pop() break return tokens def parse(self) -> None: while current := self.fetch_token(): if current == token.NAME: tp_name = current.value.strip() if self.previous and self.previous.match([token.OP, '*'], [token.OP, '**']): if self.previous == [token.OP, '*']: tp_kind = Parameter.VAR_POSITIONAL else: tp_kind = Parameter.VAR_KEYWORD # type: ignore[assignment] else: tp_kind = Parameter.POSITIONAL_OR_KEYWORD # type: ignore[assignment] tp_ann: Any = Parameter.empty tp_default: Any = Parameter.empty current = self.fetch_token() if current and current.match([token.OP, ':'], [token.OP, '=']): if current == [token.OP, ':']: tokens = self.fetch_type_param_spec() tp_ann = self._build_identifier(tokens) if self.current and self.current == [token.OP, '=']: tokens = self.fetch_type_param_spec() tp_default = self._build_identifier(tokens) if tp_kind != Parameter.POSITIONAL_OR_KEYWORD and tp_ann != Parameter.empty: msg = ('type parameter bound or constraint is not allowed ' f'for {tp_kind.description} parameters') raise SyntaxError(msg) type_param = (tp_name, tp_kind, tp_default, tp_ann) self.type_params.append(type_param) def _build_identifier(self, tokens: list[Token]) -> str: from itertools import chain, tee def pairwise(iterable): a, b = tee(iterable) next(b, None) return zip(a, b) def triplewise(iterable): for (a, _z), (b, c) in pairwise(pairwise(iterable)): yield a, b, c idents: list[str] = [] tokens: Iterable[Token] = iter(tokens) # type: ignore[no-redef] # do not format opening brackets for tok in tokens: if not tok.match([token.OP, '('], [token.OP, '['], [token.OP, '{']): # check if the first non-delimiter character is an unpack operator is_unpack_operator = tok.match([token.OP, '*'], [token.OP, ['**']]) idents.append(self._pformat_token(tok, native=is_unpack_operator)) break idents.append(tok.value) # check the remaining tokens stop = Token(token.ENDMARKER, '', (-1, -1), (-1, -1), '') is_unpack_operator = False for tok, op, after in triplewise(chain(tokens, [stop, stop])): ident = self._pformat_token(tok, native=is_unpack_operator) idents.append(ident) # determine if the next token is an unpack operator depending # on the left and right hand side of the operator symbol is_unpack_operator = ( op.match([token.OP, '*'], [token.OP, '**']) and not ( tok.match(token.NAME, token.NUMBER, token.STRING, [token.OP, ')'], [token.OP, ']'], [token.OP, '}']) and after.match(token.NAME, token.NUMBER, token.STRING, [token.OP, '('], [token.OP, '['], [token.OP, '{']) ) ) return ''.join(idents).strip() def _pformat_token(self, tok: Token, native: bool = False) -> str: if native: return tok.value if tok.match(token.NEWLINE, token.ENDMARKER): return '' if tok.match([token.OP, ':'], [token.OP, ','], [token.OP, '#']): return f'{tok.value} ' # Arithmetic operators are allowed because PEP 695 specifies the # default type parameter to be *any* expression (so "T1 << T2" is # allowed if it makes sense). The caller is responsible to ensure # that a multiplication operator ("*") is not to be confused with # an unpack operator (which will not be surrounded by spaces). # # The operators are ordered according to how likely they are to # be used and for (possible) future implementations (e.g., "&" for # an intersection type). if tok.match( # Most likely operators to appear [token.OP, '='], [token.OP, '|'], # Type composition (future compatibility) [token.OP, '&'], [token.OP, '^'], [token.OP, '<'], [token.OP, '>'], # Unlikely type composition [token.OP, '+'], [token.OP, '-'], [token.OP, '*'], [token.OP, '**'], # Unlikely operators but included for completeness [token.OP, '@'], [token.OP, '/'], [token.OP, '//'], [token.OP, '%'], [token.OP, '<<'], [token.OP, '>>'], [token.OP, '>>>'], [token.OP, '<='], [token.OP, '>='], [token.OP, '=='], [token.OP, '!='], ): return f' {tok.value} ' return tok.value def _parse_type_list( tp_list: str, env: BuildEnvironment, multi_line_parameter_list: bool = False, ) -> addnodes.desc_type_parameter_list: """Parse a list of type parameters according to PEP 695.""" type_params = addnodes.desc_type_parameter_list(tp_list) type_params['multi_line_parameter_list'] = multi_line_parameter_list # formal parameter names are interpreted as type parameter names and # type annotations are interpreted as type parameter bound or constraints parser = _TypeParameterListParser(tp_list) parser.parse() for (tp_name, tp_kind, tp_default, tp_ann) in parser.type_params: # no positional-only or keyword-only allowed in a type parameters list if tp_kind in {Parameter.POSITIONAL_ONLY, Parameter.KEYWORD_ONLY}: msg = ('positional-only or keyword-only parameters ' 'are prohibited in type parameter lists') raise SyntaxError(msg) node = addnodes.desc_type_parameter() if tp_kind == Parameter.VAR_POSITIONAL: node += addnodes.desc_sig_operator('', '*') elif tp_kind == Parameter.VAR_KEYWORD: node += addnodes.desc_sig_operator('', '**') node += addnodes.desc_sig_name('', tp_name) if tp_ann is not Parameter.empty: annotation = _parse_annotation(tp_ann, env) if not annotation: continue node += addnodes.desc_sig_punctuation('', ':') node += addnodes.desc_sig_space() type_ann_expr = addnodes.desc_sig_name('', '', *annotation) # type: ignore[arg-type] # a type bound is ``T: U`` whereas type constraints # must be enclosed with parentheses. ``T: (U, V)`` if tp_ann.startswith('(') and tp_ann.endswith(')'): type_ann_text = type_ann_expr.astext() if type_ann_text.startswith('(') and type_ann_text.endswith(')'): node += type_ann_expr else: # surrounding braces are lost when using _parse_annotation() node += addnodes.desc_sig_punctuation('', '(') node += type_ann_expr # type constraint node += addnodes.desc_sig_punctuation('', ')') else: node += type_ann_expr # type bound if tp_default is not Parameter.empty: # Always surround '=' with spaces, even if there is no annotation node += addnodes.desc_sig_space() node += addnodes.desc_sig_operator('', '=') node += addnodes.desc_sig_space() node += nodes.inline('', tp_default, classes=['default_value'], support_smartquotes=False) type_params += node return type_params def _parse_arglist( arglist: str, env: BuildEnvironment, multi_line_parameter_list: bool = False, ) -> addnodes.desc_parameterlist: """Parse a list of arguments using AST parser""" params = addnodes.desc_parameterlist(arglist) params['multi_line_parameter_list'] = multi_line_parameter_list sig = signature_from_str('(%s)' % arglist) last_kind = None for param in sig.parameters.values(): if param.kind != param.POSITIONAL_ONLY and last_kind == param.POSITIONAL_ONLY: # PEP-570: Separator for Positional Only Parameter: / params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/')) if param.kind == param.KEYWORD_ONLY and last_kind in (param.POSITIONAL_OR_KEYWORD, param.POSITIONAL_ONLY, None): # PEP-3102: Separator for Keyword Only Parameter: * params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '*')) node = addnodes.desc_parameter() if param.kind == param.VAR_POSITIONAL: node += addnodes.desc_sig_operator('', '*') node += addnodes.desc_sig_name('', param.name) elif param.kind == param.VAR_KEYWORD: node += addnodes.desc_sig_operator('', '**') node += addnodes.desc_sig_name('', param.name) else: node += addnodes.desc_sig_name('', param.name) if param.annotation is not param.empty: children = _parse_annotation(param.annotation, env) node += addnodes.desc_sig_punctuation('', ':') node += addnodes.desc_sig_space() node += addnodes.desc_sig_name('', '', *children) # type: ignore[arg-type] if param.default is not param.empty: if param.annotation is not param.empty: node += addnodes.desc_sig_space() node += addnodes.desc_sig_operator('', '=') node += addnodes.desc_sig_space() else: node += addnodes.desc_sig_operator('', '=') node += nodes.inline('', param.default, classes=['default_value'], support_smartquotes=False) params += node last_kind = param.kind if last_kind == Parameter.POSITIONAL_ONLY: # PEP-570: Separator for Positional Only Parameter: / params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/')) return params def _pseudo_parse_arglist( signode: desc_signature, arglist: str, multi_line_parameter_list: bool = False, ) -> None: """"Parse" a list of arguments separated by commas. Arguments can have "optional" annotations given by enclosing them in brackets. Currently, this will split at any comma, even if it's inside a string literal (e.g. default argument value). """ paramlist = addnodes.desc_parameterlist() paramlist['multi_line_parameter_list'] = multi_line_parameter_list stack: list[Element] = [paramlist] try: for argument in arglist.split(','): argument = argument.strip() ends_open = ends_close = 0 while argument.startswith('['): stack.append(addnodes.desc_optional()) stack[-2] += stack[-1] argument = argument[1:].strip() while argument.startswith(']'): stack.pop() argument = argument[1:].strip() while argument.endswith(']') and not argument.endswith('[]'): ends_close += 1 argument = argument[:-1].strip() while argument.endswith('['): ends_open += 1 argument = argument[:-1].strip() if argument: stack[-1] += addnodes.desc_parameter( '', '', addnodes.desc_sig_name(argument, argument)) while ends_open: stack.append(addnodes.desc_optional()) stack[-2] += stack[-1] ends_open -= 1 while ends_close: stack.pop() ends_close -= 1 if len(stack) != 1: raise IndexError except IndexError: # if there are too few or too many elements on the stack, just give up # and treat the whole argument list as one argument, discarding the # already partially populated paramlist node paramlist = addnodes.desc_parameterlist() paramlist += addnodes.desc_parameter(arglist, arglist) signode += paramlist else: signode += paramlist # This override allows our inline type specifiers to behave like :class: link # when it comes to handling "." and "~" prefixes. class PyXrefMixin: def make_xref( self, rolename: str, domain: str, target: str, innernode: type[TextlikeNode] = nodes.emphasis, contnode: Node | None = None, env: BuildEnvironment | None = None, inliner: Inliner | None = None, location: Node | None = None, ) -> Node: # we use inliner=None to make sure we get the old behaviour with a single # pending_xref node result = super().make_xref(rolename, domain, target, # type: ignore[misc] innernode, contnode, env, inliner=None, location=None) if isinstance(result, pending_xref): assert env is not None result['refspecific'] = True result['py:module'] = env.ref_context.get('py:module') result['py:class'] = env.ref_context.get('py:class') reftype, reftarget, reftitle, _ = parse_reftarget(target) if reftarget != reftitle: result['reftype'] = reftype result['reftarget'] = reftarget result.clear() result += innernode(reftitle, reftitle) elif env.config.python_use_unqualified_type_names: children = result.children result.clear() shortname = target.split('.')[-1] textnode = innernode('', shortname) contnodes = [pending_xref_condition('', '', textnode, condition='resolved'), pending_xref_condition('', '', *children, condition='*')] result.extend(contnodes) return result def make_xrefs( self, rolename: str, domain: str, target: str, innernode: type[TextlikeNode] = nodes.emphasis, contnode: Node | None = None, env: BuildEnvironment | None = None, inliner: Inliner | None = None, location: Node | None = None, ) -> list[Node]: delims = r'(\s*[\[\]\(\),](?:\s*o[rf]\s)?\s*|\s+o[rf]\s+|\s*\|\s*|\.\.\.)' delims_re = re.compile(delims) sub_targets = re.split(delims, target) split_contnode = bool(contnode and contnode.astext() == target) in_literal = False results = [] for sub_target in filter(None, sub_targets): if split_contnode: contnode = nodes.Text(sub_target) if in_literal or delims_re.match(sub_target): results.append(contnode or innernode(sub_target, sub_target)) else: results.append(self.make_xref(rolename, domain, sub_target, innernode, contnode, env, inliner, location)) if sub_target in ('Literal', 'typing.Literal', '~typing.Literal'): in_literal = True return results class PyField(PyXrefMixin, Field): pass class PyGroupedField(PyXrefMixin, GroupedField): pass class PyTypedField(PyXrefMixin, TypedField): pass class PyObject(ObjectDescription[tuple[str, str]]): """ Description of a general Python object. :cvar allow_nesting: Class is an object that allows for nested namespaces :vartype allow_nesting: bool """ option_spec: OptionSpec = { 'no-index': directives.flag, 'no-index-entry': directives.flag, 'no-contents-entry': directives.flag, 'no-typesetting': directives.flag, 'noindex': directives.flag, 'noindexentry': directives.flag, 'nocontentsentry': directives.flag, 'single-line-parameter-list': directives.flag, 'single-line-type-parameter-list': directives.flag, 'module': directives.unchanged, 'canonical': directives.unchanged, 'annotation': directives.unchanged, } doc_field_types = [ PyTypedField('parameter', label=_('Parameters'), names=('param', 'parameter', 'arg', 'argument', 'keyword', 'kwarg', 'kwparam'), typerolename='class', typenames=('paramtype', 'type'), can_collapse=True), PyTypedField('variable', label=_('Variables'), names=('var', 'ivar', 'cvar'), typerolename='class', typenames=('vartype',), can_collapse=True), PyGroupedField('exceptions', label=_('Raises'), rolename='exc', names=('raises', 'raise', 'exception', 'except'), can_collapse=True), Field('returnvalue', label=_('Returns'), has_arg=False, names=('returns', 'return')), PyField('returntype', label=_('Return type'), has_arg=False, names=('rtype',), bodyrolename='class'), ] allow_nesting = False def get_signature_prefix(self, sig: str) -> list[nodes.Node]: """May return a prefix to put before the object name in the signature. """ return [] def needs_arglist(self) -> bool: """May return true if an empty argument list is to be generated even if the document contains none. """ return False def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]: """Transform a Python signature into RST nodes. Return (fully qualified name of the thing, classname if any). If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present """ m = py_sig_re.match(sig) if m is None: raise ValueError prefix, name, tp_list, arglist, retann = m.groups() # determine module and class name (if applicable), as well as full name modname = self.options.get('module', self.env.ref_context.get('py:module')) classname = self.env.ref_context.get('py:class') if classname: add_module = False if prefix and (prefix == classname or prefix.startswith(classname + ".")): fullname = prefix + name # class name is given again in the signature prefix = prefix[len(classname):].lstrip('.') elif prefix: # class name is given in the signature, but different # (shouldn't happen) fullname = classname + '.' + prefix + name else: # class name is not given in the signature fullname = classname + '.' + name else: add_module = True if prefix: classname = prefix.rstrip('.') fullname = prefix + name else: classname = '' fullname = name signode['module'] = modname signode['class'] = classname signode['fullname'] = fullname max_len = (self.env.config.python_maximum_signature_line_length or self.env.config.maximum_signature_line_length or 0) # determine if the function arguments (without its type parameters) # should be formatted on a multiline or not by removing the width of # the type parameters list (if any) sig_len = len(sig) tp_list_span = m.span(3) multi_line_parameter_list = ( 'single-line-parameter-list' not in self.options and (sig_len - (tp_list_span[1] - tp_list_span[0])) > max_len > 0 ) # determine whether the type parameter list must be wrapped or not arglist_span = m.span(4) multi_line_type_parameter_list = ( 'single-line-type-parameter-list' not in self.options and (sig_len - (arglist_span[1] - arglist_span[0])) > max_len > 0 ) sig_prefix = self.get_signature_prefix(sig) if sig_prefix: if type(sig_prefix) is str: msg = ("Python directive method get_signature_prefix()" " must return a list of nodes." f" Return value was '{sig_prefix}'.") raise TypeError(msg) signode += addnodes.desc_annotation(str(sig_prefix), '', *sig_prefix) if prefix: signode += addnodes.desc_addname(prefix, prefix) elif modname and add_module and self.env.config.add_module_names: nodetext = modname + '.' signode += addnodes.desc_addname(nodetext, nodetext) signode += addnodes.desc_name(name, name) if tp_list: try: signode += _parse_type_list(tp_list, self.env, multi_line_type_parameter_list) except Exception as exc: logger.warning("could not parse tp_list (%r): %s", tp_list, exc, location=signode) if arglist: try: signode += _parse_arglist(arglist, self.env, multi_line_parameter_list) except SyntaxError: # fallback to parse arglist original parser # (this may happen if the argument list is incorrectly used # as a list of bases when documenting a class) # it supports to represent optional arguments (ex. "func(foo [, bar])") _pseudo_parse_arglist(signode, arglist, multi_line_parameter_list) except (NotImplementedError, ValueError) as exc: # duplicated parameter names raise ValueError and not a SyntaxError logger.warning("could not parse arglist (%r): %s", arglist, exc, location=signode) _pseudo_parse_arglist(signode, arglist, multi_line_parameter_list) else: if self.needs_arglist(): # for callables, add an empty parameter list signode += addnodes.desc_parameterlist() if retann: children = _parse_annotation(retann, self.env) signode += addnodes.desc_returns(retann, '', *children) anno = self.options.get('annotation') if anno: signode += addnodes.desc_annotation(' ' + anno, '', addnodes.desc_sig_space(), nodes.Text(anno)) return fullname, prefix def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]: if 'fullname' not in sig_node: return () modname = sig_node.get('module') fullname = sig_node['fullname'] if modname: return (modname, *fullname.split('.')) else: return tuple(fullname.split('.')) def get_index_text(self, modname: str, name: tuple[str, str]) -> str: """Return the text for the index entry of the object.""" msg = 'must be implemented in subclasses' raise NotImplementedError(msg) def add_target_and_index(self, name_cls: tuple[str, str], sig: str, signode: desc_signature) -> None: modname = self.options.get('module', self.env.ref_context.get('py:module')) fullname = (modname + '.' if modname else '') + name_cls[0] node_id = make_id(self.env, self.state.document, '', fullname) signode['ids'].append(node_id) self.state.document.note_explicit_target(signode) domain = cast(PythonDomain, self.env.get_domain('py')) domain.note_object(fullname, self.objtype, node_id, location=signode) canonical_name = self.options.get('canonical') if canonical_name: domain.note_object(canonical_name, self.objtype, node_id, aliased=True, location=signode) if 'no-index-entry' not in self.options: indextext = self.get_index_text(modname, name_cls) if indextext: self.indexnode['entries'].append(('single', indextext, node_id, '', None)) def before_content(self) -> None: """Handle object nesting before content :py:class:`PyObject` represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in :py:meth:`after_content`. For constructs that aren't nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with :py:meth:`after_content`. """ prefix = None if self.names: # fullname and name_prefix come from the `handle_signature` method. # fullname represents the full object name that is constructed using # object nesting and explicit prefixes. `name_prefix` is the # explicit prefix given in a signature (fullname, name_prefix) = self.names[-1] if self.allow_nesting: prefix = fullname elif name_prefix: prefix = name_prefix.strip('.') if prefix: self.env.ref_context['py:class'] = prefix if self.allow_nesting: classes = self.env.ref_context.setdefault('py:classes', []) classes.append(prefix) if 'module' in self.options: modules = self.env.ref_context.setdefault('py:modules', []) modules.append(self.env.ref_context.get('py:module')) self.env.ref_context['py:module'] = self.options['module'] def after_content(self) -> None: """Handle object de-nesting after content If this class is a nestable object, removing the last nested class prefix ends further nesting in the object. If this class is not a nestable object, the list of classes should not be altered as we didn't affect the nesting levels in :py:meth:`before_content`. """ classes = self.env.ref_context.setdefault('py:classes', []) if self.allow_nesting: with contextlib.suppress(IndexError): classes.pop() self.env.ref_context['py:class'] = (classes[-1] if len(classes) > 0 else None) if 'module' in self.options: modules = self.env.ref_context.setdefault('py:modules', []) if modules: self.env.ref_context['py:module'] = modules.pop() else: self.env.ref_context.pop('py:module') def _toc_entry_name(self, sig_node: desc_signature) -> str: if not sig_node.get('_toc_parts'): return '' config = self.env.app.config objtype = sig_node.parent.get('objtype') if config.add_function_parentheses and objtype in {'function', 'method'}: parens = '()' else: parens = '' *parents, name = sig_node['_toc_parts'] if config.toc_object_entries_show_parents == 'domain': return sig_node.get('fullname', name) + parens if config.toc_object_entries_show_parents == 'hide': return name + parens if config.toc_object_entries_show_parents == 'all': return '.'.join(parents + [name + parens]) return '' class PyFunction(PyObject): """Description of a function.""" option_spec: OptionSpec = PyObject.option_spec.copy() option_spec.update({ 'async': directives.flag, }) def get_signature_prefix(self, sig: str) -> list[nodes.Node]: if 'async' in self.options: return [addnodes.desc_sig_keyword('', 'async'), addnodes.desc_sig_space()] else: return [] def needs_arglist(self) -> bool: return True def add_target_and_index(self, name_cls: tuple[str, str], sig: str, signode: desc_signature) -> None: super().add_target_and_index(name_cls, sig, signode) if 'no-index-entry' not in self.options: modname = self.options.get('module', self.env.ref_context.get('py:module')) node_id = signode['ids'][0] name, cls = name_cls if modname: text = _('%s() (in module %s)') % (name, modname) self.indexnode['entries'].append(('single', text, node_id, '', None)) else: text = f'built-in function; {name}()' self.indexnode['entries'].append(('pair', text, node_id, '', None)) def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str: # add index in own add_target_and_index() instead. return '' class PyDecoratorFunction(PyFunction): """Description of a decorator.""" def run(self) -> list[Node]: # a decorator function is a function after all self.name = 'py:function' return super().run() def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]: ret = super().handle_signature(sig, signode) signode.insert(0, addnodes.desc_addname('@', '@')) return ret def needs_arglist(self) -> bool: return False class PyVariable(PyObject): """Description of a variable.""" option_spec: OptionSpec = PyObject.option_spec.copy() option_spec.update({ 'type': directives.unchanged, 'value': directives.unchanged, }) def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]: fullname, prefix = super().handle_signature(sig, signode) typ = self.options.get('type') if typ: annotations = _parse_annotation(typ, self.env) signode += addnodes.desc_annotation(typ, '', addnodes.desc_sig_punctuation('', ':'), addnodes.desc_sig_space(), *annotations) value = self.options.get('value') if value: signode += addnodes.desc_annotation(value, '', addnodes.desc_sig_space(), addnodes.desc_sig_punctuation('', '='), addnodes.desc_sig_space(), nodes.Text(value)) return fullname, prefix def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str: name, cls = name_cls if modname: return _('%s (in module %s)') % (name, modname) else: return _('%s (built-in variable)') % name class PyClasslike(PyObject): """ Description of a class-like object (classes, interfaces, exceptions). """ option_spec: OptionSpec = PyObject.option_spec.copy() option_spec.update({ 'final': directives.flag, }) allow_nesting = True def get_signature_prefix(self, sig: str) -> list[nodes.Node]: if 'final' in self.options: return [nodes.Text('final'), addnodes.desc_sig_space(), nodes.Text(self.objtype), addnodes.desc_sig_space()] else: return [nodes.Text(self.objtype), addnodes.desc_sig_space()] def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str: if self.objtype == 'class': if not modname: return _('%s (built-in class)') % name_cls[0] return _('%s (class in %s)') % (name_cls[0], modname) elif self.objtype == 'exception': return name_cls[0] else: return '' class PyMethod(PyObject): """Description of a method.""" option_spec: OptionSpec = PyObject.option_spec.copy() option_spec.update({ 'abstractmethod': directives.flag, 'async': directives.flag, 'classmethod': directives.flag, 'final': directives.flag, 'staticmethod': directives.flag, }) def needs_arglist(self) -> bool: return True def get_signature_prefix(self, sig: str) -> list[nodes.Node]: prefix: list[nodes.Node] = [] if 'final' in self.options: prefix.append(nodes.Text('final')) prefix.append(addnodes.desc_sig_space()) if 'abstractmethod' in self.options: prefix.append(nodes.Text('abstract')) prefix.append(addnodes.desc_sig_space()) if 'async' in self.options: prefix.append(nodes.Text('async')) prefix.append(addnodes.desc_sig_space()) if 'classmethod' in self.options: prefix.append(nodes.Text('classmethod')) prefix.append(addnodes.desc_sig_space()) if 'staticmethod' in self.options: prefix.append(nodes.Text('static')) prefix.append(addnodes.desc_sig_space()) return prefix def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str: name, cls = name_cls try: clsname, methname = name.rsplit('.', 1) if modname and self.env.config.add_module_names: clsname = '.'.join([modname, clsname]) except ValueError: if modname: return _('%s() (in module %s)') % (name, modname) else: return '%s()' % name if 'classmethod' in self.options: return _('%s() (%s class method)') % (methname, clsname) elif 'staticmethod' in self.options: return _('%s() (%s static method)') % (methname, clsname) else: return _('%s() (%s method)') % (methname, clsname) class PyClassMethod(PyMethod): """Description of a classmethod.""" option_spec: OptionSpec = PyObject.option_spec.copy() def run(self) -> list[Node]: self.name = 'py:method' self.options['classmethod'] = True return super().run() class PyStaticMethod(PyMethod): """Description of a staticmethod.""" option_spec: OptionSpec = PyObject.option_spec.copy() def run(self) -> list[Node]: self.name = 'py:method' self.options['staticmethod'] = True return super().run() class PyDecoratorMethod(PyMethod): """Description of a decoratormethod.""" def run(self) -> list[Node]: self.name = 'py:method' return super().run() def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]: ret = super().handle_signature(sig, signode) signode.insert(0, addnodes.desc_addname('@', '@')) return ret def needs_arglist(self) -> bool: return False class PyAttribute(PyObject): """Description of an attribute.""" option_spec: OptionSpec = PyObject.option_spec.copy() option_spec.update({ 'type': directives.unchanged, 'value': directives.unchanged, }) def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]: fullname, prefix = super().handle_signature(sig, signode) typ = self.options.get('type') if typ: annotations = _parse_annotation(typ, self.env) signode += addnodes.desc_annotation(typ, '', addnodes.desc_sig_punctuation('', ':'), addnodes.desc_sig_space(), *annotations) value = self.options.get('value') if value: signode += addnodes.desc_annotation(value, '', addnodes.desc_sig_space(), addnodes.desc_sig_punctuation('', '='), addnodes.desc_sig_space(), nodes.Text(value)) return fullname, prefix def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str: name, cls = name_cls try: clsname, attrname = name.rsplit('.', 1) if modname and self.env.config.add_module_names: clsname = '.'.join([modname, clsname]) except ValueError: if modname: return _('%s (in module %s)') % (name, modname) else: return name return _('%s (%s attribute)') % (attrname, clsname) class PyProperty(PyObject): """Description of an attribute.""" option_spec = PyObject.option_spec.copy() option_spec.update({ 'abstractmethod': directives.flag, 'classmethod': directives.flag, 'type': directives.unchanged, }) def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]: fullname, prefix = super().handle_signature(sig, signode) typ = self.options.get('type') if typ: annotations = _parse_annotation(typ, self.env) signode += addnodes.desc_annotation(typ, '', addnodes.desc_sig_punctuation('', ':'), addnodes.desc_sig_space(), *annotations) return fullname, prefix def get_signature_prefix(self, sig: str) -> list[nodes.Node]: prefix: list[nodes.Node] = [] if 'abstractmethod' in self.options: prefix.append(nodes.Text('abstract')) prefix.append(addnodes.desc_sig_space()) if 'classmethod' in self.options: prefix.append(nodes.Text('class')) prefix.append(addnodes.desc_sig_space()) prefix.append(nodes.Text('property')) prefix.append(addnodes.desc_sig_space()) return prefix def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str: name, cls = name_cls try: clsname, attrname = name.rsplit('.', 1) if modname and self.env.config.add_module_names: clsname = '.'.join([modname, clsname]) except ValueError: if modname: return _('%s (in module %s)') % (name, modname) else: return name return _('%s (%s property)') % (attrname, clsname) class PyModule(SphinxDirective): """ Directive to mark description of a new module. """ has_content = True required_arguments = 1 optional_arguments = 0 final_argument_whitespace = False option_spec: OptionSpec = { 'platform': lambda x: x, 'synopsis': lambda x: x, 'no-index': directives.flag, 'no-contents-entry': directives.flag, 'no-typesetting': directives.flag, 'noindex': directives.flag, 'nocontentsentry': directives.flag, 'deprecated': directives.flag, } def run(self) -> list[Node]: domain = cast(PythonDomain, self.env.get_domain('py')) modname = self.arguments[0].strip() no_index = 'no-index' in self.options or 'noindex' in self.options self.env.ref_context['py:module'] = modname content_node: Element = nodes.section() # necessary so that the child nodes get the right source/line set content_node.document = self.state.document nested_parse_with_titles(self.state, self.content, content_node, self.content_offset) ret: list[Node] = [] if not no_index: # note module to the domain node_id = make_id(self.env, self.state.document, 'module', modname) target = nodes.target('', '', ids=[node_id], ismod=True) self.set_source_info(target) self.state.document.note_explicit_target(target) domain.note_module(modname, node_id, self.options.get('synopsis', ''), self.options.get('platform', ''), 'deprecated' in self.options) domain.note_object(modname, 'module', node_id, location=target) # the platform and synopsis aren't printed; in fact, they are only # used in the modindex currently indextext = f'module; {modname}' inode = addnodes.index(entries=[('pair', indextext, node_id, '', None)]) # The node order is: index node first, then target node. ret.append(inode) ret.append(target) ret.extend(content_node.children) return ret class PyCurrentModule(SphinxDirective): """ This directive is just to tell Sphinx that we're documenting stuff in module foo, but links to module foo won't lead here. """ has_content = False required_arguments = 1 optional_arguments = 0 final_argument_whitespace = False option_spec: OptionSpec = {} def run(self) -> list[Node]: modname = self.arguments[0].strip() if modname == 'None': self.env.ref_context.pop('py:module', None) else: self.env.ref_context['py:module'] = modname return [] class PyXRefRole(XRefRole): def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str) -> tuple[str, str]: refnode['py:module'] = env.ref_context.get('py:module') refnode['py:class'] = env.ref_context.get('py:class') if not has_explicit_title: title = title.lstrip('.') # only has a meaning for the target target = target.lstrip('~') # only has a meaning for the title # if the first character is a tilde, don't display the module/class # parts of the contents if title[0:1] == '~': title = title[1:] dot = title.rfind('.') if dot != -1: title = title[dot + 1:] # if the first character is a dot, search more specific namespaces first # else search builtins first if target[0:1] == '.': target = target[1:] refnode['refspecific'] = True return title, target def filter_meta_fields(app: Sphinx, domain: str, objtype: str, content: Element) -> None: """Filter ``:meta:`` field from its docstring.""" if domain != 'py': return for node in content: if isinstance(node, nodes.field_list): fields = cast(list[nodes.field], node) # removing list items while iterating the list needs reversed() for field in reversed(fields): field_name = cast(nodes.field_body, field[0]).astext().strip() if field_name == 'meta' or field_name.startswith('meta '): node.remove(field) class PythonModuleIndex(Index): """ Index subclass to provide the Python module index. """ name = 'modindex' localname = _('Python Module Index') shortname = _('modules') def generate(self, docnames: Iterable[str] | None = None, ) -> tuple[list[tuple[str, list[IndexEntry]]], bool]: content: dict[str, list[IndexEntry]] = {} # list of prefixes to ignore ignores: list[str] = self.domain.env.config['modindex_common_prefix'] ignores = sorted(ignores, key=len, reverse=True) # list of all modules, sorted by module name modules = sorted(self.domain.data['modules'].items(), key=lambda x: x[0].lower()) # sort out collapsible modules prev_modname = '' num_toplevels = 0 for modname, (docname, node_id, synopsis, platforms, deprecated) in modules: if docnames and docname not in docnames: continue for ignore in ignores: if modname.startswith(ignore): modname = modname[len(ignore):] stripped = ignore break else: stripped = '' # we stripped the whole module name? if not modname: modname, stripped = stripped, '' entries = content.setdefault(modname[0].lower(), []) package = modname.split('.')[0] if package != modname: # it's a submodule if prev_modname == package: # first submodule - make parent a group head if entries: last = entries[-1] entries[-1] = IndexEntry(last[0], 1, last[2], last[3], last[4], last[5], last[6]) elif not prev_modname.startswith(package): # submodule without parent in list, add dummy entry entries.append(IndexEntry(stripped + package, 1, '', '', '', '', '')) subtype = 2 else: num_toplevels += 1 subtype = 0 qualifier = _('Deprecated') if deprecated else '' entries.append(IndexEntry(stripped + modname, subtype, docname, node_id, platforms, qualifier, synopsis)) prev_modname = modname # apply heuristics when to collapse modindex at page load: # only collapse if number of toplevel modules is larger than # number of submodules collapse = len(modules) - num_toplevels < num_toplevels # sort by first letter sorted_content = sorted(content.items()) return sorted_content, collapse class PythonDomain(Domain): """Python language domain.""" name = 'py' label = 'Python' object_types: dict[str, ObjType] = { 'function': ObjType(_('function'), 'func', 'obj'), 'data': ObjType(_('data'), 'data', 'obj'), 'class': ObjType(_('class'), 'class', 'exc', 'obj'), 'exception': ObjType(_('exception'), 'exc', 'class', 'obj'), 'method': ObjType(_('method'), 'meth', 'obj'), 'classmethod': ObjType(_('class method'), 'meth', 'obj'), 'staticmethod': ObjType(_('static method'), 'meth', 'obj'), 'attribute': ObjType(_('attribute'), 'attr', 'obj'), 'property': ObjType(_('property'), 'attr', '_prop', 'obj'), 'module': ObjType(_('module'), 'mod', 'obj'), } directives = { 'function': PyFunction, 'data': PyVariable, 'class': PyClasslike, 'exception': PyClasslike, 'method': PyMethod, 'classmethod': PyClassMethod, 'staticmethod': PyStaticMethod, 'attribute': PyAttribute, 'property': PyProperty, 'module': PyModule, 'currentmodule': PyCurrentModule, 'decorator': PyDecoratorFunction, 'decoratormethod': PyDecoratorMethod, } roles = { 'data': PyXRefRole(), 'exc': PyXRefRole(), 'func': PyXRefRole(fix_parens=True), 'class': PyXRefRole(), 'const': PyXRefRole(), 'attr': PyXRefRole(), 'meth': PyXRefRole(fix_parens=True), 'mod': PyXRefRole(), 'obj': PyXRefRole(), } initial_data: dict[str, dict[str, tuple[Any]]] = { 'objects': {}, # fullname -> docname, objtype 'modules': {}, # modname -> docname, synopsis, platform, deprecated } indices = [ PythonModuleIndex, ] @property def objects(self) -> dict[str, ObjectEntry]: return self.data.setdefault('objects', {}) # fullname -> ObjectEntry def note_object(self, name: str, objtype: str, node_id: str, aliased: bool = False, location: Any = None) -> None: """Note a python object for cross reference. .. versionadded:: 2.1 """ if name in self.objects: other = self.objects[name] if other.aliased and aliased is False: # The original definition found. Override it! pass elif other.aliased is False and aliased: # The original definition is already registered. return else: # duplicated logger.warning(__('duplicate object description of %s, ' 'other instance in %s, use :no-index: for one of them'), name, other.docname, location=location) self.objects[name] = ObjectEntry(self.env.docname, node_id, objtype, aliased) @property def modules(self) -> dict[str, ModuleEntry]: return self.data.setdefault('modules', {}) # modname -> ModuleEntry def note_module(self, name: str, node_id: str, synopsis: str, platform: str, deprecated: bool) -> None: """Note a python module for cross reference. .. versionadded:: 2.1 """ self.modules[name] = ModuleEntry(self.env.docname, node_id, synopsis, platform, deprecated) def clear_doc(self, docname: str) -> None: for fullname, obj in list(self.objects.items()): if obj.docname == docname: del self.objects[fullname] for modname, mod in list(self.modules.items()): if mod.docname == docname: del self.modules[modname] def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None: # XXX check duplicates? for fullname, obj in otherdata['objects'].items(): if obj.docname in docnames: self.objects[fullname] = obj for modname, mod in otherdata['modules'].items(): if mod.docname in docnames: self.modules[modname] = mod def find_obj(self, env: BuildEnvironment, modname: str, classname: str, name: str, type: str | None, searchmode: int = 0, ) -> list[tuple[str, ObjectEntry]]: """Find a Python object for "name", perhaps using the given module and/or classname. Returns a list of (name, object entry) tuples. """ # skip parens if name[-2:] == '()': name = name[:-2] if not name: return [] matches: list[tuple[str, ObjectEntry]] = [] newname = None if searchmode == 1: if type is None: objtypes: list[str] | None = list(self.object_types) else: objtypes = self.objtypes_for_role(type) if objtypes is not None: if modname and classname: fullname = modname + '.' + classname + '.' + name if fullname in self.objects and self.objects[fullname].objtype in objtypes: newname = fullname if not newname: if modname and modname + '.' + name in self.objects and \ self.objects[modname + '.' + name].objtype in objtypes: newname = modname + '.' + name elif name in self.objects and self.objects[name].objtype in objtypes: newname = name else: # "fuzzy" searching mode searchname = '.' + name matches = [(oname, self.objects[oname]) for oname in self.objects if oname.endswith(searchname) and self.objects[oname].objtype in objtypes] else: # NOTE: searching for exact match, object type is not considered if name in self.objects: newname = name elif type == 'mod': # only exact matches allowed for modules return [] elif classname and classname + '.' + name in self.objects: newname = classname + '.' + name elif modname and modname + '.' + name in self.objects: newname = modname + '.' + name elif modname and classname and \ modname + '.' + classname + '.' + name in self.objects: newname = modname + '.' + classname + '.' + name if newname is not None: matches.append((newname, self.objects[newname])) return matches def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, type: str, target: str, node: pending_xref, contnode: Element, ) -> Element | None: modname = node.get('py:module') clsname = node.get('py:class') searchmode = 1 if node.hasattr('refspecific') else 0 matches = self.find_obj(env, modname, clsname, target, type, searchmode) if not matches and type == 'attr': # fallback to meth (for property; Sphinx 2.4.x) # this ensures that `:attr:` role continues to refer to the old property entry # that defined by ``method`` directive in old reST files. matches = self.find_obj(env, modname, clsname, target, 'meth', searchmode) if not matches and type == 'meth': # fallback to attr (for property) # this ensures that `:meth:` in the old reST files can refer to the property # entry that defined by ``property`` directive. # # Note: _prop is a secret role only for internal look-up. matches = self.find_obj(env, modname, clsname, target, '_prop', searchmode) if not matches: return None elif len(matches) > 1: canonicals = [m for m in matches if not m[1].aliased] if len(canonicals) == 1: matches = canonicals else: logger.warning(__('more than one target found for cross-reference %r: %s'), target, ', '.join(match[0] for match in matches), type='ref', subtype='python', location=node) name, obj = matches[0] if obj[2] == 'module': return self._make_module_refnode(builder, fromdocname, name, contnode) else: # determine the content of the reference by conditions content = find_pending_xref_condition(node, 'resolved') if content: children = content.children else: # if not found, use contnode children = [contnode] return make_refnode(builder, fromdocname, obj[0], obj[1], children, name) def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element, ) -> list[tuple[str, Element]]: modname = node.get('py:module') clsname = node.get('py:class') results: list[tuple[str, Element]] = [] # always search in "refspecific" mode with the :any: role matches = self.find_obj(env, modname, clsname, target, None, 1) multiple_matches = len(matches) > 1 for name, obj in matches: if multiple_matches and obj.aliased: # Skip duplicated matches continue if obj[2] == 'module': results.append(('py:mod', self._make_module_refnode(builder, fromdocname, name, contnode))) else: # determine the content of the reference by conditions content = find_pending_xref_condition(node, 'resolved') if content: children = content.children else: # if not found, use contnode children = [contnode] role = 'py:' + self.role_for_objtype(obj[2]) # type: ignore[operator] results.append((role, make_refnode(builder, fromdocname, obj[0], obj[1], children, name))) return results def _make_module_refnode(self, builder: Builder, fromdocname: str, name: str, contnode: Node) -> Element: # get additional info for modules module = self.modules[name] title = name if module.synopsis: title += ': ' + module.synopsis if module.deprecated: title += _(' (deprecated)') if module.platform: title += ' (' + module.platform + ')' return make_refnode(builder, fromdocname, module.docname, module.node_id, contnode, title) def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]: for modname, mod in self.modules.items(): yield (modname, modname, 'module', mod.docname, mod.node_id, 0) for refname, obj in self.objects.items(): if obj.objtype != 'module': # modules are already handled if obj.aliased: # aliased names are not full-text searchable. yield (refname, refname, obj.objtype, obj.docname, obj.node_id, -1) else: yield (refname, refname, obj.objtype, obj.docname, obj.node_id, 1) def get_full_qualified_name(self, node: Element) -> str | None: modname = node.get('py:module') clsname = node.get('py:class') target = node.get('reftarget') if target is None: return None else: return '.'.join(filter(None, [modname, clsname, target])) def builtin_resolver(app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: Element) -> Element | None: """Do not emit nitpicky warnings for built-in types.""" def istyping(s: str) -> bool: if s.startswith('typing.'): s = s.split('.', 1)[1] return s in typing.__all__ if node.get('refdomain') != 'py': return None elif node.get('reftype') in ('class', 'obj') and node.get('reftarget') == 'None': return contnode elif node.get('reftype') in ('class', 'obj', 'exc'): reftarget = node.get('reftarget') if inspect.isclass(getattr(builtins, reftarget, None)): # built-in class return contnode if istyping(reftarget): # typing class return contnode return None def setup(app: Sphinx) -> dict[str, Any]: app.setup_extension('sphinx.directives') app.add_domain(PythonDomain) app.add_config_value('python_use_unqualified_type_names', False, 'env') app.add_config_value('python_maximum_signature_line_length', None, 'env', types={int, None}) app.add_config_value('python_display_short_literal_types', False, 'env') app.connect('object-description-transform', filter_meta_fields) app.connect('missing-reference', builtin_resolver, priority=900) return { 'version': 'builtin', 'env_version': 4, 'parallel_read_safe': True, 'parallel_write_safe': True, }