[3.11] gh-101100: Improve documentation on function attributes (#112933) (#113003)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Doc/c-api/function.rst

@@ -34,18 +34,20 @@ There are a few functions specific to Python functions.
    Return a new function object associated with the code object *code*. *globals*
    must be a dictionary with the global variables accessible to the function.
 
-   The function's docstring and name are retrieved from the code object. *__module__*
+   The function's docstring and name are retrieved from the code object.
+   :func:`~function.__module__`
    is retrieved from *globals*. The argument defaults, annotations and closure are
-   set to ``NULL``. *__qualname__* is set to the same value as the code object's
+   set to ``NULL``. :attr:`~function.__qualname__` is set to the same value as
-   :attr:`~codeobject.co_qualname` field.
+   the code object's :attr:`~codeobject.co_qualname` field.
 
 
 .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
 
    As :c:func:`PyFunction_New`, but also allows setting the function object's
-   ``__qualname__`` attribute.  *qualname* should be a unicode object or ``NULL``;
+   :attr:`~function.__qualname__` attribute.
-   if ``NULL``, the ``__qualname__`` attribute is set to the same value as the
+   *qualname* should be a unicode object or ``NULL``;
-   code object's :attr:`~codeobject.co_qualname` field.
+   if ``NULL``, the :attr:`!__qualname__` attribute is set to the same value as
+   the code object's :attr:`~codeobject.co_qualname` field.
 
    .. versionadded:: 3.3
 
@@ -62,11 +64,12 @@ There are a few functions specific to Python functions.
 
 .. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
 
-   Return a :term:`borrowed reference` to the *__module__* attribute of the
+   Return a :term:`borrowed reference` to the :attr:`~function.__module__`
-   function object *op*. It can be *NULL*.
+   attribute of the :ref:`function object <user-defined-funcs>` *op*.
+   It can be *NULL*.
 
-   This is normally a string containing the module name, but can be set to any
+   This is normally a :class:`string <str>` containing the module name,
-   other object by Python code.
+   but can be set to any other object by Python code.
 
 
 .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)

Doc/howto/annotations.rst

@@ -153,7 +153,8 @@ on an arbitrary object ``o``:
   unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
   appropriate, until you have found the root unwrapped function.
 * If ``o`` is a callable (but not a class), use
-  ``o.__globals__`` as the globals when calling :func:`eval`.
+  :attr:`o.__globals__ <function.__globals__>` as the globals when calling
+  :func:`eval`.
 
 However, not all string values used as annotations can
 be successfully turned into Python values by :func:`eval`.

Doc/howto/descriptor.rst

@@ -1295,7 +1295,8 @@ Using the non-data descriptor protocol, a pure Python version of
 The :func:`functools.update_wrapper` call adds a ``__wrapped__`` attribute
 that refers to the underlying function.  Also it carries forward
 the attributes necessary to make the wrapper look like the wrapped
-function: ``__name__``, ``__qualname__``, ``__doc__``, and ``__annotations__``.
+function: :attr:`~function.__name__`, :attr:`~function.__qualname__`,
+:attr:`~function.__doc__`, and :attr:`~function.__annotations__`.
 
 .. testcode::
     :hide:
@@ -1506,8 +1507,9 @@ chained together.  In Python 3.11, this functionality was deprecated.
 The :func:`functools.update_wrapper` call in ``ClassMethod`` adds a
 ``__wrapped__`` attribute that refers to the underlying function.  Also
 it carries forward the attributes necessary to make the wrapper look
-like the wrapped function: ``__name__``, ``__qualname__``, ``__doc__``,
+like the wrapped function: :attr:`~function.__name__`,
-and ``__annotations__``.
+:attr:`~function.__qualname__`, :attr:`~function.__doc__`,
+and :attr:`~function.__annotations__`.
 
 
 Member objects and __slots__

Doc/library/inspect.rst

@@ -1186,9 +1186,10 @@ Classes and functions
    * If ``obj`` is a class, ``globals`` defaults to
      ``sys.modules[obj.__module__].__dict__`` and ``locals`` defaults
      to the ``obj`` class namespace.
-   * If ``obj`` is a callable, ``globals`` defaults to ``obj.__globals__``,
+   * If ``obj`` is a callable, ``globals`` defaults to
+     :attr:`obj.__globals__ <function.__globals__>`,
      although if ``obj`` is a wrapped function (using
-     ``functools.update_wrapper()``) it is first unwrapped.
+     :func:`functools.update_wrapper`) it is first unwrapped.
 
    Calling ``get_annotations`` is best practice for accessing the
    annotations dict of any object.  See :ref:`annotations-howto` for

Doc/library/stdtypes.rst

@@ -5326,10 +5326,10 @@ Code objects are used by the implementation to represent "pseudo-compiled"
 executable Python code such as a function body. They differ from function
 objects because they don't contain a reference to their global execution
 environment.  Code objects are returned by the built-in :func:`compile` function
-and can be extracted from function objects through their :attr:`__code__`
+and can be extracted from function objects through their
-attribute. See also the :mod:`code` module.
+:attr:`~function.__code__` attribute. See also the :mod:`code` module.
 
-Accessing ``__code__`` raises an :ref:`auditing event <auditing>`
+Accessing :attr:`~function.__code__` raises an :ref:`auditing event <auditing>`
 ``object.__getattr__`` with arguments ``obj`` and ``"__code__"``.
 
 .. index::

Doc/library/xmlrpc.server.rst

@@ -84,12 +84,12 @@ alone XML-RPC servers.
 
    Register a function that can respond to XML-RPC requests.  If *name* is given,
    it will be the method name associated with *function*, otherwise
-   ``function.__name__`` will be used.  *name* is a string, and may contain
+   :attr:`function.__name__` will be used.  *name* is a string, and may contain
    characters not legal in Python identifiers, including the period character.
 
    This method can also be used as a decorator.  When used as a decorator,
    *name* can only be given as a keyword argument to register *function* under
-   *name*.  If no *name* is given, ``function.__name__`` will be used.
+   *name*.  If no *name* is given, :attr:`function.__name__` will be used.
 
    .. versionchanged:: 3.7
       :meth:`register_function` can be used as a decorator.
@@ -298,12 +298,12 @@ requests sent to Python CGI scripts.
 
    Register a function that can respond to XML-RPC requests.  If *name* is given,
    it will be the method name associated with *function*, otherwise
-   ``function.__name__`` will be used.  *name* is a string, and may contain
+   :attr:`function.__name__` will be used.  *name* is a string, and may contain
    characters not legal in Python identifiers, including the period character.
 
    This method can also be used as a decorator.  When used as a decorator,
    *name* can only be given as a keyword argument to register *function* under
-   *name*.  If no *name* is given, ``function.__name__`` will be used.
+   *name*.  If no *name* is given, :attr:`function.__name__` will be used.
 
    .. versionchanged:: 3.7
       :meth:`register_function` can be used as a decorator.

Doc/reference/compound_stmts.rst

@@ -1630,8 +1630,8 @@ body of a coroutine function.
    are mappings.
 
 .. [#] A string literal appearing as the first statement in the function body is
-   transformed into the function's ``__doc__`` attribute and therefore the
+   transformed into the function's :attr:`~function.__doc__` attribute and
-   function's :term:`docstring`.
+   therefore the function's :term:`docstring`.
 
 .. [#] A string literal appearing as the first statement in the class body is
    transformed into the namespace's ``__doc__`` item and therefore the class's

Doc/reference/datamodel.rst

@@ -534,9 +534,34 @@ section :ref:`function`).  It should be called with an argument list
 containing the same number of items as the function's formal parameter
 list.
 
-Special attributes:
+Special read-only attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tabularcolumns:: |l|L|l|
+.. index::
+   single: __closure__ (function attribute)
+   single: __globals__ (function attribute)
+   pair: global; namespace
+
+.. list-table::
+   :header-rows: 1
+
+   * - Attribute
+     - Meaning
+
+   * - .. attribute:: function.__globals__
+     - A reference to the :class:`dictionary <dict>` that holds the function's
+       :ref:`global variables <naming>` -- the global namespace of the module
+       in which the function was defined.
+
+   * - .. attribute:: function.__closure__
+     - ``None`` or a :class:`tuple` of cells that contain bindings for the
+       function's free variables.
+
+       A cell object has the attribute ``cell_contents``.
+       This can be used to get the value of the cell, as well as set the value.
+
+Special writable attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. index::
    single: __doc__ (function attribute)
@@ -544,89 +569,73 @@ Special attributes:
    single: __module__ (function attribute)
    single: __dict__ (function attribute)
    single: __defaults__ (function attribute)
-   single: __closure__ (function attribute)
    single: __code__ (function attribute)
-   single: __globals__ (function attribute)
    single: __annotations__ (function attribute)
    single: __kwdefaults__ (function attribute)
-   pair: global; namespace
 
-+-------------------------+-------------------------------+-----------+
+Most of these attributes check the type of the assigned value:
-| Attribute               | Meaning                       |           |
-+=========================+===============================+===========+
-| :attr:`__doc__`         | The function's documentation  | Writable  |
-|                         | string, or ``None`` if        |           |
-|                         | unavailable; not inherited by |           |
-|                         | subclasses.                   |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`~definition.\    | The function's name.          | Writable  |
-| __name__`               |                               |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`~definition.\    | The function's                | Writable  |
-| __qualname__`           | :term:`qualified name`.       |           |
-|                         |                               |           |
-|                         | .. versionadded:: 3.3         |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__module__`      | The name of the module the    | Writable  |
-|                         | function was defined in, or   |           |
-|                         | ``None`` if unavailable.      |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__defaults__`    | A tuple containing default    | Writable  |
-|                         | argument values for those     |           |
-|                         | arguments that have defaults, |           |
-|                         | or ``None`` if no arguments   |           |
-|                         | have a default value.         |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__code__`        | The code object representing  | Writable  |
-|                         | the compiled function body.   |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__globals__`     | A reference to the dictionary | Read-only |
-|                         | that holds the function's     |           |
-|                         | global variables --- the      |           |
-|                         | global namespace of the       |           |
-|                         | module in which the function  |           |
-|                         | was defined.                  |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`~object.__dict__`| The namespace supporting      | Writable  |
-|                         | arbitrary function            |           |
-|                         | attributes.                   |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__closure__`     | ``None`` or a tuple of cells  | Read-only |
-|                         | that contain bindings for the |           |
-|                         | function's free variables.    |           |
-|                         | See below for information on  |           |
-|                         | the ``cell_contents``         |           |
-|                         | attribute.                    |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__annotations__` | A dict containing annotations | Writable  |
-|                         | of parameters.  The keys of   |           |
-|                         | the dict are the parameter    |           |
-|                         | names, and ``'return'`` for   |           |
-|                         | the return annotation, if     |           |
-|                         | provided.  For more           |           |
-|                         | information on working with   |           |
-|                         | this attribute, see           |           |
-|                         | :ref:`annotations-howto`.     |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__kwdefaults__`  | A dict containing defaults    | Writable  |
-|                         | for keyword-only parameters.  |           |
-+-------------------------+-------------------------------+-----------+
 
-Most of the attributes labelled "Writable" check the type of the assigned value.
+.. list-table::
+   :header-rows: 1
+
+   * - Attribute
+     - Meaning
+
+   * - .. attribute:: function.__doc__
+     - The function's documentation string, or ``None`` if unavailable.
+       Not inherited by subclasses.
+
+   * - .. attribute:: function.__name__
+     - The function's name.
+       See also: :attr:`__name__ attributes <definition.__name__>`.
+
+   * - .. attribute:: function.__qualname__
+     - The function's :term:`qualified name`.
+       See also: :attr:`__qualname__ attributes <definition.__qualname__>`.
+
+       .. versionadded:: 3.3
+
+   * - .. attribute:: function.__module__
+     - The name of the module the function was defined in,
+       or ``None`` if unavailable.
+
+   * - .. attribute:: function.__defaults__
+     - A :class:`tuple` containing default parameter values
+       for those parameters that have defaults,
+       or ``None`` if no parameters have a default value.
+
+   * - .. attribute:: function.__code__
+     - The :ref:`code object <code-objects>` representing
+       the compiled function body.
+
+   * - .. attribute:: function.__dict__
+     - The namespace supporting arbitrary function attributes.
+       See also: :attr:`__dict__ attributes <object.__dict__>`.
+
+   * - .. attribute:: function.__annotations__
+     - A :class:`dictionary <dict>` containing annotations of parameters.
+       The keys of the dictionary are the parameter names,
+       and ``'return'`` for the return annotation, if provided.
+       See also: :ref:`annotations-howto`.
+
+   * - .. attribute:: function.__kwdefaults__
+     - A :class:`dictionary <dict>` containing defaults for keyword-only
+       parameters.
 
 Function objects also support getting and setting arbitrary attributes, which
 can be used, for example, to attach metadata to functions.  Regular attribute
-dot-notation is used to get and set such attributes. *Note that the current
+dot-notation is used to get and set such attributes.
-implementation only supports function attributes on user-defined functions.
-Function attributes on built-in functions may be supported in the future.*
 
-A cell object has the attribute ``cell_contents``. This can be used to get
+.. impl-detail::
-the value of the cell, as well as set the value.
+
+   CPython's current implementation only supports function attributes
+   on user-defined functions. Function attributes on
+   :ref:`built-in functions <builtin-functions>` may be supported in the
+   future.
 
 Additional information about a function's definition can be retrieved from its
-code object; see the description of internal types below. The
+:ref:`code object <code-objects>`
-:data:`cell <types.CellType>` type can be accessed in the :mod:`types`
+(accessible via the :attr:`~function.__code__` attribute).
-module.
 
 
 .. _instance-methods:
@@ -658,15 +667,17 @@ Special read-only attributes:
        :ref:`bound <method-binding>`
 
    * - .. attribute:: method.__func__
-     - Refers to the original function object
+     - Refers to the original :ref:`function object <user-defined-funcs>`
 
    * - .. attribute:: method.__doc__
-     - The method's documentation (same as :attr:`!method.__func__.__doc__`).
+     - The method's documentation
+       (same as :attr:`method.__func__.__doc__ <function.__doc__>`).
        A :class:`string <str>` if the original function had a docstring, else
        ``None``.
 
    * - .. attribute:: method.__name__
-     - The name of the method (same as :attr:`!method.__func__.__name__`)
+     - The name of the method
+       (same as :attr:`method.__func__.__name__ <function.__name__>`)
 
    * - .. attribute:: method.__module__
      - The name of the module the method was defined in, or ``None`` if
@@ -772,6 +783,8 @@ is raised and the asynchronous iterator will have reached the end of
 the set of values to be yielded.
 
 
+.. _builtin-functions:
+
 Built-in functions
 ^^^^^^^^^^^^^^^^^^
 
@@ -784,10 +797,14 @@ A built-in function object is a wrapper around a C function.  Examples of
 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
 standard built-in module). The number and type of the arguments are
 determined by the C function. Special read-only attributes:
-:attr:`__doc__` is the function's documentation string, or ``None`` if
+
-unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is
+* :attr:`!__doc__` is the function's documentation string, or ``None`` if
-set to ``None`` (but see the next item); :attr:`__module__` is the name of
+  unavailable. See :attr:`function.__doc__`.
-the module the function was defined in or ``None`` if unavailable.
+* :attr:`!__name__` is the function's name. See :attr:`function.__name__`.
+* :attr:`!__self__` is set to ``None`` (but see the next item).
+* :attr:`!__module__` is the name of
+  the module the function was defined in or ``None`` if unavailable.
+  See :attr:`function.__module__`.
 
 
 .. _builtin-methods:
@@ -837,7 +854,8 @@ the :ref:`import system <importsystem>` as invoked either by the
 :keyword:`import` statement, or by calling
 functions such as :func:`importlib.import_module` and built-in
 :func:`__import__`.  A module object has a namespace implemented by a
-dictionary object (this is the dictionary referenced by the ``__globals__``
+:class:`dictionary <dict>` object (this is the dictionary referenced by the
+:attr:`~function.__globals__`
 attribute of functions defined in the module).  Attribute references are
 translated to lookups in this dictionary, e.g., ``m.x`` is equivalent to
 ``m.__dict__["x"]``. A module object does not contain the code object used
@@ -1869,7 +1887,8 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
    .. note::
 
       This method may still be bypassed when looking up special methods as the
-      result of implicit invocation via language syntax or built-in functions.
+      result of implicit invocation via language syntax or
+      :ref:`built-in functions <builtin-functions>`.
       See :ref:`special-lookup`.
 
    .. audit-event:: object.__getattr__ obj,name object.__getattribute__

Doc/whatsnew/2.1.rst

@@ -424,7 +424,8 @@ PEP 232: Function Attributes
 
 In Python 2.1, functions can now have arbitrary information attached to them.
 People were often using docstrings to hold information about functions and
-methods, because the ``__doc__`` attribute was the only way of attaching any
+methods, because the :attr:`~function.__doc__` attribute was the only way of
+attaching any
 information to a function.  For example, in the Zope web application server,
 functions are marked as safe for public access by having a docstring, and in
 John Aycock's SPARK parsing framework, docstrings hold parts of the BNF grammar

Doc/whatsnew/2.4.rst

@@ -324,7 +324,8 @@ function, as previously described.  In other words, ``@A @B @C(args)`` becomes::
 
 Getting this right can be slightly brain-bending, but it's not too difficult.
 
-A small related change makes the :attr:`func_name` attribute of functions
+A small related change makes the :attr:`func_name <function.__name__>`
+attribute of functions
 writable.  This attribute is used to display function names in tracebacks, so
 decorators should change the name of any new function that's constructed and
 returned.

Doc/whatsnew/3.0.rst

@@ -779,14 +779,15 @@ Operators And Special Methods
 
 * Removed support for :attr:`__members__` and :attr:`__methods__`.
 
-* The function attributes named :attr:`func_X` have been renamed to
+* The function attributes named :attr:`!func_X` have been renamed to
-  use the :data:`__X__` form, freeing up these names in the function
+  use the :attr:`!__X__` form, freeing up these names in the function
   attribute namespace for user-defined attributes.  To wit,
-  :attr:`func_closure`, :attr:`func_code`, :attr:`func_defaults`,
+  :attr:`!func_closure`, :attr:`!func_code`, :attr:`!func_defaults`,
-  :attr:`func_dict`, :attr:`func_doc`, :attr:`func_globals`,
+  :attr:`!func_dict`, :attr:`!func_doc`, :attr:`!func_globals`,
-  :attr:`func_name` were renamed to :attr:`__closure__`,
+  :attr:`!func_name` were renamed to :attr:`~function.__closure__`,
-  :attr:`__code__`, :attr:`__defaults__`, :attr:`~object.__dict__`,
+  :attr:`~function.__code__`, :attr:`~function.__defaults__`,
-  :attr:`__doc__`, :attr:`__globals__`, :attr:`~definition.__name__`,
+  :attr:`~function.__dict__`, :attr:`~function.__doc__`,
+  :attr:`~function.__globals__`, :attr:`~function.__name__`,
   respectively.
 
 * :meth:`!__nonzero__` is now :meth:`~object.__bool__`.

Doc/whatsnew/3.2.rst

@@ -789,8 +789,9 @@ functools
 
 * The :func:`functools.wraps` decorator now adds a :attr:`__wrapped__` attribute
   pointing to the original callable function.  This allows wrapped functions to
-  be introspected.  It also copies :attr:`__annotations__` if defined.  And now
+  be introspected.  It also copies :attr:`~function.__annotations__` if
-  it also gracefully skips over missing attributes such as :attr:`__doc__` which
+  defined.  And now it also gracefully skips over missing attributes such as
+  :attr:`~function.__doc__` which
   might not be defined for the wrapped callable.
 
   In the above example, the cache can be removed by recovering the original

Doc/whatsnew/3.4.rst

@@ -2405,8 +2405,8 @@ Changes in the Python API
   storage).  (:issue:`17094`.)
 
 * Parameter names in ``__annotations__`` dicts are now mangled properly,
-  similarly to ``__kwdefaults__``.  (Contributed by Yury Selivanov in
+  similarly to :attr:`~function.__kwdefaults__`.
-  :issue:`20625`.)
+  (Contributed by Yury Selivanov in :issue:`20625`.)
 
 * :attr:`hashlib.hash.name` now always returns the identifier in lower case.
   Previously some builtin hashes had uppercase names, but now that it is a