From 2a1162934cbf4f356c5224adae91acdb0d2654f6 Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Tue, 23 Jul 2024 00:34:15 +0200 Subject: [PATCH 1/8] gh-122102: Fix/improve docs of `inspect.is{data,method}descriptor()` --- Doc/library/inspect.rst | 41 ++++++++++++------- ...-07-22-01-30-49.gh-issue-122102.Za48MH.rst | 3 ++ 2 files changed, 30 insertions(+), 14 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 7838eeed2843c4..06d0a6e6600ac2 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -513,8 +513,7 @@ 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. 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__` @@ -522,10 +521,10 @@ attributes (see :ref:`import-mod-attrs` for module attributes): attributes varies. A :attr:`~definition.__name__` attribute is usually sensible, and :attr:`!__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 mentioned above + (:func:`isclass`, :func:`ismethod` or :func:`isfunction`) make this function + return ``False``, simply because the other tests promise more -- you can, e.g., + count on having the :attr:`~method.__func__` attribute when an object passes :func:`ismethod`. .. versionchanged:: 3.13 @@ -536,15 +535,29 @@ 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` are 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 properties (see: :func:`property`), getset + 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. + + Typically, data descriptors have also :attr:`~definition.__name__` and + :attr:`!__doc__` attributes (properties, getsets and member descriptors have + them), but this is not guaranteed. + + .. versionchanged:: 3.8 + Now this function 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 (formerly, they were not). .. function:: isgetsetdescriptor(object) diff --git a/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst b/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst new file mode 100644 index 00000000000000..0058986b21853f --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst @@ -0,0 +1,3 @@ +Fix and improve the descriptions (and docstrings) of +:func:`inspect.ismethoddescriptor` and :func:`inspect.isdatadescriptor`. +Patch by Jan Kaliszewski. From e0ba39d3269cce36d6f4b53cfa355ea6cf4af0b8 Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Tue, 23 Jul 2024 00:47:50 +0200 Subject: [PATCH 2/8] gh-122102: Fix/improve docstrings of `inspect.is{data,method}descriptor()` --- Lib/inspect.py | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/Lib/inspect.py b/Lib/inspect.py index 0e7b40eb39bce8..9dda6868ac0ea9 100644 --- a/Lib/inspect.py +++ b/Lib/inspect.py @@ -313,9 +313,10 @@ def ismethoddescriptor(object): 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() or isfunction()) make this function + return false, simply because those other tests promise more -- you + can, e.g., count on having the __func__ attribute when an object + passes ismethod().""" if isclass(object) or ismethod(object) or isfunction(object): # mutual exclusion return False @@ -327,8 +328,14 @@ def ismethoddescriptor(object): def isdatadescriptor(object): """Return true if the object is a data descriptor. + But not if ismethod() or isclass() or isfunction() are 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 (which can be + defined only at the C level, in 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.""" From b59b5330e1d2545dc00d329812ea5c46a5fb348d Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Tue, 23 Jul 2024 15:50:39 +0200 Subject: [PATCH 3/8] Update Doc/library/inspect.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/inspect.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 06d0a6e6600ac2..8ae39eaf91e4e3 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -542,7 +542,7 @@ attributes (see :ref:`import-mod-attrs` for module attributes): a :meth:`~object.__delete__` method. Optionally, they may also have a :meth:`~object.__get__` method. - Examples of data descriptors are properties (see: :func:`property`), getset + Examples of data descriptors are :func:`properties `, getset 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`, From 8aa2934a3a4ceb266ccb6f5ab8dd19d8e9153518 Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Tue, 23 Jul 2024 16:26:39 +0200 Subject: [PATCH 4/8] Update Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- .../2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst b/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst index 0058986b21853f..5f9ba897a45ee4 100644 --- a/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst +++ b/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst @@ -1,3 +1,3 @@ -Fix and improve the descriptions (and docstrings) of +Fix and improve the descriptions of :func:`inspect.ismethoddescriptor` and :func:`inspect.isdatadescriptor`. Patch by Jan Kaliszewski. From f8ad14dd2d467eb04943fffb9003a065948e1f96 Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Tue, 23 Jul 2024 16:31:43 +0200 Subject: [PATCH 5/8] Update Doc/library/inspect.rst --- Doc/library/inspect.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 8ae39eaf91e4e3..a05e6f6bc4ad80 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -521,10 +521,10 @@ attributes (see :ref:`import-mod-attrs` for module attributes): attributes varies. A :attr:`~definition.__name__` attribute is usually sensible, and :attr:`!__doc__` often is. - Method descriptors that also pass any of the other tests mentioned above - (:func:`isclass`, :func:`ismethod` or :func:`isfunction`) make this function - return ``False``, simply because the 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 :func:`ismethod`. .. versionchanged:: 3.13 @@ -542,15 +542,14 @@ attributes (see :ref:`import-mod-attrs` for module attributes): a :meth:`~object.__delete__` method. Optionally, they may also have a :meth:`~object.__get__` method. - Examples of data descriptors are :func:`properties `, getset - 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. + Examples of data descriptors are :func:`properties `, 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. - 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 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. .. versionchanged:: 3.8 Now this function reports objects with only a :meth:`~object.__set__` method From 53077a83ef5403e4091edc9e9608a7478dd1eff6 Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Fri, 26 Jul 2024 03:07:44 +0200 Subject: [PATCH 6/8] Update Lib/inspect.py (further edits of docstrings) --- Lib/inspect.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/Lib/inspect.py b/Lib/inspect.py index 9dda6868ac0ea9..595d67e8e9d3e5 100644 --- a/Lib/inspect.py +++ b/Lib/inspect.py @@ -313,10 +313,10 @@ def ismethoddescriptor(object): often is. Methods implemented via descriptors that also pass one of the other - tests (ismethod(), isclass() or isfunction()) make this function - return false, simply because those other tests promise more -- you - can, e.g., count on having the __func__ attribute 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., + count on having the __func__ attribute when an object passes + ismethod().""" if isclass(object) or ismethod(object) or isfunction(object): # mutual exclusion return False @@ -331,10 +331,9 @@ def isdatadescriptor(object): But not if ismethod() or isclass() or isfunction() are true. Data descriptors have a __set__ or a __delete__ attribute. Examples are - properties, getsets and members. For the latter two (which can be - defined only at the C level, in extension modules) more specific tests - are available as well: isgetsetdescriptor() and ismemberdescriptor(), - respectively. + 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 From db0bd356a8bd50047804091f0e8c0d8af6743cb0 Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Wed, 2 Oct 2024 15:25:30 +0200 Subject: [PATCH 7/8] Delete the blurb (unneeded to docs-only changes) --- .../2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst diff --git a/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst b/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst deleted file mode 100644 index 5f9ba897a45ee4..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2024-07-22-01-30-49.gh-issue-122102.Za48MH.rst +++ /dev/null @@ -1,3 +0,0 @@ -Fix and improve the descriptions of -:func:`inspect.ismethoddescriptor` and :func:`inspect.isdatadescriptor`. -Patch by Jan Kaliszewski. From 5351773ade4b4eaf1856e3637e23248c43bb3b15 Mon Sep 17 00:00:00 2001 From: Jan Kaliszewski Date: Mon, 27 Jan 2025 19:53:43 +0100 Subject: [PATCH 8/8] Update Doc/library/inspect.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/inspect.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index b00dcec7526ddd..716874a6505c0b 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -577,12 +577,11 @@ attributes (see :ref:`import-mod-attrs` for module attributes): do), this is not necessarily the case in general. .. versionchanged:: 3.8 - Now this function reports objects with only a :meth:`~object.__set__` method + 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 (formerly, they were not). - + descriptors as well, which was not the case previously. .. function:: isgetsetdescriptor(object)