catch_debug – Interactive web debugging.

Module contents

class pluggdapps.web.catch_debug.CatchAndDebug(pa, *args, **kwargs)

Bases: pluggdapps.plugin.Plugin

An exception collector that finds traceback information plus supplements. Produces a data structure that can be used by formatters to render them as an interactive web page.

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_info__:

String. This information is added to the traceback, usually fairly literally.

__traceback_hide__:

Boolean or String.

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.

‘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_decorator__:

Callable. Takes frames, a list of ExceptionFrame object, modifies them inplace or return an entirely new object. What ever be the case, it is expected to return a list of frames. 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 or the rendering template.

The list of frames goes innermost first. Each frame has these attributes; some values may be None if they could not be determined. Each frame is an instance of ExceptionFrame.

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’)

render(request, etype, value, tb)

pluggdapps.web.interfaces.IHTTPLiveDebug.render() interface method.

collectFrame(request, tb, extra_data)

Collect a dictionary of information about a traceback frame.

collectException(request, etype, value, tb, limit=None)

collectException( request, *sys.exc_info() ) will return an instance of CollectedException. Attibutes of this object can be used to render traceback.

Use like:

try:
    blah blah
except:
    exc_data = plugin.collectException(*sys.exc_info())

class pluggdapps.web.catch_debug.CollectedException

Bases: builtins.dict

This is the result of collection the exception; it contains copies of data of interest.

frames = []

A list of frames (ExceptionFrame instances), innermost last.

exception_type = 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_formatted = None

The result of traceback.format_exception_only; this looks like a normal traceback you’d see in the interactive interpreter.

exception_value = None

The string representation of the exception, from str(e).

identification_code = None

An identifier which should more-or-less classify this particular exception, including where in the code it happened.

date = None

Date string (in HTTP format) adjusted to GMT.

extra_data = {}

A dictionary of supplemental data.

class pluggdapps.web.catch_debug.ExceptionFrame(**attrs)

Bases: pluggdapps.utils.lib.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.

modname = None

The name of the module; can be None, especially when the code isn’t associated with a module.

filename = None

The filename (@@: when no filename, is it None or ‘?’?).

lineno = None

Line number.

linetext = None

Text of line that took part in the exception.

revision = None

The value of __revision__ or __version__ – but only if show_revision = True (by defaut it is false). (@@: Why not collect this?).

name = None

The name of the function with the error (@@: None or ‘?’ when unknown?).

traceback_info = None

The str() of any __traceback_info__ value found.

traceback_hide = False

The value of __traceback_hide__.

traceback_decorator = None

The value of __traceback_decorator__.

tbid = None

The id() of the traceback scope, can be used to reference the scope for use elsewhere.

get_source_line(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.