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