GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-122102: Fix/improve docs of descriptor-related tools in `inspect` by zuo · Pull Request #122104 · python/cpython

Conversation

@zuo

@zuo zuo commented Jul 21, 2024 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

  • 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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-app bedevere-app Bot added the awaiting review label Jul 21, 2024
@zuo
zuo force-pushed the docs-and-tests-of-inspect-fixes-updates-improvements branch from ec0e2e9 to 5e7ce51 Compare July 21, 2024 23:32
@zuo 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 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
@zuo

zuo commented Jul 21, 2024 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@picnixz

picnixz commented Jul 22, 2024 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
picnixz
picnixz reviewed Jul 22, 2024
View reviewed changes

@picnixz picnixz left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
zuo reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Lib/test/test_inspect/test_inspect.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Lib/test/test_inspect/test_inspect.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Lib/test/test_inspect/test_inspect.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Lib/test/test_inspect/test_inspect.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Lib/test/test_inspect/test_inspect.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/inspect.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/inspect.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Lib/inspect.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/inspect.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@zuo

zuo commented Jul 22, 2024

Copy link
Copy Markdown
Contributor Author

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?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@zuo

zuo commented Jul 22, 2024

Copy link
Copy Markdown
Contributor Author

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. :)
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@picnixz

picnixz commented Jul 22, 2024

Copy link
Copy Markdown
Member

Does this rule apply also to documentation-only changes?

AFAIK, yes. @hugovk Do you confirm?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@zuo
pythongh-122102: Fix/improve docs of `inspect.is{data,method}descript…
2a11629 
…or()`
@zuo
zuo force-pushed the docs-and-tests-of-inspect-fixes-updates-improvements branch from 8ee1d5a to 2a11629 Compare July 22, 2024 22:39
@zuo 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
@zuo
pythongh-122102: Fix/improve docstrings of `inspect.is{data,method}de…
e0ba39d 
…scriptor()`
@zuo 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 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

zuo commented Jul 22, 2024 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor Author

@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...). :-|
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@zuo
zuo requested a review from picnixz July 22, 2024 23:26
picnixz
picnixz reviewed Jul 23, 2024
View reviewed changes
Comment thread Doc/library/inspect.rst Outdated
Comment on lines +524 to +525
Method descriptors that also pass any of the other tests mentioned above
(:func:`isclass`, :func:`ismethod` or :func:`isfunction`) make this function

@picnixz picnixz Jul 23, 2024

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
zuo reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Doc/library/inspect.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/inspect.rst Outdated
Comment on lines +546 to +549
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.

@picnixz picnixz Jul 23, 2024

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@zuo zuo Jul 23, 2024

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/library/inspect.rst Outdated
Comment on lines +551 to +553
Typically, data descriptors have also :attr:`~definition.__name__` and
:attr:`!__doc__` attributes (properties, getsets and member descriptors have
them), but this is not guaranteed.

@picnixz picnixz Jul 23, 2024

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@zuo zuo Jul 23, 2024

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/library/inspect.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
zuo and others added 3 commits July 23, 2024 15:50
@zuo @picnixz
Update Doc/library/inspect.rst
b59b533 
Co-authored-by: Bénédikt Tran <[email protected]>
@zuo @picnixz
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]>
@zuo
Update Doc/library/inspect.rst
f8ad14d
@zuo
zuo requested a review from picnixz July 23, 2024 14:36
@zuo
Update Lib/inspect.py
53077a8 
(further edits of docstrings)
@zuo

zuo commented Oct 2, 2024

Copy link
Copy Markdown
Contributor Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
zuo added 2 commits October 2, 2024 15:25
@zuo
Delete the blurb (unneeded to docs-only changes)
db0bd35
@zuo
Merge branch 'main' into docs-and-tests-of-inspect-fixes-updates-impr…
31fdce2 
…ovements
@picnixz picnixz added the skip news label Oct 2, 2024
picnixz
picnixz reviewed Dec 24, 2024
View reviewed changes
Comment thread Doc/library/inspect.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@zuo @picnixz
Update Doc/library/inspect.rst
5351773 
Co-authored-by: Bénédikt Tran <[email protected]>
@read-the-docs-community

read-the-docs-community Bot commented Jul 18, 2026 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #33645877 | 📁 Comparing d28b2b5 against main (ff56462)

  🔍 Preview build  

6 files changed · ± 6 modified

± Modified

  • library/concurrent.interpreters.html
  • library/filecmp.html
  • library/functions.html
  • library/inspect.html
  • whatsnew/3.15.html
  • whatsnew/changelog.html
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
zuo and others added 3 commits July 18, 2026 12:23
@zuo @picnixz
Apply suggestion from @picnixz - remove redundant links
abd2552 
Co-authored-by: Bénédikt Tran <[email protected]>
@zuo @picnixz
Apply suggestion from @picnixz (add comma)
99da393 
Co-authored-by: Bénédikt Tran <[email protected]>
@zuo @picnixz
Apply suggestion from @picnixz (tiny grammar fix)
521c83b 
Co-authored-by: Bénédikt Tran <[email protected]>
zware
zware reviewed Jul 18, 2026
View reviewed changes
Comment thread Doc/library/inspect.rst Outdated
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.

@zware zware Jul 18, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be is true

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
zuo reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Lib/inspect.py Outdated

@zware zware Jul 18, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we're probably due to update away from the "new in Python 2.2" note :)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
zuo reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Lib/inspect.py Outdated
the other tests promise more -- you can, e.g., count on having the
__func__ attribute (etc) when an object passes ismethod()."""
tests (ismethod(), isclass(), isfunction()) make this function return
false, simply because those other tests promise more -- you can, e.g.,

@zware zware Jul 18, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're generally moving away from latin abbreviations like e.g.; it can be expanded to "for example".

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
zuo reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
@zuo
A few more edits (CR)
24ee2af
@zuo
zuo requested a review from zware July 18, 2026 12:22
@zuo
Merge branch 'main' into docs-and-tests-of-inspect-fixes-updates-impr…
d28b2b5 
…ovements
zware
zware approved these changes Jul 18, 2026
View reviewed changes
@zware
zware enabled auto-merge (squash) July 18, 2026 12:28
@zware

zware commented Jul 18, 2026

Copy link
Copy Markdown
Member

Thanks for the patch! This will merge after CI passes.
zuo reacted with rocket emoji
All reactions
  • 🚀 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@zware zware added sprint and removed stale Stale PR or inactive for long period of time. labels Jul 18, 2026
@github-project-automation github-project-automation Bot added this to Sprint Jul 18, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Sprint Jul 18, 2026
@github-project-automation github-project-automation Bot moved this from Todo to In Progress in Sprint Jul 18, 2026
@zware zware added needs backport to 3.13 only security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Jul 18, 2026
@zuo zuo mentioned this pull request Jul 18, 2026
gh-122102: Improve tests for descriptor-related tools in inspect #122144
Open
@zware
zware merged commit 87f8fc8 into python:main Jul 18, 2026
61 checks passed

Uh oh!

There was an error while loading. Please reload this page.
@github-project-automation github-project-automation Bot moved this from In Progress to Done in Sprint Jul 18, 2026
@bedevere-app bedevere-app Bot removed the awaiting merge label Jul 18, 2026
@miss-islington-app

miss-islington-app Bot commented Jul 18, 2026

Copy link
Copy Markdown

Thanks @zuo for the PR, and @zware for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app

bedevere-app Bot commented Jul 18, 2026

Copy link
Copy Markdown

GH-153948 is a backport of this pull request to the 3.15 branch.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Jul 18, 2026
@bedevere-app

bedevere-app Bot commented Jul 18, 2026

Copy link
Copy Markdown

GH-153949 is a backport of this pull request to the 3.14 branch.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jul 18, 2026
@bedevere-app

bedevere-app Bot commented Jul 18, 2026

Copy link
Copy Markdown

GH-153950 is a backport of this pull request to the 3.13 branch.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.13 only security fixes label Jul 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@zware zware zware approved these changes
@picnixz picnixz picnixz approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

skip news sprint

Projects

Sprint
Archived in project

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@zuo @picnixz @zware
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.