bpo-33216: Improve the documentation for CALL_FUNCTION_* (GH-8338) (GH-8784)

This commit is contained in:
Serhiy Storchaka 2018-09-17 15:15:03 +03:00 committed by GitHub
parent b3a271fc0c
commit 5e99b56d6b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 26 deletions

View File

@ -1104,18 +1104,20 @@ All of the following opcodes use their arguments.
.. opcode:: RAISE_VARARGS (argc)
Raises an exception. *argc* indicates the number of parameters to the raise
Raises an exception. *argc* indicates the number of arguments to the raise
statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
the parameter as TOS1, and the exception as TOS.
.. opcode:: CALL_FUNCTION (argc)
Calls a function. *argc* indicates the number of positional arguments.
The positional arguments are on the stack, with the right-most argument
on top. Below the arguments, the function object to call is on the stack.
Pops all function arguments, and the function itself off the stack, and
pushes the return value.
Calls a callable object with positional arguments.
*argc* indicates the number of positional arguments.
The top of the stack contains positional arguments, with the right-most
argument on top. Below the arguments is a callable object to call.
``CALL_FUNCTION`` pops all arguments and the callable object off the stack,
calls the callable object with those arguments, and pushes the return value
returned by the callable object.
.. versionchanged:: 3.6
This opcode is used only for calls with positional arguments.
@ -1123,31 +1125,36 @@ All of the following opcodes use their arguments.
.. opcode:: CALL_FUNCTION_KW (argc)
Calls a function. *argc* indicates the number of arguments (positional
and keyword). The top element on the stack contains a tuple of keyword
argument names. Below the tuple, keyword arguments are on the stack, in
the order corresponding to the tuple. Below the keyword arguments, the
positional arguments are on the stack, with the right-most parameter on
top. Below the arguments, the function object to call is on the stack.
Pops all function arguments, and the function itself off the stack, and
pushes the return value.
Calls a callable object with positional (if any) and keyword arguments.
*argc* indicates the total number of positional and keyword arguments.
The top element on the stack contains a tuple of keyword argument names.
Below that are keyword arguments in the order corresponding to the tuple.
Below that are positional arguments, with the right-most parameter on
top. Below the arguments is a callable object to call.
``CALL_FUNCTION_KW`` pops all arguments and the callable object off the stack,
calls the callable object with those arguments, and pushes the return value
returned by the callable object.
.. versionchanged:: 3.6
Keyword arguments are packed in a tuple instead of a dictionary,
*argc* indicates the total number of arguments
*argc* indicates the total number of arguments.
.. opcode:: CALL_FUNCTION_EX (flags)
Calls a function. The lowest bit of *flags* indicates whether the
var-keyword argument is placed at the top of the stack. Below the
var-keyword argument, the var-positional argument is on the stack.
Below the arguments, the function object to call is placed.
Pops all function arguments, and the function itself off the stack, and
pushes the return value. Note that this opcode pops at most three items
from the stack. Var-positional and var-keyword arguments are packed
by :opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` and
:opcode:`BUILD_MAP_UNPACK_WITH_CALL`.
Calls a callable object with variable set of positional and keyword
arguments. If the lowest bit of *flags* is set, the top of the stack
contains a mapping object containing additional keyword arguments.
Below that is an iterable object containing positional arguments and
a callable object to call. :opcode:`BUILD_MAP_UNPACK_WITH_CALL` and
:opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` can be used for merging multiple
mapping objects and iterables containing arguments.
Before the callable is called, the mapping object and iterable object
are each "unpacked" and their contents passed in as keyword and
positional arguments respectively.
``CALL_FUNCTION_EX`` pops all arguments and the callable object off the stack,
calls the callable object with those arguments, and pushes the return value
returned by the callable object.
.. versionadded:: 3.6
@ -1179,7 +1186,8 @@ All of the following opcodes use their arguments.
Pushes a new function object on the stack. From bottom to top, the consumed
stack must consist of values if the argument carries a specified flag value
* ``0x01`` a tuple of default argument objects in positional order
* ``0x01`` a tuple of default values for positional-only and
positional-or-keyword parameters in positional order
* ``0x02`` a dictionary of keyword-only parameters' default values
* ``0x04`` an annotation dictionary
* ``0x08`` a tuple containing cells for free variables, making a closure
@ -1262,7 +1270,7 @@ instructions:
.. data:: hasconst
Sequence of bytecodes that have a constant parameter.
Sequence of bytecodes that access a constant.
.. data:: hasfree