524 lines
19 KiB
Python
524 lines
19 KiB
Python
# (c) 2005 Ian Bicking and contributors; written for Paste (http://pythonpaste.org)
|
|
# Licensed under the MIT license: http://www.opensource.org/licenses/mit-license.php
|
|
##############################################################################
|
|
#
|
|
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
|
|
# All Rights Reserved.
|
|
#
|
|
# This software is subject to the provisions of the Zope Public License,
|
|
# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
|
|
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
|
|
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
|
|
# FOR A PARTICULAR PURPOSE.
|
|
#
|
|
##############################################################################
|
|
## Originally zExceptions.ExceptionFormatter from Zope;
|
|
## Modified by Ian Bicking, Imaginary Landscape, 2005
|
|
"""
|
|
An exception collector that finds traceback information plus
|
|
supplements
|
|
"""
|
|
|
|
import sys
|
|
import traceback
|
|
import time
|
|
from six.moves import cStringIO as StringIO
|
|
import linecache
|
|
from paste.exceptions import serial_number_generator
|
|
import warnings
|
|
|
|
DEBUG_EXCEPTION_FORMATTER = True
|
|
DEBUG_IDENT_PREFIX = 'E-'
|
|
FALLBACK_ENCODING = 'UTF-8'
|
|
|
|
__all__ = ['collect_exception', 'ExceptionCollector']
|
|
|
|
class ExceptionCollector(object):
|
|
|
|
"""
|
|
Produces a data structure that can be used by formatters to
|
|
display exception reports.
|
|
|
|
Magic variables:
|
|
|
|
If you define one of these variables in your local scope, you can
|
|
add information to tracebacks that happen in that context. This
|
|
allows applications to add all sorts of extra information about
|
|
the context of the error, including URLs, environmental variables,
|
|
users, hostnames, etc. These are the variables we look for:
|
|
|
|
``__traceback_supplement__``:
|
|
You can define this locally or globally (unlike all the other
|
|
variables, which must be defined locally).
|
|
|
|
``__traceback_supplement__`` is a tuple of ``(factory, arg1,
|
|
arg2...)``. When there is an exception, ``factory(arg1, arg2,
|
|
...)`` is called, and the resulting object is inspected for
|
|
supplemental information.
|
|
|
|
``__traceback_info__``:
|
|
This information is added to the traceback, usually fairly
|
|
literally.
|
|
|
|
``__traceback_hide__``:
|
|
If set and true, this indicates that the frame should be
|
|
hidden from abbreviated tracebacks. This way you can hide
|
|
some of the complexity of the larger framework and let the
|
|
user focus on their own errors.
|
|
|
|
By setting it to ``'before'``, all frames before this one will
|
|
be thrown away. By setting it to ``'after'`` then all frames
|
|
after this will be thrown away until ``'reset'`` is found. In
|
|
each case the frame where it is set is included, unless you
|
|
append ``'_and_this'`` to the value (e.g.,
|
|
``'before_and_this'``).
|
|
|
|
Note that formatters will ignore this entirely if the frame
|
|
that contains the error wouldn't normally be shown according
|
|
to these rules.
|
|
|
|
``__traceback_reporter__``:
|
|
This should be a reporter object (see the reporter module),
|
|
or a list/tuple of reporter objects. All reporters found this
|
|
way will be given the exception, innermost first.
|
|
|
|
``__traceback_decorator__``:
|
|
This object (defined in a local or global scope) will get the
|
|
result of this function (the CollectedException defined
|
|
below). It may modify this object in place, or return an
|
|
entirely new object. This gives the object the ability to
|
|
manipulate the traceback arbitrarily.
|
|
|
|
The actually interpretation of these values is largely up to the
|
|
reporters and formatters.
|
|
|
|
``collect_exception(*sys.exc_info())`` will return an object with
|
|
several attributes:
|
|
|
|
``frames``:
|
|
A list of frames
|
|
``exception_formatted``:
|
|
The formatted exception, generally a full traceback
|
|
``exception_type``:
|
|
The type of the exception, like ``ValueError``
|
|
``exception_value``:
|
|
The string value of the exception, like ``'x not in list'``
|
|
``identification_code``:
|
|
A hash of the exception data meant to identify the general
|
|
exception, so that it shares this code with other exceptions
|
|
that derive from the same problem. The code is a hash of
|
|
all the module names and function names in the traceback,
|
|
plus exception_type. This should be shown to users so they
|
|
can refer to the exception later. (@@: should it include a
|
|
portion that allows identification of the specific instance
|
|
of the exception as well?)
|
|
|
|
The list of frames goes innermost first. Each frame has these
|
|
attributes; some values may be None if they could not be
|
|
determined.
|
|
|
|
``modname``:
|
|
the name of the module
|
|
``filename``:
|
|
the filename of the module
|
|
``lineno``:
|
|
the line of the error
|
|
``revision``:
|
|
the contents of __version__ or __revision__
|
|
``name``:
|
|
the function name
|
|
``supplement``:
|
|
an object created from ``__traceback_supplement__``
|
|
``supplement_exception``:
|
|
a simple traceback of any exception ``__traceback_supplement__``
|
|
created
|
|
``traceback_info``:
|
|
the str() of any ``__traceback_info__`` variable found in the local
|
|
scope (@@: should it str()-ify it or not?)
|
|
``traceback_hide``:
|
|
the value of any ``__traceback_hide__`` variable
|
|
``traceback_log``:
|
|
the value of any ``__traceback_log__`` variable
|
|
|
|
|
|
``__traceback_supplement__`` is thrown away, but a fixed
|
|
set of attributes are captured; each of these attributes is
|
|
optional.
|
|
|
|
``object``:
|
|
the name of the object being visited
|
|
``source_url``:
|
|
the original URL requested
|
|
``line``:
|
|
the line of source being executed (for interpreters, like ZPT)
|
|
``column``:
|
|
the column of source being executed
|
|
``expression``:
|
|
the expression being evaluated (also for interpreters)
|
|
``warnings``:
|
|
a list of (string) warnings to be displayed
|
|
``getInfo``:
|
|
a function/method that takes no arguments, and returns a string
|
|
describing any extra information
|
|
``extraData``:
|
|
a function/method that takes no arguments, and returns a
|
|
dictionary. The contents of this dictionary will not be
|
|
displayed in the context of the traceback, but globally for
|
|
the exception. Results will be grouped by the keys in the
|
|
dictionaries (which also serve as titles). The keys can also
|
|
be tuples of (importance, title); in this case the importance
|
|
should be ``important`` (shows up at top), ``normal`` (shows
|
|
up somewhere; unspecified), ``supplemental`` (shows up at
|
|
bottom), or ``extra`` (shows up hidden or not at all).
|
|
|
|
These are used to create an object with attributes of the same
|
|
names (``getInfo`` becomes a string attribute, not a method).
|
|
``__traceback_supplement__`` implementations should be careful to
|
|
produce values that are relatively static and unlikely to cause
|
|
further errors in the reporting system -- any complex
|
|
introspection should go in ``getInfo()`` and should ultimately
|
|
return a string.
|
|
|
|
Note that all attributes are optional, and under certain
|
|
circumstances may be None or may not exist at all -- the collector
|
|
can only do a best effort, but must avoid creating any exceptions
|
|
itself.
|
|
|
|
Formatters may want to use ``__traceback_hide__`` as a hint to
|
|
hide frames that are part of the 'framework' or underlying system.
|
|
There are a variety of rules about special values for this
|
|
variables that formatters should be aware of.
|
|
|
|
TODO:
|
|
|
|
More attributes in __traceback_supplement__? Maybe an attribute
|
|
that gives a list of local variables that should also be
|
|
collected? Also, attributes that would be explicitly meant for
|
|
the entire request, not just a single frame. Right now some of
|
|
the fixed set of attributes (e.g., source_url) are meant for this
|
|
use, but there's no explicit way for the supplement to indicate
|
|
new values, e.g., logged-in user, HTTP referrer, environment, etc.
|
|
Also, the attributes that do exist are Zope/Web oriented.
|
|
|
|
More information on frames? cgitb, for instance, produces
|
|
extensive information on local variables. There exists the
|
|
possibility that getting this information may cause side effects,
|
|
which can make debugging more difficult; but it also provides
|
|
fodder for post-mortem debugging. However, the collector is not
|
|
meant to be configurable, but to capture everything it can and let
|
|
the formatters be configurable. Maybe this would have to be a
|
|
configuration value, or maybe it could be indicated by another
|
|
magical variable (which would probably mean 'show all local
|
|
variables below this frame')
|
|
"""
|
|
|
|
show_revisions = 0
|
|
|
|
def __init__(self, limit=None):
|
|
self.limit = limit
|
|
|
|
def getLimit(self):
|
|
limit = self.limit
|
|
if limit is None:
|
|
limit = getattr(sys, 'tracebacklimit', None)
|
|
return limit
|
|
|
|
def getRevision(self, globals):
|
|
if not self.show_revisions:
|
|
return None
|
|
revision = globals.get('__revision__', None)
|
|
if revision is None:
|
|
# Incorrect but commonly used spelling
|
|
revision = globals.get('__version__', None)
|
|
|
|
if revision is not None:
|
|
try:
|
|
revision = str(revision).strip()
|
|
except:
|
|
revision = '???'
|
|
return revision
|
|
|
|
def collectSupplement(self, supplement, tb):
|
|
result = {}
|
|
|
|
for name in ('object', 'source_url', 'line', 'column',
|
|
'expression', 'warnings'):
|
|
result[name] = getattr(supplement, name, None)
|
|
|
|
func = getattr(supplement, 'getInfo', None)
|
|
if func:
|
|
result['info'] = func()
|
|
else:
|
|
result['info'] = None
|
|
func = getattr(supplement, 'extraData', None)
|
|
if func:
|
|
result['extra'] = func()
|
|
else:
|
|
result['extra'] = None
|
|
return SupplementaryData(**result)
|
|
|
|
def collectLine(self, tb, extra_data):
|
|
f = tb.tb_frame
|
|
lineno = tb.tb_lineno
|
|
co = f.f_code
|
|
filename = co.co_filename
|
|
name = co.co_name
|
|
globals = f.f_globals
|
|
locals = f.f_locals
|
|
if not hasattr(locals, 'keys'):
|
|
# Something weird about this frame; it's not a real dict
|
|
warnings.warn(
|
|
"Frame %s has an invalid locals(): %r" % (
|
|
globals.get('__name__', 'unknown'), locals))
|
|
locals = {}
|
|
data = {}
|
|
data['modname'] = globals.get('__name__', None)
|
|
data['filename'] = filename
|
|
data['lineno'] = lineno
|
|
data['revision'] = self.getRevision(globals)
|
|
data['name'] = name
|
|
data['tbid'] = id(tb)
|
|
|
|
# Output a traceback supplement, if any.
|
|
if '__traceback_supplement__' in locals:
|
|
# Use the supplement defined in the function.
|
|
tbs = locals['__traceback_supplement__']
|
|
elif '__traceback_supplement__' in globals:
|
|
# Use the supplement defined in the module.
|
|
# This is used by Scripts (Python).
|
|
tbs = globals['__traceback_supplement__']
|
|
else:
|
|
tbs = None
|
|
if tbs is not None:
|
|
factory = tbs[0]
|
|
args = tbs[1:]
|
|
try:
|
|
supp = factory(*args)
|
|
data['supplement'] = self.collectSupplement(supp, tb)
|
|
if data['supplement'].extra:
|
|
for key, value in data['supplement'].extra.items():
|
|
extra_data.setdefault(key, []).append(value)
|
|
except:
|
|
if DEBUG_EXCEPTION_FORMATTER:
|
|
out = StringIO()
|
|
traceback.print_exc(file=out)
|
|
text = out.getvalue()
|
|
data['supplement_exception'] = text
|
|
# else just swallow the exception.
|
|
|
|
try:
|
|
tbi = locals.get('__traceback_info__', None)
|
|
if tbi is not None:
|
|
data['traceback_info'] = str(tbi)
|
|
except:
|
|
pass
|
|
|
|
marker = []
|
|
for name in ('__traceback_hide__', '__traceback_log__',
|
|
'__traceback_decorator__'):
|
|
try:
|
|
tbh = locals.get(name, globals.get(name, marker))
|
|
if tbh is not marker:
|
|
data[name[2:-2]] = tbh
|
|
except:
|
|
pass
|
|
|
|
return data
|
|
|
|
def collectExceptionOnly(self, etype, value):
|
|
return traceback.format_exception_only(etype, value)
|
|
|
|
def collectException(self, etype, value, tb, limit=None):
|
|
# The next line provides a way to detect recursion.
|
|
__exception_formatter__ = 1
|
|
frames = []
|
|
ident_data = []
|
|
traceback_decorators = []
|
|
if limit is None:
|
|
limit = self.getLimit()
|
|
n = 0
|
|
extra_data = {}
|
|
while tb is not None and (limit is None or n < limit):
|
|
if tb.tb_frame.f_locals.get('__exception_formatter__'):
|
|
# Stop recursion. @@: should make a fake ExceptionFrame
|
|
frames.append('(Recursive formatException() stopped)\n')
|
|
break
|
|
data = self.collectLine(tb, extra_data)
|
|
frame = ExceptionFrame(**data)
|
|
frames.append(frame)
|
|
if frame.traceback_decorator is not None:
|
|
traceback_decorators.append(frame.traceback_decorator)
|
|
ident_data.append(frame.modname or '?')
|
|
ident_data.append(frame.name or '?')
|
|
tb = tb.tb_next
|
|
n = n + 1
|
|
ident_data.append(str(etype))
|
|
ident = serial_number_generator.hash_identifier(
|
|
' '.join(ident_data), length=5, upper=True,
|
|
prefix=DEBUG_IDENT_PREFIX)
|
|
|
|
result = CollectedException(
|
|
frames=frames,
|
|
exception_formatted=self.collectExceptionOnly(etype, value),
|
|
exception_type=etype,
|
|
exception_value=self.safeStr(value),
|
|
identification_code=ident,
|
|
date=time.localtime(),
|
|
extra_data=extra_data)
|
|
if etype is ImportError:
|
|
extra_data[('important', 'sys.path')] = [sys.path]
|
|
for decorator in traceback_decorators:
|
|
try:
|
|
new_result = decorator(result)
|
|
if new_result is not None:
|
|
result = new_result
|
|
except:
|
|
pass
|
|
return result
|
|
|
|
def safeStr(self, obj):
|
|
try:
|
|
return str(obj)
|
|
except UnicodeEncodeError:
|
|
try:
|
|
return unicode(obj).encode(FALLBACK_ENCODING, 'replace')
|
|
except UnicodeEncodeError:
|
|
# This is when something is really messed up, but this can
|
|
# happen when the __str__ of an object has to handle unicode
|
|
return repr(obj)
|
|
|
|
limit = 200
|
|
|
|
class Bunch(object):
|
|
|
|
"""
|
|
A generic container
|
|
"""
|
|
|
|
def __init__(self, **attrs):
|
|
for name, value in attrs.items():
|
|
setattr(self, name, value)
|
|
|
|
def __repr__(self):
|
|
name = '<%s ' % self.__class__.__name__
|
|
name += ' '.join(['%s=%r' % (name, str(value)[:30])
|
|
for name, value in self.__dict__.items()
|
|
if not name.startswith('_')])
|
|
return name + '>'
|
|
|
|
class CollectedException(Bunch):
|
|
"""
|
|
This is the result of collection the exception; it contains copies
|
|
of data of interest.
|
|
"""
|
|
# A list of frames (ExceptionFrame instances), innermost last:
|
|
frames = []
|
|
# The result of traceback.format_exception_only; this looks
|
|
# like a normal traceback you'd see in the interactive interpreter
|
|
exception_formatted = None
|
|
# The *string* representation of the type of the exception
|
|
# (@@: should we give the # actual class? -- we can't keep the
|
|
# actual exception around, but the class should be safe)
|
|
# Something like 'ValueError'
|
|
exception_type = None
|
|
# The string representation of the exception, from ``str(e)``.
|
|
exception_value = None
|
|
# An identifier which should more-or-less classify this particular
|
|
# exception, including where in the code it happened.
|
|
identification_code = None
|
|
# The date, as time.localtime() returns:
|
|
date = None
|
|
# A dictionary of supplemental data:
|
|
extra_data = {}
|
|
|
|
class SupplementaryData(Bunch):
|
|
"""
|
|
The result of __traceback_supplement__. We don't keep the
|
|
supplement object around, for fear of GC problems and whatnot.
|
|
(@@: Maybe I'm being too superstitious about copying only specific
|
|
information over)
|
|
"""
|
|
|
|
# These attributes are copied from the object, or left as None
|
|
# if the object doesn't have these attributes:
|
|
object = None
|
|
source_url = None
|
|
line = None
|
|
column = None
|
|
expression = None
|
|
warnings = None
|
|
# This is the *return value* of supplement.getInfo():
|
|
info = None
|
|
|
|
class ExceptionFrame(Bunch):
|
|
"""
|
|
This represents one frame of the exception. Each frame is a
|
|
context in the call stack, typically represented by a line
|
|
number and module name in the traceback.
|
|
"""
|
|
|
|
# The name of the module; can be None, especially when the code
|
|
# isn't associated with a module.
|
|
modname = None
|
|
# The filename (@@: when no filename, is it None or '?'?)
|
|
filename = None
|
|
# Line number
|
|
lineno = None
|
|
# The value of __revision__ or __version__ -- but only if
|
|
# show_revision = True (by defaut it is false). (@@: Why not
|
|
# collect this?)
|
|
revision = None
|
|
# The name of the function with the error (@@: None or '?' when
|
|
# unknown?)
|
|
name = None
|
|
# A SupplementaryData object, if __traceback_supplement__ was found
|
|
# (and produced no errors)
|
|
supplement = None
|
|
# If accessing __traceback_supplement__ causes any error, the
|
|
# plain-text traceback is stored here
|
|
supplement_exception = None
|
|
# The str() of any __traceback_info__ value found
|
|
traceback_info = None
|
|
# The value of __traceback_hide__
|
|
traceback_hide = False
|
|
# The value of __traceback_decorator__
|
|
traceback_decorator = None
|
|
# The id() of the traceback scope, can be used to reference the
|
|
# scope for use elsewhere
|
|
tbid = None
|
|
|
|
def get_source_line(self, context=0):
|
|
"""
|
|
Return the source of the current line of this frame. You
|
|
probably want to .strip() it as well, as it is likely to have
|
|
leading whitespace.
|
|
|
|
If context is given, then that many lines on either side will
|
|
also be returned. E.g., context=1 will give 3 lines.
|
|
"""
|
|
if not self.filename or not self.lineno:
|
|
return None
|
|
lines = []
|
|
for lineno in range(self.lineno-context, self.lineno+context+1):
|
|
lines.append(linecache.getline(self.filename, lineno))
|
|
return ''.join(lines)
|
|
|
|
if hasattr(sys, 'tracebacklimit'):
|
|
limit = min(limit, sys.tracebacklimit)
|
|
|
|
col = ExceptionCollector()
|
|
|
|
def collect_exception(t, v, tb, limit=None):
|
|
"""
|
|
Collection an exception from ``sys.exc_info()``.
|
|
|
|
Use like::
|
|
|
|
try:
|
|
blah blah
|
|
except:
|
|
exc_data = collect_exception(*sys.exc_info())
|
|
"""
|
|
return col.collectException(t, v, tb, limit=limit)
|