[3.14] gh-72088: clarify `inspect.ismethod` and `inspect.isfunction` (and related...

(cherry picked from commit 0aa59ce2d4f007a9d19740eb2f6230ed302096f7)

Co-authored-by: Stefanie Molin <24376333+stefmolin@users.noreply.github.com>
Co-authored-by: CHINMAY <89741289+Das-Chinmay@users.noreply.github.com>

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 1e0ad1a010e53a68958a9ee95ab90f58cbe35470..7a69e246e12cb04e472ad2c1f7aa9edaad33c6b7 100644 (file)
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -407,12 +407,39 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 
    Return ``True`` if the object is a bound method written in Python.
 
+   .. note::
 
-.. function:: ispackage(object)
+      For example, given this class::
 
-   Return ``True`` if the object is a :term:`package`.
+          >>> class Greeter:
+          ...     def say_hello(self):
+          ...         print('hello!')
 
-   .. versionadded:: 3.14
+      A bound method (also known as an *instance method*) is created when
+      accessing ``say_hello`` (a :term:`function` defined in the
+      ``Greeter`` namespace) through an instance of the ``Greeter`` class::
+
+          >>> instance = Greeter()
+
+          >>> instance.say_hello
+          <bound method Greeter.say_hello of <__main__.Greeter object ...>>
+          >>> ismethod(instance.say_hello)
+          True
+          >>> isfunction(instance.say_hello)
+          False
+
+      Accessing ``say_hello`` through the ``Greeter`` class will return the
+      function itself. For this function, :func:`ismethod` will return
+      ``False``, but :func:`isfunction` will return ``True``::
+
+          >>> Greeter.say_hello
+          <function Greeter.say_hello at 0x7f7503854a90>
+          >>> ismethod(Greeter.say_hello)
+          False
+          >>> isfunction(Greeter.say_hello)
+          True
+
+      See :ref:`typesmethods` for details.
 
 
 .. function:: isfunction(object)
@@ -420,11 +447,23 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
    Return ``True`` if the object is a Python function, which includes functions
    created by a :term:`lambda` expression.
 
+   See the note for :func:`~inspect.ismethod` for an example.
+
+
+.. function:: ispackage(object)
+
+   Return ``True`` if the object is a :term:`package`.
+
+   .. versionadded:: 3.14
+
 
 .. function:: isgeneratorfunction(object)
 
    Return ``True`` if the object is a Python generator function.
 
+   It also returns ``True`` for bound methods created from Python generator functions
+   (see :ref:`typesmethods` for more information).
+
    .. versionchanged:: 3.8
       Functions wrapped in :func:`functools.partial` now return ``True`` if the
       wrapped function is a Python generator function.