bpo-11822: Improve disassembly to show embedded code objects. (#1844)

The depth argument limits recursion.

1 files changed, 11 insertions, 2 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index f82dc40..bc32380 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -138,23 +138,32 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
 
-.. function:: dis(x=None, *, file=None)
+.. function:: dis(x=None, *, file=None, depth=None)
 
    Disassemble the *x* object.  *x* can denote either a module, a class, a
    method, a function, a generator, 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.  Strings are first compiled to code objects with the :func:`compile`
+   instruction.  It also recursively disassembles nested code objects (the code
+   of comprehensions, generator expressions and nested functions, and the code
+   used for building nested classes).
+   Strings are first compiled to code objects with the :func:`compile`
    built-in function before being disassembled.  If no object is provided, this
    function disassembles the last traceback.
 
    The disassembly is written as text to the supplied *file* argument if
    provided and to ``sys.stdout`` otherwise.
 
+   The maximal depth of recursion is limited by *depth* unless it is ``None``.
+   ``depth=0`` means no recursion.
+
    .. versionchanged:: 3.4
       Added *file* parameter.
 
+   .. versionchanged:: 3.7
+      Implemented recursive disassembling and added *depth* parameter.
+
 
 .. function:: distb(tb=None, *, file=None)