gh-122102: Fix/improve docs of descriptor-related tools in `inspect` #122104

zuo · 2024-07-21T23:19:40Z

Correct the docs of ismethoddescriptor() by removing the mistaken information about relation with isbuiltin().
Complement the docs of isdatadescriptor() by adding the missing information about relations with isclass(), ismethod() and isfunction().
Update and improve the docs (and docstrings) of those two functions.

📚 Documentation preview 📚: https://cpython-previews--122104.org.readthedocs.build/

Issue: Need for a few corrections/updates regarding the inspect.ismethoddescriptor()'s and inspect.isdatadescriptor()'s docs and unit tests #122102

zuo · 2024-07-21T23:36:05Z

Note: it may be worth to apply the documentation changes to all supported versions of Python (starting with 3.8).

picnixz · 2024-07-22T07:37:23Z

Note: it may be worth to apply the documentation changes to all supported versions of Python (starting with 3.8)

3.8 to 3.11 only accept security fixes
We can backport to 3.12 and 3.13.

picnixz

If you want to emphasize the terms getset, you should do it for slot as well when talking about slot descriptors I think. Personally, I would simply consider getset as a common noun, so no need for having *getset* or *properties* as well.

Lib/test/test_inspect/test_inspect.py

Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst

Doc/library/inspect.rst

Lib/inspect.py

Doc/library/inspect.rst

zuo · 2024-07-22T15:47:13Z

Note: it may be worth to apply the documentation changes to all supported versions of Python (starting with 3.8)
* 3.8 to 3.11 only accept security fixes

* We can backport to 3.12 and 3.13.

Does this rule apply also to documentation-only changes?

zuo · 2024-07-22T15:47:58Z

If you want to emphasize the terms getset, you should do it for slot as well when talking about slot descriptors I think. Personally, I would simply consider getset as a common noun, so no need for having *getset* or *properties* as well.

OK, you convinced me. :)

picnixz · 2024-07-22T15:56:29Z

Does this rule apply also to documentation-only changes?

AFAIK, yes. @hugovk Do you confirm?

…or()`

…scriptor()`

zuo · 2024-07-22T23:01:56Z

@picnixz

I decided to exclude the tests-related changes from this PR, and create a separate PR that includes them.

Rationale: those two sets of changes may be desired to be backported to different sets of Python versions, as:

I believe that the unit-tests-related part should be backported (if at all) only to 3.13 – as those changes are, in fact, a continuation of the test improvements made as a part of inspect.ismethoddescriptor(): lack of __delete__() is not checked #120381
On the other hand, the docs-related part should, most probably, be backported not only to 3.13, but also to 3.12. (And maybe to some earlier versions as well? See a separate question, asked by me above...)

I am very sorry for the fuss with all this PR splitting (I should have thought about it earlier...). :-|

picnixz · 2024-07-23T07:49:00Z

Doc/library/inspect.rst

+   Method descriptors that also pass any of the other tests mentioned above
+   (:func:`isclass`, :func:`ismethod` or :func:`isfunction`) make this function


It's a bit weird to say "mentioned above" and re-mention them. Either you mention them again (which I wouldn't suggest) or you just say "mentioned above".

Doc/library/inspect.rst

picnixz · 2024-07-23T07:53:34Z

Doc/library/inspect.rst

+   descriptors and member descriptors.  Note that for the latter two (which can
+   be defined only at the C level, in extension modules) more specific tests
+   are available: :func:`isgetsetdescriptor` and :func:`ismemberdescriptor`,
+   respectively.


Suggested change

descriptors and member descriptors. Note that for the latter two (which can

be defined only at the C level, in extension modules) more specific tests

are available: :func:`isgetsetdescriptor` and :func:`ismemberdescriptor`,

respectively.

descriptors and member descriptors. Note that specific tests robust

across different Python implementations are available for the latter

two (defined in C extension modules), namely :func:`isgetsetdescriptor`

and :func:`ismemberdescriptor` respectively.

I find the fragment about those two specific tests being robust across different Python implementations quite problematic: in a way, those two tests can be considered less robust across different Python implementations. (If I needed a test returning true for, e.g., a frame's f_locals regardless of the Python implementation being used, I'd use isdatadescriptor() rather than isgetsetdescriptor()...).

That's why I propose to remove that fragment.

IMHO, it causes more confusion than good.

Also I believe that the statement that those two tests are more specific, together with the docs of those two tests themselves, convey enough information.

picnixz · 2024-07-23T07:55:16Z

Doc/library/inspect.rst

+   Typically, data descriptors have also :attr:`~definition.__name__` and
+   :attr:`!__doc__` attributes (properties, getsets and member descriptors have
+   them), but this is not guaranteed.


Suggested change

Typically, data descriptors have also :attr:`~definition.__name__` and

:attr:`!__doc__` attributes (properties, getsets and member descriptors have

them), but this is not guaranteed.

While data descriptors such as properties, getsets or member descriptors

have :attr:`~definition.__name__` and :attr:`!__doc__` attributes, this

is not necessarily the case in general.

I believe that the fragment referring to properties, getsets or member descriptors should remain in parentheses, as it conveys here only additional (extra) information, not the crucial one (which is that, in general, the presence of the data descriptors' attributes __name__ and __doc__ is likely but optional).

Doc/library/inspect.rst

Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst

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

…2102.Za48MH.rst Co-authored-by: Bénédikt Tran <[email protected]>

(further edits of docstrings)

zuo · 2024-10-02T13:24:47Z

Sorry, I just learned that docs-only changes should not be announced in NEWS. So I delete the blurb.

…ovements

Doc/library/inspect.rst

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

…ovements

picnixz · 2025-02-01T21:57:31Z

I will have a look at it when I'm back from traveling but I think we're mostly good now. I'm sorry I forgot about your PR..

picnixz

Just English nits.

picnixz · 2025-02-24T18:47:26Z

Doc/library/inspect.rst

@@ -555,19 +555,18 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 .. function:: ismethoddescriptor(object)

   Return ``True`` if the object is a method descriptor, but not if
-   :func:`ismethod`, :func:`isclass`, :func:`isfunction` or :func:`isbuiltin`
-   are true.
+   :func:`isclass`, :func:`ismethod` or :func:`isfunction` are true.


Should we say "X, Y or Z is true" or "X, Y or Z are true"? @python/proofreaders

picnixz · 2025-02-24T18:47:57Z

Doc/library/inspect.rst

+   Method descriptors that also pass any of the other tests (:func:`isclass`,
+   :func:`ismethod` or :func:`isfunction`) make this function return ``False``,
+   simply because those other tests promise more -- you can, e.g., count on
+   having the :attr:`~method.__func__` attribute when an object passes


Suggested change

Method descriptors that also pass any of the other tests (:func:`isclass`,

:func:`ismethod` or :func:`isfunction`) make this function return ``False``,

simply because those other tests promise more -- you can, e.g., count on

having the :attr:`~method.__func__` attribute when an object passes

Method descriptors that also pass any of the other tests (:func:`!isclass`,

:func:`!ismethod` or :func:`!isfunction`) make this function return ``False``,

simply because those other tests promise more -- you can, e.g., count on

having the :attr:`~method.__func__` attribute when an object passes

To avoid linking twice in the same paragraph the functions.

picnixz · 2025-02-24T18:48:44Z

Doc/library/inspect.rst

+   member descriptors.  Note that for the latter two (defined only in C extension
+   modules) more specific tests are available: :func:`isgetsetdescriptor` and
+   :func:`ismemberdescriptor`, respectively.


Suggested change

member descriptors. Note that for the latter two (defined only in C extension

modules) more specific tests are available: :func:`isgetsetdescriptor` and

:func:`ismemberdescriptor`, respectively.

member descriptors. Note that for the latter two (defined only in C extension

modules), more specific tests are available: :func:`isgetsetdescriptor` and

:func:`ismemberdescriptor`, respectively.

picnixz · 2025-02-24T18:49:22Z

Doc/library/inspect.rst

+   While data descriptors may have also :attr:`~definition.__name__` and
+   :attr:`!__doc__` attributes (as properties, getsets and member descriptors
+   do), this is not necessarily the case in general.


Suggested change

While data descriptors may have also :attr:`~definition.__name__` and

:attr:`!__doc__` attributes (as properties, getsets and member descriptors

do), this is not necessarily the case in general.

While data descriptors may also have :attr:`~definition.__name__` and

:attr:`!__doc__` attributes (as properties, getsets and member descriptors

do), this is not necessarily the case in general.

bedevere-app bot added the awaiting review label Jul 21, 2024

zuo force-pushed the docs-and-tests-of-inspect-fixes-updates-improvements branch from ec0e2e9 to 5e7ce51 Compare July 21, 2024 23:32

zuo changed the title ~~gb-122102: Fix/improve docs + tests of descriptor tools in inspect~~ gh-122102: Fix/improve docs + tests of descriptor tools in inspect Jul 21, 2024

bedevere-app bot mentioned this pull request Jul 21, 2024

Need for a few corrections/updates regarding the inspect.ismethoddescriptor()'s and inspect.isdatadescriptor()'s docs and unit tests #122102

Open

picnixz reviewed Jul 22, 2024

View reviewed changes

pythongh-122102: Fix/improve docs of `inspect.is{data,method}descript…

2a11629

…or()`

zuo force-pushed the docs-and-tests-of-inspect-fixes-updates-improvements branch from 8ee1d5a to 2a11629 Compare July 22, 2024 22:39

zuo changed the title ~~gh-122102: Fix/improve docs + tests of descriptor tools in inspect~~ gh-122102: Fix/improve docs of inspect.is{data,method}descriptor() Jul 22, 2024

pythongh-122102: Fix/improve docstrings of `inspect.is{data,method}de…

e0ba39d

…scriptor()`

zuo changed the title ~~gh-122102: Fix/improve docs of inspect.is{data,method}descriptor()~~ gh-122102: Fix/improve docs of descriptor-related tests in inspect Jul 22, 2024

zuo changed the title ~~gh-122102: Fix/improve docs of descriptor-related tests in inspect~~ gh-122102: Fix/improve docs of descriptor-related tools in inspect Jul 22, 2024

zuo requested a review from picnixz July 22, 2024 23:26

picnixz reviewed Jul 23, 2024

View reviewed changes

zuo and others added 3 commits July 23, 2024 15:50

Update Doc/library/inspect.rst

b59b533

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

Update Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-12…

8aa2934

…2102.Za48MH.rst Co-authored-by: Bénédikt Tran <[email protected]>

Update Doc/library/inspect.rst

f8ad14d

zuo requested a review from picnixz July 23, 2024 14:36

Update Lib/inspect.py

53077a8

(further edits of docstrings)

zuo added 2 commits October 2, 2024 15:25

Delete the blurb (unneeded to docs-only changes)

db0bd35

Merge branch 'main' into docs-and-tests-of-inspect-fixes-updates-impr…

31fdce2

…ovements

picnixz added the skip news label Oct 2, 2024

picnixz reviewed Dec 24, 2024

View reviewed changes

Doc/library/inspect.rst Outdated Show resolved Hide resolved

Update Doc/library/inspect.rst

5351773

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

zuo requested a review from picnixz January 27, 2025 18:54

Merge branch 'main' into docs-and-tests-of-inspect-fixes-updates-impr…

cb2e360

…ovements

picnixz approved these changes Feb 24, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels Feb 24, 2025

		Method descriptors that also pass any of the other tests mentioned above
		(:func:`isclass`, :func:`ismethod` or :func:`isfunction`) make this function

Uh oh!

gh-122102: Fix/improve docs of descriptor-related tools in inspect #122104

Are you sure you want to change the base?

gh-122102: Fix/improve docs of descriptor-related tools in inspect #122104

Uh oh!

Conversation

zuo commented Jul 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zuo commented Jul 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz commented Jul 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zuo commented Jul 22, 2024

Uh oh!

zuo commented Jul 22, 2024

Uh oh!

picnixz commented Jul 22, 2024

Uh oh!

zuo commented Jul 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

zuo commented Oct 2, 2024

Uh oh!

Uh oh!

picnixz commented Feb 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gh-122102: Fix/improve docs of descriptor-related tools in `inspect` #122104

gh-122102: Fix/improve docs of descriptor-related tools in `inspect` #122104

zuo commented Jul 21, 2024 •

edited

Loading

zuo commented Jul 21, 2024 •

edited

Loading

picnixz commented Jul 22, 2024 •

edited

Loading

zuo commented Jul 22, 2024 •

edited

Loading

picnixz commented Feb 1, 2025 •

edited

Loading