traceback.py (26136B)
- """Extract, format and print information about Python stack traces."""
- import collections
- import itertools
- import linecache
- import sys
- __all__ = ['extract_stack', 'extract_tb', 'format_exception',
- 'format_exception_only', 'format_list', 'format_stack',
- 'format_tb', 'print_exc', 'format_exc', 'print_exception',
- 'print_last', 'print_stack', 'print_tb', 'clear_frames',
- 'FrameSummary', 'StackSummary', 'TracebackException',
- 'walk_stack', 'walk_tb']
- #
- # Formatting and printing lists of traceback lines.
- #
- def print_list(extracted_list, file=None):
- """Print the list of tuples as returned by extract_tb() or
- extract_stack() as a formatted stack trace to the given file."""
- if file is None:
- file = sys.stderr
- for item in StackSummary.from_list(extracted_list).format():
- print(item, file=file, end="")
- def format_list(extracted_list):
- """Format a list of tuples or FrameSummary objects for printing.
- Given a list of tuples or FrameSummary objects as returned by
- extract_tb() or 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.
- """
- return StackSummary.from_list(extracted_list).format()
- #
- # Printing and Extracting Tracebacks.
- #
- def print_tb(tb, limit=None, file=None):
- """Print up to 'limit' stack trace entries from the traceback 'tb'.
- If 'limit' is omitted or None, all entries are printed. If 'file'
- is omitted or None, the output goes to sys.stderr; otherwise
- 'file' should be an open file or file-like object with a write()
- method.
- """
- print_list(extract_tb(tb, limit=limit), file=file)
- def format_tb(tb, limit=None):
- """A shorthand for 'format_list(extract_tb(tb, limit))'."""
- return extract_tb(tb, limit=limit).format()
- def extract_tb(tb, limit=None):
- """
- Return a StackSummary object representing a list of
- pre-processed entries from traceback.
- This is useful for alternate formatting of stack traces. If
- 'limit' is omitted or None, all entries are extracted. A
- pre-processed stack trace entry is a FrameSummary object
- containing attributes filename, lineno, name, and line
- representing the information that is usually printed for a stack
- trace. The line is a string with leading and trailing
- whitespace stripped; if the source is not available it is None.
- """
- return StackSummary.extract(walk_tb(tb), limit=limit)
- #
- # Exception formatting and output.
- #
- _cause_message = (
- "\nThe above exception was the direct cause "
- "of the following exception:\n\n")
- _context_message = (
- "\nDuring handling of the above exception, "
- "another exception occurred:\n\n")
- class _Sentinel:
- def __repr__(self):
- return "<implicit>"
- _sentinel = _Sentinel()
- def _parse_value_tb(exc, value, tb):
- if (value is _sentinel) != (tb is _sentinel):
- raise ValueError("Both or neither of value and tb must be given")
- if value is tb is _sentinel:
- if exc is not None:
- return exc, exc.__traceback__
- else:
- return None, None
- return value, tb
- def print_exception(exc, /, value=_sentinel, tb=_sentinel, limit=None, \
- file=None, chain=True):
- """Print exception up to 'limit' stack trace entries from 'tb' to 'file'.
- This differs from print_tb() in the following ways: (1) if
- traceback is not None, it prints a header "Traceback (most recent
- call last):"; (2) it prints the exception type and value after the
- stack trace; (3) if type is SyntaxError and value has the
- appropriate format, it prints the line where the syntax error
- occurred with a caret on the next line indicating the approximate
- position of the error.
- """
- value, tb = _parse_value_tb(exc, value, tb)
- if file is None:
- file = sys.stderr
- te = TracebackException(type(value), value, tb, limit=limit, compact=True)
- for line in te.format(chain=chain):
- print(line, file=file, end="")
- def format_exception(exc, /, value=_sentinel, tb=_sentinel, limit=None, \
- chain=True):
- """Format a stack trace and the exception information.
- The arguments have the same meaning as the corresponding arguments
- to print_exception(). The return value is a list of strings, each
- ending in a newline and some containing internal newlines. When
- these lines are concatenated and printed, exactly the same text is
- printed as does print_exception().
- """
- value, tb = _parse_value_tb(exc, value, tb)
- te = TracebackException(type(value), value, tb, limit=limit, compact=True)
- return list(te.format(chain=chain))
- def format_exception_only(exc, /, value=_sentinel):
- """Format the exception part of a traceback.
- The return value is a list of strings, each ending in a newline.
- Normally, the list contains a single string; however, for
- SyntaxError exceptions, it contains 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 list.
- """
- if value is _sentinel:
- value = exc
- te = TracebackException(type(value), value, None, compact=True)
- return list(te.format_exception_only())
- # -- not official API but folk probably use these two functions.
- def _format_final_exc_line(etype, value):
- valuestr = _some_str(value)
- if value is None or not valuestr:
- line = "%s\n" % etype
- else:
- line = "%s: %s\n" % (etype, valuestr)
- return line
- def _some_str(value):
- try:
- return str(value)
- except:
- return '<unprintable %s object>' % type(value).__name__
- # --
- def print_exc(limit=None, file=None, chain=True):
- """Shorthand for 'print_exception(*sys.exc_info(), limit, file)'."""
- print_exception(*sys.exc_info(), limit=limit, file=file, chain=chain)
- def format_exc(limit=None, chain=True):
- """Like print_exc() but return a string."""
- return "".join(format_exception(*sys.exc_info(), limit=limit, chain=chain))
- def print_last(limit=None, file=None, chain=True):
- """This is a shorthand for 'print_exception(sys.last_type,
- sys.last_value, sys.last_traceback, limit, file)'."""
- if not hasattr(sys, "last_type"):
- raise ValueError("no last exception")
- print_exception(sys.last_type, sys.last_value, sys.last_traceback,
- limit, file, chain)
- #
- # Printing and Extracting Stacks.
- #
- def print_stack(f=None, limit=None, file=None):
- """Print a stack trace from its invocation point.
- The optional 'f' argument can be used to specify an alternate
- stack frame at which to start. The optional 'limit' and 'file'
- arguments have the same meaning as for print_exception().
- """
- if f is None:
- f = sys._getframe().f_back
- print_list(extract_stack(f, limit=limit), file=file)
- def format_stack(f=None, limit=None):
- """Shorthand for 'format_list(extract_stack(f, limit))'."""
- if f is None:
- f = sys._getframe().f_back
- return format_list(extract_stack(f, limit=limit))
- def extract_stack(f=None, limit=None):
- """Extract the raw traceback from the current stack frame.
- The return value has the same format as for extract_tb(). The
- optional 'f' and 'limit' arguments have the same meaning as for
- print_stack(). Each item in the list is a quadruple (filename,
- line number, function name, text), and the entries are in order
- from oldest to newest stack frame.
- """
- if f is None:
- f = sys._getframe().f_back
- stack = StackSummary.extract(walk_stack(f), limit=limit)
- stack.reverse()
- return stack
- def clear_frames(tb):
- "Clear all references to local variables in the frames of a traceback."
- while tb is not None:
- try:
- tb.tb_frame.clear()
- except RuntimeError:
- # Ignore the exception raised if the frame is still executing.
- pass
- tb = tb.tb_next
- class FrameSummary:
- """A single frame from a traceback.
- - :attr:`filename` The filename for the frame.
- - :attr:`lineno` The line within filename for the frame that was
- 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
- 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.
- """
- __slots__ = ('filename', 'lineno', 'name', '_line', 'locals')
- def __init__(self, filename, lineno, name, *, lookup_line=True,
- locals=None, line=None):
- """Construct a FrameSummary.
- :param lookup_line: If True, `linecache` is consulted for the source
- code line. Otherwise, the line will be looked up when first needed.
- :param locals: If supplied the frame locals, which will be captured as
- object representations.
- :param line: If provided, use this instead of looking up the line in
- the linecache.
- """
- self.filename = filename
- self.lineno = lineno
- self.name = name
- self._line = line
- if lookup_line:
- self.line
- self.locals = {k: repr(v) for k, v in locals.items()} if locals else None
- def __eq__(self, other):
- if isinstance(other, FrameSummary):
- return (self.filename == other.filename and
- self.lineno == other.lineno and
- self.name == other.name and
- self.locals == other.locals)
- if isinstance(other, tuple):
- return (self.filename, self.lineno, self.name, self.line) == other
- return NotImplemented
- def __getitem__(self, pos):
- return (self.filename, self.lineno, self.name, self.line)[pos]
- def __iter__(self):
- return iter([self.filename, self.lineno, self.name, self.line])
- def __repr__(self):
- return "<FrameSummary file {filename}, line {lineno} in {name}>".format(
- filename=self.filename, lineno=self.lineno, name=self.name)
- def __len__(self):
- return 4
- @property
- def line(self):
- if self._line is None:
- if self.lineno is None:
- return None
- self._line = linecache.getline(self.filename, self.lineno)
- return self._line.strip()
- def walk_stack(f):
- """Walk a stack yielding the frame and line number for each frame.
- This will follow f.f_back from the given frame. If no frame is given, the
- current stack is used. Usually used with StackSummary.extract.
- """
- if f is None:
- f = sys._getframe().f_back.f_back
- while f is not None:
- yield f, f.f_lineno
- f = f.f_back
- def walk_tb(tb):
- """Walk a traceback yielding the frame and line number for each frame.
- This will follow tb.tb_next (and thus is in the opposite order to
- walk_stack). Usually used with StackSummary.extract.
- """
- while tb is not None:
- yield tb.tb_frame, tb.tb_lineno
- tb = tb.tb_next
- _RECURSIVE_CUTOFF = 3 # Also hardcoded in traceback.c.
- class StackSummary(list):
- """A stack of frames."""
- @classmethod
- def extract(klass, frame_gen, *, limit=None, lookup_lines=True,
- capture_locals=False):
- """Create a StackSummary from a traceback or stack object.
- :param frame_gen: A generator that yields (frame, lineno) tuples to
- include in the stack.
- :param limit: None to include all frames or the number of frames to
- include.
- :param lookup_lines: If True, lookup lines for each frame immediately,
- otherwise lookup is deferred until the frame is rendered.
- :param capture_locals: If True, the local variables from each frame will
- be captured as object representations into the FrameSummary.
- """
- if limit is None:
- limit = getattr(sys, 'tracebacklimit', None)
- if limit is not None and limit < 0:
- limit = 0
- if limit is not None:
- if limit >= 0:
- frame_gen = itertools.islice(frame_gen, limit)
- else:
- frame_gen = collections.deque(frame_gen, maxlen=-limit)
- result = klass()
- fnames = set()
- for f, lineno in frame_gen:
- co = f.f_code
- filename = co.co_filename
- name = co.co_name
- fnames.add(filename)
- linecache.lazycache(filename, f.f_globals)
- # Must defer line lookups until we have called checkcache.
- if capture_locals:
- f_locals = f.f_locals
- else:
- f_locals = None
- result.append(FrameSummary(
- filename, lineno, name, lookup_line=False, locals=f_locals))
- for filename in fnames:
- linecache.checkcache(filename)
- # If immediate lookup was desired, trigger lookups now.
- if lookup_lines:
- for f in result:
- f.line
- return result
- @classmethod
- def from_list(klass, a_list):
- """
- Create a StackSummary object from a supplied list of
- FrameSummary objects or old-style list of tuples.
- """
- # While doing a fast-path check for isinstance(a_list, StackSummary) is
- # appealing, idlelib.run.cleanup_traceback and other similar code may
- # break this by making arbitrary frames plain tuples, so we need to
- # check on a frame by frame basis.
- result = StackSummary()
- for frame in a_list:
- if isinstance(frame, FrameSummary):
- result.append(frame)
- else:
- filename, lineno, name, line = frame
- result.append(FrameSummary(filename, lineno, name, line=line))
- return result
- def format(self):
- """Format the stack ready for printing.
- 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.
- For long sequences of the same frame and line, the first few
- repetitions are shown, followed by a summary line stating the exact
- number of further repetitions.
- """
- result = []
- last_file = None
- last_line = None
- last_name = None
- count = 0
- for frame in self:
- if (last_file is None or last_file != frame.filename or
- last_line is None or last_line != frame.lineno or
- last_name is None or last_name != frame.name):
- if count > _RECURSIVE_CUTOFF:
- count -= _RECURSIVE_CUTOFF
- result.append(
- f' [Previous line repeated {count} more '
- f'time{"s" if count > 1 else ""}]\n'
- )
- last_file = frame.filename
- last_line = frame.lineno
- last_name = frame.name
- count = 0
- count += 1
- if count > _RECURSIVE_CUTOFF:
- continue
- row = []
- row.append(' File "{}", line {}, in {}\n'.format(
- frame.filename, frame.lineno, frame.name))
- if frame.line:
- row.append(' {}\n'.format(frame.line.strip()))
- if frame.locals:
- for name, value in sorted(frame.locals.items()):
- row.append(' {name} = {value}\n'.format(name=name, value=value))
- result.append(''.join(row))
- if count > _RECURSIVE_CUTOFF:
- count -= _RECURSIVE_CUTOFF
- result.append(
- f' [Previous line repeated {count} more '
- f'time{"s" if count > 1 else ""}]\n'
- )
- return result
- class TracebackException:
- """An exception ready for rendering.
- The traceback module captures enough attributes from the original exception
- to this intermediary form to ensure that no references are held, while
- still being able to fully print or format it.
- Use `from_exception` to create TracebackException instances from exception
- objects, or the constructor to create TracebackException instances from
- individual components.
- - :attr:`__cause__` A TracebackException of the original *__cause__*.
- - :attr:`__context__` A TracebackException of the original *__context__*.
- - :attr:`__suppress_context__` The *__suppress_context__* value from the
- original exception.
- - :attr:`stack` A `StackSummary` representing the traceback.
- - :attr:`exc_type` The class of the original traceback.
- - :attr:`filename` For syntax errors - the filename where the error
- occurred.
- - :attr:`lineno` For syntax errors - the linenumber where the error
- occurred.
- - :attr:`end_lineno` For syntax errors - the end linenumber where the error
- occurred. Can be `None` if not present.
- - :attr:`text` For syntax errors - the text where the error
- occurred.
- - :attr:`offset` For syntax errors - the offset into the text where the
- error occurred.
- - :attr:`end_offset` For syntax errors - the offset into the text where the
- error occurred. Can be `None` if not present.
- - :attr:`msg` For syntax errors - the compiler error message.
- """
- def __init__(self, exc_type, exc_value, exc_traceback, *, limit=None,
- lookup_lines=True, capture_locals=False, compact=False,
- _seen=None):
- # NB: we need to accept exc_traceback, exc_value, exc_traceback to
- # permit backwards compat with the existing API, otherwise we
- # need stub thunk objects just to glue it together.
- # Handle loops in __cause__ or __context__.
- is_recursive_call = _seen is not None
- if _seen is None:
- _seen = set()
- _seen.add(id(exc_value))
- # TODO: locals.
- self.stack = StackSummary.extract(
- walk_tb(exc_traceback), limit=limit, lookup_lines=lookup_lines,
- capture_locals=capture_locals)
- self.exc_type = exc_type
- # Capture now to permit freeing resources: only complication is in the
- # unofficial API _format_final_exc_line
- self._str = _some_str(exc_value)
- if exc_type and issubclass(exc_type, SyntaxError):
- # Handle SyntaxError's specially
- self.filename = exc_value.filename
- lno = exc_value.lineno
- self.lineno = str(lno) if lno is not None else None
- end_lno = exc_value.end_lineno
- self.end_lineno = str(end_lno) if end_lno is not None else None
- self.text = exc_value.text
- self.offset = exc_value.offset
- self.end_offset = exc_value.end_offset
- self.msg = exc_value.msg
- if lookup_lines:
- self._load_lines()
- self.__suppress_context__ = \
- exc_value.__suppress_context__ if exc_value is not None else False
- # Convert __cause__ and __context__ to `TracebackExceptions`s, use a
- # queue to avoid recursion (only the top-level call gets _seen == None)
- if not is_recursive_call:
- queue = [(self, exc_value)]
- while queue:
- te, e = queue.pop()
- if (e and e.__cause__ is not None
- and id(e.__cause__) not in _seen):
- cause = TracebackException(
- type(e.__cause__),
- e.__cause__,
- e.__cause__.__traceback__,
- limit=limit,
- lookup_lines=lookup_lines,
- capture_locals=capture_locals,
- _seen=_seen)
- else:
- cause = None
- if compact:
- need_context = (cause is None and
- e is not None and
- not e.__suppress_context__)
- else:
- need_context = True
- if (e and e.__context__ is not None
- and need_context and id(e.__context__) not in _seen):
- context = TracebackException(
- type(e.__context__),
- e.__context__,
- e.__context__.__traceback__,
- limit=limit,
- lookup_lines=lookup_lines,
- capture_locals=capture_locals,
- _seen=_seen)
- else:
- context = None
- te.__cause__ = cause
- te.__context__ = context
- if cause:
- queue.append((te.__cause__, e.__cause__))
- if context:
- queue.append((te.__context__, e.__context__))
- @classmethod
- def from_exception(cls, exc, *args, **kwargs):
- """Create a TracebackException from an exception."""
- return cls(type(exc), exc, exc.__traceback__, *args, **kwargs)
- def _load_lines(self):
- """Private API. force all lines in the stack to be loaded."""
- for frame in self.stack:
- frame.line
- def __eq__(self, other):
- if isinstance(other, TracebackException):
- return self.__dict__ == other.__dict__
- return NotImplemented
- def __str__(self):
- return self._str
- def format_exception_only(self):
- """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 emits 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.
- """
- if self.exc_type is None:
- yield _format_final_exc_line(None, self._str)
- return
- stype = self.exc_type.__qualname__
- smod = self.exc_type.__module__
- if smod not in ("__main__", "builtins"):
- stype = smod + '.' + stype
- if not issubclass(self.exc_type, SyntaxError):
- yield _format_final_exc_line(stype, self._str)
- else:
- yield from self._format_syntax_error(stype)
- def _format_syntax_error(self, stype):
- """Format SyntaxError exceptions (internal helper)."""
- # Show exactly where the problem was found.
- filename_suffix = ''
- if self.lineno is not None:
- yield ' File "{}", line {}\n'.format(
- self.filename or "<string>", self.lineno)
- elif self.filename is not None:
- filename_suffix = ' ({})'.format(self.filename)
- text = self.text
- if text is not None:
- # text = " foo\n"
- # rtext = " foo"
- # ltext = "foo"
- rtext = text.rstrip('\n')
- ltext = rtext.lstrip(' \n\f')
- spaces = len(rtext) - len(ltext)
- yield ' {}\n'.format(ltext)
- if self.offset is not None:
- offset = self.offset
- end_offset = self.end_offset if self.end_offset is not None else offset
- if offset == end_offset or end_offset == -1:
- end_offset = offset + 1
- # Convert 1-based column offset to 0-based index into stripped text
- colno = offset - 1 - spaces
- end_colno = end_offset - 1 - spaces
- if colno >= 0:
- # non-space whitespace (likes tabs) must be kept for alignment
- caretspace = ((c if c.isspace() else ' ') for c in ltext[:colno])
- yield ' {}{}'.format("".join(caretspace), ('^' * (end_colno - colno) + "\n"))
- msg = self.msg or "<no detail available>"
- yield "{}: {}{}\n".format(stype, msg, filename_suffix)
- def format(self, *, 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.
- """
- output = []
- exc = self
- while exc:
- if chain:
- if exc.__cause__ is not None:
- chained_msg = _cause_message
- chained_exc = exc.__cause__
- elif (exc.__context__ is not None and
- not exc.__suppress_context__):
- chained_msg = _context_message
- chained_exc = exc.__context__
- else:
- chained_msg = None
- chained_exc = None
- output.append((chained_msg, exc))
- exc = chained_exc
- else:
- output.append((None, exc))
- exc = None
- for msg, exc in reversed(output):
- if msg is not None:
- yield msg
- if exc.stack:
- yield 'Traceback (most recent call last):\n'
- yield from exc.stack.format()
- yield from exc.format_exception_only()