added mention of asyncio.gather()

python · iritkatriel · Feb 5, 2021 · Feb 2, 2021 · Feb 3, 2021 · Feb 5, 2021
commit eca3b4a85e4be701f984b0577478fe99fb3df9f2
diff --git a/except_star.md b/except_star.md
@@ -20,37 +20,46 @@ related to each other as the cause or context, but there are situations where
 multiple unrelated exceptions need to be propagated together as the stack
 unwinds. Several real world use cases are listed below.

-* Concurrent errors. The Trio library for async concurrency has a `MultiError`
-  exception type used to report a collection of errors raised in parallel
-  in different child tasks. Work on this PEP was initially motivated by the
+* **Concurrent errors**. Libraries for async concurrency provide APIs to invoke
+  multiple tasks and return their results in aggregate. There isn't currently
+  a good way for such libraries to handle situations where multiple tasks
+  raise exceptions. The Python standard library's
+  [`asyncio.gather()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.gather)
+  function provides two options: raise the first exception, or return the
+  exceptions in the results list.  The [Trio](https://trio.readthedocs.io/en/stable/)
+  library has a `MultiError` exception type which it raises to report a
+  collection of errors. Work on this PEP was initially motivated by the
  difficulties in handling `MultiError`s, which are detailed in a design
-  document for an [improved version, `MultiError2`]([https://github.com/python-trio/trio/issues/611).
-  This document demonstrates how difficult it is to create an effective API
+  document for an
+  [improved version, `MultiError2`]([https://github.com/python-trio/trio/issues/611).
+  That document demonstrates how difficult it is to create an effective API
  for reporting and handling multiple errors without the language changes we
  are proposing.

-* Multiple failures when retrying an operation: The Python standard library's
+* **Multiple failures when retrying an operation.** The Python standard library's
  `socket.create_connection` may attempt to connect to different addresses,
  and if all attempts fail it needs to report that to the user. It is an open
  issue how to aggregate these errors, particularly when they are different
  [[Python issue 29980](https://bugs.python.org/issue29980)].

-* Multiple user callbacks fail: The pytest library allows users to register
+* **Multiple user callbacks fail.** The pytest library allows users to register
  finalizers which are executed at teardown. If more than one of these
  finalizers raises an exception, only the first is reported to the user. This
  can be improved with `ExceptionGroup`s, as explained in this issue by pytest
  developer Ran Benita [[Pytest issue 8217](https://github.com/pytest-dev/pytest/issues/8217)]

-* The Hypothesis library performs automatic bug reduction (simplifying
-  code that demonstrates a bug). In the process it may find variations
-  that generate different errors, and (optionally) reports all of them
+* **Multiple errors in a complex calculation.** The Hypothesis library performs
+  automatic bug reduction (simplifying code that demonstrates a bug). In the
+  process it may find variations that generate different errors, and
+  (optionally) reports all of them
  [[Hypothesis documentation](https://hypothesis.readthedocs.io/en/latest/settings.html#hypothesis.settings.report_multiple_bugs)].
  An `ExceptionGroup` mechanism as we are proposing here can resolve some of
  the difficulties with debugging that are mentioned in the link above, and
  which are due to the loss of context/cause information (communicated
  by Hypothesis Core Developer Zac Hatfield-Dodds).

-* The Python standard library's `tempfile.TemporaryDirectory` context manager
+* **Errors in wrapper code.** The Python standard library's
+  `tempfile.TemporaryDirectory` context manager
  had an issue where an exception raised during cleanup in `__exit__`
  effectively masked an exception that the user's code raised inside the context
  manager scope. While the user's exception was chained as the context of the