From 5e99b56d6b249995a4fa2bc09c0bb03841f49572 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 17 Sep 2018 15:15:03 +0300 Subject: bpo-33216: Improve the documentation for CALL_FUNCTION_* (GH-8338) (GH-8784) --- Doc/library/dis.rst | 60 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 26 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 8f505e6..9564937 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -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 -- cgit v0.12