From 5cdee3710462ea4d41e0f7f2d79a4ce4e54e8c76 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Wed, 5 Oct 2022 15:34:32 -0700 Subject: [PATCH 1/4] gh-97937: dis docs: add adaptive=False --- Doc/library/dis.rst | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 47e4bf600721701..9454b40ab7b81a6 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -34,7 +34,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 the types of objects it encounters. The + adapted bytecode can be shown by passing ``adaptive=True``. Example: Given the function :func:`myfunc`:: @@ -66,7 +68,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 @@ -86,6 +89,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 @@ -113,7 +122,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: @@ -168,7 +177,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, @@ -189,6 +198,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. @@ -199,10 +214,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 @@ -215,11 +230,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: @@ -242,10 +257,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. @@ -258,10 +273,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 function as in :func:`dis`. + .. versionadded:: 3.4 .. versionchanged:: 3.11 - Added the ``show_caches`` parameter. + Added the *show_caches* and *adaptive* parameters. .. function:: findlinestarts(code) From 0b7497f0ff978f8e30c9b9fbbd0c6abd99e8280d Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Wed, 5 Oct 2022 16:04:00 -0700 Subject: [PATCH 2/4] fix docs build --- Doc/library/dis.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 9454b40ab7b81a6..2e84ac0fe0cd19d 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -68,9 +68,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, - adaptive=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 From 57697f175a198a606f687db4abd19ccf14973c07 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Thu, 6 Oct 2022 04:19:41 -0700 Subject: [PATCH 3/4] Update Doc/library/dis.rst Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- Doc/library/dis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 2e84ac0fe0cd19d..a118c426da55a29 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -272,7 +272,7 @@ 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 function as in :func:`dis`. + The *show_caches* and *adaptive* parameters work as they do in :func:`dis`. .. versionadded:: 3.4 From b9eb5f6d41d5c930721c5738ec6a2a451112d197 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 25 Oct 2022 11:22:33 -0700 Subject: [PATCH 4/4] Update Doc/library/dis.rst Co-authored-by: Brandt Bucher --- Doc/library/dis.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index a118c426da55a29..87617e6f9bc8a81 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -35,8 +35,8 @@ interpreter. 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. Furthermore, the interpreter now adapts the - bytecode to specialize it for the types of objects it encounters. The - adapted bytecode can be shown by passing ``adaptive=True``. + bytecode to specialize it for different runtime conditions. The + adaptive bytecode can be shown by passing ``adaptive=True``. Example: Given the function :func:`myfunc`::