Issue #17911: traceback module overhaul

Provide a way to seed the linecache for a PEP-302 module without actually
loading the code.

Provide a new object API for traceback, including the ability to not lookup
lines at all until the traceback is actually rendered, without any trace of the
original objects being kept alive.

Author: rbtcollins

Doc/library/linecache.rst

@@ -43,6 +43,14 @@ The :mod:`linecache` module defines the following functions:
    changed on disk, and you require the updated version.  If *filename* is omitted,
    it will check all the entries in the cache.
 
+.. function:: lazycache(filename, module_globals)
+
+   Capture enough detail about a non-file based module to permit getting its
+   lines later via :func:`getline` even if *module_globals* is None in the later
+   call. This avoids doing I/O until a line is actually needed, without having
+   to carry the module globals around indefinitely.
+
+   .. versionadded:: 3.5
 
 Example::
 

Doc/library/traceback.rst

@@ -136,6 +136,130 @@ The module defines the following functions:
 
    .. versionadded:: 3.4
 
+.. function:: walk_stack(f)
+
+   Walk a stack following f.f_back from the given frame, yielding the frame and
+   line number for each frame. If f is None, the current stack is used.
+   This helper is used with *Stack.extract*.
+
+   .. versionadded:: 3.5
+
+.. function:: walk_tb(tb)
+
+   Walk a traceback following tb_next yielding the frame and line number for
+   each frame. This helper is used with *Stack.extract*.
+
+   .. versionadded:: 3.5
+
+The module also defines the following classes:
+
+:class:`TracebackException` Objects
+-----------------------------------
+
+:class:`.TracebackException` objects are created from actual exceptions to
+capture data for later printing in a lightweight fashion.
+
+.. class:: TracebackException(exc_type, exc_value, exc_traceback, limit=None, lookup_lines=True)
+
+   Capture an exception for later rendering. limit, lookup_lines are as for
+   the :class:`.StackSummary` class.
+
+   .. versionadded:: 3.5
+
+.. classmethod:: `.from_exception`(exc, limit=None, lookup_lines=True)
+
+   Capture an exception for later rendering. limit and lookup_lines
+   are as for the :class:`.StackSummary` class.
+
+   .. versionadded:: 3.5
+
+.. attribute:: `.__cause__` A TracebackException of the original *__cause__*.
+
+.. attribute:: `.__context__` A TracebackException of the original *__context__*.
+.. attribute:: `.__suppress_context__` The *__suppress_context__* value from the
+               original exception.
+.. attribute:: `.stack` A `StackSummary` representing the traceback.
+.. attribute:: `.exc_type` The class of the original traceback.
+.. attribute:: `.filename` For syntax errors - the filename where the error
+               occured.
+.. attribute:: `.lineno` For syntax errors - the linenumber where the error
+               occured.
+.. attribute:: `.text` For syntax errors - the text where the error
+               occured.
+.. attribute:: `.offset` For syntax errors - the offset into the text where the
+               error occured.
+.. attribute:: `.msg` For syntax errors - the compiler error message.
+
+.. method::  TracebackException.format(chain=True)
+
+    Format the exception.
+
+    If chain is not *True*, *__cause__* and *__context__* will not be formatted.
+
+    The return value is a generator of strings, each ending in a newline and
+    some containing internal newlines. `print_exception` is a wrapper around
+    this method which just prints the lines to a file.
+
+    The message indicating which exception occurred is always the last
+    string in the output.
+
+   .. versionadded:: 3.5
+
+.. method::  TracebackException.format_exception_only()
+
+    Format the exception part of the traceback.
+
+    The return value is a generator of strings, each ending in a newline.
+
+    Normally, the generator emits a single string; however, for
+    SyntaxError exceptions, it emites several lines that (when
+    printed) display detailed information about where the syntax
+    error occurred.
+
+    The message indicating which exception occurred is always the last
+    string in the output.
+
+   .. versionadded:: 3.5
+
+
+:class:`StackSummary` Objects
+-----------------------------
+
+:class:`.StackSummary` objects represent a call stack ready for formatting.
+
+.. classmethod:: StackSummary.extract(frame_gen, limit=None, lookup_lines=True)
+
+   Construct a StackSummary object from a frame generator (such as is returned by
+   `walk_stack` or `walk_tb`.
+
+   If limit is supplied, only this many frames are taken from frame_gen.
+   If lookup_lines is False, the returned FrameSummary objects will not have read
+   their lines in yet, making the cost of creating the StackSummary cheaper (which
+   may be valuable if it may not actually get formatted).
+
+   .. versionadded:: 3.5
+
+.. classmethod:: StackSummary.from_list(a_list)
+
+   Construct a StackSummary object from a supplied old-style list of tuples. Each
+   tuple should be a 4-tuple with filename, lineno, name, line as the elements.
+
+   .. versionadded:: 3.5
+
+:class:`FrameSummary` Objects
+-----------------------------
+
+FrameSummary objects represent a single frame in a traceback.
+
+.. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)
+   :noindex:
+
+   Represent a single frame in the traceback or stack that is being formatted
+   or printed. It may optionally have a stringified version of the frames
+   locals included in it. If *lookup_line* is False, the source code is not
+   looked up until the FrameSummary has the :attr:`line` attribute accessed (which
+   also happens when casting it to a tuple). Line may be directly provided, and
+   will prevent line lookups happening at all.
 
 .. _traceback-example:
 

Lib/linecache.py

@@ -5,6 +5,7 @@
 that name.
 """
 
+import functools
 import sys
 import os
 import tokenize
@@ -21,7 +22,9 @@ def getline(filename, lineno, module_globals=None):
 
 # The cache
 
-cache = {} # The cache
+# The cache. Maps filenames to either a thunk which will provide source code,
+# or a tuple (size, mtime, lines, fullname) once loaded.
+cache = {}
 
 
 def clearcache():
@@ -36,6 +39,9 @@ def getlines(filename, module_globals=None):
     Update the cache if it doesn't contain an entry for this file already."""
 
     if filename in cache:
+        entry = cache[filename]
+        if len(entry) == 1:
+            return updatecache(filename, module_globals)
         return cache[filename][2]
     else:
         return updatecache(filename, module_globals)
@@ -54,7 +60,11 @@ def checkcache(filename=None):
             return
 
     for filename in filenames:
-        size, mtime, lines, fullname = cache[filename]
+        entry = cache[filename]
+        if len(entry) == 1:
+            # lazy cache entry, leave it lazy.
+            continue
+        size, mtime, lines, fullname = entry
         if mtime is None:
             continue   # no-op for files loaded via a __loader__
         try:
@@ -72,7 +82,8 @@ def updatecache(filename, module_globals=None):
     and return an empty list."""
 
     if filename in cache:
-        del cache[filename]
+        if len(cache[filename]) != 1:
+            del cache[filename]
     if not filename or (filename.startswith('<') and filename.endswith('>')):
         return []
 
@@ -82,27 +93,23 @@ def updatecache(filename, module_globals=None):
     except OSError:
         basename = filename
 
-        # Try for a __loader__, if available
-        if module_globals and '__loader__' in module_globals:
-            name = module_globals.get('__name__')
-            loader = module_globals['__loader__']
-            get_source = getattr(loader, 'get_source', None)
-
-            if name and get_source:
-                try:
-                    data = get_source(name)
-                except (ImportError, OSError):
-                    pass
-                else:
-                    if data is None:
-                        # No luck, the PEP302 loader cannot find the source
-                        # for this module.
-                        return []
-                    cache[filename] = (
-                        len(data), None,
-                        [line+'\n' for line in data.splitlines()], fullname
-                    )
-                    return cache[filename][2]
+        # Realise a lazy loader based lookup if there is one
+        # otherwise try to lookup right now.
+        if lazycache(filename, module_globals):
+            try:
+                data = cache[filename][0]()
+            except (ImportError, OSError):
+                pass
+            else:
+                if data is None:
+                    # No luck, the PEP302 loader cannot find the source
+                    # for this module.
+                    return []
+                cache[filename] = (
+                    len(data), None,
+                    [line+'\n' for line in data.splitlines()], fullname
+                )
+                return cache[filename][2]
 
         # Try looking through the module search path, which is only useful
         # when handling a relative filename.
@@ -132,3 +139,36 @@ def updatecache(filename, module_globals=None):
     size, mtime = stat.st_size, stat.st_mtime
     cache[filename] = size, mtime, lines, fullname
     return lines
+
+
+def lazycache(filename, module_globals):
+    """Seed the cache for filename with module_globals.
+
+    The module loader will be asked for the source only when getlines is
+    called, not immediately.
+
+    If there is an entry in the cache already, it is not altered.
+
+    :return: True if a lazy load is registered in the cache,
+        otherwise False. To register such a load a module loader with a
+        get_source method must be found, the filename must be a cachable
+        filename, and the filename must not be already cached.
+    """
+    if filename in cache:
+        if len(cache[filename]) == 1:
+            return True
+        else:
+            return False
+    if not filename or (filename.startswith('<') and filename.endswith('>')):
+        return False
+    # Try for a __loader__, if available
+    if module_globals and '__loader__' in module_globals:
+        name = module_globals.get('__name__')
+        loader = module_globals['__loader__']
+        get_source = getattr(loader, 'get_source', None)
+
+        if name and get_source:
+            get_lines = functools.partial(get_source, name)
+            cache[filename] = (get_lines,)
+            return True
+    return False

Lib/test/test_linecache.py

@@ -7,6 +7,7 @@
 
 
 FILENAME = linecache.__file__
+NONEXISTENT_FILENAME = FILENAME + '.missing'
 INVALID_NAME = '!@$)(!@#_1'
 EMPTY = ''
 TESTS = 'inspect_fodder inspect_fodder2 mapping_tests'
@@ -126,6 +127,49 @@ def test_checkcache(self):
                 self.assertEqual(line, getline(source_name, index + 1))
                 source_list.append(line)
 
+    def test_lazycache_no_globals(self):
+        lines = linecache.getlines(FILENAME)
+        linecache.clearcache()
+        self.assertEqual(False, linecache.lazycache(FILENAME, None))
+        self.assertEqual(lines, linecache.getlines(FILENAME))
+
+    def test_lazycache_smoke(self):
+        lines = linecache.getlines(NONEXISTENT_FILENAME, globals())
+        linecache.clearcache()
+        self.assertEqual(
+            True, linecache.lazycache(NONEXISTENT_FILENAME, globals()))
+        self.assertEqual(1, len(linecache.cache[NONEXISTENT_FILENAME]))
+        # Note here that we're looking up a non existant filename with no
+        # globals: this would error if the lazy value wasn't resolved.
+        self.assertEqual(lines, linecache.getlines(NONEXISTENT_FILENAME))
+
+    def test_lazycache_provide_after_failed_lookup(self):
+        linecache.clearcache()
+        lines = linecache.getlines(NONEXISTENT_FILENAME, globals())
+        linecache.clearcache()
+        linecache.getlines(NONEXISTENT_FILENAME)
+        linecache.lazycache(NONEXISTENT_FILENAME, globals())
+        self.assertEqual(lines, linecache.updatecache(NONEXISTENT_FILENAME))
+
+    def test_lazycache_check(self):
+        linecache.clearcache()
+        linecache.lazycache(NONEXISTENT_FILENAME, globals())
+        linecache.checkcache()
+
+    def test_lazycache_bad_filename(self):
+        linecache.clearcache()
+        self.assertEqual(False, linecache.lazycache('', globals()))
+        self.assertEqual(False, linecache.lazycache('<foo>', globals()))
+
+    def test_lazycache_already_cached(self):
+        linecache.clearcache()
+        lines = linecache.getlines(NONEXISTENT_FILENAME, globals())
+        self.assertEqual(
+            False,
+            linecache.lazycache(NONEXISTENT_FILENAME, globals()))
+        self.assertEqual(4, len(linecache.cache[NONEXISTENT_FILENAME]))
+
+
 def test_main():
     support.run_unittest(LineCacheTests)