diff options
| author | Quentin Peter <impact27@users.noreply.github.com> | 2023-10-31 16:24:54 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-10-31 16:24:54 (GMT) |
| commit | 244567398370bfa62a332676762bb1db395c02fc (patch) | |
| tree | 3aa8ae750a8f5c702a624163cb9f97acda3e1c67 /Doc/library/sys.rst | |
| parent | 5cc6c80a7797c08c884edf94de4fc7b6075e32ce (diff) | |
| download | cpython-244567398370bfa62a332676762bb1db395c02fc.zip cpython-244567398370bfa62a332676762bb1db395c02fc.tar.gz cpython-244567398370bfa62a332676762bb1db395c02fc.tar.bz2 | |
gh-102249: Expand sys.call_tracing documentation (#102806)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Diffstat (limited to 'Doc/library/sys.rst')
| -rw-r--r-- | Doc/library/sys.rst | 20 |
1 files changed, 17 insertions, 3 deletions
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 5ef6f83..4d24606 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -175,7 +175,11 @@ always available. Call ``func(*args)``, while tracing is enabled. The tracing state is saved, and restored afterwards. This is intended to be called from a debugger from - a checkpoint, to recursively debug some other code. + a checkpoint, to recursively debug or profile some other code. + + Tracing is suspended while calling a tracing function set by + :func:`settrace` or :func:`setprofile` to avoid infinite recursion. + :func:`!call_tracing` enables explicit recursion of the tracing function. .. data:: copyright @@ -1473,13 +1477,16 @@ always available. its return value is not used, so it can simply return ``None``. Error in the profile function will cause itself unset. + .. note:: + The same tracing mechanism is used for :func:`!setprofile` as :func:`settrace`. + To trace calls with :func:`!setprofile` inside a tracing function + (e.g. in a debugger breakpoint), see :func:`call_tracing`. + Profile functions should have three arguments: *frame*, *event*, and *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends on the event type. - .. audit-event:: sys.setprofile "" sys.setprofile - The events have the following meaning: ``'call'`` @@ -1501,6 +1508,9 @@ always available. ``'c_exception'`` A C function has raised an exception. *arg* is the C function object. + .. audit-event:: sys.setprofile "" sys.setprofile + + .. function:: setrecursionlimit(limit) Set the maximum depth of the Python interpreter stack to *limit*. This limit @@ -1560,6 +1570,10 @@ always available. If there is any error occurred in the trace function, it will be unset, just like ``settrace(None)`` is called. + .. note:: + Tracing is disabled while calling the trace function (e.g. a function set by + :func:`!settrace`). For recursive tracing see :func:`call_tracing`. + The events have the following meaning: ``'call'`` |