@@ -2,13 +2,14 @@
Internal global error types
"""
-import sys, traceback
+import sys, traceback, threading, logging
from traceback import format_exception
# Add names you want to be imported by 'from errors import *' to this list.
# This must be list not a tuple as we modify it to include all of our
# the Exception classes we define below at the end of this file.
-__all__ = ['format_error']
+__all__ = ['format_error', 'context_aware', 'context', 'get_context',
+ 'context_for_exception']
def format_error():
@@ -21,6 +22,98 @@ def format_error():
return ''.join(trace)
+# Exception context information:
+# ------------------------------
+# Every function can have some context string associated with it.
+# The context string can be changed by calling context(str) and cleared by
+# calling context() with no parameters.
+# get_context() joins the current context strings of all functions in the
+# provided traceback. The result is a brief description of what the test was
+# doing in the provided traceback (which should be the traceback of a caught
+# exception).
+#
+# For example: assume a() calls b() and b() calls c().
+#
+# def a():
+# error.context("hello")
+# b()
+# error.context("world")
+# get_context() ----> 'world'
+#
+# def b():
+# error.context("foo")
+# c()
+#
+# def c():
+# error.context("bar")
+# get_context() ----> 'hello --> foo --> bar'
+
+ctx = threading.local()
+
+
+def _new_context(s=""):
+ if not hasattr(ctx, "contexts"):
+ ctx.contexts = []
+ ctx.contexts.append(s)
+
+
+def _pop_context():
+ ctx.contexts.pop()
+
+
+def get_context():
+ """Return the current context (or None if none is defined)."""
+ if hasattr(ctx, "contexts"):
+ return " --> ".join([s for s in ctx.contexts if s])
+
+
+def context_for_exception(e):
+ """Return the context of a given exception (or None if none is defined)."""
+ if hasattr(e, "_context"):
+ return e._context
+
+
+def context(s="", log=None):
+ """
+ Set the context for the currently executing function and optionally log it.
+
+ @param s: A string. If not provided, the context for the current function
+ will be cleared.
+ @param log: A logging function to pass the context message to. If None, no
+ function will be called.
+ """
+ ctx.contexts[-1] = s
+ if s and log:
+ log("Context: %s" % get_context())
+
+
+def context_aware(fn):
+ """A decorator that must be applied to functions that call context()."""
+ def new_fn(*args, **kwargs):
+ _new_context("(%s)" % fn.__name__)
+ try:
+ try:
+ return fn(*args, **kwargs)
+ except Exception, e:
+ if not hasattr(e, "_context"):
+ e._context = get_context()
+ raise
+ finally:
+ _pop_context()
+ new_fn.__name__ = fn.__name__
+ new_fn.__doc__ = fn.__doc__
+ new_fn.__dict__.update(fn.__dict__)
+ return new_fn
+
+
+def _context_message(e):
+ s = context_for_exception(e)
+ if s:
+ return " [context: %s]" % s
+ else:
+ return ""
+
+
class JobContinue(SystemExit):
"""Allow us to bail out requesting continuance."""
pass