Merged revisions 67295,67301-67302,67318,67330,67342-67343 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r67295 | benjamin.peterson | 2008-11-20 05:05:12 +0100 (jeu., 20 nov. 2008) | 1 line

  move useful sys.settrace information to the function's documentation from the debugger
........
  r67301 | benjamin.peterson | 2008-11-20 22:25:31 +0100 (jeu., 20 nov. 2008) | 1 line

  fix indentation and a sphinx warning
........
  r67302 | benjamin.peterson | 2008-11-20 22:44:23 +0100 (jeu., 20 nov. 2008) | 1 line

  oops! didn't mean to disable that test
........
  r67318 | amaury.forgeotdarc | 2008-11-21 23:05:48 +0100 (ven., 21 nov. 2008) | 4 lines

  #4363: Let uuid.uuid1() and uuid.uuid4() run even if the ctypes module is not present.

  Will backport to 2.6
........
  r67330 | georg.brandl | 2008-11-22 09:34:14 +0100 (sam., 22 nov. 2008) | 2 lines

  #4364: fix attribute name on ctypes object.
........
  r67342 | amaury.forgeotdarc | 2008-11-22 20:39:38 +0100 (sam., 22 nov. 2008) | 3 lines

  yuvconvert.c is a part of the "sv" module, an old IRIX thing
  and certainly not useful for any Windows build.
........
  r67343 | amaury.forgeotdarc | 2008-11-22 21:01:18 +0100 (sam., 22 nov. 2008) | 5 lines

  #3996: On Windows, PyOS_CheckStack is supposed to protect the interpreter from
  stack overflow. But doing this, it always crashes when the stack is nearly full.

  Reviewed by Martin von Loewis. Will backport to 2.6.
........

1 files changed, 51 insertions, 2 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 568b06d..e4dbf17 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -623,11 +623,60 @@ always available.
       single: debugger
 
    Set the system's trace function, which allows you to implement a Python
-   source code debugger in Python.  See section :ref:`debugger-hooks` in the
-   chapter on the Python debugger.  The function is thread-specific; for a
+   source code debugger in Python.  The function is thread-specific; for a
    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,