Using zope.exceptions

This module extends the standard library’s traceback module, allowing application code to add additional information to the formatted tracebacks using specially-named variables in the scope of a given frame.

Annotating Application Code

__traceback_supplement__

This variable can be defined either at either local or global scope. The formatting functions treat objects with this name as though they support the ITracebackSupplement interface. The various attributes (all optional) of that interface will be used to add structured information to the formatted traceback.

For example, assuming your code renders a template:

>>> import os
>>> class Supplement(object):
...     def __init__(self, template_file, source):
...         self.source_url = 'file://%s' % os.path.abspath(template_file)
...         self.source = source
...     def getInfo(self):
...         return self.source
>>> def render_w_supplement(template_file, options):
...     source = open(template_file).read()
...     __traceback_supplement__ = Supplement(template_file, source)

Here, the filename and source of the template will be rendered as part of the traceback.

__traceback_info__

This variable can only be defined at local scope. It will be converted to a string when added to the formatted traceback.

>>> def render_w_info(template_file, options):
...     source = open(template_file).read()
...     __traceback_info__ = '%s\n\n%s' % (template_file, source)

API Functions

Three API functions support these features when formatting Python exceptions and their associated tracebacks:

format_exception()

Use this API to format an exception and traceback as a string, using the special annotations. E.g.:

>>> import sys
>>> from zope.exceptions import format_exception
>>> try:
...     raise ValueError('demo')
... except:
...     t, v, tb = sys.exc_info()
...     report = format_exception(t, v, tb)
...     del tb # avoid a leak
...     # Now do something with report, e.g., send e-mail.

extract_stack()

Use this API to format just the traceback as a list of string,s using the special annotations. E.g.:

>>> import sys
>>> from zope.exceptions import extract_stack
>>> try:
...     raise ValueError('demo')
... except:
...     for line in extract_stack(sys.exc_info()[2].tb_frame):
...         pass # do something with each line