Add allowed_exceptions parameter to Sphinx.emit() (refs: #7683)

It allows handlers to raise specified exceptions.

1 files changed, 10 insertions, 4 deletions

diff --git a/sphinx/events.py b/sphinx/events.py
index 0f0f47b65..0911dfaaa 100644
--- a/sphinx/events.py
+++ b/sphinx/events.py
@@ -13,7 +13,7 @@
 import warnings
 from collections import defaultdict
 from operator import attrgetter
-from typing import Any, Callable, Dict, List, NamedTuple
+from typing import Any, Callable, Dict, List, NamedTuple, Tuple
 
 from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.errors import ExtensionError, SphinxError
@@ -22,6 +22,7 @@ from sphinx.util import logging
 
 if False:
     # For type annotation
+    from typing import Type  # for python3.5.1
     from sphinx.application import Sphinx
 
 
@@ -88,7 +89,8 @@ class EventManager:
                 if listener.id == listener_id:
                     listeners.remove(listener)
 
-    def emit(self, name: str, *args: Any) -> List:
+    def emit(self, name: str, *args: Any,
+             allowed_exceptions: Tuple["Type[Exception]", ...] = ()) -> List:
         """Emit a Sphinx event."""
         try:
             logger.debug('[app] emitting event: %r%s', name, repr(args)[:100])
@@ -106,6 +108,9 @@ class EventManager:
                     results.append(listener.handler(*args))
                 else:
                     results.append(listener.handler(self.app, *args))
+            except allowed_exceptions:
+                # pass through the errors specified as *allowed_exceptions*
+                raise
             except SphinxError:
                 raise
             except Exception as exc:
@@ -113,12 +118,13 @@ class EventManager:
                                      (listener.handler, name)) from exc
         return results
 
-    def emit_firstresult(self, name: str, *args: Any) -> Any:
+    def emit_firstresult(self, name: str, *args: Any,
+                         allowed_exceptions: Tuple["Type[Exception]", ...] = ()) -> Any:
         """Emit a Sphinx event and returns first result.
 
         This returns the result of the first handler that doesn't return ``None``.
         """
-        for result in self.emit(name, *args):
+        for result in self.emit(name, *args, allowed_exceptions=allowed_exceptions):
             if result is not None:
                 return result
         return None