mirror of
https://github.com/python/cpython.git
synced 2025-07-24 11:44:31 +00:00
bpo-36974: expand call protocol documentation (GH-13844)
CC @encukou I'm also adding Petr Viktorin as contributor for vectorcall in the "what's new" section. https://bugs.python.org/issue36974 Automerge-Triggered-By: @encukou Automerge-Triggered-By: @encukou
This commit is contained in:
Jeroen Demeyer
Miss Islington (bot)
parent
a12255d8de
commit
9a13a388f2
8 changed files with 467 additions and 293 deletions
|
|
@ -248,246 +248,6 @@ Object Protocol
|
|||
of base classes).
|
||||
|
||||
|
||||
.. c:function:: int PyCallable_Check(PyObject *o)
|
||||
|
||||
Determine if the object *o* is callable. Return ``1`` if the object is callable
|
||||
and ``0`` otherwise. This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable)
|
||||
|
||||
Call a callable Python object *callable* without any arguments. It is the
|
||||
most efficient way to call a callable Python object without any argument.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
|
||||
.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)
|
||||
|
||||
Call a callable Python object *callable* with exactly 1 positional argument
|
||||
*arg* and no keyword arguments.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
|
||||
|
||||
Call a callable Python object *callable*, with arguments given by the
|
||||
tuple *args*, and named arguments given by the dictionary *kwargs*.
|
||||
|
||||
*args* must not be ``NULL``, use an empty tuple if no arguments are needed.
|
||||
If no named arguments are needed, *kwargs* can be ``NULL``.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
This is the equivalent of the Python expression:
|
||||
``callable(*args, **kwargs)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
|
||||
|
||||
Call a callable Python object *callable*, with arguments given by the
|
||||
tuple *args*. If no arguments are needed, then *args* can be ``NULL``.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
This is the equivalent of the Python expression: ``callable(*args)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
|
||||
|
||||
Call a callable Python object *callable*, with a variable number of C arguments.
|
||||
The C arguments are described using a :c:func:`Py_BuildValue` style format
|
||||
string. The format can be ``NULL``, indicating that no arguments are provided.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
This is the equivalent of the Python expression: ``callable(*args)``.
|
||||
|
||||
Note that if you only pass :c:type:`PyObject \*` args,
|
||||
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The type of *format* was changed from ``char *``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
|
||||
|
||||
Call the method named *name* of object *obj* with a variable number of C
|
||||
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
|
||||
string that should produce a tuple.
|
||||
|
||||
The format can be ``NULL``, indicating that no arguments are provided.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
This is the equivalent of the Python expression:
|
||||
``obj.name(arg1, arg2, ...)``.
|
||||
|
||||
Note that if you only pass :c:type:`PyObject \*` args,
|
||||
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The types of *name* and *format* were changed from ``char *``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
|
||||
|
||||
Call a callable Python object *callable*, with a variable number of
|
||||
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
|
||||
of parameters followed by ``NULL``.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
This is the equivalent of the Python expression:
|
||||
``callable(arg1, arg2, ...)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
|
||||
|
||||
Calls a method of the Python object *obj*, where the name of the method is given as a
|
||||
Python string object in *name*. It is called with a variable number of
|
||||
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
|
||||
of parameters followed by ``NULL``.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
|
||||
|
||||
Call a method of the Python object *obj* without arguments,
|
||||
where the name of the method is given as a Python string object in *name*.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
|
||||
.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
|
||||
|
||||
Call a method of the Python object *obj* with a single positional argument
|
||||
*arg*, where the name of the method is given as a Python string object in
|
||||
*name*.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
|
||||
.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
|
||||
|
||||
Call a callable Python object *callable*, using
|
||||
:c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>` if possible.
|
||||
|
||||
*args* is a C array with the positional arguments.
|
||||
|
||||
*nargsf* is the number of positional arguments plus optionally the flag
|
||||
:const:`PY_VECTORCALL_ARGUMENTS_OFFSET` (see below).
|
||||
To get actual number of arguments, use
|
||||
:c:func:`PyVectorcall_NARGS(nargsf) <PyVectorcall_NARGS>`.
|
||||
|
||||
*kwnames* can be either ``NULL`` (no keyword arguments) or a tuple of keyword
|
||||
names, which must be strings. In the latter case, the values of the keyword
|
||||
arguments are stored in *args* after the positional arguments.
|
||||
The number of keyword arguments does not influence *nargsf*.
|
||||
|
||||
*kwnames* must contain only objects of type ``str`` (not a subclass),
|
||||
and all keys must be unique.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
This uses the vectorcall protocol if the callable supports it;
|
||||
otherwise, the arguments are converted to use
|
||||
:c:member:`~PyTypeObject.tp_call`.
|
||||
|
||||
.. note::
|
||||
|
||||
This function is provisional and expected to become public in Python 3.9,
|
||||
with a different name and, possibly, changed semantics.
|
||||
If you use the function, plan for updating your code for Python 3.9.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
|
||||
|
||||
If set in a vectorcall *nargsf* argument, the callee is allowed to
|
||||
temporarily change ``args[-1]``. In other words, *args* points to
|
||||
argument 1 (not 0) in the allocated vector.
|
||||
The callee must restore the value of ``args[-1]`` before returning.
|
||||
|
||||
For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that
|
||||
``args[0]`` may be changed.
|
||||
|
||||
Whenever they can do so cheaply (without additional allocation), callers
|
||||
are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
|
||||
Doing so will allow callables such as bound methods to make their onward
|
||||
calls (which include a prepended *self* argument) cheaply.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
|
||||
|
||||
Given a vectorcall *nargsf* argument, return the actual number of
|
||||
arguments.
|
||||
Currently equivalent to ``nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET``.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
|
||||
|
||||
Same as :c:func:`_PyObject_Vectorcall` except that the keyword arguments
|
||||
are passed as a dictionary in *kwdict*. This may be ``NULL`` if there
|
||||
are no keyword arguments.
|
||||
|
||||
For callables supporting :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>`,
|
||||
the arguments are internally converted to the vectorcall convention.
|
||||
Therefore, this function adds some overhead compared to
|
||||
:c:func:`_PyObject_Vectorcall`.
|
||||
It should only be used if the caller already has a dictionary ready to use.
|
||||
|
||||
.. note::
|
||||
|
||||
This function is provisional and expected to become public in Python 3.9,
|
||||
with a different name and, possibly, changed semantics.
|
||||
If you use the function, plan for updating your code for Python 3.9.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
|
||||
|
||||
Call a method using the vectorcall calling convention. The name of the method
|
||||
is given as Python string *name*. The object whose method is called is
|
||||
*args[0]* and the *args* array starting at *args[1]* represents the arguments
|
||||
of the call. There must be at least one positional argument.
|
||||
*nargsf* is the number of positional arguments including *args[0]*,
|
||||
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
|
||||
temporarily be changed. Keyword arguments can be passed just like in
|
||||
:c:func:`_PyObject_Vectorcall`.
|
||||
|
||||
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
|
||||
this will actually call the unbound method object with the full
|
||||
*args* vector as arguments.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
``NULL`` on failure.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
|
||||
|
||||
.. index:: builtin: hash
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue