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

sphinx/ext/autodoc/preserve_defaults.py

@@ -42,11 +42,15 @@ def get_function_def(obj: Any) -> ast.FunctionDef | None:
     This tries to parse original code for living object and returns
     AST node for given *obj*.
     """
-    warnings.warn('sphinx.ext.autodoc.preserve_defaults.get_function_def is'
-                  ' deprecated and scheduled for removal in Sphinx 9.'
-                  ' Use sphinx.ext.autodoc.preserve_defaults._get_arguments() to'
-                  ' extract AST arguments objects from a lambda or regular'
-                  ' function.', RemovedInSphinx90Warning, stacklevel=2)
+    warnings.warn(
+        'sphinx.ext.autodoc.preserve_defaults.get_function_def is'
+        ' deprecated and scheduled for removal in Sphinx 9.'
+        ' Use sphinx.ext.autodoc.preserve_defaults._get_arguments() to'
+        ' extract AST arguments objects from a lambda or regular'
+        ' function.',
+        RemovedInSphinx90Warning,
+        stacklevel=2,
+    )
 
     try:
         source = inspect.getsource(obj)
@@ -113,7 +117,7 @@ def get_default_value(lines: list[str], position: ast.expr) -> str | None:
     try:
         if position.lineno == position.end_lineno:
             line = lines[position.lineno - 1]
-            return line[position.col_offset:position.end_col_offset]
+            return line[position.col_offset : position.end_col_offset]
         else:
             # multiline value is not supported now
             return None
@@ -161,7 +165,7 @@ def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
                     # Consume kw_defaults for kwonly args
                     kw_defaults.pop(0)
             else:
-                if param.kind in (param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD):
+                if param.kind in {param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD}:
                     default = defaults.pop(0)
                     value = get_default_value(lines, default)
                     if value is None:
@@ -187,11 +191,15 @@ def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
         # In this case, we can't set __signature__.
         return
     except NotImplementedError as exc:  # failed to ast_unparse()
-        logger.warning(__("Failed to parse a default argument value for %r: %s"), obj, exc)
+        logger.warning(
+            __('Failed to parse a default argument value for %r: %s'), obj, exc
+        )
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_config_value('autodoc_preserve_defaults', False, 'env')
+    app.add_config_value(
+        'autodoc_preserve_defaults', False, 'env', types=frozenset({bool})
+    )
     app.connect('autodoc-before-process-signature', update_defvalue)
 
     return {

sphinx/ext/autodoc/type_comment.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import ast
 from inspect import Parameter, Signature, getsource
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 import sphinx
 from sphinx.locale import __
@@ -13,6 +13,7 @@ from sphinx.util import inspect, logging
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+    from typing import Any
 
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
@@ -32,35 +33,52 @@ def not_suppressed(argtypes: Sequence[ast.expr] = ()) -> bool:
     return True
 
 
-def signature_from_ast(node: ast.FunctionDef, bound_method: bool,
-                       type_comment: ast.FunctionDef) -> Signature:
+def signature_from_ast(
+    node: ast.FunctionDef, bound_method: bool, type_comment: ast.FunctionDef
+) -> Signature:
     """Return a Signature object for the given *node*.
 
     :param bound_method: Specify *node* is a bound method or not
     """
     params = []
     for arg in node.args.posonlyargs:
-        param = Parameter(arg.arg, Parameter.POSITIONAL_ONLY, annotation=arg.type_comment)
+        param = Parameter(
+            arg.arg,
+            Parameter.POSITIONAL_ONLY,
+            annotation=arg.type_comment,
+        )
         params.append(param)
 
     for arg in node.args.args:
-        param = Parameter(arg.arg, Parameter.POSITIONAL_OR_KEYWORD,
-                          annotation=arg.type_comment or Parameter.empty)
+        param = Parameter(
+            arg.arg,
+            Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=arg.type_comment or Parameter.empty,
+        )
         params.append(param)
 
     if node.args.vararg:
-        param = Parameter(node.args.vararg.arg, Parameter.VAR_POSITIONAL,
-                          annotation=node.args.vararg.type_comment or Parameter.empty)
+        param = Parameter(
+            node.args.vararg.arg,
+            Parameter.VAR_POSITIONAL,
+            annotation=node.args.vararg.type_comment or Parameter.empty,
+        )
         params.append(param)
 
     for arg in node.args.kwonlyargs:
-        param = Parameter(arg.arg, Parameter.KEYWORD_ONLY,
-                          annotation=arg.type_comment or Parameter.empty)
+        param = Parameter(
+            arg.arg,
+            Parameter.KEYWORD_ONLY,
+            annotation=arg.type_comment or Parameter.empty,
+        )
         params.append(param)
 
     if node.args.kwarg:
-        param = Parameter(node.args.kwarg.arg, Parameter.VAR_KEYWORD,
-                          annotation=node.args.kwarg.type_comment or Parameter.empty)
+        param = Parameter(
+            node.args.kwarg.arg,
+            Parameter.VAR_KEYWORD,
+            annotation=node.args.kwarg.type_comment or Parameter.empty,
+        )
         params.append(param)
 
     # Remove first parameter when *obj* is bound_method
@@ -70,8 +88,7 @@ def signature_from_ast(node: ast.FunctionDef, bound_method: bool,
     # merge type_comment into signature
     if not_suppressed(type_comment.argtypes):  # type: ignore[attr-defined]
         for i, param in enumerate(params):
-            params[i] = param.replace(
-                annotation=type_comment.argtypes[i])  # type: ignore[attr-defined]
+            params[i] = param.replace(annotation=type_comment.argtypes[i])  # type: ignore[attr-defined]
 
     if node.returns:
         return Signature(params, return_annotation=node.returns)
@@ -93,19 +110,15 @@ def get_type_comment(obj: Any, bound_method: bool = False) -> Signature | None:
             # subject is placed inside class or block.  To read its docstring,
             # this adds if-block before the declaration.
             module = ast.parse('if True:\n' + source, type_comments=True)
-            subject = cast(
-                ast.FunctionDef, module.body[0].body[0],  # type: ignore[attr-defined]
-            )
+            subject = cast('ast.FunctionDef', module.body[0].body[0])  # type: ignore[attr-defined]
         else:
             module = ast.parse(source, type_comments=True)
-            subject = cast(ast.FunctionDef, module.body[0])
+            subject = cast('ast.FunctionDef', module.body[0])
 
-        type_comment = getattr(subject, "type_comment", None)
+        type_comment = getattr(subject, 'type_comment', None)
         if type_comment:
             function = ast.parse(type_comment, mode='func_type', type_comments=True)
-            return signature_from_ast(
-                subject, bound_method, function,  # type: ignore[arg-type]
-            )
+            return signature_from_ast(subject, bound_method, function)  # type: ignore[arg-type]
         else:
             return None
     except (OSError, TypeError):  # failed to load source code
@@ -114,8 +127,13 @@ def get_type_comment(obj: Any, bound_method: bool = False) -> Signature | None:
         return None
 
 
-def update_annotations_using_type_comments(app: Sphinx, obj: Any, bound_method: bool) -> None:
+def update_annotations_using_type_comments(
+    app: Sphinx, obj: Any, bound_method: bool
+) -> None:
     """Update annotations info of *obj* using type_comments."""
+    if not app.config.autodoc_use_type_comments:
+        return
+
     try:
         type_sig = get_type_comment(obj, bound_method)
         if type_sig:
@@ -129,13 +147,22 @@ def update_annotations_using_type_comments(app: Sphinx, obj: Any, bound_method:
             if 'return' not in obj.__annotations__:
                 obj.__annotations__['return'] = type_sig.return_annotation
     except KeyError as exc:
-        logger.warning(__("Failed to update signature for %r: parameter not found: %s"),
-                       obj, exc)
+        logger.warning(
+            __('Failed to update signature for %r: parameter not found: %s'), obj, exc
+        )
     except NotImplementedError as exc:  # failed to ast.unparse()
-        logger.warning(__("Failed to parse type_comment for %r: %s"), obj, exc)
+        logger.warning(__('Failed to parse type_comment for %r: %s'), obj, exc)
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.connect('autodoc-before-process-signature', update_annotations_using_type_comments)
-
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    app.add_config_value(
+        'autodoc_use_type_comments', True, 'env', types=frozenset({bool})
+    )
+    app.connect(
+        'autodoc-before-process-signature', update_annotations_using_type_comments
+    )
+
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }

sphinx/ext/autodoc/typehints.py

@@ -3,53 +3,72 @@
 from __future__ import annotations
 
 import re
-from collections.abc import Iterable
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
 
 import sphinx
 from sphinx import addnodes
 from sphinx.util import inspect
-from sphinx.util.typing import ExtensionMetadata, stringify_annotation
+from sphinx.util.typing import stringify_annotation
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from typing import Any
+
     from docutils.nodes import Element
 
     from sphinx.application import Sphinx
     from sphinx.ext.autodoc import Options
+    from sphinx.util.typing import ExtensionMetadata, _StringifyMode
 
 
-def record_typehints(app: Sphinx, objtype: str, name: str, obj: Any,
-                     options: Options, args: str, retann: str) -> None:
+def record_typehints(
+    app: Sphinx,
+    objtype: str,
+    name: str,
+    obj: Any,
+    options: Options,
+    args: str,
+    retann: str,
+) -> None:
     """Record type hints to env object."""
+    mode: _StringifyMode
     if app.config.autodoc_typehints_format == 'short':
         mode = 'smart'
     else:
         mode = 'fully-qualified'
 
+    short_literals = app.config.python_display_short_literal_types
+
     try:
         if callable(obj):
-            annotations = app.env.temp_data.setdefault('annotations', {})
-            annotation = annotations.setdefault(name, {})
+            current_document = app.env.current_document
+            annotation = current_document.autodoc_annotations.setdefault(name, {})
             sig = inspect.signature(obj, type_aliases=app.config.autodoc_type_aliases)
             for param in sig.parameters.values():
                 if param.annotation is not param.empty:
-                    annotation[param.name] = stringify_annotation(param.annotation, mode)  # type: ignore[arg-type]
+                    annotation[param.name] = stringify_annotation(
+                        param.annotation, mode, short_literals=short_literals
+                    )
             if sig.return_annotation is not sig.empty:
-                annotation['return'] = stringify_annotation(sig.return_annotation, mode)  # type: ignore[arg-type]
+                annotation['return'] = stringify_annotation(
+                    sig.return_annotation, mode, short_literals=short_literals
+                )
     except (TypeError, ValueError):
         pass
 
 
-def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element) -> None:
+def merge_typehints(
+    app: Sphinx, domain: str, objtype: str, contentnode: Element
+) -> None:
     if domain != 'py':
         return
-    if app.config.autodoc_typehints not in ('both', 'description'):
+    if app.config.autodoc_typehints not in {'both', 'description'}:
         return
 
     try:
-        signature = cast(addnodes.desc_signature, contentnode.parent[0])
+        signature = cast('addnodes.desc_signature', contentnode.parent[0])
         if signature['module']:
             fullname = f'{signature["module"]}.{signature["fullname"]}'
         else:
@@ -58,7 +77,7 @@ def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element
         # signature node does not have valid context info for the target object
         return
 
-    annotations = app.env.temp_data.get('annotations', {})
+    annotations = app.env.current_document.autodoc_annotations
     if annotations.get(fullname, {}):
         field_lists = [n for n in contentnode if isinstance(n, nodes.field_list)]
         if field_lists == []:
@@ -66,18 +85,20 @@ def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element
             field_lists.append(field_list)
 
         for field_list in field_lists:
-            if app.config.autodoc_typehints_description_target == "all":
+            if app.config.autodoc_typehints_description_target == 'all':
                 if objtype == 'class':
-                    modify_field_list(field_list, annotations[fullname], suppress_rtype=True)
+                    modify_field_list(
+                        field_list, annotations[fullname], suppress_rtype=True
+                    )
                 else:
                     modify_field_list(field_list, annotations[fullname])
-            elif app.config.autodoc_typehints_description_target == "documented_params":
+            elif app.config.autodoc_typehints_description_target == 'documented_params':
                 augment_descriptions_with_types(
-                    field_list, annotations[fullname], force_rtype=True,
+                    field_list, annotations[fullname], force_rtype=True
                 )
             else:
                 augment_descriptions_with_types(
-                    field_list, annotations[fullname], force_rtype=False,
+                    field_list, annotations[fullname], force_rtype=False
                 )
 
 
@@ -94,10 +115,11 @@ def insert_field_list(node: Element) -> nodes.field_list:
     return field_list
 
 
-def modify_field_list(node: nodes.field_list, annotations: dict[str, str],
-                      suppress_rtype: bool = False) -> None:
+def modify_field_list(
+    node: nodes.field_list, annotations: dict[str, str], suppress_rtype: bool = False
+) -> None:
     arguments: dict[str, dict[str, bool]] = {}
-    fields = cast(Iterable[nodes.field], node)
+    fields = cast('Iterable[nodes.field]', node)
     for field in fields:
         field_name = field[0].astext()
         parts = re.split(' +', field_name)
@@ -159,7 +181,7 @@ def augment_descriptions_with_types(
     annotations: dict[str, str],
     force_rtype: bool,
 ) -> None:
-    fields = cast(Iterable[nodes.field], node)
+    fields = cast('Iterable[nodes.field]', node)
     has_description: set[str] = set()
     has_type: set[str] = set()
     for field in fields:
@@ -177,14 +199,14 @@ def augment_descriptions_with_types(
         elif parts[0] == 'type':
             name = ' '.join(parts[1:])
             has_type.add(name)
-        elif parts[0] in ('return', 'returns'):
+        elif parts[0] in {'return', 'returns'}:
             has_description.add('return')
         elif parts[0] == 'rtype':
             has_type.add('return')
 
     # Add 'type' for parameters with a description but no declared type.
     for name, annotation in annotations.items():
-        if name in ('return', 'returns'):
+        if name in {'return', 'returns'}:
             continue
 
         if '*' + name in has_description:
@@ -201,8 +223,9 @@ def augment_descriptions_with_types(
     # Add 'rtype' if 'return' is present and 'rtype' isn't.
     if 'return' in annotations:
         rtype = annotations['return']
-        if 'return' not in has_type and ('return' in has_description or
-                                         (force_rtype and rtype != "None")):
+        if 'return' not in has_type and (
+            'return' in has_description or (force_rtype and rtype != 'None')
+        ):
             field = nodes.field()
             field += nodes.field_name('', 'rtype')
             field += nodes.field_body('', nodes.paragraph('', rtype))

sphinx/ext/autosectionlabel.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from types import NoneType
 from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
@@ -32,12 +33,14 @@ def get_node_depth(node: Node) -> int:
 def register_sections_as_label(app: Sphinx, document: Node) -> None:
     domain = app.env.domains.standard_domain
     for node in document.findall(nodes.section):
-        if (app.config.autosectionlabel_maxdepth and
-                get_node_depth(node) >= app.config.autosectionlabel_maxdepth):
+        if (
+            app.config.autosectionlabel_maxdepth
+            and get_node_depth(node) >= app.config.autosectionlabel_maxdepth
+        ):
             continue
         labelid = node['ids'][0]
         docname = app.env.docname
-        title = cast(nodes.title, node[0])
+        title = cast('nodes.title', node[0])
         ref_name = getattr(title, 'rawsource', title.astext())
         if app.config.autosectionlabel_prefix_document:
             name = nodes.fully_normalize_name(docname + ':' + ref_name)
@@ -45,21 +48,35 @@ def register_sections_as_label(app: Sphinx, document: Node) -> None:
             name = nodes.fully_normalize_name(ref_name)
         sectname = clean_astext(title)
 
-        logger.debug(__('section "%s" gets labeled as "%s"'),
-                     ref_name, name,
-                     location=node, type='autosectionlabel', subtype=docname)
+        logger.debug(
+            __('section "%s" gets labeled as "%s"'),
+            ref_name,
+            name,
+            location=node,
+            type='autosectionlabel',
+            subtype=docname,
+        )
         if name in domain.labels:
-            logger.warning(__('duplicate label %s, other instance in %s'),
-                           name, app.env.doc2path(domain.labels[name][0]),
-                           location=node, type='autosectionlabel', subtype=docname)
+            logger.warning(
+                __('duplicate label %s, other instance in %s'),
+                name,
+                app.env.doc2path(domain.labels[name][0]),
+                location=node,
+                type='autosectionlabel',
+                subtype=docname,
+            )
 
         domain.anonlabels[name] = docname, labelid
         domain.labels[name] = docname, labelid, sectname
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_config_value('autosectionlabel_prefix_document', False, 'env')
-    app.add_config_value('autosectionlabel_maxdepth', None, 'env')
+    app.add_config_value(
+        'autosectionlabel_prefix_document', False, 'env', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'autosectionlabel_maxdepth', None, 'env', types=frozenset({int, NoneType})
+    )
     app.connect('doctree-read', register_sections_as_label)
 
     return {