Merge pull request #2223 from takluyver/custom_traceback

Custom traceback API

Closes gh-2221

docs/source/config/integrating.txt

@@ -0,0 +1,44 b''
+.. _integrating:
+
+=====================================
+Integrating your objects with IPython
+=====================================
+
+Tab completion
+==============
+
+To change the attributes displayed by tab-completing your object, define a
+``__dir__(self)`` method for it. For more details, see the documentation of the
+built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_.
+
+Rich display
+============
+
+The notebook and the Qt console can display richer representations of objects.
+To use this, you can define any of a number of ``_repr_*_()`` methods. Note that
+these are surrounded by single, not double underscores.
+
+Both the notebook and the Qt console can display ``svg``, ``png`` and ``jpeg``
+representations. The notebook can also display ``html``, ``javascript``,
+and ``latex``. If the methods don't exist, or return ``None``, it falls
+back to a standard ``repr()``.
+
+For example::
+
+    class Shout(object):
+        def __init__(self, text):
+            self.text = text
+        
+        def _repr_html_(self):
+            return "<h1>" + self.text + "</h1>"
+
+Custom exception tracebacks
+===========================
+
+Rarely, you might want to display a different traceback with an exception -
+IPython's own parallel computing framework does this to display errors from the
+engines. To do this, define a ``_render_traceback_(self)`` method which returns
+a list of strings, each containing one line of the traceback.
+
+Please be conservative in using this feature; by replacing the default traceback
+you may hide important information from the user.

IPython/core/display.py

@@ -186,6 +186,8 b' def display_latex(*objs, **kwargs):'
 
 def display_json(*objs, **kwargs):
     """Display the JSON representation of an object.
+    
+    Note that not many frontends support displaying JSON.
 
     Parameters
     ----------

IPython/core/interactiveshell.py

@@ -86,22 +86,6 b' from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,'
 from IPython.utils.warn import warn, error
 import IPython.core.hooks
 
-# FIXME: do this in a function to avoid circular dependencies
-# A better solution is to remove IPython.parallel.error,
-# and place those classes in IPython.core.error.
-
-class RemoteError(Exception):
-    pass
-
-def _import_remote_error():
-    global RemoteError
-    try:
-        from IPython.parallel.error import RemoteError
-    except:
-        pass
-
-_import_remote_error()
-
 #-----------------------------------------------------------------------------
 # Globals
 #-----------------------------------------------------------------------------
@@ -1735,10 +1719,6 b' class InteractiveShell(SingletonConfigurable):'
                 self.showsyntaxerror(filename)
             elif etype is UsageError:
                 self.write_err("UsageError: %s" % value)
-            elif issubclass(etype, RemoteError):
-                # IPython.parallel remote exceptions.
-                # Draw the remote traceback, not the local one.
-                self._showtraceback(etype, value, value.render_traceback())
             else:
                 if exception_only:
                     stb = ['An exception has occurred, use %tb to see '
@@ -1746,7 +1726,13 b' class InteractiveShell(SingletonConfigurable):'
                     stb.extend(self.InteractiveTB.get_exception_only(etype,
                                                                      value))
                 else:
-                    stb = self.InteractiveTB.structured_traceback(etype,
+                    try:
+                        # Exception classes can customise their traceback - we
+                        # use this in IPython.parallel for exceptions occurring
+                        # in the engines. This should return a list of strings.
+                        stb = value._render_traceback_()
+                    except Exception:
+                        stb = self.InteractiveTB.structured_traceback(etype,
                                             value, tb, tb_offset=tb_offset)
 
                     self._showtraceback(etype, value, stb)

IPython/core/tests/test_interactiveshell.py

@@ -33,6 +33,7 b' import nose.tools as nt'
 
 # Our own
 from IPython.testing.decorators import skipif
+from IPython.testing import tools as tt
 from IPython.utils import io
 
 #-----------------------------------------------------------------------------
@@ -401,6 +402,18 b' class TestSystemRaw(unittest.TestCase):'
         cmd = ur'''python -c "'åäö'"   '''
         ip.system_raw(cmd)
 
+class TestModules(unittest.TestCase, tt.TempFileMixin):
+    def test_extraneous_loads(self):
+        """Test we're not loading modules on startup that we shouldn't.
+        """
+        self.mktmp("import sys\n"
+                   "print('numpy' in sys.modules)\n"
+                   "print('IPython.parallel' in sys.modules)\n"
+                   "print('IPython.zmq' in sys.modules)\n"
+                   )
+        out = "False\nFalse\nFalse\n"
+        tt.ipexec_validate(self.fname, out)
+
 
 def test__IPYTHON__():
     # This shouldn't raise a NameError, that's all

IPython/parallel/error.py

@@ -193,6 +193,9 b' class RemoteError(KernelError):'
     def render_traceback(self):
         """render traceback to a list of lines"""
         return (self.traceback or "No traceback available").splitlines()
+    
+    # Special method for custom tracebacks within IPython
+    _render_traceback_ = render_traceback
 
     def print_traceback(self, excid=None):
         """print my traceback"""

docs/source/config/index.txt

@@ -10,5 +10,6 b' Configuration and customization'
    overview.txt
    extensions/index.txt
    ipython.txt
+   integrating.txt
    editors.txt
    old.txt

docs/source/whatsnew/development.txt

@@ -6,4 +6,8 b' This document describes in-flight development work.'
 
 The CodeMirror js library has been updated fron 2.23 to 2.32 
 this might induce a few changes in behavior of keymaps in the notebook, 
-especially intenting/deindenting blocks that is now bounded to Ctrl+] and ctr+[
+especially intenting/deindenting blocks that is now bound to Ctrl+] and ctr+[
+
+* Exception types can now be displayed with a custom traceback, by defining a
+  ``_render_traceback_()`` method which returns a list of strings, each
+  containing one line of the traceback.