gh-140456: Clarify traceback source line documentation

Author: harjothkhara

Doc/library/traceback.rst

@@ -172,8 +172,10 @@ Module-Level Functions
    :func:`extract_tb` or :func:`extract_stack`, return a list of strings ready
    for printing.  Each string in the resulting list corresponds to the item with
    the same index in the argument list.  Each string ends in a newline; the
-   strings may contain internal newlines as well, for those items whose source
-   text line is not ``None``.
+   strings may contain internal newlines as well, for items with column position
+   information whose source text spans multiple physical lines.  When
+   column position information is unavailable, only the first physical line is
+   displayed.  Old-style tuples never have column position information.
 
 
 .. function:: format_exception_only(exc, /[, value], *, show_group=False)
@@ -471,14 +473,20 @@ the module-level functions described above.
       :class:`FrameSummary` objects or old-style list of tuples.  Each tuple
       should be a 4-tuple with *filename*, *lineno*, *name*, *line* as the
       elements.
+      Old-style tuples do not have column position information, so only the
+      first physical line of *line* is displayed when they are formatted.  The
+      same applies to :class:`FrameSummary` objects without column position
+      information.
 
    .. method:: format()
 
       Returns a list of strings ready for printing.  Each string in the
       resulting list corresponds to a single :ref:`frame <frame-objects>` from
       the stack.
-      Each string ends in a newline; the strings may contain internal
-      newlines as well, for those items with source text lines.
+      Each string ends in a newline.  For frames with column position
+      information, the strings may contain internal newlines when the source
+      text spans multiple physical lines.  Otherwise, only the first physical
+      line is displayed.
 
       For long sequences of the same frame and line, the first few
       repetitions are shown, followed by a summary line stating the exact
@@ -540,7 +548,7 @@ in a :ref:`traceback <traceback-objects>`.
 
    .. attribute:: FrameSummary.line
 
-      A string representing the source code for this frame, with leading and
+      The first physical line of source code for this frame, with leading and
       trailing whitespace stripped.
       If the source is not available, it is ``None``.
 

Lib/test/test_traceback.py

@@ -3354,6 +3354,10 @@ def test_explicit_line(self):
         f = traceback.FrameSummary("f", 1, "dummy", line="line")
         self.assertEqual("line", f.line)
 
+    def test_explicit_multiline_line(self):
+        f = traceback.FrameSummary("f", 1, "dummy", line="line 1\nline 2")
+        self.assertEqual("line 1", f.line)
+
     def test_len(self):
         f = traceback.FrameSummary("f", 1, "dummy", line="line")
         self.assertEqual(len(f), 4)
@@ -3415,6 +3419,29 @@ def test_from_list(self):
             ['  File "foo.py", line 1, in fred\n    line\n'],
             s.format())
 
+    def test_from_list_multiline_without_columns(self):
+        for frame in [
+            ('foo.py', 1, 'fred', 'line 1\nline 2'),
+            traceback.FrameSummary(
+                'foo.py', 1, 'fred', line='line 1\nline 2'),
+        ]:
+            with self.subTest(frame=frame):
+                s = traceback.StackSummary.from_list([frame])
+                self.assertEqual(
+                    ['  File "foo.py", line 1, in fred\n    line 1\n'],
+                    s.format())
+
+    def test_from_list_multiline_with_columns(self):
+        frame = traceback.FrameSummary(
+            'foo.py', 1, 'fred', line='line 1\nline 2',
+            end_lineno=2, colno=0, end_colno=6)
+        s = traceback.StackSummary.from_list([frame])
+        self.assertEqual(
+            ['  File "foo.py", line 1, in fred\n'
+             '    line 1\n'
+             '    line 2\n'],
+            s.format())
+
     def test_from_list_edited_stack(self):
         s = traceback.StackSummary.from_list([('foo.py', 1, 'fred', 'line')])
         s[0] = ('foo.py', 2, 'fred', 'line')

Lib/traceback.py

@@ -84,8 +84,11 @@ def format_list(extracted_list):
 
     Each string in the resulting list corresponds to the item with the
     same index in the argument list.  Each string ends in a newline;
-    the strings may contain internal newlines as well, for those items
-    whose source text line is not None.
+    the strings may contain internal newlines as well, for items with
+    column position information whose source text spans multiple physical
+    lines.  When column position information is unavailable, only
+    the first physical line is displayed.  Old-style tuples never have
+    column position information.
     """
     return StackSummary.from_list(extracted_list).format()
 
@@ -324,8 +327,8 @@ class FrameSummary:
       active when the frame was captured.
     - :attr:`name` The name of the function or method that was executing
       when the frame was captured.
-    - :attr:`line` The text from the linecache module for the line
-      of code that was running when the frame was captured.
+    - :attr:`line` The first physical line of code that was running when
+      the frame was captured.
     - :attr:`locals` Either None if locals were not supplied, or a dict
       mapping the name to the repr() of the variable.
     - :attr:`end_lineno` The last line number of the source code for this frame.
@@ -558,6 +561,11 @@ def from_list(klass, a_list):
         """
         Create a StackSummary object from a supplied list of
         FrameSummary objects or old-style list of tuples.
+
+        Old-style tuples do not have column position information, so only the
+        first physical line of the line element is displayed when they are
+        formatted.  The same applies to FrameSummary objects without column
+        position information.
         """
         # While doing a fast-path check for isinstance(a_list, StackSummary) is
         # appealing, idlelib.run.cleanup_traceback and other similar code may
@@ -794,8 +802,10 @@ def format(self, **kwargs):
 
         Returns a list of strings ready for printing.  Each string in the
         resulting list corresponds to a single frame from the stack.
-        Each string ends in a newline; the strings may contain internal
-        newlines as well, for those items with source text lines.
+        Each string ends in a newline.  For frames with column position
+        information, the strings may contain internal newlines when the source
+        text spans multiple physical lines.  Otherwise, only the first physical
+        line is displayed.
 
         For long sequences of the same frame and line, the first few
         repetitions are shown, followed by a summary line stating the exact