pythongh-124872: Clarify expected PyContext_WatchCallback return behavior

rhansen · rhansen · commit 4c115ab49233 · 2024-10-14T00:40:05.000-04:00
diff --git a/Doc/c-api/contextvars.rst b/Doc/c-api/contextvars.rst
@@ -144,9 +144,10 @@ Context object management functions:
    Any pending exception is cleared before the callback is called and restored
    after the callback returns.
 
-   If the callback returns with an exception set, it must return ``-1``; this
-   exception will be printed as an unraisable exception using
-   :c:func:`PyErr_FormatUnraisable`. Otherwise it should return ``0``.
+   If the callback raises an exception it must return ``-1``; the exception
+   will be printed as an unraisable exception using
+   :c:func:`PyErr_FormatUnraisable` and discarded.  Otherwise it must return
+   ``0``.
 
    .. versionadded:: 3.14
 
diff --git a/Include/cpython/context.h b/Include/cpython/context.h
@@ -52,8 +52,9 @@ typedef enum {
  * Any pending exception is cleared before the callback is called and restored
  * after the callback returns.
  *
- * if the callback returns with an exception set, it must return -1. Otherwise
- * it should return 0
+ * If the callback raises an exception it must return -1; the exception will be
+ * printed as an unraisable exception using PyErr_FormatUnraisable and
+ * discarded.  Otherwise it must return 0.
  */
 typedef int (*PyContext_WatchCallback)(PyContextEvent, PyObject *);
 
