Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/ext/napoleon/docstring.py

@@ -51,12 +51,11 @@ _token_regex = re.compile(
 _default_regex = re.compile(
     r'^default[^_0-9A-Za-z].*$',
 )
-_SINGLETONS = ('None', 'True', 'False', 'Ellipsis')
+_SINGLETONS = frozenset({'None', 'True', 'False', 'Ellipsis', '...'})
 
 
 class Deque(collections.deque[Any]):
-    """
-    A subclass of deque that mimics ``pockets.iterators.modify_iter``.
+    """A subclass of deque that mimics ``pockets.iterators.modify_iter``.
 
     The `.Deque.get` and `.Deque.next` methods are added.
     """
@@ -64,8 +63,7 @@ class Deque(collections.deque[Any]):
     sentinel = object()
 
     def get(self, n: int) -> Any:
-        """
-        Return the nth element of the stack, or ``self.sentinel`` if n is
+        """Return the nth element of the stack, or ``self.sentinel`` if n is
         greater than the stack size.
         """
         return self[n] if n < len(self) else self.sentinel
@@ -77,13 +75,183 @@ class Deque(collections.deque[Any]):
             raise StopIteration
 
 
-def _convert_type_spec(_type: str, translations: dict[str, str] | None = None) -> str:
-    """Convert type specification to reference in reST."""
-    if translations is not None and _type in translations:
-        return translations[_type]
-    if _type == 'None':
-        return ':py:obj:`None`'
-    return f':py:class:`{_type}`'
+def _recombine_set_tokens(tokens: list[str]) -> list[str]:
+    token_queue = collections.deque(tokens)
+    keywords = ('optional', 'default')
+
+    def takewhile_set(tokens: collections.deque[str]) -> Iterator[str]:
+        open_braces = 0
+        previous_token = None
+        while True:
+            try:
+                token = tokens.popleft()
+            except IndexError:
+                break
+
+            if token == ', ':
+                previous_token = token
+                continue
+
+            if not token.strip():
+                continue
+
+            if token in keywords:
+                tokens.appendleft(token)
+                if previous_token is not None:
+                    tokens.appendleft(previous_token)
+                break
+
+            if previous_token is not None:
+                yield previous_token
+                previous_token = None
+
+            if token == '{':
+                open_braces += 1
+            elif token == '}':
+                open_braces -= 1
+
+            yield token
+
+            if open_braces == 0:
+                break
+
+    def combine_set(tokens: collections.deque[str]) -> Iterator[str]:
+        while True:
+            try:
+                token = tokens.popleft()
+            except IndexError:
+                break
+
+            if token == '{':
+                tokens.appendleft('{')
+                yield ''.join(takewhile_set(tokens))
+            else:
+                yield token
+
+    return list(combine_set(token_queue))
+
+
+def _tokenize_type_spec(spec: str) -> list[str]:
+    def postprocess(item: str) -> list[str]:
+        if _default_regex.match(item):
+            default = item[:7]
+            # can't be separated by anything other than a single space
+            # for now
+            other = item[8:]
+
+            return [default, ' ', other]
+        else:
+            return [item]
+
+    tokens = [
+        item
+        for raw_token in _token_regex.split(spec)
+        for item in postprocess(raw_token)
+        if item
+    ]
+    return tokens
+
+
+def _token_type(token: str, debug_location: str | None = None) -> str:
+    def is_numeric(token: str) -> bool:
+        try:
+            # use complex to make sure every numeric value is detected as literal
+            complex(token)
+        except ValueError:
+            return False
+        else:
+            return True
+
+    if token.startswith(' ') or token.endswith(' '):
+        type_ = 'delimiter'
+    elif (
+        is_numeric(token)
+        or (token.startswith('{') and token.endswith('}'))
+        or (token.startswith('"') and token.endswith('"'))
+        or (token.startswith("'") and token.endswith("'"))
+    ):
+        type_ = 'literal'
+    elif token.startswith('{'):
+        logger.warning(
+            __('invalid value set (missing closing brace): %s'),
+            token,
+            location=debug_location,
+        )
+        type_ = 'literal'
+    elif token.endswith('}'):
+        logger.warning(
+            __('invalid value set (missing opening brace): %s'),
+            token,
+            location=debug_location,
+        )
+        type_ = 'literal'
+    elif token.startswith(("'", '"')):
+        logger.warning(
+            __('malformed string literal (missing closing quote): %s'),
+            token,
+            location=debug_location,
+        )
+        type_ = 'literal'
+    elif token.endswith(("'", '"')):
+        logger.warning(
+            __('malformed string literal (missing opening quote): %s'),
+            token,
+            location=debug_location,
+        )
+        type_ = 'literal'
+    elif token in {'optional', 'default'}:
+        # default is not a official keyword (yet) but supported by the
+        # reference implementation (numpydoc) and widely used
+        type_ = 'control'
+    elif _xref_regex.match(token):
+        type_ = 'reference'
+    else:
+        type_ = 'obj'
+
+    return type_
+
+
+def _convert_type_spec(
+    _type: str,
+    translations: dict[str, str] | None = None,
+    debug_location: str | None = None,
+) -> str:
+    if translations is None:
+        translations = {}
+
+    tokens = _tokenize_type_spec(_type)
+    combined_tokens = _recombine_set_tokens(tokens)
+    types = [(token, _token_type(token, debug_location)) for token in combined_tokens]
+
+    converters = {
+        'literal': lambda x: f'``{x}``',
+        'obj': lambda x: _convert_type_spec_obj(x, translations),
+        'control': lambda x: f'*{x}*',
+        'delimiter': lambda x: x,
+        'reference': lambda x: x,
+    }
+
+    converted = ''.join(
+        converters.get(type_)(token)  # type: ignore[misc]
+        for token, type_ in types
+    )
+
+    return converted
+
+
+def _convert_type_spec_obj(obj: str, translations: dict[str, str]) -> str:
+    translation = translations.get(obj, obj)
+
+    if _xref_regex.match(translation) is not None:
+        return translation
+
+    # use :py:obj: if obj is a standard singleton
+    if translation in _SINGLETONS:
+        if translation == '...':  # allow referencing the builtin ...
+            return ':py:obj:`... <Ellipsis>`'
+        return f':py:obj:`{translation}`'
+
+    return f':py:class:`{translation}`'
 
 
 class GoogleDocstring:
@@ -252,6 +420,20 @@ class GoogleDocstring:
         """
         return '\n'.join(self.lines())
 
+    def _get_location(self) -> str | None:
+        try:
+            filepath = inspect.getfile(self._obj) if self._obj is not None else None
+        except TypeError:
+            filepath = None
+        name = self._name
+
+        if filepath is None and name is None:
+            return None
+        elif filepath is None:
+            filepath = ''
+
+        return f'{filepath}:docstring of {name}'
+
     def lines(self) -> list[str]:
         """Return the parsed lines of the docstring in reStructuredText format.
 
@@ -309,7 +491,11 @@ class GoogleDocstring:
             _type, _name = _name, _type
 
         if _type and self._config.napoleon_preprocess_types:
-            _type = _convert_type_spec(_type, self._config.napoleon_type_aliases or {})
+            _type = _convert_type_spec(
+                _type,
+                translations=self._config.napoleon_type_aliases or {},
+                debug_location=self._get_location(),
+            )
 
         indent = self._get_indent(line) + 1
         _descs = [_desc, *self._dedent(self._consume_indented_block(indent))]
@@ -357,7 +543,9 @@ class GoogleDocstring:
 
             if _type and preprocess_types and self._config.napoleon_preprocess_types:
                 _type = _convert_type_spec(
-                    _type, self._config.napoleon_type_aliases or {}
+                    _type,
+                    translations=self._config.napoleon_type_aliases or {},
+                    debug_location=self._get_location(),
                 )
 
             _desc = self.__class__(_desc, self._config).lines()
@@ -428,9 +616,9 @@ class GoogleDocstring:
             return [f'.. {admonition}:: {lines[0].strip()}', '']
         elif lines:
             lines = self._indent(self._dedent(lines), 3)
-            return ['.. %s::' % admonition, '', *lines, '']
+            return [f'.. {admonition}::', '', *lines, '']
         else:
-            return ['.. %s::' % admonition, '']
+            return [f'.. {admonition}::', '']
 
     def _format_block(
         self,
@@ -507,7 +695,7 @@ class GoogleDocstring:
         field_type: str,
         fields: list[tuple[str, str, list[str]]],
     ) -> list[str]:
-        field_type = ':%s:' % field_type.strip()
+        field_type = f':{field_type.strip()}:'
         padding = ' ' * len(field_type)
         multi = len(fields) > 1
         lines: list[str] = []
@@ -558,7 +746,7 @@ class GoogleDocstring:
         return [(' ' * n) + line for line in lines]
 
     def _is_indented(self, line: str, indent: int = 1) -> bool:
-        for i, s in enumerate(line):  # NoQA: SIM110
+        for i, s in enumerate(line):
             if i >= indent:
                 return True
             elif not s.isspace():
@@ -635,7 +823,7 @@ class GoogleDocstring:
     def _parse(self) -> None:
         self._parsed_lines = self._consume_empty()
 
-        if self._name and self._what in ('attribute', 'data', 'property'):
+        if self._name and self._what in {'attribute', 'data', 'property'}:
             res: list[str] = []
             with contextlib.suppress(StopIteration):
                 res = self._parse_attribute_docstring()
@@ -672,7 +860,7 @@ class GoogleDocstring:
         _type, _desc = self._consume_inline_attribute()
         lines = self._format_field('', '', _desc)
         if _type:
-            lines.extend(['', ':type: %s' % _type])
+            lines.extend(['', f':type: {_type}'])
         return lines
 
     def _parse_attributes_section(self, section: str) -> list[str]:
@@ -681,7 +869,7 @@ class GoogleDocstring:
             if not _type:
                 _type = self._lookup_annotation(_name)
             if self._config.napoleon_use_ivar:
-                field = ':ivar %s: ' % _name
+                field = f':ivar {_name}: '
                 lines.extend(self._format_block(field, _desc))
                 if _type:
                     lines.append(f':vartype {_name}: {_type}')
@@ -696,7 +884,7 @@ class GoogleDocstring:
                 lines.extend(self._indent(fields, 3))
                 if _type:
                     lines.append('')
-                    lines.extend(self._indent([':type: %s' % _type], 3))
+                    lines.extend(self._indent([f':type: {_type}'], 3))
                 lines.append('')
         if self._config.napoleon_use_ivar:
             lines.append('')
@@ -733,10 +921,10 @@ class GoogleDocstring:
         lines = self._strip_empty(self._consume_to_next_section())
         lines = self._dedent(lines)
         if use_admonition:
-            header = '.. admonition:: %s' % section
+            header = f'.. admonition:: {section}'
             lines = self._indent(lines, 3)
         else:
-            header = '.. rubric:: %s' % section
+            header = f'.. rubric:: {section}'
         if lines:
             return [header, '', *lines, '']
         else:
@@ -754,7 +942,7 @@ class GoogleDocstring:
     def _parse_methods_section(self, section: str) -> list[str]:
         lines: list[str] = []
         for _name, _type, _desc in self._consume_fields(parse_type=False):
-            lines.append('.. method:: %s' % _name)
+            lines.append(f'.. method:: {_name}')
             if self._opt:
                 if 'no-index' in self._opt or 'noindex' in self._opt:
                     lines.append('   :no-index:')
@@ -837,7 +1025,7 @@ class GoogleDocstring:
                 if any(field):  # only add :returns: if there's something to say
                     lines.extend(self._format_block(':returns: ', field))
                 if _type and use_rtype:
-                    lines.extend([':rtype: %s' % _type, ''])
+                    lines.extend([f':rtype: {_type}', ''])
         if lines and lines[-1]:
             lines.append('')
         return lines
@@ -893,7 +1081,7 @@ class GoogleDocstring:
 
     def _lookup_annotation(self, _name: str) -> str:
         if self._config.napoleon_attr_annotations:
-            if self._what in ('module', 'class', 'exception') and self._obj:
+            if self._what in {'module', 'class', 'exception'} and self._obj:
                 # cache the class annotations
                 if not hasattr(self, '_annotations'):
                     localns = getattr(self._config, 'autodoc_type_aliases', {})
@@ -907,194 +1095,18 @@ class GoogleDocstring:
                     )
                     self._annotations = get_type_hints(self._obj, None, localns)
                 if _name in self._annotations:
+                    short_literals = getattr(
+                        self._config, 'python_display_short_literal_types', False
+                    )
                     return stringify_annotation(
-                        self._annotations[_name], 'fully-qualified-except-typing'
+                        self._annotations[_name],
+                        mode='fully-qualified-except-typing',
+                        short_literals=short_literals,
                     )
         # No annotation found
         return ''
 
 
-def _recombine_set_tokens(tokens: list[str]) -> list[str]:
-    token_queue = collections.deque(tokens)
-    keywords = ('optional', 'default')
-
-    def takewhile_set(tokens: collections.deque[str]) -> Iterator[str]:
-        open_braces = 0
-        previous_token = None
-        while True:
-            try:
-                token = tokens.popleft()
-            except IndexError:
-                break
-
-            if token == ', ':
-                previous_token = token
-                continue
-
-            if not token.strip():
-                continue
-
-            if token in keywords:
-                tokens.appendleft(token)
-                if previous_token is not None:
-                    tokens.appendleft(previous_token)
-                break
-
-            if previous_token is not None:
-                yield previous_token
-                previous_token = None
-
-            if token == '{':
-                open_braces += 1
-            elif token == '}':
-                open_braces -= 1
-
-            yield token
-
-            if open_braces == 0:
-                break
-
-    def combine_set(tokens: collections.deque[str]) -> Iterator[str]:
-        while True:
-            try:
-                token = tokens.popleft()
-            except IndexError:
-                break
-
-            if token == '{':
-                tokens.appendleft('{')
-                yield ''.join(takewhile_set(tokens))
-            else:
-                yield token
-
-    return list(combine_set(token_queue))
-
-
-def _tokenize_type_spec(spec: str) -> list[str]:
-    def postprocess(item: str) -> list[str]:
-        if _default_regex.match(item):
-            default = item[:7]
-            # can't be separated by anything other than a single space
-            # for now
-            other = item[8:]
-
-            return [default, ' ', other]
-        else:
-            return [item]
-
-    tokens = [
-        item
-        for raw_token in _token_regex.split(spec)
-        for item in postprocess(raw_token)
-        if item
-    ]
-    return tokens
-
-
-def _token_type(token: str, location: str | None = None) -> str:
-    def is_numeric(token: str) -> bool:
-        try:
-            # use complex to make sure every numeric value is detected as literal
-            complex(token)
-        except ValueError:
-            return False
-        else:
-            return True
-
-    if token.startswith(' ') or token.endswith(' '):
-        type_ = 'delimiter'
-    elif (
-        is_numeric(token)
-        or (token.startswith('{') and token.endswith('}'))
-        or (token.startswith('"') and token.endswith('"'))
-        or (token.startswith("'") and token.endswith("'"))
-    ):
-        type_ = 'literal'
-    elif token.startswith('{'):
-        logger.warning(
-            __('invalid value set (missing closing brace): %s'),
-            token,
-            location=location,
-        )
-        type_ = 'literal'
-    elif token.endswith('}'):
-        logger.warning(
-            __('invalid value set (missing opening brace): %s'),
-            token,
-            location=location,
-        )
-        type_ = 'literal'
-    elif token.startswith(("'", '"')):
-        logger.warning(
-            __('malformed string literal (missing closing quote): %s'),
-            token,
-            location=location,
-        )
-        type_ = 'literal'
-    elif token.endswith(("'", '"')):
-        logger.warning(
-            __('malformed string literal (missing opening quote): %s'),
-            token,
-            location=location,
-        )
-        type_ = 'literal'
-    elif token in ('optional', 'default'):
-        # default is not a official keyword (yet) but supported by the
-        # reference implementation (numpydoc) and widely used
-        type_ = 'control'
-    elif _xref_regex.match(token):
-        type_ = 'reference'
-    else:
-        type_ = 'obj'
-
-    return type_
-
-
-def _convert_numpy_type_spec(
-    _type: str,
-    location: str | None = None,
-    translations: dict[str, str] | None = None,
-) -> str:
-    if translations is None:
-        translations = {}
-
-    def convert_obj(
-        obj: str, translations: dict[str, str], default_translation: str
-    ) -> str:
-        translation = translations.get(obj, obj)
-
-        # use :class: (the default) only if obj is not a standard singleton
-        if translation in _SINGLETONS and default_translation == ':class:`%s`':
-            default_translation = ':obj:`%s`'
-        elif translation == '...' and default_translation == ':class:`%s`':
-            # allow referencing the builtin ...
-            default_translation = ':obj:`%s <Ellipsis>`'
-
-        if _xref_regex.match(translation) is None:
-            translation = default_translation % translation
-
-        return translation
-
-    tokens = _tokenize_type_spec(_type)
-    combined_tokens = _recombine_set_tokens(tokens)
-    types = [(token, _token_type(token, location)) for token in combined_tokens]
-
-    converters = {
-        'literal': lambda x: '``%s``' % x,
-        'obj': lambda x: convert_obj(x, translations, ':class:`%s`'),
-        'control': lambda x: '*%s*' % x,
-        'delimiter': lambda x: x,
-        'reference': lambda x: x,
-    }
-
-    converted = ''.join(
-        converters.get(type_)(token)  # type: ignore[misc]
-        for token, type_ in types
-    )
-
-    return converted
-
-
 class NumpyDocstring(GoogleDocstring):
     """Convert NumPy style docstrings to reStructuredText.
 
@@ -1202,20 +1214,6 @@ class NumpyDocstring(GoogleDocstring):
         self._directive_sections = ['.. index::']
         super().__init__(docstring, config, app, what, name, obj, options)
 
-    def _get_location(self) -> str | None:
-        try:
-            filepath = inspect.getfile(self._obj) if self._obj is not None else None
-        except TypeError:
-            filepath = None
-        name = self._name
-
-        if filepath is None and name is None:
-            return None
-        elif filepath is None:
-            filepath = ''
-
-        return f'{filepath}:docstring of {name}'
-
     def _escape_args_and_kwargs(self, name: str) -> str:
         func = super()._escape_args_and_kwargs
 
@@ -1242,10 +1240,10 @@ class NumpyDocstring(GoogleDocstring):
             _type, _name = _name, _type
 
         if self._config.napoleon_preprocess_types:
-            _type = _convert_numpy_type_spec(
+            _type = _convert_type_spec(
                 _type,
-                location=self._get_location(),
                 translations=self._config.napoleon_type_aliases or {},
+                debug_location=self._get_location(),
             )
 
         indent = self._get_indent(line) + 1
@@ -1270,7 +1268,7 @@ class NumpyDocstring(GoogleDocstring):
         return (
             not self._lines
             or self._is_section_header()
-            or (line1 == line2 == '')
+            or (not line1 and not line2)
             or (
                 self._is_in_section
                 and line1
@@ -1298,8 +1296,7 @@ class NumpyDocstring(GoogleDocstring):
             return self._format_admonition('seealso', lines)
 
     def _parse_numpydoc_see_also_section(self, content: list[str]) -> list[str]:
-        """
-        See Also
+        """See Also
         --------
         func_name : Descriptive text
             continued text
@@ -1349,7 +1346,8 @@ class NumpyDocstring(GoogleDocstring):
                     return g[3], None
                 else:
                     return g[2], g[1]
-            raise ValueError('%s is not a item name' % text)
+            msg = f'{text} is not a item name'
+            raise ValueError(msg)
 
         def push_item(name: str | None, rest: list[str]) -> None:
             if not name:
@@ -1417,12 +1415,12 @@ class NumpyDocstring(GoogleDocstring):
             if role:
                 link = f':{role}:`{name}`'
             else:
-                link = ':obj:`%s`' % name
+                link = f':py:obj:`{name}`'
             if desc or last_had_desc:
                 lines += ['']
                 lines += [link]
             else:
-                lines[-1] += ', %s' % link
+                lines[-1] += f', {link}'
             if desc:
                 lines += self._indent([' '.join(desc)])
                 last_had_desc = True