summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorlarryhastings <larry@hastings.org>2018-07-19 23:35:28 (GMT)
committerGitHub <noreply@github.com>2018-07-19 23:35:28 (GMT)
commit76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9 (patch)
tree90e51d7132bc919c353cf545d115bd1319cd60fa
parent1b141b9553424971639bde281feb1d4e4e586dbe (diff)
downloadcpython-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.rst92
-rw-r--r--Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst2
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.