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

Doc/library/inspect.rst

@@ -635,19 +635,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` is true.
 
  This, for example, is true of ``int.__add__``. An object passing this test
  has a :meth:`~object.__get__` method, but not a :meth:`~object.__set__`
  method or a :meth:`~object.__delete__` method. Beyond that, the set of
  attributes varies. A :attr:`~definition.__name__` attribute is usually
  sensible, and :attr:`~definition.__doc__` often is.
 
-Methods implemented via descriptors that also pass one of the other tests
-return ``False`` from the :func:`ismethoddescriptor` test, simply because the
- other tests promise more -- you can, e.g., count on having the
- :attr:`~method.__func__` attribute (etc) 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, for example, count
+on having the :attr:`~method.__func__` attribute when an object passes
  :func:`ismethod`.
 
  .. versionchanged:: 3.13
@@ -658,16 +657,28 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 
 .. function:: isdatadescriptor(object)
 
- Return ``True`` if the object is a data descriptor.
+ Return ``True`` if the object is a data descriptor, but not if
+ :func:`isclass`, :func:`ismethod` or :func:`isfunction` is true.
 
- Data descriptors have a :attr:`~object.__set__` or a :attr:`~object.__delete__` method.
- Examples are properties (defined in Python), getsets, and members. The
- latter two are defined in C and there are more specific tests available for
- those types, which is robust across Python implementations. Typically, data
- descriptors will also have :attr:`~definition.__name__` and :attr:`!__doc__` attributes
- (properties, getsets, and members have both of these attributes), but this is
- not guaranteed.
+ Data descriptors always have a :meth:`~object.__set__` method and/or
+ a :meth:`~object.__delete__` method. Optionally, they may also have a
+ :meth:`~object.__get__` method.
 
+ Examples of data descriptors are :func:`properties <property>`, getsets and
+ 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.
+
+ 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.
+
+ .. versionchanged:: 3.8
+ This function now reports objects with only a :meth:`~object.__set__` method
+ as being data descriptors (the presence of :meth:`~object.__get__` is no
+ longer required for that). Moreover, objects with :meth:`~object.__delete__`,
+ but not :meth:`~object.__set__`, are now properly recognized as data
+ descriptors as well, which was not the case previously.
 
 .. function:: isgetsetdescriptor(object)
 

Lib/inspect.py

@@ -196,18 +196,18 @@ def ispackage(object):
 def ismethoddescriptor(object):
  """Return true if the object is a method descriptor.
 
- But not if ismethod() or isclass() or isfunction() are true.
+ But not if ismethod(), isclass() or isfunction() is true.
 
- This is new in Python 2.2, and, for example, is true of int.__add__.
- An object passing this test has a __get__ attribute, but not a
- __set__ attribute or a __delete__ attribute. Beyond that, the set
- of attributes varies; __name__ is usually sensible, and __doc__
- often is.
+ An object passing this test (for example, int.__add__) has a __get__
+ attribute, but not a __set__ attribute or a __delete__ attribute.
+ Beyond that, the set of attributes varies; __name__ is usually
+ sensible, and __doc__ often is.
 
  Methods implemented via descriptors that also pass one of the other
- tests return false from the ismethoddescriptor() test, simply because
- 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, for
+ example, count on having the __func__ attribute when an object passes
+ ismethod()."""
  if isclass(object) or ismethod(object) or isfunction(object):
  # mutual exclusion
  return False
@@ -219,8 +219,13 @@ def ismethoddescriptor(object):
 def isdatadescriptor(object):
  """Return true if the object is a data descriptor.
 
+ But not if ismethod(), isclass() or isfunction() is true.
+
  Data descriptors have a __set__ or a __delete__ attribute. Examples are
- properties (defined in Python) and getsets and members (defined in C).
+ properties, getsets, and members. For the latter two (defined only in C
+ extension modules) more specific tests are available as well:
+ isgetsetdescriptor() and ismemberdescriptor(), respectively.
+
  Typically, data descriptors will also have __name__ and __doc__ attributes
  (properties, getsets, and members have both of these attributes), but this
  is not guaranteed."""