Close #19378: address flaws in the new dis module APIs

- confusing line_offset parameter -> first_line parameter
- systematically test and fix new file parameter
- remove redundant Bytecode.show_info() API
- rename Bytecode.display_code() to Bytecode.dis() and have it
  return the multi-line string rather than printing it directly
- eliminated some not-so-helpful helpers from the bytecode_helper
  test support module

Also fixed a longstanding defect (worked around in the test suite)
where lines emitted by the dis module could include trailing white
space. That no longer happens, allowing the formatting tests to be
simplified to use plain string comparisons.

1 files changed, 23 insertions, 18 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 40aaeeb..79ec9d7 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -44,36 +44,39 @@ 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
+.. class:: Bytecode(x, *, first_line=None)
 
-   The bytecode operations of a piece of code
+   Analyse the bytecode corresponding to a function, method, string of
+   source code, or a code object (as returned by :func:`compile`).
 
-   This is a convenient wrapper around many of the functions listed below.
-   Instantiate it with a function, method, string of code, or a code object
-   (as returned by :func:`compile`).
+   This is a convenience wrapper around many of the functions listed below,
+   most notably :func:`get_instructions`, as iterating over a
+   :class:`ByteCode` instance yields the bytecode operations as
+   :class:`Instruction` instances.
 
-   Iterating over this yields the bytecode operations as :class:`Instruction`
-   instances.
+   If *first_line* is not None, it indicates the line number that should
+   be reported for the first source line in the disassembled code.
+   Otherwise, the source line information (if any) is taken directly from
+   the disassembled code object.
 
    .. data:: codeobj
 
       The compiled code object.
 
-   .. method:: display_code(*, file=None)
+   .. data:: first_line
 
-      Print a formatted view of the bytecode operations, like :func:`dis`.
+      The first source line of the code object (if available)
+
+   .. method:: dis()
+
+      Return a formatted view of the bytecode operations (the same as
+      printed by :func:`dis`, but returned as a multi-line string).
 
    .. method:: info()
 
       Return a formatted multi-line string with detailed information about the
       code object, like :func:`code_info`.
 
-   .. method:: show_info(*, file=None)
-
-      Print the information about the code object as returned by :meth:`info`.
-
-   .. versionadded:: 3.4
-
 Example::
 
     >>> bytecode = dis.Bytecode(myfunc)
@@ -176,7 +179,7 @@ object isn't useful:
       Added ``file`` parameter
 
 
-.. function:: get_instructions(x, *, line_offset=0)
+.. function:: get_instructions(x, *, first_line=None)
 
    Return an iterator over the instructions in the supplied function, method,
    source code string or code object.
@@ -184,8 +187,10 @@ object isn't useful:
    The iterator generates a series of :class:`Instruction` named tuples
    giving the details of each operation in the supplied code.
 
-   The given *line_offset* is added to the ``starts_line`` attribute of any
-   instructions that start a new line.
+   If *first_line* is not None, it indicates the line number that should
+   be reported for the first source line in the disassembled code.
+   Otherwise, the source line information (if any) is taken directly from
+   the disassembled code object.
 
    .. versionadded:: 3.4