Skip to content

[2.7] bpo-33216: Clarify the documentation for CALL_FUNCTION_* (GH-8338) #8783

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 17, 2018
Merged

[2.7] bpo-33216: Clarify the documentation for CALL_FUNCTION_* (GH-8338) #8783

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d2ca5a
[2.7] bpo-33216: Clarify the documentation for CALL_FUNCTION_* (GH-8338)
larryhastings Jul 19, 2018
3e6ac54
Remove the versionchanged note and the news entry.
serhiy-storchaka Aug 16, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 53 additions & 20 deletions Doc/library/dis.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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 ()
Expand Down