From 5ab9c3badba457900b590b693604e1817430a3ed Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Thu, 20 Nov 2008 04:05:12 +0000 Subject: [PATCH] move useful sys.settrace information to the function's documentation from the debugger --- Doc/library/pdb.rst | 65 --------------------------------------------- Doc/library/sys.rst | 50 ++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 65 deletions(-) diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index c1a0bcd1c14..384c7d9f38b 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -351,68 +351,3 @@ run [*args* ...] q(uit) Quit from the debugger. The program being executed is aborted. - - -.. _debugger-hooks: - -How It Works -============ - -Some changes were made to the interpreter: - -* ``sys.settrace(func)`` sets the global trace function - -* there can also a local trace function (see later) - -Trace functions have three arguments: *frame*, *event*, and *arg*. *frame* is -the current stack frame. *event* is a string: ``'call'``, ``'line'``, -``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or -``'c_exception'``. *arg* depends on the event type. - -The global trace function is invoked (with *event* set to ``'call'``) whenever a -new local scope is entered; it should return a reference to the local trace -function to be used that scope, or ``None`` if the scope shouldn't be traced. - -The local trace function should return a reference to itself (or to another -function for further tracing in that scope), or ``None`` to turn off tracing in -that scope. - -Instance methods are accepted (and very useful!) as trace functions. - -The events have the following meaning: - -``'call'`` - A function is called (or some other code block entered). The global trace - function is called; *arg* is ``None``; the return value specifies the local - trace function. - -``'line'`` - The interpreter is about to execute a new line of code (sometimes multiple line - events on one line exist). The local trace function is called; *arg* is - ``None``; the return value specifies the new local trace function. - -``'return'`` - A function (or other code block) is about to return. The local trace function - is called; *arg* is the value that will be returned. The trace function's - return value is ignored. - -``'exception'`` - An exception has occurred. The local trace function is called; *arg* is a - triple ``(exception, value, traceback)``; the return value specifies the new - local trace function. - -``'c_call'`` - A C function is about to be called. This may be an extension function or a - builtin. *arg* is the C function object. - -``'c_return'`` - A C function has returned. *arg* is ``None``. - -``'c_exception'`` - A C function has thrown an exception. *arg* is ``None``. - -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`. - diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 111755068c1..618f4e6a9ee 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -717,6 +717,56 @@ always available. debugger to support multiple threads, it must be registered using :func:`settrace` for each thread being debugged. + Trace functions should have three arguments: *frame*, *event*, and + *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, + ``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or + ``'c_exception'``. *arg* depends on the event type. + + The trace function is invoked (with *event* set to ``'call'``) whenever a new + local scope is entered; it should return a reference to a local trace + function to be used that scope, or ``None`` if the scope shouldn't be traced. + + The local trace function should return a reference to itself (or to another + function for further tracing in that scope), or ``None`` to turn off tracing + in that scope. + + The events have the following meaning: + + ``'call'`` + A function is called (or some other code block entered). The + global trace function is called; *arg* is ``None``; the return value + specifies the local trace function. + + ``'line'`` + The interpreter is about to execute a new line of code (sometimes multiple + line events on one line exist). The local trace function is called; *arg* + is ``None``; the return value specifies the new local trace function. + + ``'return'`` + A function (or other code block) is about to return. The local trace + function is called; *arg* is the value that will be returned. The trace + function's return value is ignored. + + ``'exception'`` + An exception has occurred. The local trace function is called; *arg* is a + tuple ``(exception, value, traceback)``; the return value specifies the + new local trace function. + + ``'c_call'`` + A C function is about to be called. This may be an extension function or + a builtin. *arg* is the C function object. + + ``'c_return'`` + A C function has returned. *arg* is ``None``. + + ``'c_exception'`` + A C function has thrown an exception. *arg* is ``None``. + + 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`. + .. note:: The :func:`settrace` function is intended only for implementing debuggers,