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 whose source text
+   spans multiple physical lines and has column position information.  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,6 +473,10 @@ 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()
 
@@ -540,7 +546,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,18 @@ 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_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 whose
+    source text spans multiple physical lines and has column position
+    information.  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