[Python-checkins] r67295 - in python/trunk/Doc/library: pdb.rst sys.rst

[benjamin.peterson]

Author: benjamin.peterson
Date: Thu Nov 20 05:05:12 2008
New Revision: 67295

Log:
move useful sys.settrace information to the function's documentation from the debugger

Modified:
   python/trunk/Doc/library/pdb.rst
   python/trunk/Doc/library/sys.rst

Modified: python/trunk/Doc/library/pdb.rst
==============================================================================
--- python/trunk/Doc/library/pdb.rst	(original)
+++ python/trunk/Doc/library/pdb.rst	Thu Nov 20 05:05:12 2008
@@ -351,68 +351,3 @@
 
 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`.
-

Modified: python/trunk/Doc/library/sys.rst
==============================================================================
--- python/trunk/Doc/library/sys.rst	(original)
+++ python/trunk/Doc/library/sys.rst	Thu Nov 20 05:05:12 2008
@@ -717,6 +717,56 @@
    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,