From 0a9517a75c6a5f237ae6733455615b71a7bc7efc Mon Sep 17 00:00:00 2001 From: Ram Rachum Date: Fri, 23 Aug 2019 22:34:55 +0300 Subject: [PATCH 1/4] bpo-37937: Mention frame.f_trace in sys.settrace docs --- Doc/library/sys.rst | 9 ++++++++- .../2019-08-24-12-59-06.bpo-37937.F7fHbt.rst | 1 + 2 files changed, 9 insertions(+), 1 deletion(-) 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 6119bee10ab3971..16dff13c0511b5a 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1300,7 +1300,14 @@ always available. Note that as an exception is propagated down the chain of callers, an ``'exception'`` event is generated at each level. - For more information on code and frame objects, refer to :ref:`types`. + 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. If you do this, you + must also call :func:`settrace` with the same tracing function for it to + work. 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 000000000000000..26cc16a74d1c7df --- /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. From a9c1d09950a0046315f255b32dddb4e251785eb4 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 20 Sep 2019 23:22:47 +1000 Subject: [PATCH 2/4] Clarify one more detail --- Doc/library/sys.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 16dff13c0511b5a..f7f2ffe3fb18e10 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1306,8 +1306,9 @@ always available. trace function. This is also required for activating the trace function on the current frame, which :func:`settrace` doesn't do. If you do this, you must also call :func:`settrace` with the same tracing function for it to - work. For more information on code and frame objects, refer to - :ref:`types`. + affect called functions. + + For more information on code and frame objects, refer to :ref:`types`. .. audit-event:: sys.settrace "" sys.settrace From 41b82a99abe5a4e505f67fc4c6c30b0674cddb16 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 20 Sep 2019 23:32:24 +1000 Subject: [PATCH 3/4] Further updates after double-checking in the REPL --- Doc/library/sys.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index f7f2ffe3fb18e10..c81a9f19cf1d607 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1304,9 +1304,12 @@ always available. 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. If you do this, you - must also call :func:`settrace` with the same tracing function for it to - affect called functions. + 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`. From 7443917ea84ab4a39a393e940ee3e96b458a656e Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sat, 21 Sep 2019 00:56:34 +1000 Subject: [PATCH 4/4] Fix whitespace --- Doc/library/sys.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index c81a9f19cf1d607..ba4b0a468e7390b 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1310,7 +1310,7 @@ always available. 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