Skip to content

Commit 161cfd0

Browse files
[3.11] gh-101100: Improve documentation for attributes on instance methods (GH-112832) (#112873)
gh-101100: Improve documentation for attributes on instance methods (GH-112832) (cherry picked from commit ed21d0c) Co-authored-by: Alex Waygood <[email protected]>
1 parent 5a11bcb commit 161cfd0

File tree

6 files changed

+76
-41
lines changed

6 files changed

+76
-41
lines changed

Doc/library/inspect.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -471,7 +471,7 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
471471
Methods implemented via descriptors that also pass one of the other tests
472472
return ``False`` from the :func:`ismethoddescriptor` test, simply because the
473473
other tests promise more -- you can, e.g., count on having the
474-
:ref:`__func__ <instance-methods>` attribute (etc) when an object passes
474+
:attr:`~method.__func__` attribute (etc) when an object passes
475475
:func:`ismethod`.
476476

477477

Doc/library/stdtypes.rst

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5270,25 +5270,30 @@ Methods
52705270
.. index:: pair: object; method
52715271

52725272
Methods are functions that are called using the attribute notation. There are
5273-
two flavors: built-in methods (such as :meth:`append` on lists) and class
5274-
instance methods. Built-in methods are described with the types that support
5275-
them.
5273+
two flavors: :ref:`built-in methods <builtin-methods>` (such as :meth:`append`
5274+
on lists) and :ref:`class instance method <instance-methods>`.
5275+
Built-in methods are described with the types that support them.
52765276

52775277
If you access a method (a function defined in a class namespace) through an
52785278
instance, you get a special object: a :dfn:`bound method` (also called
5279-
:dfn:`instance method`) object. When called, it will add the ``self`` argument
5279+
:ref:`instance method <instance-methods>`) object. When called, it will add
5280+
the ``self`` argument
52805281
to the argument list. Bound methods have two special read-only attributes:
5281-
``m.__self__`` is the object on which the method operates, and ``m.__func__`` is
5282+
:attr:`m.__self__ <method.__self__>` is the object on which the method
5283+
operates, and :attr:`m.__func__ <method.__func__>` is
52825284
the function implementing the method. Calling ``m(arg-1, arg-2, ..., arg-n)``
52835285
is completely equivalent to calling ``m.__func__(m.__self__, arg-1, arg-2, ...,
52845286
arg-n)``.
52855287

5286-
Like function objects, bound method objects support getting arbitrary
5288+
Like :ref:`function objects <user-defined-funcs>`, bound method objects support
5289+
getting arbitrary
52875290
attributes. However, since method attributes are actually stored on the
5288-
underlying function object (``meth.__func__``), setting method attributes on
5291+
underlying function object (:attr:`method.__func__`), setting method attributes on
52895292
bound methods is disallowed. Attempting to set an attribute on a method
52905293
results in an :exc:`AttributeError` being raised. In order to set a method
5291-
attribute, you need to explicitly set it on the underlying function object::
5294+
attribute, you need to explicitly set it on the underlying function object:
5295+
5296+
.. doctest::
52925297

52935298
>>> class C:
52945299
... def method(self):
@@ -5303,7 +5308,7 @@ attribute, you need to explicitly set it on the underlying function object::
53035308
>>> c.method.whoami
53045309
'my name is method'
53055310

5306-
See :ref:`types` for more information.
5311+
See :ref:`instance-methods` for more information.
53075312

53085313

53095314
.. index:: object; code, code object

Doc/reference/datamodel.rst

Lines changed: 52 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -519,6 +519,8 @@ These are the types to which the function call operation (see section
519519
:ref:`calls`) can be applied:
520520

521521

522+
.. _user-defined-funcs:
523+
522524
User-defined functions
523525
^^^^^^^^^^^^^^^^^^^^^^
524526

@@ -647,43 +649,64 @@ callable object (normally a user-defined function).
647649
single: __name__ (method attribute)
648650
single: __module__ (method attribute)
649651

650-
Special read-only attributes: :attr:`__self__` is the class instance object,
651-
:attr:`__func__` is the function object; :attr:`__doc__` is the method's
652-
documentation (same as ``__func__.__doc__``); :attr:`~definition.__name__` is the
653-
method name (same as ``__func__.__name__``); :attr:`__module__` is the
654-
name of the module the method was defined in, or ``None`` if unavailable.
652+
Special read-only attributes:
653+
654+
.. list-table::
655+
656+
* - .. attribute:: method.__self__
657+
- Refers to the class instance object to which the method is
658+
:ref:`bound <method-binding>`
659+
660+
* - .. attribute:: method.__func__
661+
- Refers to the original function object
662+
663+
* - .. attribute:: method.__doc__
664+
- The method's documentation (same as :attr:`!method.__func__.__doc__`).
665+
A :class:`string <str>` if the original function had a docstring, else
666+
``None``.
667+
668+
* - .. attribute:: method.__name__
669+
- The name of the method (same as :attr:`!method.__func__.__name__`)
670+
671+
* - .. attribute:: method.__module__
672+
- The name of the module the method was defined in, or ``None`` if
673+
unavailable.
655674

656675
Methods also support accessing (but not setting) the arbitrary function
657-
attributes on the underlying function object.
676+
attributes on the underlying :ref:`function object <user-defined-funcs>`.
658677

659678
User-defined method objects may be created when getting an attribute of a
660679
class (perhaps via an instance of that class), if that attribute is a
661-
user-defined function object or a class method object.
680+
user-defined :ref:`function object <user-defined-funcs>` or a
681+
:class:`classmethod` object.
682+
683+
.. _method-binding:
662684

663685
When an instance method object is created by retrieving a user-defined
664-
function object from a class via one of its instances, its
665-
:attr:`__self__` attribute is the instance, and the method object is said
666-
to be bound. The new method's :attr:`__func__` attribute is the original
667-
function object.
668-
669-
When an instance method object is created by retrieving a class method
670-
object from a class or instance, its :attr:`__self__` attribute is the
671-
class itself, and its :attr:`__func__` attribute is the function object
686+
:ref:`function object <user-defined-funcs>` from a class via one of its
687+
instances, its :attr:`~method.__self__` attribute is the instance, and the
688+
method object is said to be *bound*. The new method's :attr:`~method.__func__`
689+
attribute is the original function object.
690+
691+
When an instance method object is created by retrieving a :class:`classmethod`
692+
object from a class or instance, its :attr:`~method.__self__` attribute is the
693+
class itself, and its :attr:`~method.__func__` attribute is the function object
672694
underlying the class method.
673695

674696
When an instance method object is called, the underlying function
675-
(:attr:`__func__`) is called, inserting the class instance
676-
(:attr:`__self__`) in front of the argument list. For instance, when
697+
(:attr:`~method.__func__`) is called, inserting the class instance
698+
(:attr:`~method.__self__`) in front of the argument list. For instance, when
677699
:class:`!C` is a class which contains a definition for a function
678700
:meth:`!f`, and ``x`` is an instance of :class:`!C`, calling ``x.f(1)`` is
679701
equivalent to calling ``C.f(x, 1)``.
680702

681-
When an instance method object is derived from a class method object, the
682-
"class instance" stored in :attr:`__self__` will actually be the class
703+
When an instance method object is derived from a :class:`classmethod` object, the
704+
"class instance" stored in :attr:`~method.__self__` will actually be the class
683705
itself, so that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to
684706
calling ``f(C,1)`` where ``f`` is the underlying function.
685707

686-
Note that the transformation from function object to instance method
708+
Note that the transformation from :ref:`function object <user-defined-funcs>`
709+
to instance method
687710
object happens each time the attribute is retrieved from the instance. In
688711
some cases, a fruitful optimization is to assign the attribute to a local
689712
variable and call that local variable. Also notice that this
@@ -767,6 +790,8 @@ set to ``None`` (but see the next item); :attr:`__module__` is the name of
767790
the module the function was defined in or ``None`` if unavailable.
768791

769792

793+
.. _builtin-methods:
794+
770795
Built-in methods
771796
^^^^^^^^^^^^^^^^
772797

@@ -778,8 +803,9 @@ Built-in methods
778803
This is really a different disguise of a built-in function, this time containing
779804
an object passed to the C function as an implicit extra argument. An example of
780805
a built-in method is ``alist.append()``, assuming *alist* is a list object. In
781-
this case, the special read-only attribute :attr:`__self__` is set to the object
782-
denoted by *alist*.
806+
this case, the special read-only attribute :attr:`!__self__` is set to the object
807+
denoted by *alist*. (The attribute has the same semantics as it does with
808+
:attr:`other instance methods <method.__self__>`.)
783809

784810

785811
Classes
@@ -894,8 +920,9 @@ https://www.python.org/download/releases/2.3/mro/.
894920

895921
When a class attribute reference (for class :class:`!C`, say) would yield a
896922
class method object, it is transformed into an instance method object whose
897-
:attr:`__self__` attribute is :class:`!C`. When it would yield a static
898-
method object, it is transformed into the object wrapped by the static method
923+
:attr:`~method.__self__` attribute is :class:`!C`.
924+
When it would yield a :class:`staticmethod` object,
925+
it is transformed into the object wrapped by the static method
899926
object. See section :ref:`descriptors` for another way in which attributes
900927
retrieved from a class may differ from those actually contained in its
901928
:attr:`~object.__dict__`.
@@ -958,7 +985,7 @@ in which attribute references are searched. When an attribute is not found
958985
there, and the instance's class has an attribute by that name, the search
959986
continues with the class attributes. If a class attribute is found that is a
960987
user-defined function object, it is transformed into an instance method
961-
object whose :attr:`__self__` attribute is the instance. Static method and
988+
object whose :attr:`~method.__self__` attribute is the instance. Static method and
962989
class method objects are also transformed; see above under "Classes". See
963990
section :ref:`descriptors` for another way in which attributes of a class
964991
retrieved via its instances may differ from the objects actually stored in

Doc/tutorial/classes.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -768,8 +768,10 @@ data from a string buffer instead, and pass it as an argument.
768768
or arithmetic operators, and assigning such a "pseudo-file" to sys.stdin will
769769
not cause the interpreter to read further input from it.)
770770
771-
Instance method objects have attributes, too: ``m.__self__`` is the instance
772-
object with the method :meth:`!m`, and ``m.__func__`` is the function object
771+
:ref:`Instance method objects <instance-methods>` have attributes, too:
772+
:attr:`m.__self__ <method.__self__>` is the instance
773+
object with the method :meth:`!m`, and :attr:`m.__func__ <method.__func__>` is
774+
the :ref:`function object <user-defined-funcs>`
773775
corresponding to the method.
774776

775777

Doc/whatsnew/2.6.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1678,8 +1678,8 @@ Some smaller changes made to the core Python language are:
16781678

16791679
* Instance method objects have new attributes for the object and function
16801680
comprising the method; the new synonym for :attr:`!im_self` is
1681-
:ref:`__self__ <instance-methods>`, and :attr:`!im_func` is also available as
1682-
:ref:`__func__ <instance-methods>`.
1681+
:attr:`~method.__self__`, and :attr:`!im_func` is also available as
1682+
:attr:`~method.__func__`.
16831683
The old names are still supported in Python 2.6, but are gone in 3.0.
16841684

16851685
* An obscure change: when you use the :func:`locals` function inside a

Doc/whatsnew/2.7.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -858,9 +858,10 @@ Some smaller changes made to the core Python language are:
858858

859859
.. XXX bytearray doesn't seem to be documented
860860
861-
* When using ``@classmethod`` and ``@staticmethod`` to wrap
861+
* When using :class:`@classmethod <classmethod>` and
862+
:class:`@staticmethod <staticmethod>` to wrap
862863
methods as class or static methods, the wrapper object now
863-
exposes the wrapped function as their :ref:`__func__ <instance-methods>`
864+
exposes the wrapped function as their :attr:`~method.__func__`
864865
attribute.
865866
(Contributed by Amaury Forgeot d'Arc, after a suggestion by
866867
George Sakkis; :issue:`5982`.)

0 commit comments

Comments
 (0)