Skip to content

Commit 2a11629

Browse files
committed
gh-122102: Fix/improve docs of inspect.is{data,method}descriptor()
1 parent 0dcbc83 commit 2a11629

File tree

2 files changed

+30
-14
lines changed

2 files changed

+30
-14
lines changed

Doc/library/inspect.rst

Lines changed: 27 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -513,19 +513,18 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
513513
.. function:: ismethoddescriptor(object)
514514

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

519518
This, for example, is true of ``int.__add__``. An object passing this test
520519
has a :meth:`~object.__get__` method, but not a :meth:`~object.__set__`
521520
method or a :meth:`~object.__delete__` method. Beyond that, the set of
522521
attributes varies. A :attr:`~definition.__name__` attribute is usually
523522
sensible, and :attr:`!__doc__` often is.
524523

525-
Methods implemented via descriptors that also pass one of the other tests
526-
return ``False`` from the :func:`ismethoddescriptor` test, simply because the
527-
other tests promise more -- you can, e.g., count on having the
528-
:attr:`~method.__func__` attribute (etc) when an object passes
524+
Method descriptors that also pass any of the other tests mentioned above
525+
(:func:`isclass`, :func:`ismethod` or :func:`isfunction`) make this function
526+
return ``False``, simply because the other tests promise more -- you can, e.g.,
527+
count on having the :attr:`~method.__func__` attribute when an object passes
529528
:func:`ismethod`.
530529

531530
.. versionchanged:: 3.13
@@ -536,15 +535,29 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
536535

537536
.. function:: isdatadescriptor(object)
538537

539-
Return ``True`` if the object is a data descriptor.
538+
Return ``True`` if the object is a data descriptor, but not if
539+
:func:`isclass`, :func:`ismethod` or :func:`isfunction` are true.
540540

541-
Data descriptors have a :attr:`~object.__set__` or a :attr:`~object.__delete__` method.
542-
Examples are properties (defined in Python), getsets, and members. The
543-
latter two are defined in C and there are more specific tests available for
544-
those types, which is robust across Python implementations. Typically, data
545-
descriptors will also have :attr:`~definition.__name__` and :attr:`!__doc__` attributes
546-
(properties, getsets, and members have both of these attributes), but this is
547-
not guaranteed.
541+
Data descriptors always have a :meth:`~object.__set__` method and/or
542+
a :meth:`~object.__delete__` method. Optionally, they may also have a
543+
:meth:`~object.__get__` method.
544+
545+
Examples of data descriptors are properties (see: :func:`property`), getset
546+
descriptors and member descriptors. Note that for the latter two (which can
547+
be defined only at the C level, in extension modules) more specific tests
548+
are available: :func:`isgetsetdescriptor` and :func:`ismemberdescriptor`,
549+
respectively.
550+
551+
Typically, data descriptors have also :attr:`~definition.__name__` and
552+
:attr:`!__doc__` attributes (properties, getsets and member descriptors have
553+
them), but this is not guaranteed.
554+
555+
.. versionchanged:: 3.8
556+
Now this function reports objects with only a :meth:`~object.__set__` method
557+
as being data descriptors (the presence of :meth:`~object.__get__` is no
558+
longer required for that). Moreover, objects with :meth:`~object.__delete__`,
559+
but not :meth:`~object.__set__`, are now properly recognized as data
560+
descriptors as well (formerly, they were not).
548561

549562

550563
.. function:: isgetsetdescriptor(object)
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Fix and improve the descriptions (and docstrings) of
2+
:func:`inspect.ismethoddescriptor` and :func:`inspect.isdatadescriptor`.
3+
Patch by Jan Kaliszewski.

0 commit comments

Comments
 (0)