Merged revisions 67245,67277,67289,67295,67301-67303,67307,67330,67332,67336,67355,67359,67362,67364,67367-67368,67370 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67245 | benjamin.peterson | 2008-11-17 23:05:19 +0100 (Mon, 17 Nov 2008) | 1 line
improve __hash__ docs
........
r67277 | skip.montanaro | 2008-11-19 04:35:41 +0100 (Wed, 19 Nov 2008) | 1 line
patch from issue 1108
........
r67289 | brett.cannon | 2008-11-19 21:29:39 +0100 (Wed, 19 Nov 2008) | 2 lines
Ignore .pyc and .pyo files.
........
r67295 | benjamin.peterson | 2008-11-20 05:05:12 +0100 (Thu, 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 (Thu, 20 Nov 2008) | 1 line
fix indentation and a sphinx warning
........
r67302 | benjamin.peterson | 2008-11-20 22:44:23 +0100 (Thu, 20 Nov 2008) | 1 line
oops! didn't mean to disable that test
........
r67303 | benjamin.peterson | 2008-11-20 23:06:22 +0100 (Thu, 20 Nov 2008) | 1 line
backport r67300
........
r67307 | amaury.forgeotdarc | 2008-11-21 00:34:31 +0100 (Fri, 21 Nov 2008) | 9 lines
Fixed issue #4233.
Changed semantic of _fileio.FileIO's close() method on file objects with closefd=False.
The file descriptor is still kept open but the file object behaves like a closed file.
The FileIO object also got a new readonly attribute closefd.
Approved by Barry
Backport of r67106 from the py3k branch
........
r67330 | georg.brandl | 2008-11-22 09:34:14 +0100 (Sat, 22 Nov 2008) | 2 lines
#4364: fix attribute name on ctypes object.
........
r67332 | georg.brandl | 2008-11-22 09:45:33 +0100 (Sat, 22 Nov 2008) | 2 lines
Fix typo.
........
r67336 | georg.brandl | 2008-11-22 11:08:50 +0100 (Sat, 22 Nov 2008) | 2 lines
Fix error about "-*-" being mandatory in coding cookies.
........
r67355 | georg.brandl | 2008-11-23 20:17:25 +0100 (Sun, 23 Nov 2008) | 2 lines
#4392: fix parameter name.
........
r67359 | georg.brandl | 2008-11-23 22:57:30 +0100 (Sun, 23 Nov 2008) | 2 lines
#4399: fix typo.
........
r67362 | gregory.p.smith | 2008-11-24 01:41:43 +0100 (Mon, 24 Nov 2008) | 2 lines
Document PY_SSIZE_T_CLEAN for PyArg_ParseTuple.
........
r67364 | benjamin.peterson | 2008-11-24 02:16:29 +0100 (Mon, 24 Nov 2008) | 2 lines
replace reference to debugger-hooks
........
r67367 | georg.brandl | 2008-11-24 17:16:07 +0100 (Mon, 24 Nov 2008) | 2 lines
Fix typo.
........
r67368 | georg.brandl | 2008-11-24 20:56:47 +0100 (Mon, 24 Nov 2008) | 2 lines
#4404: make clear what "path" is.
........
r67370 | jeremy.hylton | 2008-11-24 23:00:29 +0100 (Mon, 24 Nov 2008) | 8 lines
Add unittests that verify documented behavior of public methods in Transport
class.
These methods can be overridden. The tests verify that the overridden
methods are called, and that changes to the connection have a visible
effect on the request.
........
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 1117550..fa7b7f0 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -712,11 +712,60 @@
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,