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-97937: dis docs: add adaptive=False (#97939)

Browse source 
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
This commit is contained in:
Jelle Zijlstra 2022-10-25 15:58:04 -07:00 • committed by GitHub
parent 7cfbb49fcd
commit 5d8bf2b106
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 29 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

42
Doc/library/dis.rst
View file

@ -38,7 +38,9 @@ interpreter.
Some instructions are accompanied by one or more inline cache entries, Some instructions are accompanied by one or more inline cache entries,
which take the form of :opcode:`CACHE` instructions. These instructions which take the form of :opcode:`CACHE` instructions. These instructions
are hidden by default, but can be shown by passing ``show_caches=True`` to 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`:: 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 :class:`Bytecode` object that provides easy access to details of the compiled
code. 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 Analyse the bytecode corresponding to a function, generator, asynchronous
generator, coroutine, method, string of source code, or a code object (as 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 disassembled code. Setting this means :meth:`.dis` will display a "current
instruction" marker against the specified opcode. 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) .. classmethod:: from_traceback(tb, *, show_caches=False)
Construct a :class:`Bytecode` instance from the given traceback, setting Construct a :class:`Bytecode` instance from the given traceback, setting
@ -117,7 +125,7 @@ code.
This can now handle coroutine and asynchronous generator objects. This can now handle coroutine and asynchronous generator objects.
.. versionchanged:: 3.11 .. versionchanged:: 3.11
Added the ``show_caches`` parameter. Added the *show_caches* and *adaptive* parameters.
Example: Example:
@ -172,7 +180,7 @@ operation is being performed, so the intermediate analysis object isn't useful:
Added *file* parameter. 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 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 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``. The maximal depth of recursion is limited by *depth* unless it is ``None``.
``depth=0`` means no recursion. ``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 .. versionchanged:: 3.4
Added *file* parameter. 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. This can now handle coroutine and asynchronous generator objects.
.. versionchanged:: 3.11 .. 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 Disassemble the top-of-stack function of a traceback, using the last
traceback if none was passed. The instruction causing the exception is 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. Added *file* parameter.
.. versionchanged:: 3.11 .. 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) .. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)
disco(code, lasti=-1, *, file=None, show_caches=False) disco(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)
Disassemble a code object, indicating the last instruction if *lasti* was Disassemble a code object, indicating the last instruction if *lasti* was
provided. The output is divided in the following columns: 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. Added *file* parameter.
.. versionchanged:: 3.11 .. 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, Return an iterator over the instructions in the supplied function, method,
source code string or code object. 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 source line information (if any) is taken directly from the disassembled code
object. object.
The *show_caches* and *adaptive* parameters work as they do in :func:`dis`.
.. versionadded:: 3.4 .. versionadded:: 3.4
.. versionchanged:: 3.11 .. versionchanged:: 3.11
Added the ``show_caches`` parameter. Added the *show_caches* and *adaptive* parameters.
.. function:: findlinestarts(code) .. function:: findlinestarts(code)