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

lincolnj1 · 2025-03-12T18:54:31Z

Calling inspect.getdoc on a cached_property that inherits a docstring and does not define one would return None rather than the inherited docstring. This is because inspect._finddoc would treat the cached_property obj as a methoddescriptor and encounter an AttributeError trying to access obj.__name__. This PR adds a special case for cached_properties in _finddoc so that it can find the inherited docstring.

Issue: inspect.getdoc() failing to return docstring for cached_property for subclass that overrides code but not docstring #131116

…d parts

…-fix

scotscotmcc · 2025-03-12T21:34:39Z

In Lib/test/test_inspect/inspect_fodder.py, the last class has a bunch of comments where the comment includes the specific line number, i.e. # line 95 is line 95 of the original file. The updates in this PR include adding lines to that file and so those comments are no longer on the lines that they reference.

I'm having trouble getting the test suite working locally to get a sense of if that matters at all, but I'm guessing that some inspect tests may be looking at those comments for some reason or another?

lincolnj1 · 2025-03-12T21:46:00Z

In Lib/test/test_inspect/inspect_fodder.py, the last class has a bunch of comments where the comment includes the specific line number, i.e. # line 95 is line 95 of the original file. The updates in this PR include adding lines to that file and so those comments are no longer on the lines that they reference.

I'm having trouble getting the test suite working locally to get a sense of if that matters at all, but I'm guessing that some inspect tests may be looking at those comments for some reason or another?

I believe I fully reverted that in my later commits. There should no longer be any changes to inspect_fodder.py. Which commit have you pulled?

Those comments are there to test the comment extractor part of inspect.py. After a bit of testing I felt adding new stuff to the fodder file required changing more hard coded numbers than I thought was worthwhile, so I made a new fodder file.

I'm also having trouble getting the test suite working after my last pull from main. Are you getting the same "cannot import name 'Union' from '_typing' (unknown location)" error?

scotscotmcc · 2025-03-12T21:51:20Z

ope, my bad, was looking at a commit and spent so long trying to get the devcontainer to work you had made new updates since then that I didn't look at.

auvipy

can you please check the failing tests here please, Tests / Hypothesis tests on Ubuntu (pull_request) ? if they are relevant failures?

lincolnj1 · 2025-03-13T22:26:57Z

can you please check the failing tests here please, Tests / Hypothesis tests on Ubuntu (pull_request) ? if they are relevant failures?

Syncing with main this afternoon seems to have fixed it. I'm not sure why it was failing in the first place, since it seems to test code that I didn't modify at all. The tests ran fine on my Ubuntu terminal before and after I submitted so that was a bit baffling to me.

picnixz · 2025-03-13T22:30:14Z

The test is flaky I think (we've seen similar failures elsewhere)

lincolnj1 · 2025-03-24T23:14:15Z

@picnixz Do you have any thoughts on this pr? It's been a couple weeks and I'm hoping for core dev to look at it.

picnixz · 2025-03-24T23:23:44Z

I don't have time until the end of the week so I'm requesting myself a review

Lib/test/test_inspect/inspect_fodder3.py

Lib/test/test_inspect/test_inspect.py

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

Doc/library/inspect.rst

Lib/test/test_inspect/inspect_fodder3.py

Co-authored-by: Bénédikt Tran <[email protected]>

picnixz · 2025-04-06T14:47:21Z

Lib/test/test_inspect/inspect_fodder3.py

+    def foo(self):
+        pass
+
+# Redine foo as something other than cached_property


Suggested change

# Redine foo as something other than cached_property

# redefine foo as something other than cached_property

Lib/test/test_inspect/inspect_fodder3.py

picnixz

Just some cosmetic nits.

@serhiy-storchaka is there something we need to be careful about here?

picnixz · 2025-04-12T11:47:55Z

Lib/test/test_inspect/inspect_fodder3.py

+    def foo(self):
+        """docstring for foo defined in parent"""
+
+class ChildInheritDoc(ParentInheritDoc): pass


Suggested change

class ChildInheritDoc(ParentInheritDoc): pass

class ChildInheritDoc(ParentInheritDoc):

pass

picnixz · 2025-04-12T11:48:01Z

Lib/test/test_inspect/inspect_fodder3.py

+    def foo(self):
+        pass
+
+class ChildNoDoc(ParentNoDoc): pass


Suggested change

class ChildNoDoc(ParentNoDoc): pass

class ChildNoDoc(ParentNoDoc):

pass

picnixz · 2025-04-12T11:48:32Z

Lib/test/test_inspect/test_inspect.py

+        self.assertEqual(inspect.getdoc(mod3.ChildNoDoc.foo),
+                         None)


Suggested change

self.assertEqual(inspect.getdoc(mod3.ChildNoDoc.foo),

None)

self.assertIsNone(inspect.getdoc(mod3.ChildNoDoc.foo))

picnixz · 2025-04-12T11:49:51Z

Lib/test/test_inspect/test_inspect.py

+        self.assertEqual(inspect.getdoc(mod3.ChildInheritDoc.foo),
+                         'docstring for foo defined in parent')
+        self.assertEqual(inspect.getdoc(mod3.ChildInheritDefineDoc.foo),
+                         'docstring for foo defined in parent')


Suggested change

self.assertEqual(inspect.getdoc(mod3.ChildInheritDoc.foo),

'docstring for foo defined in parent')

self.assertEqual(inspect.getdoc(mod3.ChildInheritDefineDoc.foo),

'docstring for foo defined in parent')

doc = inspect.getdoc(mod3.ParentInheritDoc.foo)

self.assertEqual(doc, 'docstring for foo defined in parent')

self.assertEqual(inspect.getdoc(mod3.ChildInheritDoc.foo), doc)

self.assertEqual(inspect.getdoc(mod3.ChildInheritDefineDoc.foo), doc)

picnixz · 2025-04-12T11:50:28Z

Lib/test/test_inspect/inspect_fodder3.py

+    @property
+    def foo(self):
+        """docstring for the property foo"""
+        pass


Suggested change

pass

picnixz · 2025-04-12T11:50:49Z

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.


Suggested change

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

:func:`inspect.getdoc` now correctly returns an inherited docstring on

:class:`~functools.cached_property` objects if none is given in a subclass.

python-cla-bot · 2025-04-18T09:27:50Z

All commit authors signed the Contributor License Agreement.

serhiy-storchaka · 2025-04-18T10:28:46Z

I haven't looked at this PR yet, but note that there is a duplicate of this function in the pydoc module.

picnixz · 2025-04-18T10:34:04Z

but note that there is a duplicate of this function in the pydoc module.

Good to know then. @lincolnj1 can you check also the pydoc module please?

serhiy-storchaka

It seems to me that you went overboard with the tests (the simplest test would have been enough), but overall LGTM.

picnixz · 2025-04-18T16:13:28Z

It seems to me that you went overboard with the tests (the simplest test would have been enough),

This is a trauma I had from maintaining Sphinx. There were so many edge cases because of inheritance. It also serves as a robust way to detect future possible regressions (but I agree that it's a bit of an overkill).

lincolnj1 · 2025-04-18T16:53:33Z

but note that there is a duplicate of this function in the pydoc module.

Good to know then. @lincolnj1 can you check also the pydoc module please?

Yes, it seems that one is also broken in the same way (see below). I'll take a look at fixing it. Should I open a new PR to fix that or keep working in this one?

Edit: I used the private _getdoc method here when I should've used the public getdoc, but the behavior is consistent using either method.

>>> import pydoc
>>> import inspect
>>> pydoc._getdoc(int)
"int([x]) -> integer\nint(x, base=10) -> integer\n\nConvert a number or string to an integer, or return 0 if no arguments\nare given.  If x is a number, return x.__int__().  For floating-point\nnumbers, this truncates towards zero.\n\nIf x is not a number or if base is given, then x must be a string,\nbytes, or bytearray instance representing an integer literal in the\ngiven base.  The literal can be preceded by '+' or '-' and be surrounded\nby whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.\nBase 0 means to interpret the base from the string as an integer literal.\n>>> int('0b100', base=0)\n4"
>>> inspect.getdoc(int)
"int([x]) -> integer\nint(x, base=10) -> integer\n\nConvert a number or string to an integer, or return 0 if no arguments\nare given.  If x is a number, return x.__int__().  For floating-point\nnumbers, this truncates towards zero.\n\nIf x is not a number or if base is given, then x must be a string,\nbytes, or bytearray instance representing an integer literal in the\ngiven base.  The literal can be preceded by '+' or '-' and be surrounded\nby whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.\nBase 0 means to interpret the base from the string as an integer literal.\n>>> int('0b100', base=0)\n4"
>>> inspect.getdoc(int) == pydoc._getdoc(int)
True
>>>
>>> from functools import cached_property
>>> class A:
...     @cached_property
...     def foo(self):
...         "this is the docstring for foo"
...         return 1
...
>>> class B(A):
...     @cached_property
...     def foo(self): ...
...
>>> pydoc._getdoc(B.foo)
>>> pydoc._getdoc(A.foo)
'this is the docstring for foo'
>>> pydoc._getdoc(B.foo) == pydoc._getdoc(A.foo)
False
>>>
>>>
>>>
>>> class MethodBase:
...     def foo(self):
...             "my method foo"
...
>>> class Child(MethodBase):
...     def foo(self): ...
...
>>> pydoc._getdoc(MethodBase.foo) == pydoc._getdoc(Child.foo) #method docstrings are inherited properly!
True

serhiy-storchaka · 2025-04-18T17:53:22Z

If there are plans to backport this change, you need to fix the pydoc version too (it is just a copy). Otherwise, you may wait until #132686 has been resolved.

lincolnj1 and others added 6 commits March 12, 2025 10:41

attempted fix of issue python#131116. Test case failing on non change…

19d5c42

…d parts

Moved new test fodder to seperate file to fix errors

02ec2c1

Cleaned workspace and actually added the changed files this time

8786c3c

Merge branch 'python:main' into getdoc-fix

9fe818c

Seperated new tests into new test case

5772f7b

Merge branch 'getdoc-fix' of github.com:lincolnj1/cpython into getdoc…

f68119e

…-fix

bedevere-app bot added the awaiting review label Mar 12, 2025

bedevere-app bot mentioned this pull request Mar 12, 2025

inspect.getdoc() failing to return docstring for cached_property for subclass that overrides code but not docstring #131116

Open

lincolnj1 changed the title ~~gh-131116: Fixed inspect._finddoc to work with cached_property objects.~~ gh-131116: Fix inspect._finddoc to work with cached_property objects. Mar 12, 2025

📜🤖 Added by blurb_it.

2406055

auvipy suggested changes Mar 13, 2025

View reviewed changes

bedevere-app bot added awaiting core review and removed awaiting review labels Mar 13, 2025

Merge branch 'python:main' into getdoc-fix

5f0d6d4

picnixz self-requested a review March 24, 2025 23:23

picnixz reviewed Mar 30, 2025

View reviewed changes

Lib/test/test_inspect/inspect_fodder3.py Outdated Show resolved Hide resolved

picnixz reviewed Mar 30, 2025

View reviewed changes

Lib/test/test_inspect/test_inspect.py Outdated Show resolved Hide resolved

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

Added more tests and versionchanged to Doc

d61ab34

picnixz reviewed Apr 1, 2025

View reviewed changes

lincolnj1 and others added 4 commits April 1, 2025 10:55

Update Doc/library/inspect.rst

4b74d4e

Co-authored-by: Bénédikt Tran <[email protected]>

Update Lib/test/test_inspect/inspect_fodder3.py

cfe3e99

Co-authored-by: Bénédikt Tran <[email protected]>

Update Lib/test/test_inspect/inspect_fodder3.py

fa92ad3

Co-authored-by: Bénédikt Tran <[email protected]>

Update Lib/test/test_inspect/inspect_fodder3.py

d83205c

Co-authored-by: Bénédikt Tran <[email protected]>

Update Lib/test/test_inspect/inspect_fodder3.py

c4764ff

Co-authored-by: Bénédikt Tran <[email protected]>

picnixz self-requested a review April 6, 2025 14:38

picnixz reviewed Apr 6, 2025

View reviewed changes

Fixed inspect_fodder3 comments and added new test cases

1b0471f

picnixz approved these changes Apr 12, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Apr 12, 2025

serhiy-storchaka self-requested a review April 12, 2025 16:35

serhiy-storchaka approved these changes Apr 18, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

lincolnj1 commented Mar 12, 2025 •

edited by bedevere-app bot

Loading

scotscotmcc commented Mar 12, 2025

lincolnj1 commented Mar 12, 2025 •

edited

Loading

scotscotmcc commented Mar 12, 2025

auvipy left a comment

lincolnj1 commented Mar 13, 2025

picnixz commented Mar 13, 2025

lincolnj1 commented Mar 24, 2025

picnixz commented Mar 24, 2025

picnixz Apr 6, 2025

picnixz left a comment

picnixz Apr 12, 2025

picnixz Apr 12, 2025

picnixz Apr 12, 2025

picnixz Apr 12, 2025

picnixz Apr 12, 2025

picnixz Apr 12, 2025

python-cla-bot bot commented Apr 18, 2025 •

edited

Loading

serhiy-storchaka commented Apr 18, 2025

picnixz commented Apr 18, 2025

serhiy-storchaka left a comment

picnixz commented Apr 18, 2025

lincolnj1 commented Apr 18, 2025 •

edited

Loading

serhiy-storchaka commented Apr 18, 2025

	# Redine foo as something other than cached_property
	# redefine foo as something other than cached_property

	class ChildInheritDoc(ParentInheritDoc): pass
	class ChildInheritDoc(ParentInheritDoc):
	pass

	class ChildNoDoc(ParentNoDoc): pass
	class ChildNoDoc(ParentNoDoc):
	pass

	self.assertEqual(inspect.getdoc(mod3.ChildNoDoc.foo),
	None)
	self.assertIsNone(inspect.getdoc(mod3.ChildNoDoc.foo))

		@@ -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.

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

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

Are you sure you want to change the base?

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

Conversation

lincolnj1 commented Mar 12, 2025 • edited by bedevere-app bot Loading

scotscotmcc commented Mar 12, 2025

lincolnj1 commented Mar 12, 2025 • edited Loading

scotscotmcc commented Mar 12, 2025

auvipy left a comment

Choose a reason for hiding this comment

lincolnj1 commented Mar 13, 2025

picnixz commented Mar 13, 2025

lincolnj1 commented Mar 24, 2025

picnixz commented Mar 24, 2025

picnixz Apr 6, 2025

Choose a reason for hiding this comment

picnixz left a comment

Choose a reason for hiding this comment

picnixz Apr 12, 2025

Choose a reason for hiding this comment

picnixz Apr 12, 2025

Choose a reason for hiding this comment

picnixz Apr 12, 2025

Choose a reason for hiding this comment

picnixz Apr 12, 2025

Choose a reason for hiding this comment

picnixz Apr 12, 2025

Choose a reason for hiding this comment

picnixz Apr 12, 2025

Choose a reason for hiding this comment

python-cla-bot bot commented Apr 18, 2025 • edited Loading

serhiy-storchaka commented Apr 18, 2025

picnixz commented Apr 18, 2025

serhiy-storchaka left a comment

Choose a reason for hiding this comment

picnixz commented Apr 18, 2025

lincolnj1 commented Apr 18, 2025 • edited Loading

serhiy-storchaka commented Apr 18, 2025

lincolnj1 commented Mar 12, 2025 •

edited by bedevere-app bot

Loading

lincolnj1 commented Mar 12, 2025 •

edited

Loading

python-cla-bot bot commented Apr 18, 2025 •

edited

Loading

lincolnj1 commented Apr 18, 2025 •

edited

Loading