mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-19 08:11:46 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

Browse source 
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
This commit is contained in:
Alex Waygood 2023-12-12 12:19:02 +00:00 • committed by GitHub
parent ada2d77977
commit f83087ce03
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 151 additions and 121 deletions
Download patch file Download diff file Expand all files Collapse all files

23
Doc/c-api/function.rst
View file

@ -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
:attr:`~codeobject.co_qualname` field.
set to ``NULL``. :attr:`~function.__qualname__` is set to the same value as
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``;
if ``NULL``, the ``__qualname__`` attribute is set to the same value as the
code object's :attr:`~codeobject.co_qualname` field.
:attr:`~function.__qualname__` attribute.
*qualname* should be a unicode object or ``NULL``;
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
function object *op*. It can be *NULL*.
Return a :term:`borrowed reference` to the :attr:`~function.__module__`
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
other object by Python code.
This is normally a :class:`string <str>` containing the module name,
but can be set to any other object by Python code.
.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)

3
Doc/howto/annotations.rst
View file

@ -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`.

8
Doc/howto/descriptor.rst
View file

@ -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__``,
and ``__annotations__``.
like the wrapped function: :attr:`~function.__name__`,
:attr:`~function.__qualname__`, :attr:`~function.__doc__`,
and :attr:`~function.__annotations__`.
Member objects and __slots__

5
Doc/library/inspect.rst
View file

@ -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

6
Doc/library/stdtypes.rst
View file

@ -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__`
attribute. See also the :mod:`code` module.
and can be extracted from function objects through their
: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::

8
Doc/library/xmlrpc.server.rst
View file

@ -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.

4
Doc/reference/compound_stmts.rst
View file

@ -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
function's :term:`docstring`.
transformed into the function's :attr:`~function.__doc__` attribute and
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

185
Doc/reference/datamodel.rst
View file

@ -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
+-------------------------+-------------------------------+-----------+
| 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 these attributes check the type of the assigned value:
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
implementation only supports function attributes on user-defined functions.
Function attributes on built-in functions may be supported in the future.*
dot-notation is used to get and set such attributes.
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.
.. impl-detail::
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
:data:`cell <types.CellType>` type can be accessed in the :mod:`types`
module.
:ref:`code object <code-objects>`
(accessible via the :attr:`~function.__code__` attribute).
.. _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
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.
* :attr:`!__doc__` is the function's documentation string, or ``None`` if
unavailable. See :attr:`function.__doc__`.
* :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__

3
Doc/whatsnew/2.1.rst
View file

@ -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

3
Doc/whatsnew/2.4.rst
View file

@ -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.

15
Doc/whatsnew/3.0.rst
View file

@ -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
use the :data:`__X__` form, freeing up these names in the function
* The function attributes named :attr:`!func_X` have been renamed to
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_dict`, :attr:`func_doc`, :attr:`func_globals`,
:attr:`func_name` were renamed to :attr:`__closure__`,
:attr:`__code__`, :attr:`__defaults__`, :attr:`~object.__dict__`,
:attr:`__doc__`, :attr:`__globals__`, :attr:`~definition.__name__`,
:attr:`!func_closure`, :attr:`!func_code`, :attr:`!func_defaults`,
:attr:`!func_dict`, :attr:`!func_doc`, :attr:`!func_globals`,
:attr:`!func_name` were renamed to :attr:`~function.__closure__`,
:attr:`~function.__code__`, :attr:`~function.__defaults__`,
:attr:`~function.__dict__`, :attr:`~function.__doc__`,
:attr:`~function.__globals__`, :attr:`~function.__name__`,
respectively.
* :meth:`!__nonzero__` is now :meth:`~object.__bool__`.

5
Doc/whatsnew/3.2.rst
View file

@ -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
it also gracefully skips over missing attributes such as :attr:`__doc__` which
be introspected. It also copies :attr:`~function.__annotations__` if
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

4
Doc/whatsnew/3.4.rst
View file

@ -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
:issue:`20625`.)
similarly to :attr:`~function.__kwdefaults__`.
(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