Skip to content

Commit f8e34ee

Browse files
bpo-33216: Improve the documentation for CALL_FUNCTION_* (GH-8338) (GH-8784)
(cherry picked from commit 5e99b56) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
1 parent efdf316 commit f8e34ee

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
@@ -1059,50 +1059,57 @@ All of the following opcodes use their arguments.
10591059

10601060
.. opcode:: RAISE_VARARGS (argc)
10611061

1062-
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.
10651065

10661066

10671067
.. opcode:: CALL_FUNCTION (argc)
10681068

1069-
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.
10741076

10751077
.. versionchanged:: 3.6
10761078
This opcode is used only for calls with positional arguments.
10771079

10781080

10791081
.. opcode:: CALL_FUNCTION_KW (argc)
10801082

1081-
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.
10891092

10901093
.. 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.
10931096

10941097

10951098
.. opcode:: CALL_FUNCTION_EX (flags)
10961099

1097-
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.
11061113

11071114
.. 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
11361143

1137-
* ``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:
12171225

12181226
.. data:: hasconst
12191227

1220-
Sequence of bytecodes that have a constant parameter.
1228+
Sequence of bytecodes that access a constant.
12211229

12221230

12231231
.. data:: hasfree

0 commit comments

Comments
 (0)