[Python-checkins] [2.7] bpo-33216: Clarify the documentation for CALL_FUNCTION_* (GH-8338) (GH-8783)
Serhiy Storchaka
webhook-mailer at python.org
Mon Sep 17 08:15:51 EDT 2018
https://github.com/python/cpython/commit/afa591d7748c66831e6e650108024f3293be33f1
commit: afa591d7748c66831e6e650108024f3293be33f1
branch: 2.7
author: Serhiy Storchaka <storchaka at gmail.com>
committer: GitHub <noreply at github.com>
date: 2018-09-17T15:15:48+03:00
summary:
[2.7] bpo-33216: Clarify the documentation for CALL_FUNCTION_* (GH-8338) (GH-8783)
(cherry picked from commit 76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9)
Co-authored-by: larryhastings <larry at hastings.org>
files:
M Doc/library/dis.rst
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 04b9b1538633..e773ab8090fc 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,53 @@ 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``.
.. 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, 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
+ 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 ()
More information about the Python-checkins
mailing list