Reword docs for exception_handler in CallbackRegistry.

anntzer · anntzer · commit fc70bfa6e046 · 2020-12-01T09:40:33.000+01:00
- Describe the signature of `exception_handler` in prose (the parameter
  name is not actually relevant, nor is the return value).
- "Consuming" an exception is not a standard idiom.
- Picklability is a detail here only relevant if you want to pickle the
  CallbackRegistry, and anyways it is generally true that setting an
  unpicklable attribute on an otherwise picklable object will make that
  object unpicklable.
- The description of the default exception handler was incorrect.
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -138,20 +138,14 @@ class CallbackRegistry:
     Parameters
     ----------
     exception_handler : callable, optional
-       If provided must have signature ::
-
-          def handler(exc: Exception) -> None:
-
-       If not None this function will be called with any `Exception`
-       subclass raised by the callbacks in `CallbackRegistry.process`.
-       The handler may either consume the exception or re-raise.
-
-       The callable must be pickle-able.
-
-       The default handler is ::
-
-          def h(exc):
-              traceback.print_exc()
+       If not None, *exception_handler* must be a function that takes an
+       `Exception` as single parameter.  It gets called with any `Exception`
+       raised by the callbacks during `CallbackRegistry.process`, and may
+       either re-raise the exception or handle it in another manner.
+
+       The default handler prints the exception (with `traceback.print_exc`) if
+       an interactive event loop is running; it re-raises the exception if no
+       interactive event loop is running.
     """
 
     # We maintain two mappings:
