Merged revisions 87807,87820,87831,87859 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r87807 | georg.brandl | 2011-01-06 20:28:18 +0100 (Do, 06 Jan 2011) | 1 line

  #10846: fix typo.
........
  r87820 | georg.brandl | 2011-01-07 19:28:45 +0100 (Fr, 07 Jan 2011) | 1 line

  #10856: document (Base)Exception.args better.
........
  r87831 | georg.brandl | 2011-01-07 21:58:25 +0100 (Fr, 07 Jan 2011) | 1 line

  Fix indent.
........
  r87859 | georg.brandl | 2011-01-08 10:45:43 +0100 (Sa, 08 Jan 2011) | 1 line

  #10855: document close() semantics of wave objects.
........

3 files changed, 41 insertions, 18 deletions

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 7e94c0c..f9a6bee 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -26,7 +26,7 @@ equivalent, even if they have the same name.
 
 The built-in exceptions listed below can be generated by the interpreter or
 built-in functions.  Except where mentioned, they have an "associated value"
-indicating the detailed cause of the error. This may be a string or a tuple
+indicating the detailed cause of the error.  This may be a string or a tuple
 containing several items of information (e.g., an error code and a string
 explaining the code). The associated value is the second argument to the
 :keyword:`raise` statement.  If the exception class is derived from the standard
@@ -46,18 +46,35 @@ defining exceptions is available in the Python Tutorial under
 
 The following exceptions are only used as base classes for other exceptions.
 
-
 .. exception:: BaseException
 
    The base class for all built-in exceptions.  It is not meant to be directly
-   inherited by user-defined classes (for that use :exc:`Exception`).  If
+   inherited by user-defined classes (for that, use :exc:`Exception`).  If
    :func:`str` or :func:`unicode` is called on an instance of this class, the
-   representation of the argument(s) to the instance are returned or the empty
-   string when there were no arguments.  All arguments are  stored in :attr:`args`
-   as a tuple.
+   representation of the argument(s) to the instance are returned, or the empty
+   string when there were no arguments.
 
    .. versionadded:: 2.5
 
+   .. attribute:: args
+
+      The tuple of arguments given to the exception constructor.  Some built-in
+      exceptions (like :exc:`IOError`) expect a certain number of arguments and
+      assign a special meaning to the elements of this tuple, while others are
+      usually called only with a single string giving an error message.
+
+   .. method:: with_traceback(tb)
+
+      This method sets *tb* as the new traceback for the exception and returns
+      the exception object.  It is usually used in exception handling code like
+      this::
+
+         try:
+             ...
+         except SomeException:
+             tb = sys.exc_info()[2]
+             raise OtherException(...).with_traceback(tb)
+
 
 .. exception:: Exception
 
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 4a6041f..0766511 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -655,9 +655,9 @@ waiting until some other thread calls :meth:`release`.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Semaphores are often used to guard resources with limited capacity, for example,
-a database server.  In any situation where the size of the resource size is
-fixed, you should use a bounded semaphore.  Before spawning any worker threads,
-your main thread would initialize the semaphore::
+a database server.  In any situation where the size of the resource is fixed,
+you should use a bounded semaphore.  Before spawning any worker threads, your
+main thread would initialize the semaphore::
 
    maxconnections = 5
    ...
diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index 3be0343..c1db523 100644
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -14,8 +14,8 @@ The :mod:`wave` module defines the following function and exception:
 
 .. function:: open(file[, mode])
 
-   If *file* is a string, open the file by that name, other treat it as a seekable
-   file-like object. *mode* can be any of
+   If *file* is a string, open the file by that name, otherwise treat it as a
+   seekable file-like object.  *mode* can be any of
 
    ``'r'``, ``'rb'``
       Read only mode.
@@ -26,9 +26,14 @@ The :mod:`wave` module defines the following function and exception:
    Note that it does not allow read/write WAV files.
 
    A *mode* of ``'r'`` or ``'rb'`` returns a :class:`Wave_read` object, while a
-   *mode* of ``'w'`` or ``'wb'`` returns a :class:`Wave_write` object.  If *mode*
-   is omitted and a file-like  object is passed as *file*, ``file.mode`` is used as
-   the default value for *mode* (the ``'b'`` flag is still added if  necessary).
+   *mode* of ``'w'`` or ``'wb'`` returns a :class:`Wave_write` object.  If
+   *mode* is omitted and a file-like object is passed as *file*, ``file.mode``
+   is used as the default value for *mode* (the ``'b'`` flag is still added if
+   necessary).
+
+   If you pass in a file-like object, the wave object will not close it when its
+   :meth:`close` method is called; it is the caller's responsibility to close
+   the file object.
 
 
 .. function:: openfp(file, mode)
@@ -52,8 +57,8 @@ Wave_read objects, as returned by :func:`.open`, have the following methods:
 
 .. method:: Wave_read.close()
 
-   Close the stream, and make the instance unusable. This is called automatically
-   on object collection.
+   Close the stream if it was opened by :mod:`wave`, and make the instance
+   unusable.  This is called automatically on object collection.
 
 
 .. method:: Wave_read.getnchannels()
@@ -139,8 +144,8 @@ Wave_write objects, as returned by :func:`.open`, have the following methods:
 
 .. method:: Wave_write.close()
 
-   Make sure *nframes* is correct, and close the file. This method is called upon
-   deletion.
+   Make sure *nframes* is correct, and close the file if it was opened by
+   :mod:`wave`.  This method is called upon object collection.
 
 
 .. method:: Wave_write.setnchannels(n)
@@ -192,6 +197,7 @@ Wave_write objects, as returned by :func:`.open`, have the following methods:
 
    Write audio frames and make sure *nframes* is correct.
 
+
 Note that it is invalid to set any parameters after calling :meth:`writeframes`
 or :meth:`writeframesraw`, and any attempt to do so will raise
 :exc:`wave.Error`.