Skip to content

gh-137352: Add terms links to dis.rst #137787

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

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

gh-137352: Add terms links to dis.rst #137787

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b88d5a3
Add links to glossary in dis.rst
Tapeline Aug 14, 2025
83f91ed
Revert accidental changes
Tapeline Aug 14, 2025
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
91 changes: 47 additions & 44 deletions Doc/library/dis.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

--------------

The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
The :mod:`dis` module supports the analysis of :term:`CPython` :term:`bytecode` by
disassembling it. The CPython bytecode which this module takes as an input is
defined in the file :file:`Include/opcode.h` and used by the compiler and the
interpreter.
Expand Down Expand Up @@ -141,9 +141,9 @@ code.
show_caches=False, adaptive=False, show_offsets=False,\
show_positions=False)

Analyse the bytecode corresponding to a function, generator, asynchronous
generator, coroutine, method, string of source code, or a code object (as
returned by :func:`compile`).
Analyse the bytecode corresponding to a function, :term:`generator`,
:term:`asynchronous generator`, :term:`coroutine`, method, string of source code,
or a code object (as returned by :func:`compile`).

This is a convenience wrapper around many of the functions listed below, most
notably :func:`get_instructions`, as iterating over a :class:`Bytecode`
Expand Down Expand Up @@ -194,7 +194,7 @@ code.
code object, like :func:`code_info`.

.. versionchanged:: 3.7
This can now handle coroutine and asynchronous generator objects.
This can now handle :term:`coroutine` and :term:`asynchronous generator` objects.

.. versionchanged:: 3.11
Added the *show_caches* and *adaptive* parameters.
Expand Down Expand Up @@ -230,7 +230,7 @@ operation is being performed, so the intermediate analysis object isn't useful:
.. function:: code_info(x)

Return a formatted multi-line string with detailed code object information
for the supplied function, generator, asynchronous generator, coroutine,
for the supplied function, :term:`generator`, :term:`asynchronous generator`, :term:`coroutine`,
method, source code string or code object.

Note that the exact contents of code info strings are highly implementation
Expand Down Expand Up @@ -262,13 +262,13 @@ operation is being performed, so the intermediate analysis object isn't useful:
adaptive=False, show_offsets=False, show_positions=False)

Disassemble the *x* object. *x* can denote either a module, a class, a
method, a function, a generator, an asynchronous generator, a coroutine,
method, a function, a :term:`generator`, an :term:`asynchronous generator`, a :term:`coroutine`,
a code object, a string of source code or a byte sequence of raw bytecode.
For a module, it disassembles all functions. For a class, it disassembles
all methods (including class and static methods). For a code object or
sequence of raw bytecode, it prints one line per bytecode instruction.
It also recursively disassembles nested code objects. These can include
generator expressions, nested functions, the bodies of nested classes,
:term:`generator expressions <generator expression>`, nested functions, the bodies of nested classes,
and the code objects used for :ref:`annotation scopes <annotation-scopes>`.
Strings are first compiled to code objects with the :func:`compile`
built-in function before being disassembled. If no object is provided, this
Expand All @@ -293,7 +293,7 @@ operation is being performed, so the intermediate analysis object isn't useful:
Implemented recursive disassembling and added *depth* parameter.

.. versionchanged:: 3.7
This can now handle coroutine and asynchronous generator objects.
This can now handle :term:`coroutine` and :term:`asynchronous generator` objects.

.. versionchanged:: 3.11
Added the *show_caches* and *adaptive* parameters.
Expand Down Expand Up @@ -364,10 +364,10 @@ operation is being performed, so the intermediate analysis object isn't useful:

.. function:: get_instructions(x, *, first_line=None, show_caches=False, adaptive=False)

Return an iterator over the instructions in the supplied function, method,
Return an :term:`iterator` over the instructions in the supplied function, method,
source code string or code object.

The iterator generates a series of :class:`Instruction` named tuples giving
The iterator generates a series of :class:`Instruction` :term:`named tuples <named tuple>` giving
the details of each operation in the supplied code.

If *first_line* is not ``None``, it indicates the line number that should be
Expand All @@ -390,7 +390,7 @@ operation is being performed, so the intermediate analysis object isn't useful:

.. function:: findlinestarts(code)

This generator function uses the :meth:`~codeobject.co_lines` method
This :term:`generator` function uses the :meth:`~codeobject.co_lines` method
of the :ref:`code object <code-objects>` *code* to find the offsets which
are starts of
lines in the source code. They are generated as ``(offset, lineno)`` pairs.
Expand Down Expand Up @@ -604,7 +604,7 @@ operations on it as if it was a Python list. The top of the stack corresponds to
.. opcode:: END_SEND

Implements ``del STACK[-2]``.
Used to clean up when a generator exits.
Used to clean up when a :term:`generator` exits.

.. versionadded:: 3.12

Expand Down Expand Up @@ -763,7 +763,7 @@ not have to be) the original ``STACK[-2]``.
.. opcode:: GET_AWAITABLE (where)

Implements ``STACK[-1] = get_awaitable(STACK[-1])``, where ``get_awaitable(o)``
returns ``o`` if ``o`` is a coroutine object or a generator object with
returns ``o`` if ``o`` is a :term:`coroutine` object or a :term:`generator` object with
the :data:`~inspect.CO_ITERABLE_COROUTINE` flag, or resolves
``o.__await__``.

Expand Down Expand Up @@ -800,7 +800,7 @@ not have to be) the original ``STACK[-2]``.
.. opcode:: END_ASYNC_FOR

Terminates an :keyword:`async for` loop. Handles an exception raised
when awaiting a next item. The stack contains the async iterable in
when awaiting a next item. The stack contains the async :term:`iterable` in
``STACK[-2]`` and the raised exception in ``STACK[-1]``. Both are popped.
If the exception is not :exc:`StopAsyncIteration`, it is re-raised.

Expand Down Expand Up @@ -830,7 +830,7 @@ not have to be) the original ``STACK[-2]``.
item = STACK.pop()
set.add(STACK[-i], item)

Used to implement set comprehensions.
Used to implement :term:`set comprehensions <set comprehension>`.


.. opcode:: LIST_APPEND (i)
Expand All @@ -840,7 +840,7 @@ not have to be) the original ``STACK[-2]``.
item = STACK.pop()
list.append(STACK[-i], item)

Used to implement list comprehensions.
Used to implement :term:`list comprehensions <list comprehension>`.


.. opcode:: MAP_ADD (i)
Expand Down Expand Up @@ -997,7 +997,7 @@ iterations of the loop.

.. opcode:: MATCH_KEYS

``STACK[-1]`` is a tuple of mapping keys, and ``STACK[-2]`` is the match subject.
``STACK[-1]`` is a tuple of :term:`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``.

Expand Down Expand Up @@ -1032,7 +1032,7 @@ iterations of the loop.

.. opcode:: UNPACK_EX (counts)

Implements assignment with a starred target: Unpacks an iterable in ``STACK[-1]``
Implements assignment with a starred target: Unpacks an :term:`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.
Expand Down Expand Up @@ -1102,16 +1102,16 @@ iterations of the loop.

.. opcode:: LOAD_LOCALS

Pushes a reference to the locals dictionary onto the stack. This is used
to prepare namespace dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF`
Pushes a reference to the locals :term:`dictionary` onto the stack. This is used
to prepare :term:`namespace` dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF`
and :opcode:`LOAD_FROM_DICT_OR_GLOBALS`.

.. versionadded:: 3.12


.. opcode:: LOAD_FROM_DICT_OR_GLOBALS (i)

Pops a mapping off the stack and looks up the value for ``co_names[namei]``.
Pops a :term:`mapping` off the stack and looks up the value for ``co_names[namei]``.
If the name is not found there, looks it up in the globals and then the builtins,
similar to :opcode:`LOAD_GLOBAL`.
This is used for loading global variables in
Expand Down Expand Up @@ -1188,7 +1188,7 @@ iterations of the loop.

.. opcode:: BUILD_MAP (count)

Pushes a new dictionary object onto the stack. Pops ``2 * count`` items
Pushes a new :term:`dictionary` object onto the stack. Pops ``2 * count`` items
so that the dictionary holds *count* entries:
``{..., STACK[-4]: STACK[-3], STACK[-2]: STACK[-1]}``.

Expand Down Expand Up @@ -1321,7 +1321,7 @@ iterations of the loop.

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
The module object is pushed onto the stack. The current :term:`namespace` is not affected: for a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
modifies the namespace.


Expand Down Expand Up @@ -1432,7 +1432,7 @@ iterations of the loop.

.. opcode:: LOAD_FAST_BORROW (var_num)

Pushes a borrowed reference to the local ``co_varnames[var_num]`` onto the
Pushes a :term:`borrowed reference` to the local ``co_varnames[var_num]`` onto the
stack.

.. versionadded:: 3.14
Expand Down Expand Up @@ -1511,7 +1511,7 @@ iterations of the loop.

.. opcode:: LOAD_FROM_DICT_OR_DEREF (i)

Pops a mapping off the stack and looks up the name associated with
Pops a :term:`mapping` off the stack and looks up the name associated with
slot ``i`` of the "fast locals" storage in this mapping.
If the name is not found there, loads it from the cell contained in
slot ``i``, similar to :opcode:`LOAD_DEREF`. This is used for loading
Expand Down Expand Up @@ -1564,12 +1564,12 @@ iterations of the loop.

.. opcode:: CALL (argc)

Calls a callable object with the number of arguments specified by ``argc``.
Calls a :term:`callable` object with the number of arguments specified by ``argc``.
On the stack are (in ascending order):

* The callable
* ``self`` or ``NULL``
* The remaining positional arguments
* The remaining :term:`positional arguments <positional argument>`

``argc`` is the total of the positional arguments, excluding ``self``.

Expand All @@ -1583,15 +1583,15 @@ iterations of the loop.
The callable now always appears at the same position on the stack.

.. versionchanged:: 3.13
Calls with keyword arguments are now handled by :opcode:`CALL_KW`.
Calls with :term:`keyword arguments <keyword argument>` are now handled by :opcode:`CALL_KW`.


.. opcode:: CALL_KW (argc)

Calls a callable object with the number of arguments specified by ``argc``,
including one or more named arguments. On the stack are (in ascending order):

* The callable
* The :term:`callable`
* ``self`` or ``NULL``
* The remaining positional arguments
* The named arguments
Expand All @@ -1611,10 +1611,10 @@ iterations of the loop.

Calls a callable object with variable set of positional and keyword
arguments. If the lowest bit of *flags* is set, the top of the stack
contains a mapping object containing additional keyword arguments.
Before the callable is called, the mapping object and iterable object
contains a :term:`mapping` object containing additional :term:`keyword arguments <keyword argument>`.
Before the :term:`callable` is called, the mapping object and :term:`iterable` object
are each "unpacked" and their contents passed in as keyword and
positional arguments respectively.
:term:`positional arguments <positional argument>` respectively.
``CALL_FUNCTION_EX`` 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.
Expand All @@ -1636,7 +1636,7 @@ iterations of the loop.
Pushes a new function object on the stack built from the code object at ``STACK[-1]``.

.. versionchanged:: 3.10
Flag value ``0x04`` is a tuple of strings instead of dictionary
Flag value ``0x04`` is a tuple of strings instead of :term:`dictionary`

.. versionchanged:: 3.11
Qualified name at ``STACK[-1]`` was removed.
Expand All @@ -1655,8 +1655,8 @@ iterations of the loop.
* ``0x01`` a tuple of default values for positional-only and
positional-or-keyword parameters in positional order
* ``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
* ``0x04`` a tuple of strings containing parameters' :term:`annotations <annotation>`
* ``0x08`` a tuple containing cells for :term:`free variables <free variable>`, making a closure

.. versionadded:: 3.13

Expand Down Expand Up @@ -1701,7 +1701,7 @@ iterations of the loop.
* ``oparg == 2``: call :func:`repr` on *value*
* ``oparg == 3``: call :func:`ascii` on *value*

Used for implementing formatted string literals (f-strings).
Used for implementing formatted string literals (:term:`f-strings <f-string>`).

.. versionadded:: 3.13

Expand Down Expand Up @@ -1757,7 +1757,7 @@ iterations of the loop.
The ``context`` operand consists of two parts. The lowest two bits
indicate where the ``RESUME`` occurs:

* ``0`` The start of a function, which is neither a generator, coroutine
* ``0`` The start of a function, which is neither a :term:`generator`, :term:`coroutine`
nor an async generator
* ``1`` After a ``yield`` expression
* ``2`` After a ``yield from`` expression
Expand All @@ -1775,7 +1775,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.
Used as first opcode of in code object for the above mentioned :term:`callables <callable>`.
Clear the current frame and return the newly created generator.

.. versionadded:: 3.11
Expand Down Expand Up @@ -1828,15 +1828,16 @@ iterations of the loop.
| ``INTRINSIC_1_INVALID`` | Not valid |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_PRINT`` | Prints the argument to standard |
| | out. Used in the REPL. |
| | out. Used in the :term:`REPL`. |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_IMPORT_STAR`` | Performs ``import *`` for the |
| | named module. |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_STOPITERATION_ERROR`` | Extracts the return value from a |
| | ``StopIteration`` exception. |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_ASYNC_GEN_WRAP`` | Wraps an async generator value |
| ``INTRINSIC_ASYNC_GEN_WRAP`` | Wraps an async |
| | :term:`generator` value |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_UNARY_POSITIVE`` | Performs the unary ``+`` |
| | operation |
Expand All @@ -1858,7 +1859,7 @@ iterations of the loop.
| | :class:`typing.TypeAliasType`; |
| | used in the :keyword:`type` |
| | statement. The argument is a tuple|
| | of the type alias's name, |
| | of the :term:`type alias`'s name, |
| | type parameters, and value. |
+-----------------------------------+-----------------------------------+

Expand Down Expand Up @@ -1901,7 +1902,7 @@ iterations of the loop.

.. opcode:: LOAD_SPECIAL

Performs special method lookup on ``STACK[-1]``.
Performs :term:`special method` lookup on ``STACK[-1]``.
If ``type(STACK[-1]).__xxx__`` is a method, leave
``type(STACK[-1]).__xxx__; STACK[-1]`` on the stack.
If ``type(STACK[-1]).__xxx__`` is not a method, leave
Expand Down Expand Up @@ -1938,7 +1939,7 @@ but are replaced by real opcodes or removed before bytecode is generated.
``target``.

This variant is used in :keyword:`with` and :keyword:`async with`
constructs, which push the return value of the context manager's
constructs, which push the return value of the :term:`context manager`'s
:meth:`~object.__enter__` or :meth:`~object.__aenter__` to the stack.


Expand Down Expand Up @@ -1996,6 +1997,8 @@ instructions:

.. data:: opmap

Dictionary :term:`mapping`

Dictionary mapping operation names to bytecodes.


Expand Down
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/Documentation/2025-08-15-01-28-04.gh-issue-137352.PMvwxi.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add links to glossary terms in ``dis.rst``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blurbs are not necessary for Docs changes.

Loading