Replace MultiError with BaseExceptionGroup

docs-requirements.in

@@ -13,6 +13,7 @@ async_generator >= 1.9
 idna
 outcome
 sniffio
+exceptiongroup
 
 # See note in test-requirements.in
 immutables >= 0.6

docs-requirements.txt

@@ -1,8 +1,8 @@
 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.7
 # To update, run:
 #
-#    pip-compile --output-file docs-requirements.txt docs-requirements.in
+#    pip-compile --output-file=docs-requirements.txt docs-requirements.in
 #
 alabaster==0.7.12
     # via sphinx
@@ -28,6 +28,8 @@ docutils==0.17.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
+exceptiongroup==1.0.0rc1
+    # via -r docs-requirements.in
 idna==3.3
     # via
     #   -r docs-requirements.in
@@ -36,6 +38,8 @@ imagesize==1.2.0
     # via sphinx
 immutables==0.16
     # via -r docs-requirements.in
+importlib-metadata==4.10.1
+    # via click
 incremental==21.3.0
     # via towncrier
 jinja2==3.0.2
@@ -87,5 +91,14 @@ toml==0.10.2
     # via towncrier
 towncrier==21.3.0
     # via -r docs-requirements.in
+typing-extensions==4.0.1
+    # via
+    #   immutables
+    #   importlib-metadata
 urllib3==1.26.7
     # via requests
+zipp==3.7.0
+    # via importlib-metadata
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

docs/source/design.rst

@@ -465,9 +465,6 @@ There are two notable sub-modules that are largely independent of
 the rest of Trio, and could (possibly should?) be extracted into their
 own independent packages:
 
-* ``_multierror.py``: Implements :class:`MultiError` and associated
-  infrastructure.
-
 * ``_ki.py``: Implements the core infrastructure for safe handling of
   :class:`KeyboardInterrupt`.
 

docs/source/history.rst

@@ -232,9 +232,9 @@ Bugfixes
 - On Ubuntu systems, the system Python includes a custom
   unhandled-exception hook to perform `crash reporting
   <https://wiki.ubuntu.com/Apport>`__. Unfortunately, Trio wants to use
-  the same hook to print nice `MultiError` tracebacks, causing a
+  the same hook to print nice ``MultiError`` tracebacks, causing a
   conflict. Previously, Trio would detect the conflict, print a warning,
-  and you just wouldn't get nice `MultiError` tracebacks. Now, Trio has
+  and you just wouldn't get nice ``MultiError`` tracebacks. Now, Trio has
   gotten clever enough to integrate its hook with Ubuntu's, so the two
   systems should Just Work together. (`#1065 <https://github.com/python-trio/trio/issues/1065>`__)
 - Fixed an over-strict test that caused failures on Alpine Linux.
@@ -436,7 +436,7 @@ Features
   violated. (One common source of such violations is an async generator
   that yields within a cancel scope.) The previous behavior was an
   inscrutable chain of TrioInternalErrors. (`#882 <https://github.com/python-trio/trio/issues/882>`__)
-- MultiError now defines its ``exceptions`` attribute in ``__init__()``
+- ``MultiError`` now defines its ``exceptions`` attribute in ``__init__()``
   to better support linters and code autocompletion. (`#1066 <https://github.com/python-trio/trio/issues/1066>`__)
 - Use ``__slots__`` in more places internally, which should make Trio slightly faster. (`#984 <https://github.com/python-trio/trio/issues/984>`__)
 
@@ -457,7 +457,7 @@ Bugfixes
   :meth:`~trio.Path.cwd`, are now async functions.  Previously, a bug
   in the forwarding logic meant :meth:`~trio.Path.cwd` was synchronous
   and :meth:`~trio.Path.home` didn't work at all. (`#960 <https://github.com/python-trio/trio/issues/960>`__)
-- An exception encapsulated within a :class:`MultiError` doesn't need to be
+- An exception encapsulated within a ``MultiError`` doesn't need to be
   hashable anymore.
 
   .. note::
@@ -1248,7 +1248,7 @@ Other changes
   interfering with direct use of
   :func:`~trio.testing.wait_all_tasks_blocked` in the same test.
 
-* :meth:`MultiError.catch` now correctly preserves ``__context__``,
+* ``MultiError.catch()`` now correctly preserves ``__context__``,
   despite Python's best attempts to stop us (`#165
   <https://github.com/python-trio/trio/issues/165>`__)
 

docs/source/reference-core.rst

@@ -641,7 +641,7 @@ crucial things to keep in mind:
 
   * Any unhandled exceptions are re-raised inside the parent task. If
     there are multiple exceptions, then they're collected up into a
-    single :exc:`MultiError` exception.
+    single ``BaseExceptionGroup`` or ``ExceptionGroup`` exception.
 
 Since all tasks are descendents of the initial task, one consequence
 of this is that :func:`run` can't finish until all tasks have
@@ -712,14 +712,9 @@ limitation. Consider code like::
 what? In some sense, the answer should be "both of these at once", but
 in Python there can only be one exception at a time.
 
-Trio's answer is that it raises a :exc:`MultiError` object. This is a
+Trio's answer is that it raises a ``BaseExceptionGroup`` object. This is a
 special exception which encapsulates multiple exception objects –
-either regular exceptions or nested :exc:`MultiError`\s. To make these
-easier to work with, Trio installs a custom `sys.excepthook` that
-knows how to print nice tracebacks for unhandled :exc:`MultiError`\s,
-and it also provides some helpful utilities like
-:meth:`MultiError.catch`, which allows you to catch "part of" a
-:exc:`MultiError`.
+either regular exceptions or nested ``BaseExceptionGroup``\s.
 
 
 Spawning tasks without becoming a parent
@@ -837,104 +832,6 @@ The nursery API
    See :meth:`~Nursery.start`.
 
 
-Working with :exc:`MultiError`\s
-++++++++++++++++++++++++++++++++
-
-.. autoexception:: MultiError
-
-   .. attribute:: exceptions
-
-      The list of exception objects that this :exc:`MultiError`
-      represents.
-
-   .. automethod:: filter
-
-   .. automethod:: catch
-      :with:
-
-Examples:
-
-Suppose we have a handler function that discards :exc:`ValueError`\s::
-
-    def handle_ValueError(exc):
-        if isinstance(exc, ValueError):
-            return None
-        else:
-            return exc
-
-Then these both raise :exc:`KeyError`::
-
-    with MultiError.catch(handle_ValueError):
-         raise MultiError([KeyError(), ValueError()])
-
-    with MultiError.catch(handle_ValueError):
-         raise MultiError([
-             ValueError(),
-             MultiError([KeyError(), ValueError()]),
-         ])
-
-And both of these raise nothing at all::
-
-    with MultiError.catch(handle_ValueError):
-         raise MultiError([ValueError(), ValueError()])
-
-    with MultiError.catch(handle_ValueError):
-         raise MultiError([
-             MultiError([ValueError(), ValueError()]),
-             ValueError(),
-         ])
-
-You can also return a new or modified exception, for example::
-
-    def convert_ValueError_to_MyCustomError(exc):
-        if isinstance(exc, ValueError):
-            # Similar to 'raise MyCustomError from exc'
-            new_exc = MyCustomError(...)
-            new_exc.__cause__ = exc
-            return new_exc
-        else:
-            return exc
-
-In the example above, we set ``__cause__`` as a form of explicit
-context chaining. :meth:`MultiError.filter` and
-:meth:`MultiError.catch` also perform implicit exception chaining – if
-you return a new exception object, then the new object's
-``__context__`` attribute will automatically be set to the original
-exception.
-
-We also monkey patch :class:`traceback.TracebackException` to be able
-to handle formatting :exc:`MultiError`\s. This means that anything that
-formats exception messages like :mod:`logging` will work out of the
-box::
-
-    import logging
-
-    logging.basicConfig()
-
-    try:
-        raise MultiError([ValueError("foo"), KeyError("bar")])
-    except:
-        logging.exception("Oh no!")
-        raise
-
-Will properly log the inner exceptions:
-
-.. code-block:: none
-
-    ERROR:root:Oh no!
-    Traceback (most recent call last):
-      File "<stdin>", line 2, in <module>
-    trio.MultiError: ValueError('foo',), KeyError('bar',)
-
-    Details of embedded exception 1:
-
-      ValueError: foo
-
-    Details of embedded exception 2:
-
-      KeyError: 'bar'
-
-
 .. _task-local-storage:
 
 Task-local storage

docs/source/tutorial.rst

@@ -13,14 +13,13 @@ Tutorial
    still probably read this, because Trio is different.)
 
    Trio turns Python into a concurrent language. It takes the core
-   async/await syntax introduced in 3.5, and uses it to add three
+   async/await syntax introduced in 3.5, and uses it to add two
    new pieces of semantics:
 
    - cancel scopes: a generic system for managing timeouts and
      cancellation
    - nurseries: which let your program do multiple things at the same
      time
-   - MultiErrors: for when multiple things go wrong at once
 
    Of course it also provides a complete suite of APIs for doing
    networking, file I/O, using worker threads,
@@ -57,8 +56,6 @@ Tutorial
    and demonstrate start()
    then point out that you can just use serve_tcp()
 
-   exceptions and MultiError
-
    example: catch-all logging in our echo server
 
    review of the three (or four) core language extensions
@@ -1149,9 +1146,6 @@ TODO: explain :exc:`Cancelled`
 TODO: explain how cancellation is also used when one child raises an
 exception
 
-TODO: show an example :exc:`MultiError` traceback and walk through its
-structure
-
 TODO: maybe a brief discussion of :exc:`KeyboardInterrupt` handling?
 
 ..

newsfragments/2063.bugfix.rst

@@ -1,3 +1,3 @@
-Trio now avoids creating cyclic garbage when a `MultiError` is generated and filtered,
+Trio now avoids creating cyclic garbage when a ``MultiError`` is generated and filtered,
 including invisibly within the cancellation system.  This means errors raised
 through nurseries and cancel scopes should result in less GC latency.

newsfragments/2210.removal.rst

@@ -0,0 +1 @@
+Remove support for Python 3.6.

newsfragments/2211.removal.rst

@@ -0,0 +1,4 @@
+``trio.MultiError`` has been removed in favor of the built-in ``BaseExceptionGroup``
+(and its derivative ``ExceptionGroup``), falling back to the backport_ on Python < 3.11.
+
+.. _backport: https://pypi.org/project/exceptiongroup/

test-requirements.in

@@ -7,6 +7,7 @@ trustme               # for the ssl tests
 pylint                # for pylint finding all symbols tests
 jedi                  # for jedi code completion tests
 cryptography>=36.0.0  # 35.0.0 is transitive but fails
+exceptiongroup        # for catch()
 
 # Tools
 black; implementation_name == "cpython"

test-requirements.txt

@@ -32,6 +32,8 @@ cryptography==36.0.1
     #   trustme
 decorator==5.1.0
     # via ipython
+exceptiongroup==1.0.0rc1
+    # via -r test-requirements.in
 flake8==4.0.1
     # via -r test-requirements.in
 idna==3.3

trio/__init__.py

@@ -22,7 +22,6 @@
     Cancelled,
     BusyResourceError,
     ClosedResourceError,
-    MultiError,
     run,
     open_nursery,
     CancelScope,

trio/_core/__init__.py

@@ -17,8 +17,6 @@
     EndOfChannel,
 )
 
-from ._multierror import MultiError
-
 from ._ki import (
     enable_ki_protection,
     disable_ki_protection,