From 9c2682efc69568e1b42a0c1759489d6f2e3b30ea Mon Sep 17 00:00:00 2001
From: Ram Rachum <ram@rachum.com>
Date: Fri, 20 Sep 2019 18:19:02 +0300
Subject: [PATCH] bpo-37937: Mention frame.f_trace in sys.settrace docs
 (GH-15439)

Mention frame.f_trace in sys.settrace docs, as well as the fact you still
need to call `sys.settrace` to enable the tracing machinery before setting
`frame.f_trace` will have any effect.
---
 Doc/library/sys.rst                                   | 11 +++++++++++
 .../2019-08-24-12-59-06.bpo-37937.F7fHbt.rst          |  1 +
 2 files changed, 12 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2019-08-24-12-59-06.bpo-37937.F7fHbt.rst

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index ca43dc994cb..c6c643b38de 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1301,6 +1301,17 @@ always available.
    Note that as an exception is propagated down the chain of callers, an
    ``'exception'`` event is generated at each level.
 
+   For more fine-grained usage, it's possible to set a trace function by
+   assigning ``frame.f_trace = tracefunc`` explicitly, rather than relying on
+   it being set indirectly via the return value from an already installed
+   trace function. This is also required for activating the trace function on
+   the current frame, which :func:`settrace` doesn't do. Note that in order
+   for this to work, a global tracing function must have been installed
+   with :func:`settrace` in order to enable the runtime tracing machinery,
+   but it doesn't need to be the same tracing function (e.g. it could be a
+   low overhead tracing function that simply returns ``None`` to disable
+   itself immediately on each frame).
+
    For more information on code and frame objects, refer to :ref:`types`.
 
    .. audit-event:: sys.settrace "" sys.settrace
diff --git a/Misc/NEWS.d/next/Documentation/2019-08-24-12-59-06.bpo-37937.F7fHbt.rst b/Misc/NEWS.d/next/Documentation/2019-08-24-12-59-06.bpo-37937.F7fHbt.rst
new file mode 100644
index 00000000000..26cc16a74d1
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-08-24-12-59-06.bpo-37937.F7fHbt.rst
@@ -0,0 +1 @@
+Mention ``frame.f_trace`` in :func:`sys.settrace` docs.