bpo-33216: Improve the documentation for CALL_FUNCTION_* (GH-8338) (G… · python/cpython@f8e34ee

@@ -1059,50 +1059,57 @@ All of the following opcodes use their arguments.

1059105910601060

.. opcode:: RAISE_VARARGS (argc)

106110611062-

Raises an exception. *argc* indicates the number of parameters to the raise

1062+

Raises an exception. *argc* indicates the number of arguments to the raise

10631063

statement, ranging from 0 to 3. The handler will find the traceback as TOS2,

10641064

the parameter as TOS1, and the exception as TOS.

106510651066106610671067

.. opcode:: CALL_FUNCTION (argc)

106810681069-

Calls a function. *argc* indicates the number of positional arguments.

1070-

The positional arguments are on the stack, with the right-most argument

1071-

on top. Below the arguments, the function object to call is on the stack.

1072-

Pops all function arguments, and the function itself off the stack, and

1073-

pushes the return value.

1069+

Calls a callable object with positional arguments.

1070+

*argc* indicates the number of positional arguments.

1071+

The top of the stack contains positional arguments, with the right-most

1072+

argument on top. Below the arguments is a callable object to call.

1073+

``CALL_FUNCTION`` pops all arguments and the callable object off the stack,

1074+

calls the callable object with those arguments, and pushes the return value

1075+

returned by the callable object.

1074107610751077

.. versionchanged:: 3.6

10761078

This opcode is used only for calls with positional arguments.

107710791078108010791081

.. opcode:: CALL_FUNCTION_KW (argc)

108010821081-

Calls a function. *argc* indicates the number of arguments (positional

1082-

and keyword). The top element on the stack contains a tuple of keyword

1083-

argument names. Below the tuple, keyword arguments are on the stack, in

1084-

the order corresponding to the tuple. Below the keyword arguments, the

1085-

positional arguments are on the stack, with the right-most parameter on

1086-

top. Below the arguments, the function object to call is on the stack.

1087-

Pops all function arguments, and the function itself off the stack, and

1088-

pushes the return value.

1083+

Calls a callable object with positional (if any) and keyword arguments.

1084+

*argc* indicates the total number of positional and keyword arguments.

1085+

The top element on the stack contains a tuple of keyword argument names.

1086+

Below that are keyword arguments in the order corresponding to the tuple.

1087+

Below that are positional arguments, with the right-most parameter on

1088+

top. Below the arguments is a callable object to call.

1089+

``CALL_FUNCTION_KW`` pops all arguments and the callable object off the stack,

1090+

calls the callable object with those arguments, and pushes the return value

1091+

returned by the callable object.

1089109210901093

.. versionchanged:: 3.6

10911094

Keyword arguments are packed in a tuple instead of a dictionary,

1092-

*argc* indicates the total number of arguments

1095+

*argc* indicates the total number of arguments.

109310961094109710951098

.. opcode:: CALL_FUNCTION_EX (flags)

109610991097-

Calls a function. The lowest bit of *flags* indicates whether the

1098-

var-keyword argument is placed at the top of the stack. Below the

1099-

var-keyword argument, the var-positional argument is on the stack.

1100-

Below the arguments, the function object to call is placed.

1101-

Pops all function arguments, and the function itself off the stack, and

1102-

pushes the return value. Note that this opcode pops at most three items

1103-

from the stack. Var-positional and var-keyword arguments are packed

1104-

by :opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` and

1105-

:opcode:`BUILD_MAP_UNPACK_WITH_CALL`.

1100+

Calls a callable object with variable set of positional and keyword

1101+

arguments. If the lowest bit of *flags* is set, the top of the stack

1102+

contains a mapping object containing additional keyword arguments.

1103+

Below that is an iterable object containing positional arguments and

1104+

a callable object to call. :opcode:`BUILD_MAP_UNPACK_WITH_CALL` and

1105+

:opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` can be used for merging multiple

1106+

mapping objects and iterables containing arguments.

1107+

Before the callable is called, the mapping object and iterable object

1108+

are each "unpacked" and their contents passed in as keyword and

1109+

positional arguments respectively.

1110+

``CALL_FUNCTION_EX`` pops all arguments and the callable object off the stack,

1111+

calls the callable object with those arguments, and pushes the return value

1112+

returned by the callable object.

1106111311071114

.. versionadded:: 3.6

11081115

@@ -1134,7 +1141,8 @@ All of the following opcodes use their arguments.

11341141

Pushes a new function object on the stack. From bottom to top, the consumed

11351142

stack must consist of values if the argument carries a specified flag value

113611431137-

* ``0x01`` a tuple of default argument objects in positional order

1144+

* ``0x01`` a tuple of default values for positional-only and

1145+

positional-or-keyword parameters in positional order

11381146

* ``0x02`` a dictionary of keyword-only parameters' default values

11391147

* ``0x04`` an annotation dictionary

11401148

* ``0x08`` a tuple containing cells for free variables, making a closure

@@ -1217,7 +1225,7 @@ instructions:

1217122512181226

.. data:: hasconst

121912271220-

Sequence of bytecodes that have a constant parameter.

1228+

Sequence of bytecodes that access a constant.

122112291222123012231231

.. data:: hasfree