Skip to content

bpo-33216: Clarify the documentation for CALL_FUNCTION_* #8338

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 5 commits into from
Jul 19, 2018
Merged

bpo-33216: Clarify the documentation for CALL_FUNCTION_* #8338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2c9b6f8
Clarify the documentation for CALL_FUNCTION_*.
larryhastings Jul 19, 2018
f87d0af
Minor touch-ups to the documentation clarification
larryhastings Jul 19, 2018
e2a99cd
Additional doc corrections courtesy of Serhiy S.
larryhastings Jul 19, 2018
86e9157
Fix "hasconst".
larryhastings Jul 19, 2018
20ac601
Added versionchanged directives.
larryhastings Jul 19, 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
92 changes: 70 additions & 22 deletions Doc/library/dis.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -960,34 +960,38 @@ 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)

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)

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1071,7 +1119,7 @@ instructions:

.. data:: hasconst

Sequence of bytecodes that have a constant parameter.
Sequence of bytecodes that access a constant.


.. data:: hasfree
Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Clarify the documentation for CALL_FUNCTION_VAR, CALL_FUNCTION_KW, and
CALL_FUNCTION_VAR_KW.