mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

gh-96461: Improve docs for bytecode instructions (GH-96462)

Browse source 
* Clarify the meaning of the oparg for CACHE and COPY opcode in dis doc

* Use STACK to describe stack operation in analogy with a Python list

* Remove (delta) from BEFORE_WITH since BEFORE_WITH does not take an argument

* Fix the description of the stack impact of multiple opcodes
This commit is contained in:
Matthieu Dartiailh 2023-01-12 19:23:50 +01:00 • committed by GitHub
parent c549fcccbb
commit eecd422d1b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 236 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

359
Doc/library/dis.rst
View file

@ -402,6 +402,10 @@ The Python compiler currently generates the following bytecode instructions.
**General instructions**
In the following, We will refer to the interpreter stack as STACK and describe
operations on it as if it was a Python list. The top of the stack corresponds to
``STACK[-1]`` in this language.
.. opcode:: NOP
Do nothing code. Used as a placeholder by the bytecode optimizer, and to
@ -410,7 +414,9 @@ The Python compiler currently generates the following bytecode instructions.
.. opcode:: POP_TOP
Removes the top-of-stack (TOS) item.
Removes the top-of-stack item.::
STACK.pop()
.. opcode:: END_FOR
@ -424,15 +430,20 @@ The Python compiler currently generates the following bytecode instructions.
.. opcode:: COPY (i)
Push the *i*-th item to the top of the stack. The item is not removed from its
original location.
Push the i-th item to the top of the stack without removing it from its original
location.::
assert i > 0
STACK.append(STACK[-i])
.. versionadded:: 3.11
.. opcode:: SWAP (i)
Swap TOS with the item at position *i*.
Swap the top of the stack with the i-th element.::
STACK[-i], STACK[-1] = stack[-1], STACK[-i]
.. versionadded:: 3.11
@ -463,79 +474,102 @@ result back on the stack.
.. opcode:: UNARY_NEGATIVE
Implements ``TOS = -TOS``.
Implements ``STACK[-1] = -STACK[-1]``.
.. opcode:: UNARY_NOT
Implements ``TOS = not TOS``.
Implements ``STACK[-1] = not STACK[-1]``.
.. opcode:: UNARY_INVERT
Implements ``TOS = ~TOS``.
Implements ``STACK[-1] = ~STACK[-1]``.
.. opcode:: GET_ITER
Implements ``TOS = iter(TOS)``.
Implements ``STACK[-1] = iter(STACK[-1])``.
.. opcode:: GET_YIELD_FROM_ITER
If ``TOS`` is a :term:`generator iterator` or :term:`coroutine` object
it is left as is. Otherwise, implements ``TOS = iter(TOS)``.
If ``STACK[-1]`` is a :term:`generator iterator` or :term:`coroutine` object
it is left as is. Otherwise, implements ``STACK[-1] = iter(STACK[-1])``.
.. versionadded:: 3.5
**Binary and in-place operations**
In the following, TOS is the top-of-stack.
TOS1, TOS2, TOS3 are the second, third and fourth items on the stack, respectively.
Binary operations remove the top two items from the stack (TOS and TOS1).
They perform the operation, then put the result back on the stack.
Binary operations remove the top two items from the stack (``STACK[-1]`` and
``STACK[-2]``). They perform the operation, then put the result back on the stack.
In-place operations are like binary operations, but the operation is done in-place
when TOS1 supports it, and the resulting TOS may be (but does not have to be)
the original TOS1.
when ``STACK[-2]`` supports it, and the resulting ``STACK[-1]`` may be (but does
not have to be) the original ``STACK[-2]``.
.. opcode:: BINARY_OP (op)
Implements the binary and in-place operators (depending on the value of
*op*).
``TOS = TOS1 op TOS``.
*op*).::
rhs = STACK.pop()
lhs = STACK.pop()
STACK.append(lhs op rhs)
.. versionadded:: 3.11
.. opcode:: BINARY_SUBSCR
Implements ``TOS = TOS1[TOS]``.
Implements::
key = STACK.pop()
container = STACK.pop()
STACK.append(container[index])
.. opcode:: STORE_SUBSCR
Implements ``TOS1[TOS] = TOS2``.
Implements::
key = STACK.pop()
container = STACK.pop()
value = STACK.pop()
container[key] = value
.. opcode:: DELETE_SUBSCR
Implements ``del TOS1[TOS]``.
Implements::
key = STACK.pop()
container = STACK.pop()
del container[key]
.. opcode:: BINARY_SLICE
Implements ``TOS = TOS2[TOS1:TOS]``.
Implements::
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
STACK.append(container[start:end])
.. versionadded:: 3.12
.. opcode:: STORE_SLICE
Implements ``TOS2[TOS1:TOS] = TOS3``.
Implements::
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
values = STACK.pop()
container[start:end] = value
.. versionadded:: 3.12
@ -544,7 +578,7 @@ the original TOS1.
.. opcode:: GET_AWAITABLE (where)
Implements ``TOS = get_awaitable(TOS)``, where ``get_awaitable(o)``
Implements ``STACK[-1] = get_awaitable(STACK[-1])``, where ``get_awaitable(o)``
returns ``o`` if ``o`` is a coroutine object or a generator object with
the CO_ITERABLE_COROUTINE flag, or resolves
``o.__await__``.
@ -563,7 +597,7 @@ the original TOS1.
.. opcode:: GET_AITER
Implements ``TOS = TOS.__aiter__()``.
Implements ``STACK[-1] = STACK[-1].__aiter__()``.
.. versionadded:: 3.5
.. versionchanged:: 3.7
@ -573,8 +607,8 @@ the original TOS1.
.. opcode:: GET_ANEXT
Pushes ``get_awaitable(TOS.__anext__())`` to the stack. See
``GET_AWAITABLE`` for details about ``get_awaitable``.
Implement ``STACK.append(get_awaitable(STACK[-1].__anext__()))`` to the stack.
See ``GET_AWAITABLE`` for details about ``get_awaitable``.
.. versionadded:: 3.5
@ -582,7 +616,7 @@ the original TOS1.
.. opcode:: END_ASYNC_FOR
Terminates an :keyword:`async for` loop. Handles an exception raised
when awaiting a next item. If TOS is :exc:`StopAsyncIteration` pop 3
when awaiting a next item. If ``STACK[-1]`` is :exc:`StopAsyncIteration` pop 3
values from the stack and restore the exception state using the second
of them. Otherwise re-raise the exception using the value
from the stack. An exception handler block is removed from the block stack.
@ -596,17 +630,19 @@ the original TOS1.
.. opcode:: CLEANUP_THROW
Handles an exception raised during a :meth:`~generator.throw` or
:meth:`~generator.close` call through the current frame. If TOS is an
:meth:`~generator.close` call through the current frame. If ``STACK[-1]`` is an
instance of :exc:`StopIteration`, pop three values from the stack and push
its ``value`` member. Otherwise, re-raise TOS.
its ``value`` member. Otherwise, re-raise ``STACK[-1]``.
.. versionadded:: 3.12
.. opcode:: BEFORE_ASYNC_WITH
Resolves ``__aenter__`` and ``__aexit__`` from the object on top of the
stack. Pushes ``__aexit__`` and result of ``__aenter__()`` to the stack.
Resolves ``__aenter__`` and ``__aexit__`` from ``STACK[-1]``.
Pushes ``__aexit__`` and result of ``__aenter__()`` to the stack::
STACK.extend((__aexit__, __aenter__())
.. versionadded:: 3.5
@ -616,22 +652,37 @@ the original TOS1.
.. opcode:: SET_ADD (i)
Calls ``set.add(TOS1[-i], TOS)``. Used to implement set comprehensions.
Implements::
item = STACK.pop()
set.add(STACK[-i], item)
Used to implement set comprehensions.
.. opcode:: LIST_APPEND (i)
Calls ``list.append(TOS1[-i], TOS)``. Used to implement list comprehensions.
Implements::
item = STACK.pop()
list.append(STACK[-i], item)
Used to implement list comprehensions.
.. opcode:: MAP_ADD (i)
Calls ``dict.__setitem__(TOS1[-i], TOS1, TOS)``. Used to implement dict
comprehensions.
Implements::
value = STACK.pop()
key = STACK.pop()
dict.__setitem__(STACK[-i], key, value)
Used to implement dict comprehensions.
.. versionadded:: 3.1
.. versionchanged:: 3.8
Map value is TOS and map key is TOS1. Before, those were reversed.
Map value is ``STACK[-1]`` and map key is ``STACK[-2]``. Before, those
were reversed.
For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:`MAP_ADD`
instructions, while the added value or key/value pair is popped off, the
@ -641,12 +692,12 @@ iterations of the loop.
.. opcode:: RETURN_VALUE
Returns with TOS to the caller of the function.
Returns with ``STACK[-1]`` to the caller of the function.
.. opcode:: YIELD_VALUE
Pops TOS and yields it from a :term:`generator`.
Yields ``STACK.pop()`` from a :term:`generator`.
.. versionchanged:: 3.11
oparg set to be the stack depth, for efficient handling on frames.
@ -690,15 +741,16 @@ iterations of the loop.
.. opcode:: CHECK_EXC_MATCH
Performs exception matching for ``except``. Tests whether the TOS1 is an exception
matching TOS. Pops TOS and pushes the boolean result of the test.
Performs exception matching for ``except``. Tests whether the ``STACK[-2]``
is an exception matching ``STACK[-1]``. Pops STACK[-1] and pushes the boolean
result of the test.
.. versionadded:: 3.11
.. opcode:: CHECK_EG_MATCH
Performs exception matching for ``except*``. Applies ``split(TOS)`` on
the exception group representing TOS1.
Performs exception matching for ``except*``. Applies ``split(STACK[-1])`` on
the exception group representing ``STACK[-2]``.
In case of a match, pops two items from the stack and pushes the
non-matching subgroup (``None`` in case of full match) followed by the
@ -709,9 +761,9 @@ iterations of the loop.
.. opcode:: PREP_RERAISE_STAR
Combines the raised and reraised exceptions list from TOS, into an exception
group to propagate from a try-except* block. Uses the original exception
group from TOS1 to reconstruct the structure of reraised exceptions. Pops
Combines the raised and reraised exceptions list from ``STACK[-1]``, into an
exception group to propagate from a try-except* block. Uses the original exception
group from ``STACK[-2]`` to reconstruct the structure of reraised exceptions. Pops
two items from the stack and pushes the exception to reraise or ``None``
if there isn't one.
@ -745,7 +797,7 @@ iterations of the loop.
to construct a class.
.. opcode:: BEFORE_WITH (delta)
.. opcode:: BEFORE_WITH
This opcode performs several operations before a with block starts. First,
it loads :meth:`~object.__exit__` from the context manager and pushes it onto
@ -758,24 +810,24 @@ iterations of the loop.
.. opcode:: GET_LEN
Push ``len(TOS)`` onto the stack.
Perform ``STACK.append(len(STACK[-1]))``.
.. versionadded:: 3.10
.. opcode:: MATCH_MAPPING
If TOS is an instance of :class:`collections.abc.Mapping` (or, more technically: if
it has the :const:`Py_TPFLAGS_MAPPING` flag set in its
:c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. Otherwise, push
``False``.
If ``STACK[-1]`` is an instance of :class:`collections.abc.Mapping` (or, more
technically: if it has the :const:`Py_TPFLAGS_MAPPING` flag set in its
:c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. Otherwise,
push ``False``.
.. versionadded:: 3.10
.. opcode:: MATCH_SEQUENCE
If TOS is an instance of :class:`collections.abc.Sequence` and is *not* an instance
If ``STACK[-1]`` is an instance of :class:`collections.abc.Sequence` and is *not* an instance
of :class:`str`/:class:`bytes`/:class:`bytearray` (or, more technically: if it has
the :const:`Py_TPFLAGS_SEQUENCE` flag set in its :c:member:`~PyTypeObject.tp_flags`),
push ``True`` onto the stack. Otherwise, push ``False``.
@ -785,9 +837,9 @@ iterations of the loop.
.. opcode:: MATCH_KEYS
TOS is a tuple of mapping keys, and TOS1 is the match subject. If TOS1
contains all of the keys in TOS, push a :class:`tuple` containing the
corresponding values. Otherwise, push ``None``.
``STACK[-1]`` is a tuple of mapping keys, and ``STACK[-2]`` is the match subject.
If ``STACK[-2]`` contains all of the keys in ``STACK[-1]``, push a :class:`tuple`
containing the corresponding values. Otherwise, push ``None``.
.. versionadded:: 3.10
@ -798,7 +850,7 @@ iterations of the loop.
.. opcode:: STORE_NAME (namei)
Implements ``name = TOS``. *namei* is the index of *name* in the attribute
Implements ``name = STACK.pop()``. *namei* is the index of *name* in the attribute
:attr:`co_names` of the code object. The compiler tries to use
:opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.
@ -811,31 +863,49 @@ iterations of the loop.
.. opcode:: UNPACK_SEQUENCE (count)
Unpacks TOS into *count* individual values, which are put onto the stack
right-to-left.
Unpacks ``STACK[-1]`` into *count* individual values, which are put onto the stack
right-to-left.::
STACK.extend(STACK.pop()[:count:-1])
.. opcode:: UNPACK_EX (counts)
Implements assignment with a starred target: Unpacks an iterable in TOS into
individual values, where the total number of values can be smaller than the
Implements assignment with a starred target: Unpacks an iterable in ``STACK[-1]``
into individual values, where the total number of values can be smaller than the
number of items in the iterable: one of the new values will be a list of all
leftover items.
The low byte of *counts* is the number of values before the list value, the
high byte of *counts* the number of values after it. The resulting values
are put onto the stack right-to-left.
The number of values before and after the list value is limited to 255.
The number of values before the list value is encoded in the argument of the
opcode. The number of values after the list if any is encoded using an
``EXTENDED_ARG``. As a consequence, the argument can be seen as a two bytes values
where the low byte of *counts* is the number of values before the list value, the
high byte of *counts* the number of values after it.
The extracted values are put onto the stack right-to-left, i.e. ``a, *b, c = d``
will be stored after execution as ``STACK.extend((a, b, c))``.
.. opcode:: STORE_ATTR (namei)
Implements ``TOS.name = TOS1``, where *namei* is the index of name in
:attr:`co_names`.
Implements::
obj = STACK.pop()
value = STACK.pop()
obj.name = value
where *namei* is the index of name in :attr:`co_names`.
.. opcode:: DELETE_ATTR (namei)
Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
Implements::
obj = STACK.pop()
del obj.name
where *namei* is the index of name into :attr:`co_names`.
.. opcode:: STORE_GLOBAL (namei)
@ -861,7 +931,11 @@ iterations of the loop.
.. opcode:: BUILD_TUPLE (count)
Creates a tuple consuming *count* items from the stack, and pushes the
resulting tuple onto the stack.
resulting tuple onto the stack.::
assert count > 0
STACK, values = STACK[:-count], STACK[-count:]
STACK.append(tuple(values))
.. opcode:: BUILD_LIST (count)
@ -878,7 +952,7 @@ iterations of the loop.
Pushes a new dictionary object onto the stack. Pops ``2 * count`` items
so that the dictionary holds *count* entries:
``{..., TOS3: TOS2, TOS1: TOS}``.
``{..., STACK[-4]: STACK[-3], STACK[-2]: STACK[-1]}``.
.. versionchanged:: 3.5
The dictionary is created from stack items instead of creating an
@ -889,7 +963,7 @@ iterations of the loop.
The version of :opcode:`BUILD_MAP` specialized for constant keys. Pops the
top element on the stack which contains a tuple of keys, then starting from
``TOS1``, pops *count* values to form values in the built dictionary.
``STACK[-2]``, pops *count* values to form values in the built dictionary.
.. versionadded:: 3.6
@ -904,21 +978,36 @@ iterations of the loop.
.. opcode:: LIST_EXTEND (i)
Calls ``list.extend(TOS1[-i], TOS)``. Used to build lists.
Implements::
seq = STACK.pop()
list.extend(STACK[-i], seq)
Used to build lists.
.. versionadded:: 3.9
.. opcode:: SET_UPDATE (i)
Calls ``set.update(TOS1[-i], TOS)``. Used to build sets.
Implements::
seq = STACK.pop()
set.update(STACK[-i], seq)
Used to build sets.
.. versionadded:: 3.9
.. opcode:: DICT_UPDATE (i)
Calls ``dict.update(TOS1[-i], TOS)``. Used to build dicts.
Implements::
map = STACK.pop()
dict.update(STACK[-i], map)
Used to build dicts.
.. versionadded:: 3.9
@ -932,16 +1021,16 @@ iterations of the loop.
.. opcode:: LOAD_ATTR (namei)
If the low bit of ``namei`` is not set, this replaces TOS with
``getattr(TOS, co_names[namei>>1])``.
If the low bit of ``namei`` is not set, this replaces ``STACK[-1]`` with
``getattr(STACK[-1], co_names[namei>>1])``.
If the low bit of ``namei`` is set, this will attempt to load a method named
``co_names[namei>>1]`` from the TOS object. TOS is popped.
This bytecode distinguishes two cases: if TOS has a method with the correct
name, the bytecode pushes the unbound method and TOS. TOS will be used as
the first argument (``self``) by :opcode:`CALL` when calling the
unbound method. Otherwise, ``NULL`` and the object return by the attribute
lookup are pushed.
``co_names[namei>>1]`` from the ``STACK[-1]`` object. ``STACK[-1]`` is popped.
This bytecode distinguishes two cases: if ``STACK[-1]`` has a method with the
correct name, the bytecode pushes the unbound method and ``STACK[-1]``.
``STACK[-1]`` will be used as the first argument (``self``) by :opcode:`CALL`
when calling the unbound method. Otherwise, ``NULL`` and the object return by
the attribute lookup are pushed.
.. versionchanged:: 3.12
If the low bit of ``namei`` is set, then a ``NULL`` or ``self`` is
@ -970,17 +1059,16 @@ iterations of the loop.
.. opcode:: IMPORT_NAME (namei)
Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide
the *fromlist* and *level* arguments of :func:`__import__`. The module
object is pushed onto the stack. The current namespace is not affected: for
a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
Imports the module ``co_names[namei]``. ``STACK[-1]`` and ``STACK[-2]`` are
popped and provide the *fromlist* and *level* arguments of :func:`__import__`.
The module object is pushed onto the stack. The current namespace is not affected: for a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
modifies the namespace.
.. opcode:: IMPORT_FROM (namei)
Loads the attribute ``co_names[namei]`` from the module found in TOS. The
resulting object is pushed onto the stack, to be subsequently stored by a
Loads the attribute ``co_names[namei]`` from the module found in ``STACK[-1]``.
The resulting object is pushed onto the stack, to be subsequently stored by a
:opcode:`STORE_FAST` instruction.
@ -1005,7 +1093,8 @@ iterations of the loop.
.. opcode:: POP_JUMP_IF_TRUE (delta)
If TOS is true, increments the bytecode counter by *delta*. TOS is popped.
If ``STACK[-1]`` is true, increments the bytecode counter by *delta*.
``STACK[-1]`` is popped.
.. versionchanged:: 3.11
The oparg is now a relative delta rather than an absolute target.
@ -1017,7 +1106,8 @@ iterations of the loop.
.. opcode:: POP_JUMP_IF_FALSE (delta)
If TOS is false, increments the bytecode counter by *delta*. TOS is popped.
If ``STACK[-1]`` is false, increments the bytecode counter by *delta*.
``STACK[-1]`` is popped.
.. versionchanged:: 3.11
The oparg is now a relative delta rather than an absolute target.
@ -1029,7 +1119,11 @@ iterations of the loop.
.. opcode:: POP_JUMP_IF_NOT_NONE (delta)
If TOS is not ``None``, increments the bytecode counter by *delta*. TOS is popped.
If ``STACK[-1]`` is not ``None``, increments the bytecode counter by *delta*.
``STACK[-1]`` is popped.
This opcode is a pseudo-instruction, replaced in final bytecode by
the directed versions (forward/backward).
.. versionadded:: 3.11
@ -1039,7 +1133,11 @@ iterations of the loop.
.. opcode:: POP_JUMP_IF_NONE (delta)
If TOS is ``None``, increments the bytecode counter by *delta*. TOS is popped.
If ``STACK[-1]`` is ``None``, increments the bytecode counter by *delta*.
``STACK[-1]`` is popped.
This opcode is a pseudo-instruction, replaced in final bytecode by
the directed versions (forward/backward).
.. versionadded:: 3.11
@ -1049,8 +1147,9 @@ iterations of the loop.
.. opcode:: JUMP_IF_TRUE_OR_POP (delta)
If TOS is true, increments the bytecode counter by *delta* and leaves TOS on the
stack. Otherwise (TOS is false), TOS is popped.
If ``STACK[-1]`` is true, increments the bytecode counter by *delta* and leaves
``STACK[-1]`` on the stack. Otherwise (``STACK[-1]`` is false), ``STACK[-1]``
is popped.
.. versionadded:: 3.1
@ -1059,8 +1158,9 @@ iterations of the loop.
.. opcode:: JUMP_IF_FALSE_OR_POP (delta)
If TOS is false, increments the bytecode counter by *delta* and leaves TOS on the
stack. Otherwise (TOS is true), TOS is popped.
If ``STACK[-1]`` is false, increments the bytecode counter by *delta* and leaves
``STACK[-1]`` on the stack. Otherwise (``STACK[-1]`` is true), ``STACK[-1]`` is
popped.
.. versionadded:: 3.1
@ -1070,10 +1170,10 @@ iterations of the loop.
.. opcode:: FOR_ITER (delta)
TOS is an :term:`iterator`. Call its :meth:`~iterator.__next__` method. If
this yields a new value, push it on the stack (leaving the iterator below
it). If the iterator indicates it is exhausted then the byte
code counter is incremented by *delta*.
``STACK[-1]`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` method.
If this yields a new value, push it on the stack (leaving the iterator below
it). If the iterator indicates it is exhausted then the byte code counter is
incremented by *delta*.
.. versionchanged:: 3.12
Up until 3.11 the iterator was popped when it was exhausted.
@ -1104,7 +1204,7 @@ iterations of the loop.
.. opcode:: STORE_FAST (var_num)
Stores TOS into the local ``co_varnames[var_num]``.
Stores ``STACK.pop()`` into the local ``co_varnames[var_num]``.
.. opcode:: DELETE_FAST (var_num)
@ -1155,7 +1255,7 @@ iterations of the loop.
.. opcode:: STORE_DEREF (i)
Stores TOS into the cell contained in slot ``i`` of the "fast locals"
Stores ``STACK.pop()`` into the cell contained in slot ``i`` of the "fast locals"
storage.
.. versionchanged:: 3.11
@ -1188,9 +1288,9 @@ iterations of the loop.
depending on the value of *argc*:
* 0: ``raise`` (re-raise previous exception)
* 1: ``raise TOS`` (raise exception instance or type at ``TOS``)
* 2: ``raise TOS1 from TOS`` (raise exception instance or type at ``TOS1``
with ``__cause__`` set to ``TOS``)
* 1: ``raise STACK[-1]`` (raise exception instance or type at ``STACK[-1]``)
* 2: ``raise STACK[-2] from STACK[-1]`` (raise exception instance or type at
``STACK[-2]`` with ``__cause__`` set to ``STACK[-1]``)
.. opcode:: CALL (argc)
@ -1246,7 +1346,7 @@ iterations of the loop.
.. versionadded:: 3.11
.. opcode:: KW_NAMES (i)
.. opcode:: KW_NAMES (consti)
Prefixes :opcode:`CALL`.
Stores a reference to ``co_consts[consti]`` into an internal variable
@ -1265,8 +1365,8 @@ iterations of the loop.
* ``0x02`` a dictionary of keyword-only parameters' default values
* ``0x04`` a tuple of strings containing parameters' annotations
* ``0x08`` a tuple containing cells for free variables, making a closure
* the code associated with the function (at TOS1)
* the :term:`qualified name` of the function (at TOS)
* the code associated with the function (at ``STACK[-2]``)
* the :term:`qualified name` of the function (at ``STACK[-1]``)
.. versionchanged:: 3.10
Flag value ``0x04`` is a tuple of strings instead of dictionary
@ -1275,9 +1375,20 @@ iterations of the loop.
.. index:: builtin: slice
Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
pushed. See the :func:`slice` built-in function for more information.
Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2, implements::
end = STACK.pop()
start = STACK.pop()
STACK.append(slice(start, stop))
if it is 3, implements::
step = STACK.pop()
end = STACK.pop()
start = STACK.pop()
STACK.append(slice(start, end, step))
See the :func:`slice` built-in function for more information.
.. opcode:: EXTENDED_ARG (ext)
@ -1312,13 +1423,14 @@ iterations of the loop.
.. opcode:: MATCH_CLASS (count)
TOS is a tuple of keyword attribute names, TOS1 is the class being matched
against, and TOS2 is the match subject. *count* is the number of positional
sub-patterns.
``STACK[-1]`` is a tuple of keyword attribute names, ``STACK[-2]`` is the class
being matched against, and ``STACK[-3]`` is the match subject. *count* is the
number of positional sub-patterns.
Pop TOS, TOS1, and TOS2. If TOS2 is an instance of TOS1 and has the
positional and keyword attributes required by *count* and TOS, push a tuple
of extracted attributes. Otherwise, push ``None``.
Pop ``STACK[-1]``, ``STACK[-2]``, and ``STACK[-3]``. If ``STACK[-3]`` is an
instance of ``STACK[-2]`` and has the positional and keyword attributes
required by *count* and ``STACK[-1]``, push a tuple of extracted attributes.
Otherwise, push ``None``.
.. versionadded:: 3.10
@ -1333,7 +1445,8 @@ iterations of the loop.
The ``where`` operand marks where the ``RESUME`` occurs:
* ``0`` The start of a function
* ``0`` The start of a function, which is neither a generator, coroutine
nor an async generator
* ``1`` After a ``yield`` expression
* ``2`` After a ``yield from`` expression
* ``3`` After an ``await`` expression
@ -1344,6 +1457,7 @@ iterations of the loop.
.. opcode:: RETURN_GENERATOR
Create a generator, coroutine, or async generator from the current frame.
Used as first opcode of in code object for the above mentioned callables.
Clear the current frame and return the newly created generator.
.. versionadded:: 3.11
@ -1351,8 +1465,8 @@ iterations of the loop.
.. opcode:: SEND (delta)
Equivalent to ``TOS = TOS1.send(TOS)``. Used in ``yield from`` and ``await``
statements.
Equivalent to ``STACK[-1] = STACK[-2].send(STACK[-1])``. Used in ``yield from``
and ``await`` statements.
If the call raises :exc:`StopIteration`, pop both items, push the
exception's ``value`` attribute, and increment the bytecode counter by
@ -1382,9 +1496,8 @@ iterations of the loop.
.. opcode:: CALL_INTRINSIC_1
Calls an intrinsic function with one argument. Passes the TOS as the argument
and sets TOS to the result. Used to implement functionality that is necessary
but not performance critical.
Calls an intrinsic function with one argument. Passes ``STACK[-1]`` as the
argument and sets ``STACK[-1]`` to the result. Used to implement functionality that is necessary but not performance critical.
The operand determines which intrinsic function is called: