Skip to content

Commit 9a13a38

Browse files
jdemeyermiss-islington
authored andcommitted
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
1 parent a12255d commit 9a13a38

File tree

8 files changed

+467
-293
lines changed

8 files changed

+467
-293
lines changed

Doc/c-api/abstract.rst

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
1818
.. toctree::
1919

2020
object.rst
21+
call.rst
2122
number.rst
2223
sequence.rst
2324
mapping.rst

Doc/c-api/call.rst

+411
Large diffs are not rendered by default.

Doc/c-api/exceptions.rst

+4
Original file line numberDiff line numberDiff line change
@@ -697,13 +697,17 @@ The following functions are used to create and modify Unicode exceptions from C.
697697
``0`` on success, ``-1`` on failure.
698698
699699
700+
.. _recursion:
701+
700702
Recursion Control
701703
=================
702704
703705
These two functions provide a way to perform safe recursive calls at the C
704706
level, both in the core and in extension modules. They are needed if the
705707
recursive code does not necessarily invoke Python code (which tracks its
706708
recursion depth automatically).
709+
They are also not needed for *tp_call* implementations
710+
because the :ref:`call protocol <call>` takes care of recursion handling.
707711
708712
.. c:function:: int Py_EnterRecursiveCall(const char *where)
709713

Doc/c-api/object.rst

-240
Original file line numberDiff line numberDiff line change
@@ -248,246 +248,6 @@ Object Protocol
248248
of base classes).
249249
250250
251-
.. c:function:: int PyCallable_Check(PyObject *o)
252-
253-
Determine if the object *o* is callable. Return ``1`` if the object is callable
254-
and ``0`` otherwise. This function always succeeds.
255-
256-
257-
.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable)
258-
259-
Call a callable Python object *callable* without any arguments. It is the
260-
most efficient way to call a callable Python object without any argument.
261-
262-
Return the result of the call on success, or raise an exception and return
263-
``NULL`` on failure.
264-
265-
.. versionadded:: 3.9
266-
267-
268-
.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)
269-
270-
Call a callable Python object *callable* with exactly 1 positional argument
271-
*arg* and no keyword arguments.
272-
273-
Return the result of the call on success, or raise an exception and return
274-
``NULL`` on failure.
275-
276-
.. versionadded:: 3.9
277-
278-
279-
.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
280-
281-
Call a callable Python object *callable*, with arguments given by the
282-
tuple *args*, and named arguments given by the dictionary *kwargs*.
283-
284-
*args* must not be ``NULL``, use an empty tuple if no arguments are needed.
285-
If no named arguments are needed, *kwargs* can be ``NULL``.
286-
287-
Return the result of the call on success, or raise an exception and return
288-
``NULL`` on failure.
289-
290-
This is the equivalent of the Python expression:
291-
``callable(*args, **kwargs)``.
292-
293-
294-
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
295-
296-
Call a callable Python object *callable*, with arguments given by the
297-
tuple *args*. If no arguments are needed, then *args* can be ``NULL``.
298-
299-
Return the result of the call on success, or raise an exception and return
300-
``NULL`` on failure.
301-
302-
This is the equivalent of the Python expression: ``callable(*args)``.
303-
304-
305-
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
306-
307-
Call a callable Python object *callable*, with a variable number of C arguments.
308-
The C arguments are described using a :c:func:`Py_BuildValue` style format
309-
string. The format can be ``NULL``, indicating that no arguments are provided.
310-
311-
Return the result of the call on success, or raise an exception and return
312-
``NULL`` on failure.
313-
314-
This is the equivalent of the Python expression: ``callable(*args)``.
315-
316-
Note that if you only pass :c:type:`PyObject \*` args,
317-
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
318-
319-
.. versionchanged:: 3.4
320-
The type of *format* was changed from ``char *``.
321-
322-
323-
.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
324-
325-
Call the method named *name* of object *obj* with a variable number of C
326-
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
327-
string that should produce a tuple.
328-
329-
The format can be ``NULL``, indicating that no arguments are provided.
330-
331-
Return the result of the call on success, or raise an exception and return
332-
``NULL`` on failure.
333-
334-
This is the equivalent of the Python expression:
335-
``obj.name(arg1, arg2, ...)``.
336-
337-
Note that if you only pass :c:type:`PyObject \*` args,
338-
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
339-
340-
.. versionchanged:: 3.4
341-
The types of *name* and *format* were changed from ``char *``.
342-
343-
344-
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
345-
346-
Call a callable Python object *callable*, with a variable number of
347-
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
348-
of parameters followed by ``NULL``.
349-
350-
Return the result of the call on success, or raise an exception and return
351-
``NULL`` on failure.
352-
353-
This is the equivalent of the Python expression:
354-
``callable(arg1, arg2, ...)``.
355-
356-
357-
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
358-
359-
Calls a method of the Python object *obj*, where the name of the method is given as a
360-
Python string object in *name*. It is called with a variable number of
361-
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
362-
of parameters followed by ``NULL``.
363-
364-
Return the result of the call on success, or raise an exception and return
365-
``NULL`` on failure.
366-
367-
368-
.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
369-
370-
Call a method of the Python object *obj* without arguments,
371-
where the name of the method is given as a Python string object in *name*.
372-
373-
Return the result of the call on success, or raise an exception and return
374-
``NULL`` on failure.
375-
376-
.. versionadded:: 3.9
377-
378-
379-
.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
380-
381-
Call a method of the Python object *obj* with a single positional argument
382-
*arg*, where the name of the method is given as a Python string object in
383-
*name*.
384-
385-
Return the result of the call on success, or raise an exception and return
386-
``NULL`` on failure.
387-
388-
.. versionadded:: 3.9
389-
390-
391-
.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
392-
393-
Call a callable Python object *callable*, using
394-
:c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>` if possible.
395-
396-
*args* is a C array with the positional arguments.
397-
398-
*nargsf* is the number of positional arguments plus optionally the flag
399-
:const:`PY_VECTORCALL_ARGUMENTS_OFFSET` (see below).
400-
To get actual number of arguments, use
401-
:c:func:`PyVectorcall_NARGS(nargsf) <PyVectorcall_NARGS>`.
402-
403-
*kwnames* can be either ``NULL`` (no keyword arguments) or a tuple of keyword
404-
names, which must be strings. In the latter case, the values of the keyword
405-
arguments are stored in *args* after the positional arguments.
406-
The number of keyword arguments does not influence *nargsf*.
407-
408-
*kwnames* must contain only objects of type ``str`` (not a subclass),
409-
and all keys must be unique.
410-
411-
Return the result of the call on success, or raise an exception and return
412-
``NULL`` on failure.
413-
414-
This uses the vectorcall protocol if the callable supports it;
415-
otherwise, the arguments are converted to use
416-
:c:member:`~PyTypeObject.tp_call`.
417-
418-
.. note::
419-
420-
This function is provisional and expected to become public in Python 3.9,
421-
with a different name and, possibly, changed semantics.
422-
If you use the function, plan for updating your code for Python 3.9.
423-
424-
.. versionadded:: 3.8
425-
426-
.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
427-
428-
If set in a vectorcall *nargsf* argument, the callee is allowed to
429-
temporarily change ``args[-1]``. In other words, *args* points to
430-
argument 1 (not 0) in the allocated vector.
431-
The callee must restore the value of ``args[-1]`` before returning.
432-
433-
For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that
434-
``args[0]`` may be changed.
435-
436-
Whenever they can do so cheaply (without additional allocation), callers
437-
are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
438-
Doing so will allow callables such as bound methods to make their onward
439-
calls (which include a prepended *self* argument) cheaply.
440-
441-
.. versionadded:: 3.8
442-
443-
.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
444-
445-
Given a vectorcall *nargsf* argument, return the actual number of
446-
arguments.
447-
Currently equivalent to ``nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET``.
448-
449-
.. versionadded:: 3.8
450-
451-
.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
452-
453-
Same as :c:func:`_PyObject_Vectorcall` except that the keyword arguments
454-
are passed as a dictionary in *kwdict*. This may be ``NULL`` if there
455-
are no keyword arguments.
456-
457-
For callables supporting :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>`,
458-
the arguments are internally converted to the vectorcall convention.
459-
Therefore, this function adds some overhead compared to
460-
:c:func:`_PyObject_Vectorcall`.
461-
It should only be used if the caller already has a dictionary ready to use.
462-
463-
.. note::
464-
465-
This function is provisional and expected to become public in Python 3.9,
466-
with a different name and, possibly, changed semantics.
467-
If you use the function, plan for updating your code for Python 3.9.
468-
469-
.. versionadded:: 3.8
470-
471-
.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
472-
473-
Call a method using the vectorcall calling convention. The name of the method
474-
is given as Python string *name*. The object whose method is called is
475-
*args[0]* and the *args* array starting at *args[1]* represents the arguments
476-
of the call. There must be at least one positional argument.
477-
*nargsf* is the number of positional arguments including *args[0]*,
478-
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
479-
temporarily be changed. Keyword arguments can be passed just like in
480-
:c:func:`_PyObject_Vectorcall`.
481-
482-
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
483-
this will actually call the unbound method object with the full
484-
*args* vector as arguments.
485-
486-
Return the result of the call on success, or raise an exception and return
487-
``NULL`` on failure.
488-
489-
.. versionadded:: 3.9
490-
491251
.. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
492252
493253
.. index:: builtin: hash

Doc/c-api/structures.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,8 @@ also keyword arguments. So there are a total of 6 calling conventions:
208208

209209
Extension of :const:`METH_FASTCALL` supporting also keyword arguments,
210210
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
211-
Keyword arguments are passed the same way as in the vectorcall protocol:
211+
Keyword arguments are passed the same way as in the
212+
:ref:`vectorcall protocol <vectorcall>`:
212213
there is an additional fourth :c:type:`PyObject\*` parameter
213214
which is a tuple representing the names of the keyword arguments
214215
(which are guaranteed to be strings)

Doc/c-api/type.rst

+1
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,7 @@ The following functions and structs are used to create
193193
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
194194
* :c:member:`~PyTypeObject.tp_dictoffset`
195195
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
196+
* :c:member:`~PyTypeObject.tp_vectorcall_offset`
196197
* :c:member:`~PyBufferProcs.bf_getbuffer`
197198
* :c:member:`~PyBufferProcs.bf_releasebuffer`
198199

0 commit comments

Comments
 (0)