Fix sphinx.ext.autodoc.preserve_defaults extension.

CHANGES

@@ -10,6 +10,12 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #11459: ``sphinx.ext.autodoc.preserve_defaults.get_function_def`` is
+  renamed ``sphinx.ext.autodoc.preserve_defaults.get_arguments`` and its
+  signature is updated accordingly. It now extracts the ``ast.arguments`` from
+  a function or a lambda function object.
+  Patch by Bénédikt Tran.
+
 Deprecated
 ----------
 
@@ -48,12 +54,18 @@ Features added
 * #11572: Improve ``debug`` logging of reasons why files are detected as out of
   date.
   Patch by Eric Larson.
+* #11459: ``sphinx.ext.autodoc.preserve_defaults``: Add support for
+  ``async def`` functions and lambda functions.
+  Patch by Bénédikt Tran.
 
 Bugs fixed
 ----------
 
 * #11077: graphviz: Fix relative links from within the graph.
   Patch by Ralf Grubenmann.
+* #11459: ``sphinx.ext.autodoc.preserve_defaults``: fix lambda functions
+  used inside ``@property`` should be ignored in a multi-line context.
+  Patch by Bénédikt Tran.
 * #11529: Line Block in LaTeX builder outputs spurious empty token.
   Patch by Adrian Vollmer.
 * #11196: autosummary: Summary line extraction failed with "e.g."

sphinx/ext/autodoc/preserve_defaults.py

@@ -8,6 +8,7 @@
 
 import ast
 import inspect
+from types import LambdaType
 from typing import Any
 
 import sphinx
@@ -27,8 +28,15 @@ def __repr__(self) -> str:
         return self.name
 
 
-def get_function_def(obj: Any) -> ast.FunctionDef | None:
-    """Get FunctionDef object from living object.
+_LAMBDA_NAME = (lambda: None).__name__
+
+
+def _islambda(v):
+    return isinstance(v, LambdaType) and v.__name__ == _LAMBDA_NAME
+
+
+def get_arguments(obj: Any) -> ast.arguments | None:
+    """Get ast.arguments object from living object.
     This tries to parse original code for living object and returns
     AST node for given *obj*.
     """
@@ -38,12 +46,35 @@ def get_function_def(obj: Any) -> ast.FunctionDef | 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)
-            return module.body[0].body[0]  # type: ignore
+            subject = module.body[0].body[0]  # type: ignore[attr-defined]
         else:
             module = ast.parse(source)
-            return module.body[0]  # type: ignore
+            subject = module.body[0]
     except (OSError, TypeError):  # failed to load source code
         return None
+    except SyntaxError:
+        if _islambda(obj):
+            # most likely a multi-line arising from detecting a lambda, e.g.:
+            #
+            # class Foo:
+            #     x = property(
+            #         lambda self: 1, doc="...")
+            return None
+
+        # Other syntax errors that are not due to the fact that we are
+        # documenting a lambda function are propagated (in particular,
+        # if a lambda function is renamed by the user, the SyntaxError is
+        # propagated).
+        raise
+
+    def _get_arguments(x: Any) -> ast.arguments | None:
+        if isinstance(x, (ast.AsyncFunctionDef, ast.FunctionDef, ast.Lambda)):
+            return x.args
+        if isinstance(x, (ast.Assign, ast.AnnAssign)):
+            return _get_arguments(x.value)
+        return None
+
+    return _get_arguments(subject)
 
 
 def get_default_value(lines: list[str], position: ast.AST) -> str | None:
@@ -66,17 +97,22 @@ def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
     try:
         lines = inspect.getsource(obj).splitlines()
         if lines[0].startswith((' ', r'\t')):
-            lines.insert(0, '')  # insert a dummy line to follow what get_function_def() does.
+            lines.insert(0, '')  # insert a dummy line to follow what get_arguments() does.
     except (OSError, TypeError):
         lines = []
 
     try:
-        function = get_function_def(obj)
-        assert function is not None  # for mypy
-        if function.args.defaults or function.args.kw_defaults:
+        args = get_arguments(obj)
+        if args is None:
+            # If the object is a built-in, we won't be always able to recover
+            # the function definition and its arguments. This happens if *obj*
+            # is the `__init__` method generated automatically for dataclasses.
+            return
+
+        if args.defaults or args.kw_defaults:
             sig = inspect.signature(obj)
-            defaults = list(function.args.defaults)
-            kw_defaults = list(function.args.kw_defaults)
+            defaults = list(args.defaults)
+            kw_defaults = list(args.kw_defaults)
             parameters = list(sig.parameters.values())
             for i, param in enumerate(parameters):
                 if param.default is param.empty:

tests/roots/test-ext-autodoc/target/preserve_defaults.py

@@ -30,3 +30,31 @@ def clsmeth(cls, name: str = CONSTANT, sentinel: Any = SENTINEL,
                 now: datetime = datetime.now(), color: int = 0xFFFFFF,
                 *, kwarg1, kwarg2 = 0xFFFFFF) -> None:
         """docstring"""
+
+
+get_sentinel = lambda custom=SENTINEL: custom
+"""docstring"""
+
+
+class MultiLine:
+    """docstring"""
+
+    # The properties will raise a silent SyntaxError because "lambda self: 1"
+    # will be detected as a function to update the default values of. However,
+    # only prop3 will not fail because it's on a single line whereas the others
+    # will fail to parse.
+
+    prop1 = property(
+      lambda self: 1, doc="docstring")
+
+    prop2 = property(
+      lambda self: 2, doc="docstring"
+    )
+
+    prop3 = property(lambda self: 3, doc="docstring")
+
+    prop4 = (property
+    (lambda self: 4, doc="docstring"))
+
+    prop5 = property\
+    (lambda self: 5, doc="docstring")

tests/test_ext_autodoc_preserve_defaults.py

@@ -40,11 +40,53 @@ def test_preserve_defaults(app):
         '      docstring',
         '',
         '',
+        '.. py:class:: MultiLine()',
+        '   :module: target.preserve_defaults',
+        '',
+        '   docstring',
+        '',
+        '',
+        '   .. py:property:: MultiLine.prop1',
+        '      :module: target.preserve_defaults',
+        '',
+        '      docstring',
+        '',
+        '',
+        '   .. py:property:: MultiLine.prop2',
+        '      :module: target.preserve_defaults',
+        '',
+        '      docstring',
+        '',
+        '',
+        '   .. py:property:: MultiLine.prop3',
+        '      :module: target.preserve_defaults',
+        '',
+        '      docstring',
+        '',
+        '',
+        '   .. py:property:: MultiLine.prop4',
+        '      :module: target.preserve_defaults',
+        '',
+        '      docstring',
+        '',
+        '',
+        '   .. py:property:: MultiLine.prop5',
+        '      :module: target.preserve_defaults',
+        '',
+        '      docstring',
+        '',
+        '',
         '.. py:function:: foo(name: str = CONSTANT, sentinel: ~typing.Any = SENTINEL, '
         'now: ~datetime.datetime = datetime.now(), color: int = %s, *, kwarg1, '
         'kwarg2=%s) -> None' % (color, color),
         '   :module: target.preserve_defaults',
         '',
         '   docstring',
         '',
+        '',
+        '.. py:function:: get_sentinel(custom=SENTINEL)',
+        '   :module: target.preserve_defaults',
+        '',
+        '   docstring',
+        '',
     ]