From: Georg Brandl Date: Sun, 9 Jan 2011 07:58:45 +0000 (+0000) Subject: Merged revisions 87807,87820,87831,87859 via svnmerge from X-Git-Tag: v2.7.2rc1~385 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=335d4f5eb4af064af4972a01481307fb94e8ead3;p=python 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. ........ --- diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 7e94c0c3ba..f9a6bee64d 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 4a6041fa1a..076651192c 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 3be0343346..c1db523073 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`.