First draft

This is totally incomplete
E.g. the tests are ripped out of Trio's current MultiError tests and
probably just wrong because of that
But I want to get something up...

Author: njsmith

exceptiongroup/__init__.py

@@ -1,3 +1,46 @@
 """Top-level package for exceptiongroup."""
 
 from ._version import __version__
+
+__all__ = ["ExceptionGroup", "split", "catch"]
+
+
+class ExceptionGroup(BaseException):
+    """An exception that contains other exceptions.
+
+    Its main use is to represent the situation when multiple child tasks all
+    raise errors "in parallel".
+
+    Args:
+      message (str): A description of the overall exception.
+      exceptions (list): The exceptions.
+      sources (list): For each exception, a string describing where it came
+        from.
+
+    Raises:
+      TypeError: if any of the passed in objects are not instances of
+          :exc:`BaseException`.
+      ValueError: if the exceptions and sources lists don't have the same
+          length.
+
+    """
+
+    def __init__(self, message, exceptions, sources):
+        super().__init__(message)
+        self.exceptions = list(exceptions)
+        for exc in self.exceptions:
+            if not isinstance(exc, BaseException):
+                raise TypeError(
+                    "Expected an exception object, not {!r}".format(exc)
+                )
+        self.sources = list(sources)
+        if len(self.sources) != len(self.exceptions):
+            raise ValueError(
+                "different number of sources ({}) and exceptions ({})".format(
+                    len(self.sources), len(self.exceptions)
+                )
+            )
+
+
+from . import _monkeypatch
+from ._tools import split, catch

exceptiongroup/_monkeypatch.py

@@ -0,0 +1,126 @@
+################################################################
+# ExceptionGroup traceback formatting
+#
+# This file contains the terrible, terrible monkey patching of various things,
+# especially the traceback module, to add support for handling
+# ExceptionGroups.
+################################################################
+
+import sys
+import textwrap
+import traceback
+import warnings
+
+from . import ExceptionGroup
+
+traceback_exception_original_init = traceback.TracebackException.__init__
+
+
+def traceback_exception_init(
+    self,
+    exc_type,
+    exc_value,
+    exc_traceback,
+    *,
+    limit=None,
+    lookup_lines=True,
+    capture_locals=False,
+    _seen=None
+):
+    if _seen is None:
+        _seen = set()
+
+    # Capture the original exception and its cause and context as
+    # TracebackExceptions
+    traceback_exception_original_init(
+        self,
+        exc_type,
+        exc_value,
+        exc_traceback,
+        limit=limit,
+        lookup_lines=lookup_lines,
+        capture_locals=capture_locals,
+        _seen=_seen,
+    )
+
+    # Capture each of the exceptions in the ExceptionGroup along with each of
+    # their causes and contexts
+    if isinstance(exc_value, ExceptionGroup):
+        exceptions = []
+        sources = []
+        for exc, source in zip(exc_value.exceptions, exc_value.sources):
+            if exc not in _seen:
+                exceptions.append(
+                    traceback.TracebackException.from_exception(
+                        exc,
+                        limit=limit,
+                        lookup_lines=lookup_lines,
+                        capture_locals=capture_locals,
+                        # copy the set of _seen exceptions so that duplicates
+                        # shared between sub-exceptions are not omitted
+                        _seen=set(_seen),
+                    )
+                )
+                sources.append(source)
+        self.exceptions = exceptions
+        self.sources = sources
+    else:
+        self.exceptions = []
+        self.sources = []
+
+
+def traceback_exception_format(self, *, chain=True):
+    yield from traceback_exception_original_format(self, chain=chain)
+
+    for exc, source in zip(self.exceptions, self.sources):
+        yield "\n  {}:\n\n".format(source)
+        yield from (
+            textwrap.indent(line, " " * 4) for line in exc.format(chain=chain)
+        )
+
+
+def exceptiongroup_excepthook(etype, value, tb):
+    sys.stderr.write("".join(traceback.format_exception(etype, value, tb)))
+
+
+traceback.TracebackException.__init__ = traceback_exception_init
+traceback_exception_original_format = traceback.TracebackException.format
+traceback.TracebackException.format = traceback_exception_format
+
+IPython_handler_installed = False
+warning_given = False
+if "IPython" in sys.modules:
+    import IPython
+
+    ip = IPython.get_ipython()
+    if ip is not None:
+        if ip.custom_exceptions != ():
+            warnings.warn(
+                "IPython detected, but you already have a custom exception "
+                "handler installed. I'll skip installing exceptiongroup's "
+                "custom handler, but this means you won't see full tracebacks "
+                "for ExceptionGroups.",
+                category=RuntimeWarning,
+            )
+            warning_given = True
+        else:
+
+            def trio_show_traceback(self, etype, value, tb, tb_offset=None):
+                # XX it would be better to integrate with IPython's fancy
+                # exception formatting stuff (and not ignore tb_offset)
+                exceptiongroup_excepthook(etype, value, tb)
+
+            ip.set_custom_exc((ExceptionGroup,), trio_show_traceback)
+            IPython_handler_installed = True
+
+if sys.excepthook is sys.__excepthook__:
+    sys.excepthook = exceptiongroup_excepthook
+else:
+    if not IPython_handler_installed and not warning_given:
+        warnings.warn(
+            "You seem to already have a custom sys.excepthook handler "
+            "installed. I'll skip installing exceptiongroup's custom handler, "
+            "but this means you won't see full tracebacks for "
+            "ExceptionGroups.",
+            category=RuntimeWarning,
+        )

exceptiongroup/_tests/test_exceptiongroup.py

@@ -0,0 +1,2 @@
+import traceback
+from exceptiongroup import ExceptionGroup, split, catch

exceptiongroup/_tests/test_scripts/__init__.py

@@ -0,0 +1,2 @@
+# This isn't really a package, everything in here is a standalone script. This
+# __init__.py is just to fool setup.py into actually installing the things.

exceptiongroup/_tests/test_scripts/_common.py

@@ -0,0 +1,7 @@
+# https://coverage.readthedocs.io/en/latest/subprocess.html
+try:
+    import coverage
+except ImportError:  # pragma: no cover
+    pass
+else:
+    coverage.process_startup()

exceptiongroup/_tests/test_scripts/custom_excepthook.py

@@ -0,0 +1,20 @@
+import _common
+
+import sys
+
+
+def custom_excepthook(*args):
+    print("custom running!")
+    return sys.__excepthook__(*args)
+
+
+sys.excepthook = custom_excepthook
+
+# Should warn that we'll get kinda-broken tracebacks
+import exceptiongroup
+
+# The custom excepthook should run, because we were polite and didn't
+# override it
+raise exceptiongroup.ExceptionGroup(
+    "demo", [ValueError(), KeyError()], ["a", "b"]
+)

exceptiongroup/_tests/test_scripts/ipython_custom_exc.py

@@ -0,0 +1,37 @@
+import _common
+
+# Override the regular excepthook too -- it doesn't change anything either way
+# because ipython doesn't use it, but we want to make sure exceptiongroup
+# doesn't warn about it.
+import sys
+
+
+def custom_excepthook(*args):
+    print("custom running!")
+    return sys.__excepthook__(*args)
+
+
+sys.excepthook = custom_excepthook
+
+import IPython
+ip = IPython.get_ipython()
+
+
+# Set this to some random nonsense
+class SomeError(Exception):
+    pass
+
+
+def custom_exc_hook(etype, value, tb, tb_offset=None):
+    ip.showtraceback()
+
+
+ip.set_custom_exc((SomeError,), custom_exc_hook)
+
+import exceptiongroup
+
+# The custom excepthook should run, because we were polite and didn't
+# override it
+raise exceptiongroup.ExceptionGroup(
+    "demo", [ValueError(), KeyError()], ["a", "b"]
+)

exceptiongroup/_tests/test_scripts/simple_excepthook.py

@@ -0,0 +1,23 @@
+import _common
+
+import exceptiongroup
+
+
+def exc1_fn():
+    try:
+        raise ValueError
+    except Exception as exc:
+        return exc
+
+
+def exc2_fn():
+    try:
+        raise KeyError
+    except Exception as exc:
+        return exc
+
+
+# This should be printed nicely, because we overrode sys.excepthook
+raise exceptiongroup.ExceptionGroup(
+    "demo", [exc1_fn(), exc2_fn()], ["a", "b"],
+)

exceptiongroup/_tests/test_scripts/simple_excepthook_IPython.py

@@ -0,0 +1,7 @@
+import _common
+
+# To tickle the "is IPython loaded?" logic, make sure that our package
+# tolerates IPython loaded but not actually in use
+import IPython
+
+import simple_excepthook