Skip to content
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

Jump to bottom

Various small fixes to dis docs #103923

Merged
merged 1 commit into from
Apr 29, 2023
Merged

Various small fixes to dis docs #103923

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
157 changes: 79 additions & 78 deletions Doc/library/dis.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,12 @@
adaptive bytecode can be shown by passing ``adaptive=True``.


Example: Given the function :func:`myfunc`::

Check warning on line 46 in Doc/library/dis.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:func reference target not found: myfunc

def myfunc(alist):
return len(alist)

the following command can be used to display the disassembly of

Check warning on line 51 in Doc/library/dis.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:func reference target not found: myfunc
:func:`myfunc`:

.. doctest::
Expand Down Expand Up @@ -402,7 +402,7 @@

**General instructions**

In the following, We will refer to the interpreter stack as STACK and describe
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.

Expand All @@ -414,15 +414,15 @@

.. opcode:: POP_TOP

Removes the top-of-stack item.::
Removes the top-of-stack item::

STACK.pop()


.. opcode:: END_FOR

Removes the top two values from the stack.
Equivalent to POP_TOP; POP_TOP.
Equivalent to ``POP_TOP``; ``POP_TOP``.
Used to clean up at the end of loops, hence the name.

.. versionadded:: 3.12
Expand All @@ -431,7 +431,7 @@
.. opcode:: COPY (i)

Push the i-th item to the top of the stack without removing it from its original
location.::
location::

assert i > 0
STACK.append(STACK[-i])
Expand All @@ -441,7 +441,7 @@

.. opcode:: SWAP (i)

Swap the top of the stack with the i-th element.::
Swap the top of the stack with the i-th element::

STACK[-i], STACK[-1] = stack[-1], STACK[-i]

Expand Down Expand Up @@ -513,7 +513,7 @@
.. opcode:: BINARY_OP (op)

Implements the binary and in-place operators (depending on the value of
*op*).::
*op*)::

rhs = STACK.pop()
lhs = STACK.pop()
Expand Down Expand Up @@ -580,14 +580,14 @@

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
the :data:`~inspect.CO_ITERABLE_COROUTINE` flag, or resolves
``o.__await__``.

If the ``where`` operand is nonzero, it indicates where the instruction
occurs:

* ``1`` After a call to ``__aenter__``
* ``2`` After a call to ``__aexit__``
* ``1``: After a call to ``__aenter__``
* ``2``: After a call to ``__aexit__``

.. versionadded:: 3.5

Expand Down Expand Up @@ -652,6 +652,7 @@
.. opcode:: SET_ADD (i)

Implements::

item = STACK.pop()
set.add(STACK[-i], item)

Expand Down Expand Up @@ -705,11 +706,11 @@

Yields ``STACK.pop()`` from a :term:`generator`.

.. versionchanged:: 3.11
oparg set to be the stack depth.
.. versionchanged:: 3.11
oparg set to be the stack depth.

.. versionchanged:: 3.12
oparg set to be the exception block depth, for efficient closing of generators.
.. versionchanged:: 3.12
oparg set to be the exception block depth, for efficient closing of generators.


.. opcode:: SETUP_ANNOTATIONS
Expand All @@ -726,32 +727,32 @@

Pops a value from the stack, which is used to restore the exception state.

.. versionchanged:: 3.11
Exception representation on the stack now consist of one, not three, items.
.. versionchanged:: 3.11
Exception representation on the stack now consist of one, not three, items.

.. opcode:: RERAISE

Re-raises the exception currently on top of the stack. If oparg is non-zero,
pops an additional value from the stack which is used to set ``f_lasti``
of the current frame.
Re-raises the exception currently on top of the stack. If oparg is non-zero,
pops an additional value from the stack which is used to set ``f_lasti``
of the current frame.

.. versionadded:: 3.9
.. versionadded:: 3.9

.. versionchanged:: 3.11
Exception representation on the stack now consist of one, not three, items.
.. versionchanged:: 3.11
Exception representation on the stack now consist of one, not three, items.

.. opcode:: PUSH_EXC_INFO

Pops a value from the stack. Pushes the current exception to the top of the stack.
Pushes the value originally popped back to the stack.
Used in exception handlers.
Pops a value from the stack. Pushes the current exception to the top of the stack.
Pushes the value originally popped back to the stack.
Used in exception handlers.

.. versionadded:: 3.11
.. versionadded:: 3.11

.. opcode:: CHECK_EXC_MATCH

Performs exception matching for ``except``. Tests whether the ``STACK[-2]``
is an exception matching ``STACK[-1]``. Pops STACK[-1] and pushes the boolean
is an exception matching ``STACK[-1]``. Pops ``STACK[-1]`` and pushes the boolean
result of the test.

.. versionadded:: 3.11
Expand All @@ -770,16 +771,16 @@

.. opcode:: WITH_EXCEPT_START

Calls the function in position 4 on the stack with arguments (type, val, tb)
representing the exception at the top of the stack.
Used to implement the call ``context_manager.__exit__(*exc_info())`` when an exception
has occurred in a :keyword:`with` statement.
Calls the function in position 4 on the stack with arguments (type, val, tb)
representing the exception at the top of the stack.
Used to implement the call ``context_manager.__exit__(*exc_info())`` when an exception
has occurred in a :keyword:`with` statement.

.. versionadded:: 3.9
.. versionadded:: 3.9

.. versionchanged:: 3.11
The ``__exit__`` function is in position 4 of the stack rather than 7.
Exception representation on the stack now consist of one, not three, items.
.. versionchanged:: 3.11
The ``__exit__`` function is in position 4 of the stack rather than 7.
Exception representation on the stack now consist of one, not three, items.


.. opcode:: LOAD_ASSERTION_ERROR
Expand All @@ -792,7 +793,7 @@

.. opcode:: LOAD_BUILD_CLASS

Pushes :func:`builtins.__build_class__` onto the stack. It is later called

Check warning on line 796 in Doc/library/dis.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:func reference target not found: builtins.__build_class__
to construct a class.


Expand Down Expand Up @@ -849,21 +850,21 @@

.. opcode:: STORE_NAME (namei)

Implements ``name = STACK.pop()``. *namei* is the index of *name* in the attribute

Check warning on line 853 in Doc/library/dis.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:attr reference target not found: co_names
:attr:`co_names` of the code object. The compiler tries to use
:opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.


.. opcode:: DELETE_NAME (namei)

Implements ``del name``, where *namei* is the index into :attr:`co_names`

Check warning on line 860 in Doc/library/dis.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:attr reference target not found: co_names
attribute of the code object.


.. opcode:: UNPACK_SEQUENCE (count)

Unpacks ``STACK[-1]`` into *count* individual values, which are put onto the stack
right-to-left.::
right-to-left::

STACK.extend(STACK.pop()[:count:-1])

Expand Down Expand Up @@ -895,7 +896,7 @@
value = STACK.pop()
obj.name = value

where *namei* is the index of name in :attr:`co_names`.

Check warning on line 899 in Doc/library/dis.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:attr reference target not found: co_names

.. opcode:: DELETE_ATTR (namei)

Expand All @@ -904,7 +905,7 @@
obj = STACK.pop()
del obj.name

where *namei* is the index of name into :attr:`co_names`.

Check warning on line 908 in Doc/library/dis.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:attr reference target not found: co_names


.. opcode:: STORE_GLOBAL (namei)
Expand Down Expand Up @@ -1028,7 +1029,7 @@
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
when calling the unbound method. Otherwise, ``NULL`` and the object returned by
the attribute lookup are pushed.

.. versionchanged:: 3.12
Expand Down Expand Up @@ -1207,7 +1208,7 @@

.. opcode:: MAKE_CELL (i)

Creates a new cell in slot ``i``. If that slot is empty then
Creates a new cell in slot ``i``. If that slot is nonempty then
that value is stored into the new cell.

.. versionadded:: 3.11
Expand Down Expand Up @@ -1332,9 +1333,9 @@

.. opcode:: PUSH_NULL

Pushes a ``NULL`` to the stack.
Used in the call sequence to match the ``NULL`` pushed by
:opcode:`LOAD_METHOD` for non-method calls.
Pushes a ``NULL`` to the stack.
Used in the call sequence to match the ``NULL`` pushed by
:opcode:`LOAD_METHOD` for non-method calls.

.. versionadded:: 3.11

Expand Down Expand Up @@ -1434,38 +1435,38 @@

.. opcode:: RESUME (where)

A no-op. Performs internal tracing, debugging and optimization checks.
A no-op. Performs internal tracing, debugging and optimization checks.

The ``where`` operand marks where the ``RESUME`` occurs:
The ``where`` operand marks where the ``RESUME`` occurs:

* ``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
* ``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

.. versionadded:: 3.11


.. 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.
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
.. versionadded:: 3.11


.. opcode:: SEND (delta)

Equivalent to ``STACK[-1] = STACK[-2].send(STACK[-1])``. 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
*delta*.
If the call raises :exc:`StopIteration`, pop both items, push the
exception's ``value`` attribute, and increment the bytecode counter by
*delta*.

.. versionadded:: 3.11
.. versionadded:: 3.11


.. opcode:: HAVE_ARGUMENT
Expand Down Expand Up @@ -1493,15 +1494,15 @@
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:
The operand determines which intrinsic function is called:

* ``0`` Not valid
* ``1`` Prints the argument to standard out. Used in the REPL.
* ``2`` Performs ``import *`` for the named module.
* ``3`` Extracts the return value from a ``StopIteration`` exception.
* ``4`` Wraps an aync generator value
* ``5`` Performs the unary ``+`` operation
* ``6`` Converts a list to a tuple
* ``0`` Not valid
* ``1`` Prints the argument to standard out. Used in the REPL.
* ``2`` Performs ``import *`` for the named module.
* ``3`` Extracts the return value from a ``StopIteration`` exception.
* ``4`` Wraps an aync generator value
* ``5`` Performs the unary ``+`` operation
* ``6`` Converts a list to a tuple

.. versionadded:: 3.12

Expand All @@ -1511,17 +1512,17 @@
arguments 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:
The operand determines which intrinsic function is called:

* ``0`` Not valid
* ``1`` Calculates the :exc:`ExceptionGroup` to raise from a ``try-except*``.
* ``0`` Not valid
* ``1`` Calculates the :exc:`ExceptionGroup` to raise from a ``try-except*``.

.. versionadded:: 3.12


**Pseudo-instructions**

These opcodes do not appear in python bytecode, they are used by the compiler
These opcodes do not appear in Python bytecode. They are used by the compiler
but are replaced by real opcodes or removed before bytecode is generated.

.. opcode:: SETUP_FINALLY (target)
Expand All @@ -1533,7 +1534,7 @@

.. opcode:: SETUP_CLEANUP (target)

Like ``SETUP_FINALLY``, but in case of exception also pushes the last
Like ``SETUP_FINALLY``, but in case of an exception also pushes the last
instruction (``lasti``) to the stack so that ``RERAISE`` can restore it.
If an exception occurs, the value stack level and the last instruction on
the frame are restored to their current state, and control is transferred
Expand All @@ -1542,7 +1543,7 @@

.. opcode:: SETUP_WITH (target)

Like ``SETUP_CLEANUP``, but in case of exception one more item is popped
Like ``SETUP_CLEANUP``, but in case of an exception one more item is popped
from the stack before control is transferred to the exception handler at
``target``.

Expand Down Expand Up @@ -1576,9 +1577,9 @@
These collections are provided for automatic introspection of bytecode
instructions:

.. versionchanged:: 3.12
The collections now contain pseudo instructions as well. These are
opcodes with values ``>= MIN_PSEUDO_OPCODE``.
.. versionchanged:: 3.12
The collections now contain pseudo instructions as well. These are
opcodes with values ``>= MIN_PSEUDO_OPCODE``.

.. data:: opname

Expand All @@ -1599,7 +1600,7 @@

Sequence of bytecodes that use their argument.

.. versionadded:: 3.12
.. versionadded:: 3.12


.. data:: hasconst
Expand All @@ -1609,10 +1610,10 @@

.. data:: hasfree

Sequence of bytecodes that access a free variable (note that 'free' in this
Sequence of bytecodes that access a free variable. 'free' in this
context refers to names in the current scope that are referenced by inner
scopes or names in outer scopes that are referenced from this scope. It does
*not* include references to global or builtin scopes).
*not* include references to global or builtin scopes.


.. data:: hasname
Expand Down Expand Up @@ -1643,4 +1644,4 @@

Sequence of bytecodes that set an exception handler.

.. versionadded:: 3.12
.. versionadded:: 3.12