Skip to content

Commit 9c2682e

Browse files
cool-RRncoghlan
authored andcommitted
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.
1 parent 062cfe3 commit 9c2682e

File tree

2 files changed

+12
-0
lines changed

2 files changed

+12
-0
lines changed

Doc/library/sys.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1301,6 +1301,17 @@ always available.
13011301
Note that as an exception is propagated down the chain of callers, an
13021302
``'exception'`` event is generated at each level.
13031303

1304+
For more fine-grained usage, it's possible to set a trace function by
1305+
assigning ``frame.f_trace = tracefunc`` explicitly, rather than relying on
1306+
it being set indirectly via the return value from an already installed
1307+
trace function. This is also required for activating the trace function on
1308+
the current frame, which :func:`settrace` doesn't do. Note that in order
1309+
for this to work, a global tracing function must have been installed
1310+
with :func:`settrace` in order to enable the runtime tracing machinery,
1311+
but it doesn't need to be the same tracing function (e.g. it could be a
1312+
low overhead tracing function that simply returns ``None`` to disable
1313+
itself immediately on each frame).
1314+
13041315
For more information on code and frame objects, refer to :ref:`types`.
13051316

13061317
.. audit-event:: sys.settrace "" sys.settrace
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Mention ``frame.f_trace`` in :func:`sys.settrace` docs.

0 commit comments

Comments
 (0)