[Python-checkins] bpo-37937: Mention frame.f_trace in sys.settrace docs (GH-15439)
Miss Islington (bot)
webhook-mailer at python.org
Fri Sep 20 11:26:31 EDT 2019
https://github.com/python/cpython/commit/c410390e89071c4a4c2a437a227c14274add4116
commit: c410390e89071c4a4c2a437a227c14274add4116
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-09-20T08:26:27-07:00
summary:
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.
(cherry picked from commit 9c2682efc69568e1b42a0c1759489d6f2e3b30ea)
Co-authored-by: Ram Rachum <ram at rachum.com>
files:
A Misc/NEWS.d/next/Documentation/2019-08-24-12-59-06.bpo-37937.F7fHbt.rst
M Doc/library/sys.rst
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 975c14c88824..a698ecb64d85 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1324,6 +1324,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 000000000000..26cc16a74d1c
--- /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.
More information about the Python-checkins
mailing list