From 4d2ca5a385c66bd9a4926028201eddcafa49b435 Mon Sep 17 00:00:00 2001 From: larryhastings Date: Thu, 19 Jul 2018 16:35:28 -0700 Subject: [PATCH 1/2] [2.7] bpo-33216: Clarify the documentation for CALL_FUNCTION_* (GH-8338) (cherry picked from commit 76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9) Co-authored-by: larryhastings --- Doc/library/dis.rst | 79 ++++++++++++++----- .../2018-07-19-00-02-23.bpo-33216.YrBgBe.rst | 2 + 2 files changed, 61 insertions(+), 20 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 04b9b15386336e..101dfbe3bc1d70 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -107,7 +107,7 @@ The :mod:`dis` module defines the following functions and constants: .. data:: hasconst - Sequence of bytecodes that have a constant parameter. + Sequence of bytecodes that access a constant. .. data:: hasfree @@ -796,21 +796,25 @@ the more significant byte last. .. 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. The low byte of *argc* indicates the number of positional - parameters, the high byte the number of keyword parameters. On the stack, the - opcode finds the keyword parameters first. For each keyword argument, the - value is on top of the key. Below the keyword parameters, the positional - parameters are on the stack, with the right-most parameter on top. Below the - parameters, 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. The low byte of *argc* indicates the number of + positional arguments, the high byte the number of keyword arguments. + The stack contains keyword arguments on top (if any), then the positional + arguments below that (if any), then the callable object to call below that. + Each keyword argument is represented with two values on the stack: + the argument's name, and its value, with the argument's value above the + name on the stack. + The positional arguments are pushed in the order that they are passed in + to the callable object, with the right-most positional argument on top. + ``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. .. opcode:: MAKE_FUNCTION (argc) @@ -847,24 +851,59 @@ the more significant byte last. .. opcode:: CALL_FUNCTION_VAR (argc) - Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The - top element on the stack contains the variable argument list, followed by - keyword and positional arguments. + Calls a callable object, similarly to :opcode:`CALL_FUNCTION`. + *argc* represents the number of keyword and positional + arguments, identically to :opcode:`CALL_FUNCTION`. + The top of the stack contains an iterable object containing + additional positional arguments. + Below that are keyword arguments (if any), positional arguments (if any) + and a callable object, identically to :opcode:`CALL_FUNCTION`. + Before the callable object is called, the iterable object + is "unpacked" and its contents are appended to the positional + arguments passed in. + The iterable object is ignored when computing + the value of ``argc``. + + .. versionchanged:: 3.5 + In versions 3.0 to 3.4, the iterable object was above + the keyword arguments; in 3.5 the iterable object was moved + below the keyword arguments. + .. opcode:: CALL_FUNCTION_KW (argc) - Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The - top element on the stack contains the keyword arguments dictionary, followed - by explicit keyword and positional arguments. + Calls a callable object, similarly to :opcode:`CALL_FUNCTION`. + *argc* represents the number of keyword and positional + arguments, identically to :opcode:`CALL_FUNCTION`. + The top of the stack contains a mapping object containing additional keyword + arguments. + Below that are keyword arguments (if any), positional arguments (if any) + and a callable object, identically to :opcode:`CALL_FUNCTION`. + Before the callable is called, the mapping object at the top of the stack is + "unpacked" and its contents are appended to the keyword arguments passed in. + The mapping object at the top of the stack is ignored when computing + the value of ``argc``. .. opcode:: CALL_FUNCTION_VAR_KW (argc) - Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The - top element on the stack contains the keyword arguments dictionary, followed - by the variable-arguments tuple, followed by explicit keyword and positional - arguments. + Calls a callable object, similarly to :opcode:`CALL_FUNCTION_VAR` and + :opcode:`CALL_FUNCTION_KW`. + *argc* represents the number of keyword and positional + arguments, identically to :opcode:`CALL_FUNCTION`. + The top of the stack contains a mapping object, as per + :opcode:`CALL_FUNCTION_KW`. + Below that + is an iterable object containing additional positional arguments. + Below that are keyword arguments (if any), positional arguments (if any) + and a callable object, identically to :opcode:`CALL_FUNCTION`. + 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, + identically to :opcode:`CALL_FUNCTION_VAR` and :opcode:`CALL_FUNCTION_KW`. + The mapping object and iterable object are both ignored when computing + the value of ``argc``. .. opcode:: HAVE_ARGUMENT () diff --git a/Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst b/Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst new file mode 100644 index 00000000000000..566891584017d6 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst @@ -0,0 +1,2 @@ +Clarify the documentation for CALL_FUNCTION_VAR, CALL_FUNCTION_KW, and +CALL_FUNCTION_VAR_KW. From 3e6ac54bdf0ea2672f58db3371dc210605a5d6fe Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 16 Aug 2018 21:15:26 +0300 Subject: [PATCH 2/2] Remove the versionchanged note and the news entry. --- Doc/library/dis.rst | 10 ++-------- .../2018-07-19-00-02-23.bpo-33216.YrBgBe.rst | 2 -- 2 files changed, 2 insertions(+), 10 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 101dfbe3bc1d70..e773ab8090fc1c 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -864,12 +864,6 @@ the more significant byte last. The iterable object is ignored when computing the value of ``argc``. - .. versionchanged:: 3.5 - In versions 3.0 to 3.4, the iterable object was above - the keyword arguments; in 3.5 the iterable object was moved - below the keyword arguments. - - .. opcode:: CALL_FUNCTION_KW (argc) @@ -894,8 +888,8 @@ the more significant byte last. arguments, identically to :opcode:`CALL_FUNCTION`. The top of the stack contains a mapping object, as per :opcode:`CALL_FUNCTION_KW`. - Below that - is an iterable object containing additional positional arguments. + Below that is an iterable object, as per + :opcode:`CALL_FUNCTION_VAR`. Below that are keyword arguments (if any), positional arguments (if any) and a callable object, identically to :opcode:`CALL_FUNCTION`. Before the callable is called, the mapping object and iterable object diff --git a/Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst b/Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst deleted file mode 100644 index 566891584017d6..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst +++ /dev/null @@ -1,2 +0,0 @@ -Clarify the documentation for CALL_FUNCTION_VAR, CALL_FUNCTION_KW, and -CALL_FUNCTION_VAR_KW.