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.
........

10 files changed, 90 insertions, 103 deletions

diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst
index 21ae111..561ce29 100644
--- a/Doc/howto/unicode.rst
+++ b/Doc/howto/unicode.rst
@@ -410,9 +410,9 @@ either the first or second line of the source file::
     
 The syntax is inspired by Emacs's notation for specifying variables local to a
 file.  Emacs supports many different variables, but Python only supports
-'coding'.  The ``-*-`` symbols indicate that the comment is special; within
-them, you must supply the name ``coding`` and the name of your chosen encoding,
-separated by ``':'``.
+'coding'.  The ``-*-`` symbols indicate to Emacs that the comment is special;
+they have no significance to Python but are a convention.  Python looks for
+``coding: name`` or ``coding=name`` in the comment.
 
 If you don't include such a comment, the default encoding used will be ASCII.
 Versions of Python before 2.4 were Euro-centric and assumed Latin-1 as a default
diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst
index 82a1c21..3041b7b 100644
--- a/Doc/library/bdb.rst
+++ b/Doc/library/bdb.rst
@@ -107,8 +107,9 @@ The :mod:`bdb` module also defines two classes:
 
       The *arg* parameter depends on the previous event.
 
-      For more information on trace functions, see :ref:`debugger-hooks`.  For
-      more information on code and frame objects, refer to :ref:`types`.
+      See the documentation for :func:`sys.settrace` for more information on the
+      trace function.  For more information on code and frame objects, refer to
+      :ref:`types`.
 
    .. method:: dispatch_line(frame)
 
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 258b54f..40ec9e8 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -60,7 +60,7 @@ ABC                        Inherits               Abstract Methods        Mixin
                            :class:`Iterable`,     and ``__len__``         ``index``, and ``count``
                            :class:`Container`     
                                                   
-:class:`MutableSequnce`    :class:`Sequence`      ``__getitem__``         Inherited Sequence methods and
+:class:`MutableSequence`   :class:`Sequence`      ``__getitem__``         Inherited Sequence methods and
                                                   ``__delitem__``,        ``append``, ``reverse``, ``extend``, ``pop``,
                                                   ``insert``,             ``remove``, and ``__iadd__``
                                                   and ``__len__``
@@ -487,16 +487,16 @@ Named tuples assign meaning to each position in a tuple and allow for more reada
 self-documenting code.  They can be used wherever regular tuples are used, and
 they add the ability to access fields by name instead of position index.
 
-.. function:: namedtuple(typename, fieldnames, [verbose])
+.. function:: namedtuple(typename, field_names, [verbose])
 
    Returns a new tuple subclass named *typename*.  The new subclass is used to
    create tuple-like objects that have fields accessible by attribute lookup as
    well as being indexable and iterable.  Instances of the subclass also have a
-   helpful docstring (with typename and fieldnames) and a helpful :meth:`__repr__`
+   helpful docstring (with typename and field_names) and a helpful :meth:`__repr__`
    method which lists the tuple contents in a ``name=value`` format.
 
-   The *fieldnames* are a single string with each fieldname separated by whitespace
-   and/or commas, for example ``'x y'`` or ``'x, y'``.  Alternatively, *fieldnames*
+   The *field_names* are a single string with each fieldname separated by whitespace
+   and/or commas, for example ``'x y'`` or ``'x, y'``.  Alternatively, *field_names*
    can be a sequence of strings such as ``['x', 'y']``.
 
    Any valid Python identifier may be used for a fieldname except for names
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 8e920f8..0e37332 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1370,7 +1370,7 @@ function exported by these libraries, and reacquired afterwards.
 
 All these classes can be instantiated by calling them with at least one
 argument, the pathname of the shared library.  If you have an existing handle to
-an already loaded shard library, it can be passed as the ``handle`` named
+an already loaded shared library, it can be passed as the ``handle`` named
 parameter, otherwise the underlying platforms ``dlopen`` or :meth:`LoadLibrary`
 function is used to load the library into the process, and to get a handle to
 it.
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 18df0e0..25d5f16 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -214,8 +214,10 @@ I/O Base Classes
 
    .. method:: close()
 
-      Flush and close this stream.  This method has no effect if the file is
-      already closed.
+      Flush and close this stream. This method has no effect if the file is
+      already closed. Once the file is closed, any operation on the file 
+      (e.g. reading or writing) will raise an :exc:`IOError`. The internal
+      file descriptor isn't closed if *closefd* was False.
 
    .. attribute:: closed
 
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 7a13183..e1992cc 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -919,7 +919,7 @@ inherited by child processes.
 
    Note that *lock* is a keyword only argument.
 
-   Note that an array of :data:`ctypes.c_char` has *value* and *rawvalue*
+   Note that an array of :data:`ctypes.c_char` has *value* and *raw*
    attributes which allow one to use it to store and retrieve strings.
 
 
@@ -968,7 +968,7 @@ processes.
    :func:`Value` instead to make sure that access is automatically synchronized
    using a lock.
 
-   Note that an array of :data:`ctypes.c_char` has ``value`` and ``rawvalue``
+   Note that an array of :data:`ctypes.c_char` has ``value`` and ``raw``
    attributes which allow one to use it to store and retrieve strings -- see
    documentation for :mod:`ctypes`.
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 14784fa..1cb450b 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -933,10 +933,10 @@ Files and Directories
 
 .. function:: listdir(path)
 
-   Return a list containing the names of the entries in the directory. The list is
-   in arbitrary order.  It does not include the special entries ``'.'`` and
-   ``'..'`` even if they are present in the directory. Availability:
-   Unix, Windows.
+   Return a list containing the names of the entries in the directory given by
+   *path*.  The list is in arbitrary order.  It does not include the special
+   entries ``'.'`` and ``'..'`` even if they are present in the
+   directory.  Availability: Unix, Windows.
 
    .. versionchanged:: 2.3
       On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index c1a0bcd..384c7d9 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 1117550..fa7b7f0 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -712,11 +712,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,
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index b1ab8fd..7304c9c 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1365,21 +1365,21 @@ Basic customization
       object: dictionary
       builtin: hash
 
-   Called for the key object for dictionary operations, and by the built-in
-   function :func:`hash`.  Should return an integer usable as a hash value
-   for dictionary operations.  The only required property is that objects which
-   compare equal have the same hash value; it is advised to somehow mix together
-   (e.g., using exclusive or) the hash values for the components of the object that
-   also play a part in comparison of objects.
+   Called by built-in function :func:`hash` and for operations on members of
+   hashed collections including :class:`set`, :class:`frozenset`, and
+   :class:`dict`.  :meth:`__hash__` should return an integer.  The only required
+   property is that objects which compare equal have the same hash value; it is
+   advised to somehow mix together (e.g. using exclusive or) the hash values for
+   the components of the object that also play a part in comparison of objects.
 
    If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it
    should not define a :meth:`__hash__` operation either; if it defines
    :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances
-   will not be usable as dictionary keys.  If a class defines mutable objects
+   will not be usable in hashed collections.  If a class defines mutable objects
    and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
-   implement :meth:`__hash__`, since the dictionary implementation requires that
-   a key's hash value is immutable (if the object's hash value changes, it will
-   be in the wrong hash bucket).
+   implement :meth:`__hash__`, since hashable collection implementations require
+   that a object's hash value is immutable (if the object's hash value changes,
+   it will be in the wrong hash bucket).
 
    User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods
    by default; with them, all objects compare unequal (except with themselves)
@@ -1389,13 +1389,13 @@ Basic customization
    change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash
    value returned is no longer appropriate (e.g. by switching to a value-based
    concept of equality instead of the default identity based equality) can
-   explicitly flag themselves as being unhashable by setting
-   ``__hash__ = None`` in the class definition. Doing so means that not only
-   will instances of the class raise an appropriate :exc:`TypeError` when
-   a program attempts to retrieve their hash value, but they will also be
-   correctly identified as unhashable when checking
-   ``isinstance(obj, collections.Hashable)`` (unlike classes which define
-   their own :meth:`__hash__` to explicitly raise :exc:`TypeError`).
+   explicitly flag themselves as being unhashable by setting ``__hash__ = None``
+   in the class definition. Doing so means that not only will instances of the
+   class raise an appropriate :exc:`TypeError` when a program attempts to
+   retrieve their hash value, but they will also be correctly identified as
+   unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike
+   classes which define their own :meth:`__hash__` to explicitly raise
+   :exc:`TypeError`).
 
    .. versionchanged:: 2.5
       :meth:`__hash__` may now also return a long integer object; the 32-bit