gh-131116: Fix inspect._finddoc to work with cached_property objects.

Doc/library/inspect.rst

@@ -627,6 +627,9 @@ Retrieving source code
    .. versionchanged:: 3.5
       Documentation strings are now inherited if not overridden.
 
+   .. versionchanged:: next
+      Now correctly returns an inherited docstring on :class:`~functools.cached_property` objects if not overridden.
+
 
 .. function:: getcomments(object)
 

Lib/inspect.py

@@ -747,6 +747,12 @@ def _finddoc(obj):
         cls = _findclass(obj.fget)
         if cls is None or getattr(cls, name) is not obj:
             return None
+    # Should be tested before ismethoddescriptor()
+    elif isinstance(obj, functools.cached_property):
+        name = obj.attrname
+        cls = _findclass(obj.func)
+        if cls is None or getattr(cls, name) is not obj:
+            return None
     elif ismethoddescriptor(obj) or isdatadescriptor(obj):
         name = obj.__name__
         cls = obj.__objclass__

Lib/test/test_inspect/inspect_fodder3.py

@@ -0,0 +1,34 @@
+from functools import cached_property
+
+# Docstring in parent, inherited in child
+class ParentInheritDoc:
+    @cached_property
+    def foo(self):
+        "docstring for foo defined in parent"
+
+class ChildInheritDoc(ParentInheritDoc):
+    @cached_property
+    def foo(self):
+        pass
+
+# Redine foo as something other than cached_property
+class ChildPropertyFoo(ParentInheritDoc):
+    @property
+    def foo(self):
+        "docstring for the property foo"
+        pass
+
+class ChildMethodFoo(ParentInheritDoc):
+    def foo(self):
+        "docstring for the method foo"
+
+# Docstring in child but not parent
+class ParentNoDoc:
+    @cached_property
+    def foo(self):
+        pass
+
+class ChildDefineDoc(ParentNoDoc):
+    @cached_property
+    def foo(self):
+        "docstring for foo defined in child"

Lib/test/test_inspect/test_inspect.py

@@ -46,6 +46,7 @@
 
 from test.test_inspect import inspect_fodder as mod
 from test.test_inspect import inspect_fodder2 as mod2
+from test.test_inspect import inspect_fodder3 as mod3
 from test.test_inspect import inspect_stringized_annotations
 from test.test_inspect import inspect_deferred_annotations
 
@@ -665,6 +666,20 @@ def test_getdoc_inherited(self):
         self.assertEqual(inspect.getdoc(mod.FesteringGob.contradiction),
                          'The automatic gainsaying.')
 
+    def test_getdoc_inherited_cached_property(self):
+        self.assertEqual(inspect.getdoc(mod3.ChildInheritDoc.foo),
+                         'docstring for foo defined in parent')
+
+    def test_getdoc_redefine_cached_property_as_other(self):
+        self.assertEqual(inspect.getdoc(mod3.ChildPropertyFoo.foo),
+                         'docstring for the property foo')
+        self.assertEqual(inspect.getdoc(mod3.ChildMethodFoo.foo),
+                         'docstring for the method foo')
+
+    def test_getdoc_define_cached_property(self):
+        self.assertEqual(inspect.getdoc(mod3.ChildDefineDoc.foo),
+                         'docstring for foo defined in child')
+
     @unittest.skipIf(MISSING_C_DOCSTRINGS, "test requires docstrings")
     def test_finddoc(self):
         finddoc = inspect._finddoc

Misc/NEWS.d/next/Library/2025-03-12-18-57-10.gh-issue-131116.uTpwXZ.rst

@@ -0,0 +1 @@
+:func:`inspect.getdoc` now correctly returns an inherited docstring on :class:`~functools.cached_property` objects if none is given in a subclass.