Merge lp:~pconnell/entrails/modularise into lp:entrails

[Phil Connell]

Split monolithic entrails module into a package.

Split monolithic entrails module into a package.

Tweaked naming slightly (e.g. entrails.OutputHTML -> entrails.HTMLOutput).

A few other trivial changes along the way e.g. added a couple of docstrings/__all__s

New modules:

_trace.py: core tracing functionality
_utils.py: mostly-empty dumping ground for util functions
_filter.py: filters
_output.py: output generators
__init__.py: pull everything together into the public entrails namespace

Also updated trace.py to handle the new namespace.

[Phil Connell (pconnell)]

Will sort out the namespacing (stick everything in the top level), and address the couple of cosmetic comments.

[Martin Morrison (isoschiz)]

review: Approve

=== added directory 'src/entrails'
=== renamed file 'src/entrails.py' => 'src/entrails/__init__.py'
--- src/entrails.py	2013-03-27 09:10:41 +0000
+++ src/entrails/__init__.py	2014-07-07 09:01:02 +0000
@@ -1,531 +1,41 @@
-#!/usr/bin/env python2.7
 # -----------------------------------------------------------------------------
-# EnTrails - Python Execution Tracing Module
-# Copyright 2012, Ensoft Ltd.
+# EnTrails - Python Execution Tracing
+# Copyright 2012, 2014, Ensoft Ltd.
 # Created by Ben Eills
 # -----------------------------------------------------------------------------
 
 """
-Single-file module, containing main EnTrails components and several output
-  modules/filters.
+Trace execution of Python programs.
+
 Outputs may be loaded/unloaded during execution and tracing may be toggled
-  during runtime.
+during runtime.
 
 Example Usage as a module:
-  t = Entrails('mylabel')
-  o = OutputLogFile('/tmp/log')
-  t.add_otuput(o)
+  import entrails
+  t = entrails.Entrails('mylabel')
+  o = entrails.LogFileOutput('/tmp/log')
+  t.add_output(o)
   t.start_trace()
   do_stuff()
   t.end_trace()
 
 Consider using trace.py to add EnTrails tracing to an existing Python program
-  without having to add the boilerplate code yourself.  That convenience script
-  should be distributed with this source file.
+without having to add the boilerplate code yourself.  That convenience script
+should be distributed with this source file.
+
 """
 
-import os.path
-import sys
-import datetime
-import time
-import sys
-import xml.dom
-import xml.etree.ElementTree as ET
-from collections import OrderedDict
-
-
-def pretty_resize_string(string, length=25, cutoff='back', exact=False):
-    """
-    Shortens or lengthens a string to be at most length characters long.
-    cutoff should be 'front' or 'back', dictating where the ellipsis goes.
-    exact toggles whitespace padding.
-    """
-    if len(string) > length:
-        cutoff_string = '{0}...' if cutoff is 'back' else '...{0}'
-        return cutoff_string.format(string[3-length:])
-    else:
-        exact_string = '{:>25}' if exact else '{0}'
-        return exact_string.format(string)
-
-
-class FrameObject(dict):
-    """
-    Holds information about the frame.
-
-    Use as a dict to access the important bits of the frame and arg
-    parameters, along with timestamp and label.  Also has convienience
-    methods to generate function call string and class info.  This is
-    supplied to an output adapter's call(), return() and exception()
-    methods.
-    """
-    def parameters(self):
-        """
-        Returns dict of form {parameter_name: argument_value}.
-        """
-        # We rely on CPython putting arguments at start of f_locals (in reverse
-        #   order for some reason...).  This is undocumented, but consistent.
-        parameters = [(k, v) for k, v in self["f_locals"].iteritems()
-                    if k in self["co_varnames"][0:self["co_argcount"]]]
-        parameters.reverse()
-        return OrderedDict(parameters)
-
-    def arguments(self):
-        """
-        Returns argument list, possibly excluding the first 'self' arg
-        if the function is a method.
-
-        Only designed for 'call' event (i.e. function entry)
-        """
-        # Possibly chop off first self argument
-        ignorer = 0 if not self.is_method() else 1
-        return self.parameters().values()[ignorer:]
-
-    def string_arguments(self):
-        """
-        Returns list of nice string argument representations.
-
-        If the argument object encounters an error during repr() call
-          (some standard library classes can do this under certain conditions)
-          fail cleanly.
-        """
-        strings = []
-        for arg in self.arguments():
-            try:
-                strings.append(repr(arg))
-            except:
-                strings.append('<repr error>')
-        return strings
-
-    def call_string(self):
-        """
-        Returns a pretty string representation of the function call built
-          from function name and args, nicely formatted/abbrieviated.
-
-        Only designed for 'call' event (i.e. function entry)
-        """
-        if self.is_method():
-            return '{0}.{1}({2})'.format(self.instance_name(), self['co_name'],
-                                         ', '.join(self.string_arguments()))
-        else:
-            return '{0}({1})'.format(self['co_name'],
-                                     ', '.join(self.string_arguments()))
-
-    def short_call_string(self, length=40):
-        """
-        Returns a pretty string of the function call, shortened to at
-          most length characters.
-
-        Only designed for 'call' event (i.e. function entry)
-        """
-        return pretty_resize_string(self.call_string(), length)
-
-    def short_return_value(self, length=40):
-        """
-        Returns a pretty string representation of the return value,
-          shortened to at most length characters.
-
-        Only designed for 'call' event (i.e. function entry)
-        """
-        try:
-            return pretty_resize_string(repr(self['return_value']), length)
-        except:
-            return pretty_resize_string('<repr error>', length)
-
-        # Do we close quotation marks in string return values?
-        # if len(repr(rv)) > 40:
-        #     if rv.__class__.__name__ == 'str':
-        #         return repr(rv)[0:length-4]+"...'"
-        #     else:
-        #         return repr(rv)[0:length-3]+"..."
-        # else:
-        #     return repr(rv)
-
-    def nice_filename(self):
-        """
-        Nice filename, without directory segment.
-        """
-        return os.path.basename(self["co_filename"])
-
-
-    def is_method(self):
-        """
-        True if function is an instance method  (and the programmer
-          did not defy all convention by abandonning the use of 'self'
-          as the instance pointer).
-        Only designed for 'call' event (i.e. function entry)
-
-        TODO: What happens for class methods/other decorated methods?
-        """
-        if self['co_varnames'] and self['co_varnames'][0] == 'self':
-            return True
-        return False
-
-    def instance_name(self):
-        """
-        Class instance name of method, or empty string if not method.
-        Only designed for 'call' event (i.e. function entry)
-        We cache value after first proper lookup.
-        """
-        if 'instance_name' not in self:
-            self['instance_name'] = self._retrieve_instance_name()
-        return self['instance_name']
-
-    def _retrieve_instance_name(self):
-        """
-        Get class instance name by performance-intensive lookup.
-        Should only be called on methods.
-        """
-        try:
-            # This is confusing.  We go into the previous (parent) frame and
-            #   find the local variable name in that pointing to a our class.
-            for k, v in self['f_back'].f_locals.items():
-                if v == self['f_locals']['self']:
-                    return k
-        except:
-            return '<lookup error>'
-
-    def class_name(self):
-        """
-        Class name of method, or empty string if not method.
-        Only designed for 'call' event (i.e. function entry)
-        Should only be called on methods.
-        """
-        try:
-            return self["f_locals"]["self"].__class__.__name__
-        except:
-            return '<lookup error>'
-
-
-class Filter(object):
-    """
-    Returns True if object remains unfiltered.
-    Must be very fast at executing, since we deal with so many objects.
-    """
-    def filter(self, frameobjects):
-        """
-        Trivial filter (allowing all events to pass through)
-        """
-        return frameobjects
-
-class LibraryFilter(Filter):
-    """
-    Filters out major 3rd party libraries and Standard Library.
-    """
-    matches = ("/usr/lib", "/usr/local/lib", "/usr/lib64", "/twisted", "/zope")
-
-    def filter(self, frameobject):
-        for m in self.matches:
-            if m in frameobject['co_filename']:
-                return False
-        return True
-
-class SelfFilter(Filter):
-    """
-    Filter out EnTrails events.
-
-    Performance-wise, it might be better to have this hardcoded below
-      to save a couple of JMP statements, but architecturally this is
-      where it goes.
-    """
-    matches = ("remove_output", "end_trace")
-
-    def filter(self, frameobject):
-        for m in self.matches:
-            if m in frameobject['co_name']:
-                return False
-        return True
-
-### TODO BELOW LINE
-
-class Entrails(object):
-    """
-    Implements entrails functionality to monitor program execution flow.
-
-    Instantiate at in process to be traced, add outputs and call start_trace().
-    Run end_trace() to safely close outputs and stop tracing.
-    """
-    event_names = { 'call' : 'enter',
-                    'return' : 'exit',
-                    'exception' : 'exception' }
-
-    def __init__(self,
-                 label='<untitled>', filters=(LibraryFilter(), SelfFilter())):
-        self._outputs = []
-        self._init_time = time.time()
-        self._label = label
-        self._filters = filters
-    
-    def filter(self, obj):
-        """
-        Returns True if object remains unfiltered, False otherise.
-        """
-        if all(f.filter(obj) for f in self._filters):
-            return True
-        return False
-
-    def _trace_function(self, trace, event, arg):
-        # Build FrameObject
-        obj = FrameObject()
-        obj["label"] = self._label
-        obj["timestamp"] = time.time() - self._init_time
-        obj["f_lineno"] = trace.f_lineno
-        obj["f_back"] = trace.f_back
-        obj["f_locals"] = trace.f_locals
-        obj["co_name"] = trace.f_code.co_name
-        obj["co_argcount"] = trace.f_code.co_argcount
-        obj["co_filename"] = trace.f_code.co_filename
-        obj["co_names"] = trace.f_code.co_names
-        obj["co_varnames"] = trace.f_code.co_varnames
-
-        # Filter
-        # If this object is to be discarded, return trace_function to
-        #   indicate that we wish to continue tracing.
-        if not self.filter(obj):
-            return self._trace_function
-
-        # Possibly add return_value.  If event is non-return, arg isn't really
-        #   that useful.
-        if event is 'return':
-            obj["return_value"] = arg
-
-        if event in self.event_names:
-            for output in self._outputs:
-                #try:
-                getattr(output, self.event_names[event])(obj)
-        return self._trace_function
-
-    def add_output(self, output_object):
-        """
-        Adds output adapter, accepting argument of type EntrailsOutput.
-        """
-        self._outputs.append(output_object)
-
-    def remove_output(self, output_object):
-        """
-        Cease sending tracing data to a particular output.
-        Removes from internal list and runs output.__del__()@@@
-        """
-        output_object.close()
-        if output_object in self._outputs:
-            self._outputs.remove(output_object)
-
-    def start_trace(self):
-        """
-        Start tracing.
-        """
-        sys.settrace(self._trace_function)
-    def end_trace(self):
-        """
-        Stop tracing.  Safely removes all outputs.
-        """
-        for o in self._outputs:
-            self.remove_output(o)
-        sys.settrace(None)
-
-class EntrailsOutput(object):
-    """
-    Skeleton output adapter class; methods called for function
-    entry/exit and exceptions.
-
-    Use as template to implement custom output adapters.
-    """
-    def __init__(self):
-        pass
-    def close(self):
-        pass
-    def enter(self, o):
-        pass
-    def exit(self, o):
-        pass
-    def exception(self, o):
-        pass
-    def logging(self, o, event_type_string):
-        pass
-
-class OutputPlainText(EntrailsOutput):
-    """
-    Output adapter generating plaintext of variable verbosity, one
-    event per line.
-
-    TODO: printf formatting, verbosity
-    """
-    def __init__(self, verbosity, prefix_func=None, depth_spacer=" ",
-                 enter_func=None, exit_func=None, exception_func=None):
-        self.depth_spacer = depth_spacer
-        self.safe_write("Starting trace in program\n")
-        self.depth = 0
-        self.prefix_func = prefix_func or self._default_prefix_func
-        self.enter_func = enter_func or self._default_enter_func
-        self.exit_func = exit_func or self._default_exit_func
-        self.exception_func = exception_func or self._default_exception_func
-
-    def close(self):
-        if not self.f.closed:
-            self.f.close()
-
-    def safe_write(self, data):
-        if not self.f.closed:
-            self.f.write(data)
-
-    def _default_enter_func(self, o):
-        return "Call " + o.short_call_string()
-
-    def _default_exit_func(self, o):
-        return "Return from {0} with value {1}".format(o["co_name"],
-                                                       o.short_return_value())
-
-    def _default_exception_func(self, o):
-        return "Encountered exception" #@@@ more info TODO
-
-    def _default_prefix_func(self, o):
-        return ("[%s][%03d:%s]" + "  "*self.depth) % (o["label"],
-                                                      o["f_lineno"],
-                                                      pretty_resize_string(o.nice_filename(), 15, exact=True))
-
-    def enter(self, o):
-        self.depth += 1
-        self.safe_write(self.prefix_func(o) + self.enter_func(o) + "\n")
-        return None
-
-    def exit(self, o):
-        self.safe_write(self.prefix_func(o) + self.exit_func(o) + "\n")
-        self.depth -= 1
-        return None
-
-    def exception(self, o):
-        self.safe_write(self.prefix_func(o) + self.exception_func(o) + "\n")
-        return None
-
-    def logging(self, o, event_type_string):
-        self.safe_write("ERROR TRACING with event: %s on line %d in %s\n" % (
-                event_type_string, o["f_lineno"], o["co_filename"]))
-        return None
-
-
-class OutputLogFile(OutputPlainText):
-    """
-    Convienience function to send plaintext output to a file.
-    """
-    def __init__(self, filename, verbosity, prefix_func=None, depth_spacer=" ",
-                 enter_func=None, exit_func=None, exception_func=None):
-        self.f = open(filename, 'a', 1) #line-buffering
-        super(OutputLogFile, self).__init__(verbosity, prefix_func=prefix_func,
-                                            depth_spacer=depth_spacer,
-                                            enter_func=enter_func,
-                                            exit_func=exit_func,
-                                            exception_func=exception_func)
-
-
-class OutputConsole(OutputPlainText):
-    """
-    Convienience function to send plaintext output to stdout.
-    """
-    def __init__(self, filename, verbosity, prefix_func=None, depth_spacer=" ",
-                 enter_func=None, exit_func=None, exception_func=None):
-        self.f = sys.stdout
-        super(OutputConsole, self).__init__(verbosity, prefix_func=prefix_func,
-                                            depth_spacer=depth_spacer,
-                                            enter_func=enter_func,
-                                            exit_func=exit_func,
-                                            exception_func=exception_func)
-
-
-class OutputDebug(EntrailsOutput):
-    """
-    Displays all output data with little formatting.
-    """
-    def __init__(self):
-        print "Entrails debug output started on {0}".format(
-            datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
-
-    def close(self):
-        print "Entrails debug output ended on {0}".format(
-            datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
-
-    def enter(self, o):
-        print "FUNCTION CALL: " + o.call_string()
-        for k, v in o.iteritems():
-            print "\t{0}:{1}".format(k, str(v))
-        return None
-
-    def exit(self, o):
-        print "FUNCTION EXIT"
-        for k, v in o.iteritems():
-            print "\t{0}:{1}".format(k, str(v))
-        return None
-
-    def exception(self, o):
-        print "EXCEPTION on line {0} in {1}".format(o["f_lineno"],
-                                                    o["co_filename"])
-        for k, v in o.iteritems():
-          print k + ": " + str(v)
-        return None
-
-    def logging(self, o, event_type_string):
-        print "ERROR TRACING with event: {0} on line {1} in {2}".format(event_type_string,
-                                                                        o["f_lineno"],
-                                                                        o["co_filename"])
-        return None
-
-
-class OutputHTML(EntrailsOutput):
-    """
-    Not fully implemented.  Basic HTML output.
-    """
-    def __init__(self, filename, verbosity):
-        self.depth = 0
-        self.f = open(filename, 'a', 1) #line-buffering
-        self.f.write("<html><body><h1>Trace of program started on {0}</h1>\n".format(datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")))
-
-    def __del__(self):
-        self.f.write("\n</body></html>\n")
-        self.f.close()
-
-    def enter(self, codeframe):
-        self.depth += 1
-        self.f.write(" > "*self.depth + "<b>Now entering:</b> " + codeframe["name"] + "<br />\n")
-        return None
-
-    def exit(self, codeframe):
-        self.depth -= 1
-        self.f.write(" > "*(self.depth+1) + "<b>and exiting:</b> " + codeframe["name"] + " with return value " + str(codeframe["return_value"]) + "<br />\n")
-        return None
-
-    def exception(self, o):
-        self.f.write("<h3>Encountered exception!</h3>")
-        return None
-
-    def logging(self, o, event_type_string):
-        self.f.write("<h4>ERROR TRACING with event: %s on line %d in %s</h4>" % (event_type_string, o["f_lineno"], o["co_filename"]))
-        return None
-
-
-class OutputXML(EntrailsOutput):
-    def __init__(self, filename):
-        self.filename = filename
-        self.root = ET.Element("data")
-
-    def close(self):
-        tree = ET.ElementTree(self.root)
-        tree.write(self.filename, xml_declaration=True, method="xml")
-
-    def write_out(self, codeframe, event_type):
-        event = ET.SubElement(self.root, "event")
-        event.attrib = {"timestamp" : "{0:f}".format(codeframe["timestamp"])}
-        for k, v in codeframe.iteritems():
-            if k != "timestamp":
-                ET.SubElement(event, k).text = str(v)
-        ET.SubElement(event, "type").text = event_type
-        ET.SubElement(event, "call_string").text = codeframe.call_string()
-        ET.SubElement(event, "short_call_string").text = codeframe.short_call_string()
-        ET.SubElement(event, "short_return_value").text = codeframe.short_return_value()
-        ET.SubElement(event, "nice_filename").text = codeframe.nice_filename()
-
-    def enter(self, codeframe):
-        self.write_out(codeframe, "enter")
-
-    def exit(self, codeframe):
-        self.write_out(codeframe, "exit")
-
-    def exception(self, codeframe):
-        self.write_out(codeframe, "exception")
+from . import _filter
+from . import _output
+from . import _trace
+
+__all__ = (
+    _filter.__all__ +
+    _output.__all__ +
+    _trace.__all__
+)
+
+from ._filter import *
+from ._output import *
+from ._trace import *
+

=== added file 'src/entrails/_filter.py'
--- src/entrails/_filter.py	1970-01-01 00:00:00 +0000
+++ src/entrails/_filter.py	2014-07-07 09:01:02 +0000
@@ -0,0 +1,60 @@
+# -----------------------------------------------------------------------------
+# _filter.py - Tracing filters.
+#
+# 2012, Ben Eills
+#
+# Copyright 2012, 2014, Ensoft Ltd.
+# -----------------------------------------------------------------------------
+
+"""Tracing filters."""
+
+__all__ = (
+    "EntrailsFilter",
+    "LibraryFilter",
+    "SelfFilter",
+)
+
+
+class EntrailsFilter(object):
+    """
+    Base class for filters.
+
+    Returns True if object remains unfiltered.
+    Must be very fast at executing, since we deal with so many objects.
+    """
+    def filter(self, frameobjects):
+        """
+        Trivial filter (allowing all events to pass through)
+        """
+        return frameobjects
+
+
+class LibraryFilter(EntrailsFilter):
+    """
+    Filters out major 3rd party libraries and Standard Library.
+    """
+    matches = ("/usr/lib", "/usr/local/lib", "/usr/lib64", "/twisted", "/zope")
+
+    def filter(self, frameobject):
+        for m in self.matches:
+            if m in frameobject['co_filename']:
+                return False
+        return True
+
+
+class SelfFilter(EntrailsFilter):
+    """
+    Filter out EnTrails events.
+
+    Performance-wise, it might be better to have this hardcoded below
+      to save a couple of JMP statements, but architecturally this is
+      where it goes.
+    """
+    matches = ("remove_output", "end_trace")
+
+    def filter(self, frameobject):
+        for m in self.matches:
+            if m in frameobject['co_name']:
+                return False
+        return True
+

=== added file 'src/entrails/_output.py'
--- src/entrails/_output.py	1970-01-01 00:00:00 +0000
+++ src/entrails/_output.py	2014-07-07 09:01:02 +0000
@@ -0,0 +1,235 @@
+# -----------------------------------------------------------------------------
+# _output.py - Output generators.
+#
+# 2012, Ben Eills
+#
+# Copyright 2012, 2014, Ensoft Ltd.
+# -----------------------------------------------------------------------------
+
+"""Output generators."""
+
+__all__ = (
+    "EntrailsOutput",
+    "ConsoleOutput",
+    "DebugOutput",
+    "HTMLOutput",
+    "LogFileOutput",
+    "PlainTextOutput",
+    "XMLOutput",
+)
+
+
+import datetime
+import sys
+
+from . import _utils
+
+
+class EntrailsOutput(object):
+    """
+    Base output adapter class.
+
+    Use as template to implement custom output adapters.
+    """
+    def __init__(self):
+        pass
+    def close(self):
+        pass
+    def enter(self, o):
+        pass
+    def exit(self, o):
+        pass
+    def exception(self, o):
+        pass
+    def logging(self, o, event_type_string):
+        pass
+
+
+class PlainTextOutput(EntrailsOutput):
+    """
+    Output adapter generating plaintext of variable verbosity, one
+    event per line.
+
+    TODO: printf formatting, verbosity
+    """
+    def __init__(self, verbosity, prefix_func=None, depth_spacer=" ",
+                 enter_func=None, exit_func=None, exception_func=None):
+        self.depth_spacer = depth_spacer
+        self.safe_write("Starting trace in program\n")
+        self.depth = 0
+        self.prefix_func = prefix_func or self._default_prefix_func
+        self.enter_func = enter_func or self._default_enter_func
+        self.exit_func = exit_func or self._default_exit_func
+        self.exception_func = exception_func or self._default_exception_func
+
+    def close(self):
+        if not self.f.closed:
+            self.f.close()
+
+    def safe_write(self, data):
+        if not self.f.closed:
+            self.f.write(data)
+
+    def _default_enter_func(self, o):
+        return "Call " + o.short_call_string()
+
+    def _default_exit_func(self, o):
+        return "Return from {0} with value {1}".format(o["co_name"],
+                                                       o.short_return_value())
+
+    def _default_exception_func(self, o):
+        return "Encountered exception" #@@@ more info TODO
+
+    def _default_prefix_func(self, o):
+        return ("[%s][%03d:%s]" + "  "*self.depth) % (o["label"],
+                                                      o["f_lineno"],
+                                                      _utils.pretty_resize_string(o.nice_filename(), 15, exact=True))
+
+    def enter(self, o):
+        self.depth += 1
+        self.safe_write(self.prefix_func(o) + self.enter_func(o) + "\n")
+        return None
+
+    def exit(self, o):
+        self.safe_write(self.prefix_func(o) + self.exit_func(o) + "\n")
+        self.depth -= 1
+        return None
+
+    def exception(self, o):
+        self.safe_write(self.prefix_func(o) + self.exception_func(o) + "\n")
+        return None
+
+    def logging(self, o, event_type_string):
+        self.safe_write("ERROR TRACING with event: %s on line %d in %s\n" % (
+                event_type_string, o["f_lineno"], o["co_filename"]))
+        return None
+
+
+class LogFileOutput(PlainTextOutput):
+    """
+    Convienience function to send plaintext output to a file.
+    """
+    def __init__(self, filename, verbosity, prefix_func=None, depth_spacer=" ",
+                 enter_func=None, exit_func=None, exception_func=None):
+        self.f = open(filename, 'a', 1) #line-buffering
+        super(LogFileOutput, self).__init__(verbosity, prefix_func=prefix_func,
+                                            depth_spacer=depth_spacer,
+                                            enter_func=enter_func,
+                                            exit_func=exit_func,
+                                            exception_func=exception_func)
+
+
+class ConsoleOutput(PlainTextOutput):
+    """
+    Convienience function to send plaintext output to stdout.
+    """
+    def __init__(self, filename, verbosity, prefix_func=None, depth_spacer=" ",
+                 enter_func=None, exit_func=None, exception_func=None):
+        self.f = sys.stdout
+        super(ConsoleOutput, self).__init__(verbosity, prefix_func=prefix_func,
+                                            depth_spacer=depth_spacer,
+                                            enter_func=enter_func,
+                                            exit_func=exit_func,
+                                            exception_func=exception_func)
+
+
+class DebugOutput(EntrailsOutput):
+    """
+    Displays all output data with little formatting.
+    """
+    def __init__(self):
+        print "Entrails debug output started on {0}".format(
+            datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
+
+    def close(self):
+        print "Entrails debug output ended on {0}".format(
+            datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
+
+    def enter(self, o):
+        print "FUNCTION CALL: " + o.call_string()
+        for k, v in o.iteritems():
+            print "\t{0}:{1}".format(k, str(v))
+        return None
+
+    def exit(self, o):
+        print "FUNCTION EXIT"
+        for k, v in o.iteritems():
+            print "\t{0}:{1}".format(k, str(v))
+        return None
+
+    def exception(self, o):
+        print "EXCEPTION on line {0} in {1}".format(o["f_lineno"],
+                                                    o["co_filename"])
+        for k, v in o.iteritems():
+          print k + ": " + str(v)
+        return None
+
+    def logging(self, o, event_type_string):
+        print "ERROR TRACING with event: {0} on line {1} in {2}".format(event_type_string,
+                                                                        o["f_lineno"],
+                                                                        o["co_filename"])
+        return None
+
+
+class HTMLOutput(EntrailsOutput):
+    """
+    Not fully implemented.  Basic HTML output.
+    """
+    def __init__(self, filename, verbosity):
+        self.depth = 0
+        self.f = open(filename, 'a', 1) #line-buffering
+        self.f.write("<html><body><h1>Trace of program started on {0}</h1>\n".format(datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")))
+
+    def __del__(self):
+        self.f.write("\n</body></html>\n")
+        self.f.close()
+
+    def enter(self, codeframe):
+        self.depth += 1
+        self.f.write(" > "*self.depth + "<b>Now entering:</b> " + codeframe["name"] + "<br />\n")
+        return None
+
+    def exit(self, codeframe):
+        self.depth -= 1
+        self.f.write(" > "*(self.depth+1) + "<b>and exiting:</b> " + codeframe["name"] + " with return value " + str(codeframe["return_value"]) + "<br />\n")
+        return None
+
+    def exception(self, o):
+        self.f.write("<h3>Encountered exception!</h3>")
+        return None
+
+    def logging(self, o, event_type_string):
+        self.f.write("<h4>ERROR TRACING with event: %s on line %d in %s</h4>" % (event_type_string, o["f_lineno"], o["co_filename"]))
+        return None
+
+
+class XMLOutput(EntrailsOutput):
+    def __init__(self, filename):
+        self.filename = filename
+        self.root = ET.Element("data")
+
+    def close(self):
+        tree = ET.ElementTree(self.root)
+        tree.write(self.filename, xml_declaration=True, method="xml")
+
+    def write_out(self, codeframe, event_type):
+        event = ET.SubElement(self.root, "event")
+        event.attrib = {"timestamp" : "{0:f}".format(codeframe["timestamp"])}
+        for k, v in codeframe.iteritems():
+            if k != "timestamp":
+                ET.SubElement(event, k).text = str(v)
+        ET.SubElement(event, "type").text = event_type
+        ET.SubElement(event, "call_string").text = codeframe.call_string()
+        ET.SubElement(event, "short_call_string").text = codeframe.short_call_string()
+        ET.SubElement(event, "short_return_value").text = codeframe.short_return_value()
+        ET.SubElement(event, "nice_filename").text = codeframe.nice_filename()
+
+    def enter(self, codeframe):
+        self.write_out(codeframe, "enter")
+
+    def exit(self, codeframe):
+        self.write_out(codeframe, "exit")
+
+    def exception(self, codeframe):
+        self.write_out(codeframe, "exception")
+

=== added file 'src/entrails/_trace.py'
--- src/entrails/_trace.py	1970-01-01 00:00:00 +0000
+++ src/entrails/_trace.py	2014-07-07 09:01:02 +0000
@@ -0,0 +1,258 @@
+# -----------------------------------------------------------------------------
+# _trace.py - Execution tracer
+#
+# 2012, Ben Eills
+#
+# Copyright 2012, 2014, Ensoft Ltd.
+# -----------------------------------------------------------------------------
+
+"""Execution tracer."""
+
+__all__ = (
+    "Entrails",
+)
+
+
+import collections
+import os.path
+import sys
+import time
+
+from . import _filter
+from . import _utils
+
+
+class _Frame(dict):
+    """
+    Holds information about a frame.
+
+    Use as a dict to access the important bits of the frame and arg
+    parameters, along with timestamp and label.  Also has convienience
+    methods to generate function call string and class info.  This is
+    supplied to an output adapter's call(), return() and exception()
+    methods.
+    """
+    def parameters(self):
+        """
+        Returns dict of form {parameter_name: argument_value}.
+        """
+        # We rely on CPython putting arguments at start of f_locals (in reverse
+        #   order for some reason...).  This is undocumented, but consistent.
+        parameters = [(k, v) for k, v in self["f_locals"].iteritems()
+                    if k in self["co_varnames"][0:self["co_argcount"]]]
+        parameters.reverse()
+        return collections.OrderedDict(parameters)
+
+    def arguments(self):
+        """
+        Returns argument list, possibly excluding the first 'self' arg
+        if the function is a method.
+
+        Only designed for 'call' event (i.e. function entry)
+        """
+        # Possibly chop off first self argument
+        ignorer = 0 if not self.is_method() else 1
+        return self.parameters().values()[ignorer:]
+
+    def string_arguments(self):
+        """
+        Returns list of nice string argument representations.
+
+        If the argument object encounters an error during repr() call
+          (some standard library classes can do this under certain conditions)
+          fail cleanly.
+        """
+        strings = []
+        for arg in self.arguments():
+            try:
+                strings.append(repr(arg))
+            except:
+                strings.append('<repr error>')
+        return strings
+
+    def call_string(self):
+        """
+        Returns a pretty string representation of the function call built
+          from function name and args, nicely formatted/abbrieviated.
+
+        Only designed for 'call' event (i.e. function entry)
+        """
+        if self.is_method():
+            return '{0}.{1}({2})'.format(self.instance_name(), self['co_name'],
+                                         ', '.join(self.string_arguments()))
+        else:
+            return '{0}({1})'.format(self['co_name'],
+                                     ', '.join(self.string_arguments()))
+
+    def short_call_string(self, length=40):
+        """
+        Returns a pretty string of the function call, shortened to at
+          most length characters.
+
+        Only designed for 'call' event (i.e. function entry)
+        """
+        return _utils.pretty_resize_string(self.call_string(), length)
+
+    def short_return_value(self, length=40):
+        """
+        Returns a pretty string representation of the return value,
+          shortened to at most length characters.
+
+        Only designed for 'call' event (i.e. function entry)
+        """
+        try:
+            return _utils.pretty_resize_string(repr(self['return_value']), length)
+        except:
+            return _utils.pretty_resize_string('<repr error>', length)
+
+        # Do we close quotation marks in string return values?
+        # if len(repr(rv)) > 40:
+        #     if rv.__class__.__name__ == 'str':
+        #         return repr(rv)[0:length-4]+"...'"
+        #     else:
+        #         return repr(rv)[0:length-3]+"..."
+        # else:
+        #     return repr(rv)
+
+    def nice_filename(self):
+        """
+        Nice filename, without directory segment.
+        """
+        return os.path.basename(self["co_filename"])
+
+    def is_method(self):
+        """
+        True if function is an instance method  (and the programmer
+          did not defy all convention by abandonning the use of 'self'
+          as the instance pointer).
+        Only designed for 'call' event (i.e. function entry)
+
+        TODO: What happens for class methods/other decorated methods?
+        """
+        if self['co_varnames'] and self['co_varnames'][0] == 'self':
+            return True
+        return False
+
+    def instance_name(self):
+        """
+        Class instance name of method, or empty string if not method.
+        Only designed for 'call' event (i.e. function entry)
+        We cache value after first proper lookup.
+        """
+        if 'instance_name' not in self:
+            self['instance_name'] = self._retrieve_instance_name()
+        return self['instance_name']
+
+    def _retrieve_instance_name(self):
+        """
+        Get class instance name by performance-intensive lookup.
+        Should only be called on methods.
+        """
+        try:
+            # This is confusing.  We go into the previous (parent) frame and
+            #   find the local variable name in that pointing to a our class.
+            for k, v in self['f_back'].f_locals.items():
+                if v == self['f_locals']['self']:
+                    return k
+        except:
+            return '<lookup error>'
+
+    def class_name(self):
+        """
+        Class name of method, or empty string if not method.
+        Only designed for 'call' event (i.e. function entry)
+        Should only be called on methods.
+        """
+        try:
+            return self["f_locals"]["self"].__class__.__name__
+        except:
+            return '<lookup error>'
+
+
+class Entrails(object):
+    """
+    Implements entrails functionality to monitor program execution flow.
+
+    Instantiate at in process to be traced, add outputs and call start_trace().
+    Run end_trace() to safely close outputs and stop tracing.
+    """
+    event_names = { 'call' : 'enter',
+                    'return' : 'exit',
+                    'exception' : 'exception' }
+
+    def __init__(self,
+                 label='<untitled>',
+                 filters=(_filter.LibraryFilter(), _filter.SelfFilter())):
+        self._outputs = []
+        self._init_time = time.time()
+        self._label = label
+        self._filters = filters
+
+    def filter(self, obj):
+        """
+        Returns True if object remains unfiltered, False otherise.
+        """
+        if all(f.filter(obj) for f in self._filters):
+            return True
+        return False
+
+    def _trace_function(self, trace, event, arg):
+        # Build Frame
+        obj = _Frame()
+        obj["label"] = self._label
+        obj["timestamp"] = time.time() - self._init_time
+        obj["f_lineno"] = trace.f_lineno
+        obj["f_back"] = trace.f_back
+        obj["f_locals"] = trace.f_locals
+        obj["co_name"] = trace.f_code.co_name
+        obj["co_argcount"] = trace.f_code.co_argcount
+        obj["co_filename"] = trace.f_code.co_filename
+        obj["co_names"] = trace.f_code.co_names
+        obj["co_varnames"] = trace.f_code.co_varnames
+
+        # Filter
+        # If this object is to be discarded, return trace_function to
+        #   indicate that we wish to continue tracing.
+        if not self.filter(obj):
+            return self._trace_function
+
+        # Possibly add return_value.  If event is non-return, arg isn't really
+        #   that useful.
+        if event is 'return':
+            obj["return_value"] = arg
+
+        if event in self.event_names:
+            for output in self._outputs:
+                #try:
+                getattr(output, self.event_names[event])(obj)
+        return self._trace_function
+
+    def add_output(self, output_object):
+        """
+        Adds output adapter, accepting argument of type EntrailsOutput.
+        """
+        self._outputs.append(output_object)
+
+    def remove_output(self, output_object):
+        """
+        Cease sending tracing data to a particular output.
+        Removes from internal list and runs output.__del__()@@@
+        """
+        output_object.close()
+        if output_object in self._outputs:
+            self._outputs.remove(output_object)
+
+    def start_trace(self):
+        """
+        Start tracing.
+        """
+        sys.settrace(self._trace_function)
+
+    def end_trace(self):
+        """
+        Stop tracing.  Safely removes all outputs.
+        """
+        for o in self._outputs:
+            self.remove_output(o)
+        sys.settrace(None)
+

=== added file 'src/entrails/_utils.py'
--- src/entrails/_utils.py	1970-01-01 00:00:00 +0000
+++ src/entrails/_utils.py	2014-07-07 09:01:02 +0000
@@ -0,0 +1,29 @@
+# -----------------------------------------------------------------------------
+# _utils.py - Shared utilities
+#
+# July 2014, Phil Connell
+#
+# Copyright 2014, Ensoft Ltd.
+# -----------------------------------------------------------------------------
+
+"""Shared utilities."""
+
+__all__ = (
+    "pretty_resize_string",
+)
+
+
+def pretty_resize_string(string, length=25, cutoff='back', exact=False):
+    """
+    Shortens or lengthens a string to be at most length characters long.
+
+    cutoff should be 'front' or 'back', dictating where the ellipsis goes.
+    exact toggles whitespace padding.
+    """
+    if len(string) > length:
+        cutoff_string = '{0}...' if cutoff is 'back' else '...{0}'
+        return cutoff_string.format(string[3-length:])
+    else:
+        exact_string = '{:>25}' if exact else '{0}'
+        return exact_string.format(string)
+

=== modified file 'src/trace.py'
--- src/trace.py	2012-08-20 10:31:04 +0000
+++ src/trace.py	2014-07-07 09:01:02 +0000
@@ -1,4 +1,4 @@
-#!/usr/bin/env python2.7
+#!/usr/bin/env python
 # -----------------------------------------------------------------------------
 # EnTrails - Python Execution Tracing Module
 # Copyright 2012, Ensoft Ltd.
@@ -106,13 +106,13 @@
         label = args.label
 
     if args.output == 'debug':
-        output_code_string = "_entrails_o = entrails.OutputDebug()"
+        output_code_string = "_entrails_o = entrails.DebugOutput()"
     elif args.output == 'logfile':
-        output_code_string = "_entrails_o = entrails.OutputLogFile(\"%s\", 1)" % args.filename
+        output_code_string = "_entrails_o = entrails.LogFileOutput(\"%s\", 1)" % args.filename
     elif args.output == 'console':
-        output_code_string = "_entrails_o = entrails.OutputConsole(1)"
+        output_code_string = "_entrails_o = entrails.ConsoleOutput(1)"
     elif args.output == 'xml':
-        output_code_string = "_entrails_o = entrails.OutputXML(\"%s\")" % args.filename
+        output_code_string = "_entrails_o = entrails.XMLOutput(\"%s\")" % args.filename
 
     if args.action == "add":
         if not already_modified(args.sourcefile):