gh-97937: dis docs: add adaptive=False (#97939)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>

1 files changed, 29 insertions, 13 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 33df7be..c6b4303 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -38,7 +38,9 @@ interpreter.
       Some instructions are accompanied by one or more inline cache entries,
       which take the form of :opcode:`CACHE` instructions. These instructions
       are hidden by default, but can be shown by passing ``show_caches=True`` to
-      any :mod:`dis` utility.
+      any :mod:`dis` utility. Furthermore, the interpreter now adapts the
+      bytecode to specialize it for different runtime conditions. The
+      adaptive bytecode can be shown by passing ``adaptive=True``.
 
 
 Example: Given the function :func:`myfunc`::
@@ -70,8 +72,8 @@ The bytecode analysis API allows pieces of Python code to be wrapped in a
 :class:`Bytecode` object that provides easy access to details of the compiled
 code.
 
-.. class:: Bytecode(x, *, first_line=None, current_offset=None, show_caches=False)
-
+.. class:: Bytecode(x, *, first_line=None, current_offset=None,\
+                    show_caches=False, adaptive=False)
 
    Analyse the bytecode corresponding to a function, generator, asynchronous
    generator, coroutine, method, string of source code, or a code object (as
@@ -90,6 +92,12 @@ code.
    disassembled code. Setting this means :meth:`.dis` will display a "current
    instruction" marker against the specified opcode.
 
+   If *show_caches* is ``True``, :meth:`.dis` will display inline cache
+   entries used by the interpreter to specialize the bytecode.
+
+   If *adaptive* is ``True``, :meth:`.dis` will display specialized bytecode
+   that may be different from the original bytecode.
+
    .. classmethod:: from_traceback(tb, *, show_caches=False)
 
       Construct a :class:`Bytecode` instance from the given traceback, setting
@@ -117,7 +125,7 @@ code.
       This can now handle coroutine and asynchronous generator objects.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 Example:
 
@@ -172,7 +180,7 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
 
-.. function:: dis(x=None, *, file=None, depth=None, show_caches=False)
+.. function:: dis(x=None, *, file=None, depth=None, show_caches=False, adaptive=False)
 
    Disassemble the *x* object.  *x* can denote either a module, a class, a
    method, a function, a generator, an asynchronous generator, a coroutine,
@@ -193,6 +201,12 @@ operation is being performed, so the intermediate analysis object isn't useful:
    The maximal depth of recursion is limited by *depth* unless it is ``None``.
    ``depth=0`` means no recursion.
 
+   If *show_caches* is ``True``, this function will display inline cache
+   entries used by the interpreter to specialize the bytecode.
+
+   If *adaptive* is ``True``, this function will display specialized bytecode
+   that may be different from the original bytecode.
+
    .. versionchanged:: 3.4
       Added *file* parameter.
 
@@ -203,10 +217,10 @@ operation is being performed, so the intermediate analysis object isn't useful:
       This can now handle coroutine and asynchronous generator objects.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
-.. function:: distb(tb=None, *, file=None, show_caches=False)
+.. function:: distb(tb=None, *, file=None, show_caches=False, adaptive=False)
 
    Disassemble the top-of-stack function of a traceback, using the last
    traceback if none was passed.  The instruction causing the exception is
@@ -219,11 +233,11 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
-.. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False)
-              disco(code, lasti=-1, *, file=None, show_caches=False)
+.. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)
+              disco(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)
 
    Disassemble a code object, indicating the last instruction if *lasti* was
    provided.  The output is divided in the following columns:
@@ -246,10 +260,10 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
-.. function:: get_instructions(x, *, first_line=None, show_caches=False)
+.. function:: get_instructions(x, *, first_line=None, show_caches=False, adaptive=False)
 
    Return an iterator over the instructions in the supplied function, method,
    source code string or code object.
@@ -262,10 +276,12 @@ operation is being performed, so the intermediate analysis object isn't useful:
    source line information (if any) is taken directly from the disassembled code
    object.
 
+   The *show_caches* and *adaptive* parameters work as they do in :func:`dis`.
+
    .. versionadded:: 3.4
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
 .. function:: findlinestarts(code)