add docs

python · iritkatriel · Aug 21, 2024 · Aug 20, 2024 · Aug 20, 2024 · Aug 20, 2024
commit 7a608e7c6a6e2244ca281d6992de0763aea1bd19
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
@@ -56,6 +56,10 @@ interpreter.
       for jump targets and exception handlers. The ``-O`` command line
       option and the ``show_offsets`` argument were added.
 
+   .. versionchanged:: 3.14
+      Add the :option:`-K <dis --show-positions>` command-line option
+      and the ``show_positions`` argument.
+
 Example: Given the function :func:`!myfunc`::
 
    def myfunc(alist):
@@ -85,7 +89,7 @@ The :mod:`dis` module can be invoked as a script from the command line:
 
 .. code-block:: sh
 
-   python -m dis [-h] [-C] [-O] [infile]
+   python -m dis [-h] [-C] [-O] [-K] [infile]
 
 The following options are accepted:
 
@@ -103,6 +107,10 @@ The following options are accepted:
 
    Show offsets of instructions.
 
+.. cmdoption:: -K, --show-positions
+
+   Show positions of instructions.
+
 If :file:`infile` is specified, its disassembled code will be written to stdout.
 Otherwise, disassembly is performed on compiled source code received from stdin.
 
@@ -116,7 +124,8 @@ The bytecode analysis API allows pieces of Python code to be wrapped in a
 code.
 
 .. class:: Bytecode(x, *, first_line=None, current_offset=None,\
-                    show_caches=False, adaptive=False, show_offsets=False)
+                    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
@@ -144,6 +153,9 @@ code.
    If *show_offsets* is ``True``, :meth:`.dis` will include instruction
    offsets in the output.
 
+   If *show_positions* is ``True``, :meth:`.dis` will include instruction
+   positions in the output.
+
    .. classmethod:: from_traceback(tb, *, show_caches=False)
 
       Construct a :class:`Bytecode` instance from the given traceback, setting
@@ -173,6 +185,12 @@ code.
    .. versionchanged:: 3.11
       Added the *show_caches* and *adaptive* parameters.
 
+   .. versionchanged:: 3.13
+      Added the *show_offsets* parameter
+
+   .. versionchanged:: 3.14
+      Added the *show_positions* parameter.
+
 Example:
 
 .. doctest::
@@ -226,7 +244,8 @@ 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, adaptive=False)
+.. function:: dis(x=None, *, file=None, depth=None, show_caches=False,
+                  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,
@@ -265,9 +284,14 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.11
       Added the *show_caches* and *adaptive* parameters.
 
+   .. versionchanged:: 3.13
+      Added the *show_offsets* parameter.
+
+   .. versionchanged:: 3.14
+      Added the *show_positions* parameter.
 
 .. function:: distb(tb=None, *, file=None, show_caches=False, adaptive=False,
-                    show_offset=False)
+                    show_offset=False, show_positions=False)
 
    Disassemble the top-of-stack function of a traceback, using the last
    traceback if none was passed.  The instruction causing the exception is
@@ -285,14 +309,18 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.13
       Added the *show_offsets* parameter.
 
+   .. versionchanged:: 3.14
+      Added the *show_positions* parameter.
+
 .. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)
               disco(code, lasti=-1, *, file=None, show_caches=False, adaptive=False,
-              show_offsets=False)
+              show_offsets=False, show_positions=False)
 
    Disassemble a code object, indicating the last instruction if *lasti* was
    provided.  The output is divided in the following columns:
 
-   #. the line number, for the first instruction of each line
+   #. the line number, for the first instruction of each line, or the
+      instruction positions if *show_positions* is true.
    #. the current instruction, indicated as ``-->``,
    #. a labelled instruction, indicated with ``>>``,
    #. the address of the instruction,
@@ -315,6 +343,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.13
       Added the *show_offsets* parameter.
 
+   .. versionchanged:: 3.14
+      Added the *show_positions* parameter.
+
 .. function:: get_instructions(x, *, first_line=None, show_caches=False, adaptive=False)
 
    Return an iterator over the instructions in the supplied function, method,