bpo-17799: Explain real behaviour of sys.settrace and sys.setprofile (GH-4056) (#5298)

(cherry picked from commit 131fd7f96c619bc7eaea956e45c6337175f4b27f)

1 files changed, 7 insertions, 3 deletions

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 2965bc9..a2c55fe 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1137,15 +1137,19 @@ Python-level trace functions in previous versions.
    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)