Skip to content

Commit 5e99b56

Browse files
bpo-33216: Improve the documentation for CALL_FUNCTION_* (GH-8338) (GH-8784)
1 parent b3a271f commit 5e99b56

File tree

1 file changed

+34
-26
lines changed

1 file changed

+34
-26
lines changed

Doc/library/dis.rst

Lines changed: 34 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1104,50 +1104,57 @@ All of the following opcodes use their arguments.
11041104

11051105
.. opcode:: RAISE_VARARGS (argc)
11061106

1107-
Raises an exception. *argc* indicates the number of parameters to the raise
1107+
Raises an exception. *argc* indicates the number of arguments to the raise
11081108
statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
11091109
the parameter as TOS1, and the exception as TOS.
11101110

11111111

11121112
.. opcode:: CALL_FUNCTION (argc)
11131113

1114-
Calls a function. *argc* indicates the number of positional arguments.
1115-
The positional arguments are on the stack, with the right-most argument
1116-
on top. Below the arguments, the function object to call is on the stack.
1117-
Pops all function arguments, and the function itself off the stack, and
1118-
pushes the return value.
1114+
Calls a callable object with positional arguments.
1115+
*argc* indicates the number of positional arguments.
1116+
The top of the stack contains positional arguments, with the right-most
1117+
argument on top. Below the arguments is a callable object to call.
1118+
``CALL_FUNCTION`` pops all arguments and the callable object off the stack,
1119+
calls the callable object with those arguments, and pushes the return value
1120+
returned by the callable object.
11191121

11201122
.. versionchanged:: 3.6
11211123
This opcode is used only for calls with positional arguments.
11221124

11231125

11241126
.. opcode:: CALL_FUNCTION_KW (argc)
11251127

1126-
Calls a function. *argc* indicates the number of arguments (positional
1127-
and keyword). The top element on the stack contains a tuple of keyword
1128-
argument names. Below the tuple, keyword arguments are on the stack, in
1129-
the order corresponding to the tuple. Below the keyword arguments, the
1130-
positional arguments are on the stack, with the right-most parameter on
1131-
top. Below the arguments, the function object to call is on the stack.
1132-
Pops all function arguments, and the function itself off the stack, and
1133-
pushes the return value.
1128+
Calls a callable object with positional (if any) and keyword arguments.
1129+
*argc* indicates the total number of positional and keyword arguments.
1130+
The top element on the stack contains a tuple of keyword argument names.
1131+
Below that are keyword arguments in the order corresponding to the tuple.
1132+
Below that are positional arguments, with the right-most parameter on
1133+
top. Below the arguments is a callable object to call.
1134+
``CALL_FUNCTION_KW`` pops all arguments and the callable object off the stack,
1135+
calls the callable object with those arguments, and pushes the return value
1136+
returned by the callable object.
11341137

11351138
.. versionchanged:: 3.6
11361139
Keyword arguments are packed in a tuple instead of a dictionary,
1137-
*argc* indicates the total number of arguments
1140+
*argc* indicates the total number of arguments.
11381141

11391142

11401143
.. opcode:: CALL_FUNCTION_EX (flags)
11411144

1142-
Calls a function. The lowest bit of *flags* indicates whether the
1143-
var-keyword argument is placed at the top of the stack. Below the
1144-
var-keyword argument, the var-positional argument is on the stack.
1145-
Below the arguments, the function object to call is placed.
1146-
Pops all function arguments, and the function itself off the stack, and
1147-
pushes the return value. Note that this opcode pops at most three items
1148-
from the stack. Var-positional and var-keyword arguments are packed
1149-
by :opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` and
1150-
:opcode:`BUILD_MAP_UNPACK_WITH_CALL`.
1145+
Calls a callable object with variable set of positional and keyword
1146+
arguments. If the lowest bit of *flags* is set, the top of the stack
1147+
contains a mapping object containing additional keyword arguments.
1148+
Below that is an iterable object containing positional arguments and
1149+
a callable object to call. :opcode:`BUILD_MAP_UNPACK_WITH_CALL` and
1150+
:opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` can be used for merging multiple
1151+
mapping objects and iterables containing arguments.
1152+
Before the callable is called, the mapping object and iterable object
1153+
are each "unpacked" and their contents passed in as keyword and
1154+
positional arguments respectively.
1155+
``CALL_FUNCTION_EX`` pops all arguments and the callable object off the stack,
1156+
calls the callable object with those arguments, and pushes the return value
1157+
returned by the callable object.
11511158

11521159
.. versionadded:: 3.6
11531160

@@ -1179,7 +1186,8 @@ All of the following opcodes use their arguments.
11791186
Pushes a new function object on the stack. From bottom to top, the consumed
11801187
stack must consist of values if the argument carries a specified flag value
11811188

1182-
* ``0x01`` a tuple of default argument objects in positional order
1189+
* ``0x01`` a tuple of default values for positional-only and
1190+
positional-or-keyword parameters in positional order
11831191
* ``0x02`` a dictionary of keyword-only parameters' default values
11841192
* ``0x04`` an annotation dictionary
11851193
* ``0x08`` a tuple containing cells for free variables, making a closure
@@ -1262,7 +1270,7 @@ instructions:
12621270

12631271
.. data:: hasconst
12641272

1265-
Sequence of bytecodes that have a constant parameter.
1273+
Sequence of bytecodes that access a constant.
12661274

12671275

12681276
.. data:: hasfree

0 commit comments

Comments
 (0)