diff options
author | larryhastings <larry@hastings.org> | 2018-07-19 23:35:28 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-07-19 23:35:28 (GMT) |
commit | 76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9 (patch) | |
tree | 90e51d7132bc919c353cf545d115bd1319cd60fa | |
parent | 1b141b9553424971639bde281feb1d4e4e586dbe (diff) | |
download | cpython-76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9.zip cpython-76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9.tar.gz cpython-76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9.tar.bz2 |
bpo-33216: Clarify the documentation for CALL_FUNCTION_* (#8338)
Clarify the documentation for the CALL_FUNCTION_* bytecodes. They changed in 3.5 in subtle ways and the documentation has never been correct, much less clear.
-rw-r--r-- | Doc/library/dis.rst | 92 | ||||
-rw-r--r-- | Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst | 2 |
2 files changed, 72 insertions, 22 deletions
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 186aab4..5168638 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -960,21 +960,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) @@ -982,12 +986,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 +1024,68 @@ 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 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 + 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 this 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 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 + 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``. + + .. 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 @@ -1071,7 +1119,7 @@ instructions: .. data:: hasconst - Sequence of bytecodes that have a constant parameter. + Sequence of bytecodes that access a constant. .. 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 0000000..5668915 --- /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. |