bpo-17799: Explain real behaviour of sys.settrace and sys.setprofile (GH-4056). (#5299)
(cherry picked from commit 131fd7f96c619bc7eaea956e45c6337175f4b27f)
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 7643a37..eade412 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1057,15 +1057,19 @@
function as its first parameter, and may be any Python object, or *NULL*. If
the profile function needs to maintain state, using a different value for *obj*
for each thread provides a convenient and thread-safe place to store it. The
- profile function is called for all monitored events except the line-number
- events.
+ profile function is called for all monitored events except :const:`PyTrace_LINE`
+ and :const:`PyTrace_EXCEPTION`.
.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
Set the tracing function to *func*. This is similar to
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
- events.
+ events and does not receive any event related to C function objects being called. Any
+ trace function registered using :c:func:`PyEval_SetTrace` will not receive
+ :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or :const:`PyTrace_C_RETURN`
+ as a value for the *what* parameter.
+
.. c:function:: PyObject* PyEval_GetCallStats(PyObject *self)