@@ -162,6 +162,7 @@
   * [SetGlobalClientHandler](cefpython.md#setglobalclienthandler)
   * [SetOsModalLoop](cefpython.md#setosmodalloop)
   * [Shutdown](cefpython.md#shutdown)
+  * [UnraisableHook](cefpython.md#unraisablehook)
 * [Command line switches](CommandLineSwitches.md#command-line-switches)
   * [enable-media-stream](CommandLineSwitches.md#enable-media-stream)
   * [proxy-server](CommandLineSwitches.md#proxy-server)
 
@@ -32,6 +32,7 @@ Table of contents:
   * [SetGlobalClientHandler](#setglobalclienthandler)
   * [SetOsModalLoop](#setosmodalloop)
   * [Shutdown](#shutdown)
+  * [UnraisableHook](#unraisablehook)
 
 
 ## Functions
@@ -93,6 +94,9 @@ This hook does the following: in case of exception write it to
 the "error.log" file, display it to the console, shutdown CEF
 and exit application immediately by ignoring "finally" (_exit()).
 
+See also [UnraisableHook](#unraisablehook) for exceptions that escape a
+callback handler.
+
 See also Tutorial: [Handling Python exceptions](../docs/Tutorial.md#handling-python-exceptions).
 
 
@@ -380,3 +384,31 @@ modal message loop. Set to false after exiting the modal message loop.
 This function should be called on the main application thread (UI thread) to shut down CEF before the application exits.
 
 You must call this function so that CEF shuts down cleanly. Remember also to delete all CEF browsers references for the browsers to shut down cleanly. For an example see the wxpython.py example MainFrame.OnClose().
+
+
+### UnraisableHook
+
+| Parameter | Type |
+| --- | --- |
+| unraisable | - |
+| __Return__ | void |
+
+Global unraisable hook, companion to [ExceptHook](#excepthook). Assign it
+with `sys.unraisablehook = cef.UnraisableHook`.
+
+CEF Python's callback handlers are compiled with Cython and declared as
+"noexcept", so an exception must not propagate out of a handler into CEF's
+C++ code. Handlers catch their own exceptions and forward them to
+`sys.excepthook`, but if an exception still escapes a handler (for example a
+handler not wrapped in try/except, or whose except block itself raises) then
+Python reports it through
+[sys.unraisablehook](https://docs.python.org/3/library/sys.html#sys.unraisablehook)
+rather than crashing the process. By default that only prints to stderr and
+is easy to miss.
+
+This hook forwards the escaped exception to [ExceptHook](#excepthook), so it
+is written to the "error.log" file, printed, and CEF is shut down cleanly -
+same as any other Python exception. Reaching this code path indicates a bug
+in a handler that should be fixed.
+
+See also Tutorial: [Handling Python exceptions](../docs/Tutorial.md#handling-python-exceptions).
@@ -163,6 +163,28 @@ The cef.ExceptHook helper function does the following:
 If you would like to modify `ExceptHook` behavior, see its source code
 in src/[helpers.pyx](../src/helpers.pyx) file.
 
+There is a second, related case. CEF Python's callback handlers are
+compiled with Cython and declared as "noexcept", meaning an exception
+must not propagate out of a handler into CEF's C++ code. Handlers catch
+their own exceptions and forward them to `sys.excepthook`, but if an
+exception still escapes a handler (for example a handler that forgot to
+use try/except, or whose except block itself raises) then Python does
+not crash the process - it reports the exception through
+[sys.unraisablehook](https://docs.python.org/3/library/sys.html#sys.unraisablehook),
+which by default only prints to stderr and is easy to miss. To give
+these escaped exceptions the same treatment as any other error, examples
+also set:
+
+```python
+sys.unraisablehook = cef.UnraisableHook  # For exceptions that escape a handler
+```
+
+cef.[UnraisableHook](../api/cefpython.md#unraisablehook) forwards to
+cef.[ExceptHook](../api/cefpython.md#excepthook), so an escaped exception
+is written to "error.log", printed, and CEF is shut down cleanly instead
+of being silently logged. Reaching this code path indicates a bug in a
+handler that should be fixed.
+
 
 ## Settings
 
 
@@ -60,6 +60,8 @@
 def main():
     check_versions()
     sys.excepthook = cef.ExceptHook  # To shutdown all CEF processes on error
+    sys.unraisablehook = cef.UnraisableHook  # Same, for exceptions that
+    #                                          escape a callback handler
     # To change user agent use either "product_version"
     # or "user_agent" options. Explained in Tutorial in
     # "Change user agent string" section.
 
@@ -47,6 +47,21 @@ def ExceptHook(exc_type, exc_value, exc_trace):
     os._exit(1)
 
 
+def UnraisableHook(unraisable):
+    """Global unraisable hook, companion to ExceptHook.
+
+    Cython callback handlers are declared "noexcept": an exception that
+    escapes a handler (one not wrapped in try/except, or whose except block
+    itself raises) does not propagate into CEF's C++ code. Python instead
+    reports it via sys.unraisablehook, which by default only prints to stderr
+    and is easy to miss. Assigning this hook routes such exceptions through
+    ExceptHook so they are written to "error.log", printed, and CEF is shut
+    down cleanly - same as any other Python exception.
+    """
+    ExceptHook(unraisable.exc_type, unraisable.exc_value,
+               unraisable.exc_traceback)
+
+
 cpdef str GetModuleDirectory():
     """Get path to the cefpython module (so/pyd)."""
     if platform.system() == "Linux" and os.getenv("CEFPYTHON3_PATH"):