languages/cpython
languages/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython synced 2024-07-20 09:45:46 +00:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

gh-101100: Improve documentation on function attributes (#112933)

Browse source 
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
This commit is contained in:
Alex Waygood 2023-12-11 10:00:42 +00:00 committed by GitHub
parent 9cdf05bc28
commit 4c5b9c107a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 158 additions and 129 deletions
Show stats 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

@ -1342,7 +1342,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:
@ -1522,8 +1523,9 @@ Using the non-data descriptor protocol, a pure Python version of
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

@ -1225,9 +1225,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

@ -5384,10 +5384,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.

7
Doc/reference/compound_stmts.rst
View file

@ -1261,7 +1261,8 @@ except that the original function is not temporarily bound to the name ``func``.
A list of :ref:`type parameters <type-params>` may be given in square brackets
between the function's name and the opening parenthesis for its parameter list.
This indicates to static type checkers that the function is generic. At runtime,
the type parameters can be retrieved from the function's ``__type_params__``
the type parameters can be retrieved from the function's
:attr:`~function.__type_params__`
attribute. See :ref:`generic-functions` for more.
.. versionchanged:: 3.12
@ -1868,8 +1869,8 @@ like ``TYPE_PARAMS_OF_ListOrSet`` are not actually bound at runtime.
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

195
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,96 +569,78 @@ 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)
single: __type_params__ (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. | |
+-------------------------+-------------------------------+-----------+
| :attr:`__type_params__` | A tuple containing the | Writable |
| | :ref:`type parameters | |
| | <type-params>` of a | |
| | :ref:`generic function | |
| | <generic-functions>`. | |
+-------------------------+-------------------------------+-----------+
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.
* - .. attribute:: function.__type_params__
- A :class:`tuple` containing the :ref:`type parameters <type-params>` of
a :ref:`generic function <generic-functions>`.
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:
@ -665,15 +672,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
@ -779,6 +788,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
^^^^^^^^^^^^^^^^^^
@ -791,10 +802,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:
@ -844,7 +859,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
@ -1891,7 +1907,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__`.

2
Doc/whatsnew/3.13.rst
View file

@ -483,7 +483,7 @@ Deprecated
(as has always been the case for an executing frame).
(Contributed by Irit Katriel in :gh:`79932`.)
* Assignment to a function's ``__code__`` attribute where the new code
* Assignment to a function's :attr:`~function.__code__` attribute where the new code
object's type does not match the function's type, is deprecated. The
different types are: plain function, generator, async generator and
coroutine.

5
Doc/whatsnew/3.2.rst
View file

@ -791,8 +791,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