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

[zuo]

• 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]

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

[picnixz]

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.

[zuo]

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]

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]

Does this rule apply also to documentation-only changes?

AFAIK, yes. @hugovk Do you confirm?

[zuo]

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

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

[picnixz]

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.

[zuo]

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]

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.

[zuo]

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

[picnixz]

Was it really fixed since 3.8?

[zuo]

Yes, with the PR gh-1959.

[zuo]

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