Sphinx 8.0.1__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/util/cfamily.py

@@ -25,19 +25,23 @@ logger = logging.getLogger(__name__)
 
 _whitespace_re = re.compile(r'\s+')
 anon_identifier_re = re.compile(r'(@[a-zA-Z0-9_])[a-zA-Z0-9_]*\b')
-identifier_re = re.compile(r'''
+identifier_re = re.compile(
+    r"""
     (   # This 'extends' _anon_identifier_re with the ordinary identifiers,
         # make sure they are in sync.
         (~?\b[a-zA-Z_])  # ordinary identifiers
     |   (@[a-zA-Z0-9_])  # our extension for names of anonymous entities
     )
     [a-zA-Z0-9_]*\b
-''', flags=re.VERBOSE)
+""",
+    flags=re.VERBOSE,
+)
 integer_literal_re = re.compile(r'[1-9][0-9]*(\'[0-9]+)*')
 octal_literal_re = re.compile(r'0[0-7]*(\'[0-7]+)*')
 hex_literal_re = re.compile(r'0[xX][0-9a-fA-F]+(\'[0-9a-fA-F]+)*')
 binary_literal_re = re.compile(r'0[bB][01]+(\'[01]+)*')
-integers_literal_suffix_re = re.compile(r'''
+integers_literal_suffix_re = re.compile(
+    r"""
     # unsigned and/or (long) long, in any order, but at least one of them
     (
         ([uU]    ([lL]  |  (ll)  |  (LL))?)
@@ -46,8 +50,11 @@ integers_literal_suffix_re = re.compile(r'''
     )\b
     # the ending word boundary is important for distinguishing
     # between suffixes and UDLs in C++
-''', flags=re.VERBOSE)
-float_literal_re = re.compile(r'''
+""",
+    flags=re.VERBOSE,
+)
+float_literal_re = re.compile(
+    r"""
     [+-]?(
     # decimal
       ([0-9]+(\'[0-9]+)*[eE][+-]?[0-9]+(\'[0-9]+)*)
@@ -59,10 +66,13 @@ float_literal_re = re.compile(r'''
         [0-9a-fA-F]+(\'[0-9a-fA-F]+)*([pP][+-]?[0-9a-fA-F]+(\'[0-9a-fA-F]+)*)?)
     | (0[xX][0-9a-fA-F]+(\'[0-9a-fA-F]+)*\.([pP][+-]?[0-9a-fA-F]+(\'[0-9a-fA-F]+)*)?)
     )
-''', flags=re.VERBOSE)
+""",
+    flags=re.VERBOSE,
+)
 float_literal_suffix_re = re.compile(r'[fFlL]\b')
 # the ending word boundary is important for distinguishing between suffixes and UDLs in C++
-char_literal_re = re.compile(r'''
+char_literal_re = re.compile(
+    r"""
     ((?:u8)|u|U|L)?
     '(
       (?:[^\\'])
@@ -74,7 +84,9 @@ char_literal_re = re.compile(r'''
       | (?:U[0-9a-fA-F]{8})
       ))
     )'
-''', flags=re.VERBOSE)
+""",
+    flags=re.VERBOSE,
+)
 
 
 def verify_description_mode(mode: str) -> None:
@@ -116,6 +128,7 @@ class ASTBaseBase:
 # Attributes
 ################################################################################
 
+
 class ASTAttribute(ASTBaseBase):
     def describe_signature(self, signode: TextElement) -> None:
         raise NotImplementedError(repr(self))
@@ -134,7 +147,7 @@ class ASTCPPAttribute(ASTAttribute):
         return hash(self.arg)
 
     def _stringify(self, transform: StringifyTransform) -> str:
-        return f"[[{self.arg}]]"
+        return f'[[{self.arg}]]'
 
     def describe_signature(self, signode: TextElement) -> None:
         signode.append(addnodes.desc_sig_punctuation('[[', '[['))
@@ -258,12 +271,14 @@ class ASTAttributeList(ASTBaseBase):
 
 ################################################################################
 
+
 class ASTBaseParenExprList(ASTBaseBase):
     pass
 
 
 ################################################################################
 
+
 class UnsupportedMultiCharacterCharLiteral(Exception):
     pass
 
@@ -273,9 +288,13 @@ class DefinitionError(Exception):
 
 
 class BaseParser:
-    def __init__(self, definition: str, *,
-                 location: nodes.Node | tuple[str, int] | str,
-                 config: Config) -> None:
+    def __init__(
+        self,
+        definition: str,
+        *,
+        location: nodes.Node | tuple[str, int] | str,
+        config: Config,
+    ) -> None:
         self.definition = definition.strip()
         self.location = location  # for warnings
         self.config = config
@@ -315,16 +334,19 @@ class BaseParser:
     def status(self, msg: str) -> None:
         # for debugging
         indicator = '-' * self.pos + '^'
-        logger.debug(f"{msg}\n{self.definition}\n{indicator}")  # NoQA: G004
+        logger.debug(f'{msg}\n{self.definition}\n{indicator}')  # NoQA: G004
 
     def fail(self, msg: str) -> None:
         errors = []
         indicator = '-' * self.pos + '^'
-        exMain = DefinitionError(
-            'Invalid %s declaration: %s [error at %d]\n  %s\n  %s' %
-            (self.language, msg, self.pos, self.definition, indicator))
-        errors.append((exMain, "Main error"))
-        errors.extend((err, "Potential other error") for err in self.otherErrors)
+        msg = (
+            f'Invalid {self.language} declaration: {msg} [error at {self.pos}]\n'
+            f'  {self.definition}\n'
+            f'  {indicator}'
+        )
+        exc_main = DefinitionError(msg)
+        errors.append((exc_main, 'Main error'))
+        errors.extend((err, 'Potential other error') for err in self.otherErrors)
         self.otherErrors = []
         raise self._make_multi_error(errors, '')
 
@@ -342,7 +364,7 @@ class BaseParser:
 
     def skip_string(self, string: str) -> bool:
         strlen = len(string)
-        if self.definition[self.pos:self.pos + strlen] == string:
+        if self.definition[self.pos : self.pos + strlen] == string:
             self.pos += strlen
             return True
         return False
@@ -383,14 +405,14 @@ class BaseParser:
         return ''
 
     def read_rest(self) -> str:
-        rv = self.definition[self.pos:]
+        rv = self.definition[self.pos :]
         self.pos = self.end
         return rv
 
     def assert_end(self, *, allowSemicolon: bool = False) -> None:
         self.skip_ws()
         if allowSemicolon:
-            if not self.eof and self.definition[self.pos:] != ';':
+            if not self.eof and self.definition[self.pos :] != ';':
                 self.fail('Expected end of definition or ;.')
         else:
             if not self.eof:
@@ -418,13 +440,14 @@ class BaseParser:
                 symbols.append(brackets[self.current_char])
             elif len(symbols) > 0 and self.current_char == symbols[-1]:
                 symbols.pop()
-            elif self.current_char in ")]}":
+            elif self.current_char in ')]}':
                 self.fail("Unexpected '%s' in balanced-token-seq." % self.current_char)
             self.pos += 1
         if self.eof:
-            self.fail("Could not find end of balanced-token-seq starting at %d."
-                      % startPos)
-        return self.definition[startPos:self.pos]
+            self.fail(
+                f'Could not find end of balanced-token-seq starting at {startPos}.'
+            )
+        return self.definition[startPos : self.pos]
 
     def _parse_attribute(self) -> ASTAttribute | None:
         self.skip_ws()

sphinx/util/console.py

@@ -41,6 +41,7 @@ if TYPE_CHECKING:
 try:
     # check if colorama is installed to support color on Windows
     import colorama
+
     COLORAMA_AVAILABLE = True
 except ImportError:
     COLORAMA_AVAILABLE = False

sphinx/util/display.py

@@ -78,7 +78,7 @@ class progress_message:
         val: BaseException | None,
         tb: TracebackType | None,
     ) -> bool:
-        prefix = "" if self.nonl else bold(self.message + ': ')
+        prefix = '' if self.nonl else bold(self.message + ': ')
         if isinstance(val, SkipProgressMessage):
             logger.info(prefix + __('skipped'))
             if val.args:

sphinx/util/docfields.py

@@ -3,6 +3,7 @@
 "Doc fields" are reST field lists in object descriptions that will
 be domain-specifically transformed to a more appealing presentation.
 """
+
 from __future__ import annotations
 
 import contextlib
@@ -31,7 +32,7 @@ def _is_single_paragraph(node: nodes.field_body) -> bool:
     if len(node) == 0:
         return False
     elif len(node) > 1:
-        for subnode in node[1:]:  # type: Node
+        for subnode in node[1:]:
             if not isinstance(subnode, nodes.system_message):
                 return False
     return isinstance(node[0], nodes.paragraph)
@@ -70,10 +71,17 @@ class Field:
         self.rolename = rolename
         self.bodyrolename = bodyrolename
 
-    def make_xref(self, rolename: str, domain: str, target: str,
-                  innernode: type[TextlikeNode] = addnodes.literal_emphasis,
-                  contnode: Node | None = None, env: BuildEnvironment | None = None,
-                  inliner: Inliner | None = None, location: Element | None = None) -> Node:
+    def make_xref(
+        self,
+        rolename: str,
+        domain: str,
+        target: str,
+        innernode: type[TextlikeNode] = addnodes.literal_emphasis,
+        contnode: Node | None = None,
+        env: BuildEnvironment | None = None,
+        inliner: Inliner | None = None,
+        location: Element | None = None,
+    ) -> Node:
         # note: for backwards compatibility env is last, but not optional
         assert env is not None
         assert (inliner is None) == (location is None), (inliner, location)
@@ -84,11 +92,18 @@ class Field:
         role = env.get_domain(domain).role(rolename)
         if role is None or inliner is None:
             if role is None and inliner is not None:
-                msg = __("Problem in %s domain: field is supposed "
-                         "to use role '%s', but that role is not in the domain.")
+                msg = __(
+                    'Problem in %s domain: field is supposed '
+                    "to use role '%s', but that role is not in the domain."
+                )
                 logger.warning(__(msg), domain, rolename, location=location)
-            refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
-                                            reftype=rolename, reftarget=target)
+            refnode = addnodes.pending_xref(
+                '',
+                refdomain=domain,
+                refexplicit=False,
+                reftype=rolename,
+                reftarget=target,
+            )
             refnode += contnode or innernode(target, target)  # type: ignore[call-arg]
             env.get_domain(domain).process_field_xref(refnode)
             return refnode
@@ -99,13 +114,22 @@ class Field:
         ns, messages = role(rolename, target, target, lineno, inliner, {}, [])
         return nodes.inline(target, '', *ns)
 
-    def make_xrefs(self, rolename: str, domain: str, target: str,
-                   innernode: type[TextlikeNode] = addnodes.literal_emphasis,
-                   contnode: Node | None = None, env: BuildEnvironment | None = None,
-                   inliner: Inliner | None = None, location: Element | None = None,
-                   ) -> list[Node]:
-        return [self.make_xref(rolename, domain, target, innernode, contnode,
-                               env, inliner, location)]
+    def make_xrefs(
+        self,
+        rolename: str,
+        domain: str,
+        target: str,
+        innernode: type[TextlikeNode] = addnodes.literal_emphasis,
+        contnode: Node | None = None,
+        env: BuildEnvironment | None = None,
+        inliner: Inliner | None = None,
+        location: Element | None = None,
+    ) -> list[Node]:
+        return [
+            self.make_xref(
+                rolename, domain, target, innernode, contnode, env, inliner, location
+            )
+        ]
 
     def make_entry(self, fieldarg: str, content: list[Node]) -> tuple[str, list[Node]]:
         return (fieldarg, content)
@@ -123,17 +147,35 @@ class Field:
         fieldname = nodes.field_name('', self.label)
         if fieldarg:
             fieldname += nodes.Text(' ')
-            fieldname.extend(self.make_xrefs(self.rolename, domain,
-                                             fieldarg, nodes.Text,
-                                             env=env, inliner=inliner, location=location))
+            fieldname.extend(
+                self.make_xrefs(
+                    self.rolename,
+                    domain,
+                    fieldarg,
+                    nodes.Text,
+                    env=env,
+                    inliner=inliner,
+                    location=location,
+                )
+            )
 
         if len(content) == 1 and (
-                isinstance(content[0], nodes.Text) or
-                (isinstance(content[0], nodes.inline) and len(content[0]) == 1 and
-                 isinstance(content[0][0], nodes.Text))):
-            content = self.make_xrefs(self.bodyrolename, domain,
-                                      content[0].astext(), contnode=content[0],
-                                      env=env, inliner=inliner, location=location)
+            isinstance(content[0], nodes.Text)
+            or (
+                isinstance(content[0], nodes.inline)
+                and len(content[0]) == 1
+                and isinstance(content[0][0], nodes.Text)
+            )
+        ):
+            content = self.make_xrefs(
+                self.bodyrolename,
+                domain,
+                content[0].astext(),
+                contnode=content[0],
+                env=env,
+                inliner=inliner,
+                location=location,
+            )
         fieldbody = nodes.field_body('', nodes.paragraph('', '', *content))
         return nodes.field('', fieldname, fieldbody)
 
@@ -155,8 +197,14 @@ class GroupedField(Field):
     is_grouped = True
     list_type = nodes.bullet_list
 
-    def __init__(self, name: str, names: tuple[str, ...] = (), label: str = '',
-                 rolename: str = '', can_collapse: bool = False) -> None:
+    def __init__(
+        self,
+        name: str,
+        names: tuple[str, ...] = (),
+        label: str = '',
+        rolename: str = '',
+        can_collapse: bool = False,
+    ) -> None:
         super().__init__(name, names, label, True, rolename)
         self.can_collapse = can_collapse
 
@@ -173,9 +221,17 @@ class GroupedField(Field):
         listnode = self.list_type()
         for fieldarg, content in items:
             par = nodes.paragraph()
-            par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
-                                       addnodes.literal_strong,
-                                       env=env, inliner=inliner, location=location))
+            par.extend(
+                self.make_xrefs(
+                    self.rolename,
+                    domain,
+                    fieldarg,
+                    addnodes.literal_strong,
+                    env=env,
+                    inliner=inliner,
+                    location=location,
+                )
+            )
             par += nodes.Text(' -- ')
             par += content
             listnode += nodes.list_item('', par)
@@ -236,8 +292,11 @@ class TypedField(GroupedField):
     ) -> nodes.field:
         def handle_item(fieldarg: str, content: list[Node]) -> nodes.paragraph:
             par = nodes.paragraph()
-            par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
-                                       addnodes.literal_strong, env=env))
+            par.extend(
+                self.make_xrefs(
+                    self.rolename, domain, fieldarg, addnodes.literal_strong, env=env
+                )
+            )
             if fieldarg in types:
                 par += nodes.Text(' (')
                 # NOTE: using .pop() here to prevent a single type node to be
@@ -246,9 +305,17 @@ class TypedField(GroupedField):
                 fieldtype = types.pop(fieldarg)
                 if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                     typename = fieldtype[0].astext()
-                    par.extend(self.make_xrefs(self.typerolename, domain, typename,
-                                               addnodes.literal_emphasis, env=env,
-                                               inliner=inliner, location=location))
+                    par.extend(
+                        self.make_xrefs(
+                            self.typerolename,
+                            domain,
+                            typename,
+                            addnodes.literal_emphasis,
+                            env=env,
+                            inliner=inliner,
+                            location=location,
+                        )
+                    )
                 else:
                     par += fieldtype
                 par += nodes.Text(')')
@@ -329,8 +396,13 @@ class DocFieldTransformer:
                 entries.append(field)
 
                 # but if this has a type then we can at least link it
-                if (typedesc and is_typefield and content and
-                        len(content) == 1 and isinstance(content[0], nodes.Text)):
+                if (
+                    typedesc
+                    and is_typefield
+                    and content
+                    and len(content) == 1
+                    and isinstance(content[0], nodes.Text)
+                ):
                     typed_field = cast(TypedField, typedesc)
                     target = content[0].astext()
                     xrefs = typed_field.make_xrefs(
@@ -356,7 +428,9 @@ class DocFieldTransformer:
             if is_typefield:
                 # filter out only inline nodes; others will result in invalid
                 # markup being written out
-                content = [n for n in content if isinstance(n, nodes.Inline | nodes.Text)]
+                content = [
+                    n for n in content if isinstance(n, nodes.Inline | nodes.Text)
+                ]
                 if content:
                     types.setdefault(typename, {})[fieldarg] = content
                 continue
@@ -368,12 +442,10 @@ class DocFieldTransformer:
                 except ValueError:
                     pass
                 else:
-                    types.setdefault(typename, {})[argname] = \
-                        [nodes.Text(argtype)]
+                    types.setdefault(typename, {})[argname] = [nodes.Text(argtype)]
                     fieldarg = argname
 
-            translatable_content = nodes.inline(field_body.rawsource,
-                                                translatable=True)
+            translatable_content = nodes.inline(field_body.rawsource, translatable=True)
             translatable_content.document = field_body.parent.document
             translatable_content.source = field_body.parent.source
             translatable_content.line = field_body.parent.line
@@ -383,7 +455,9 @@ class DocFieldTransformer:
             # get one entry per field
             if typedesc.is_grouped:
                 if typename in groupindices:
-                    group = cast(tuple[Field, list, Node], entries[groupindices[typename]])
+                    group = cast(
+                        tuple[Field, list, Node], entries[groupindices[typename]]
+                    )
                 else:
                     groupindices[typename] = len(entries)
                     group = (typedesc, [], field)
@@ -406,7 +480,13 @@ class DocFieldTransformer:
                 env = self.directive.state.document.settings.env
                 inliner = self.directive.state.inliner
                 domain = self.directive.domain or ''
-                new_list += fieldtype.make_field(fieldtypes, domain, items,
-                                                 env=env, inliner=inliner, location=location)
+                new_list += fieldtype.make_field(
+                    fieldtypes,
+                    domain,
+                    items,
+                    env=env,
+                    inliner=inliner,
+                    location=location,
+                )
 
         node.replace_self(new_list)

sphinx/util/docstrings.py

@@ -29,7 +29,7 @@ def separate_metadata(s: str | None) -> tuple[str | None, dict[str, str]]:
                 field_name = matched.group()[1:].split(':', 1)[0]
                 if field_name.startswith('meta '):
                     name = field_name[5:].strip()
-                    metadata[name] = line[matched.end():].strip()
+                    metadata[name] = line[matched.end() :].strip()
                 else:
                     lines.append(line)
             else: