From 2c9b6f84b6d07985b3dd6595d55dcc34b628571d Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Thu, 19 Jul 2018 00:02:29 -0700 Subject: [PATCH 1/5] Clarify the documentation for CALL_FUNCTION_*. --- Doc/library/dis.rst | 72 +++++++++++++------ .../2018-07-19-00-02-23.bpo-33216.YrBgBe.rst | 2 + 2 files changed, 53 insertions(+), 21 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 186aab40f636f9..bf9abd706cd3dd 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -960,7 +960,7 @@ 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. @@ -968,13 +968,15 @@ the more significant byte last. .. 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. + 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 function to call below that. + Each keyword argument is represented with two values on the stack, the argument's + name and its value, with the value above the name on the stack. The positional + arguments are pushed in the order that they are passed in to the function, + with the right-most positional argument on top. ``CALL_FUNCTION`` + pops all arguments and the function off the stack, calls the function with those + arguments, and pushes the function's return value. .. opcode:: MAKE_FUNCTION (argc) @@ -982,12 +984,12 @@ the more significant byte last. Pushes a new function object on the stack. From bottom to top, the consumed stack must consist of - * ``argc & 0xFF`` default argument objects in positional order + * ``argc & 0xFF`` default argument objects in positional order, for positional parameters * ``(argc >> 8) & 0xFF`` pairs of name and default argument, with the name just below the object on the stack, for keyword-only parameters * ``(argc >> 16) & 0x7FFF`` parameter annotation objects * a tuple listing the parameter names for the annotations (only if there are - ony annotation objects) + any annotation objects) * the code associated with the function (at TOS1) * the :term:`qualified name` of the function (at TOS) @@ -1020,24 +1022,52 @@ 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 function, 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 this are keyword arguments (if any), positional arguments (if any), + and function to call, identically to :opcode:`CALL_FUNCTION`. + When the function is called, the iterable object at the top of the stack is + "unpacked" and its contents are appended to the positional arguments passed + in to the function. + The iterable object at the top of the stack is ignored when computing + the value of ``argc``. .. 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 function, 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 this are keyword arguments (if any), positional arguments (if any), + and function to call, identically to :opcode:`CALL_FUNCTION`. + When the function is called, the mapping object at the top of the stack is + "unpacked" and its contents are appended to the keyword arguments passed in + to the function. + 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 function, 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, as per :opcode:`CALL_FUNCTION_VAR`. + Below this are keyword arguments (if any), positional arguments (if any), + and function to call, identically to :opcode:`CALL_FUNCTION`. + When the function is called, the mapping object and iterable object on the + stack are "unpacked" and passed in to the function, identically to + :opcode:`CALL_FUNCTION_VAR` and :opcode:`CALL_FUNCTION_KW`. + The mapping object and iterable object at the top of the stack + are both ignored when computing the value of ``argc``. .. opcode:: HAVE_ARGUMENT @@ -1071,7 +1101,7 @@ instructions: .. data:: hasconst - Sequence of bytecodes that have a constant parameter. + Sequence of bytecodes that have a constant argument. .. data:: hasfree 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 f87d0afd5341321960528e8fda017507b7d1a4c0 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Thu, 19 Jul 2018 00:26:41 -0700 Subject: [PATCH 2/5] Minor touch-ups to the documentation clarification --- Doc/library/dis.rst | 52 +++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index bf9abd706cd3dd..64e9122af265c6 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -967,16 +967,18 @@ the more significant byte last. .. opcode:: CALL_FUNCTION (argc) - Calls a function. 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 function to call below that. - Each keyword argument is represented with two values on the stack, the argument's - name and its value, with the value above the name on the stack. The positional - arguments are pushed in the order that they are passed in to the function, - with the right-most positional argument on top. ``CALL_FUNCTION`` - pops all arguments and the function off the stack, calls the function with those - arguments, and pushes the function's 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) @@ -1022,39 +1024,38 @@ the more significant byte last. .. opcode:: CALL_FUNCTION_VAR (argc) - Calls a function, similarly to :opcode:`CALL_FUNCTION`. + 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 this are keyword arguments (if any), positional arguments (if any), - and function to call, identically to :opcode:`CALL_FUNCTION`. - When the function is called, the iterable object at the top of the stack is - "unpacked" and its contents are appended to the positional arguments passed - in to the function. + and a callable object, identically to :opcode:`CALL_FUNCTION`. + Before the callable object is called, the iterable object at the top of the stack + is "unpacked" and its contents are appended to the positional arguments passed + in. The iterable object at the top of the stack is ignored when computing the value of ``argc``. .. opcode:: CALL_FUNCTION_KW (argc) - Calls a function, similarly to :opcode:`CALL_FUNCTION`. + 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 this are keyword arguments (if any), positional arguments (if any), - and function to call, identically to :opcode:`CALL_FUNCTION`. - When the function is called, the mapping object at the top of the stack is - "unpacked" and its contents are appended to the keyword arguments passed in - to the function. + 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, similarly to :opcode:`CALL_FUNCTION_VAR` and + 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`. @@ -1062,10 +1063,11 @@ the more significant byte last. :opcode:`CALL_FUNCTION_KW`. Below that is an iterable object, as per :opcode:`CALL_FUNCTION_VAR`. Below this are keyword arguments (if any), positional arguments (if any), - and function to call, identically to :opcode:`CALL_FUNCTION`. - When the function is called, the mapping object and iterable object on the - stack are "unpacked" and passed in to the function, identically to - :opcode:`CALL_FUNCTION_VAR` and :opcode:`CALL_FUNCTION_KW`. + and a callable object, identically to :opcode:`CALL_FUNCTION`. + Before the callable is called, the mapping object and iterable object on the + stack 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 at the top of the stack are both ignored when computing the value of ``argc``. From e2a99cd32c8a5dc200b4004ac449eb9955ceb4ca Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Thu, 19 Jul 2018 00:53:55 -0700 Subject: [PATCH 3/5] Additional doc corrections courtesy of Serhiy S. --- Doc/library/dis.rst | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 64e9122af265c6..a97eacf5d15159 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1027,14 +1027,16 @@ the more significant byte last. 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 this are keyword arguments (if any), positional arguments (if any), + The top of the stack contains keyword arguments (if any), stored + identically to :opcode:`CALL_FUNCTION`. + Below that + is an iterable object containing additional positional arguments. + Below that are positional arguments (if any) and a callable object, identically to :opcode:`CALL_FUNCTION`. - Before the callable object is called, the iterable object at the top of the stack - is "unpacked" and its contents are appended to the positional arguments passed - in. - The iterable object at the top of the stack is ignored when computing + 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``. @@ -1061,15 +1063,18 @@ 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, as per :opcode:`CALL_FUNCTION_VAR`. - Below this are keyword arguments (if any), positional arguments (if any), + Below that are keyword arguments (if any), stored + identically to :opcode:`CALL_FUNCTION`. + Below that + is an iterable object containing additional positional arguments. + Below that are positional arguments (if any) and a callable object, identically to :opcode:`CALL_FUNCTION`. - Before the callable is called, the mapping object and iterable object on the - stack are each "unpacked" and their contents passed in as keyword and + 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 at the top of the stack - are both ignored when computing the value of ``argc``. + The mapping object and iterable object are both ignored when computing + the value of ``argc``. .. opcode:: HAVE_ARGUMENT From 86e915771ceb8800ae8dff848b08de191965b191 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Thu, 19 Jul 2018 04:36:36 -0700 Subject: [PATCH 4/5] Fix "hasconst". --- Doc/library/dis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index a97eacf5d15159..ff29ae96b51eaa 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1108,7 +1108,7 @@ instructions: .. data:: hasconst - Sequence of bytecodes that have a constant argument. + Sequence of bytecodes that access a constant. .. data:: hasfree From 20ac601355f72c923874a4256897f166fe5ad526 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Thu, 19 Jul 2018 05:47:43 -0700 Subject: [PATCH 5/5] Added versionchanged directives. --- Doc/library/dis.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index ff29ae96b51eaa..5168638ec4cd04 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1039,6 +1039,12 @@ 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) @@ -1076,6 +1082,11 @@ the more significant byte last. The mapping object and iterable object are both 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:: HAVE_ARGUMENT