Merged revisions 87807,87820,87831,87859,87870 via svnmerge from
svn+ssh://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. ........ r87870 | georg.brandl | 2011-01-08 22:04:25 +0100 (Sa, 08 Jan 2011) | 1 line zlib only works with bytes objects. ........
This commit is contained in:
Georg Brandl
parent
7fdc746a81
commit
ec78b8b170
|
|
@ -18,12 +18,10 @@ 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
|
||||
containing several items of information (e.g., an error code and a string
|
||||
explaining the code). The associated value is usually passed to the exception
|
||||
class's constructor. If the exception class is derived from the standard root
|
||||
class :exc:`BaseException`, the associated value is present as the exception
|
||||
instance's :attr:`args` attribute.
|
||||
indicating the detailed cause of the error. This may be a string or a tuple of
|
||||
several items of information (e.g., an error code and a string explaining the
|
||||
code). The associated value is usually passed as arguments to the exception
|
||||
class's constructor.
|
||||
|
||||
User code can raise built-in exceptions. This can be used to test an exception
|
||||
handler or to report an error condition "just like" the situation in which the
|
||||
|
|
@ -38,16 +36,32 @@ defining exceptions is available in the Python Tutorial under
|
|||
|
||||
The following exceptions are used mostly as base classes for other exceptions.
|
||||
|
||||
.. XXX document with_traceback()
|
||||
|
||||
.. 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:`bytes` or :func:`str` 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.
|
||||
|
||||
.. 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
|
||||
|
|
|
|||
|
|
@ -632,9 +632,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
|
||||
...
|
||||
|
|
|
|||
|
|
@ -14,8 +14,8 @@ The :mod:`wave` module defines the following function and exception:
|
|||
|
||||
.. function:: open(file, mode=None)
|
||||
|
||||
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`.
|
||||
|
|
|
|||
|
|
@ -51,9 +51,9 @@ The available exception and functions in this module are:
|
|||
regardless of sign.
|
||||
|
||||
|
||||
.. function:: compress(string[, level])
|
||||
.. function:: compress(data[, level])
|
||||
|
||||
Compresses the data in *string*, returning a string contained compressed data.
|
||||
Compresses the bytes in *data*, returning a bytes object containing compressed data.
|
||||
*level* is an integer from ``1`` to ``9`` controlling the level of compression;
|
||||
``1`` is fastest and produces the least compression, ``9`` is slowest and
|
||||
produces the most. The default value is ``6``. Raises the :exc:`error`
|
||||
|
|
@ -92,9 +92,9 @@ The available exception and functions in this module are:
|
|||
regardless of sign.
|
||||
|
||||
|
||||
.. function:: decompress(string[, wbits[, bufsize]])
|
||||
.. function:: decompress(data[, wbits[, bufsize]])
|
||||
|
||||
Decompresses the data in *string*, returning a string containing the
|
||||
Decompresses the bytes in *data*, returning a bytes object containing the
|
||||
uncompressed data. The *wbits* parameter controls the size of the window
|
||||
buffer. If *bufsize* is given, it is used as the initial size of the output
|
||||
buffer. Raises the :exc:`error` exception if any error occurs.
|
||||
|
|
@ -121,21 +121,21 @@ The available exception and functions in this module are:
|
|||
Compression objects support the following methods:
|
||||
|
||||
|
||||
.. method:: Compress.compress(string)
|
||||
.. method:: Compress.compress(data)
|
||||
|
||||
Compress *string*, returning a string containing compressed data for at least
|
||||
part of the data in *string*. This data should be concatenated to the output
|
||||
Compress *data*, returning a bytes object containing compressed data for at least
|
||||
part of the data in *data*. This data should be concatenated to the output
|
||||
produced by any preceding calls to the :meth:`compress` method. Some input may
|
||||
be kept in internal buffers for later processing.
|
||||
|
||||
|
||||
.. method:: Compress.flush([mode])
|
||||
|
||||
All pending input is processed, and a string containing the remaining compressed
|
||||
All pending input is processed, and a bytes object containing the remaining compressed
|
||||
output is returned. *mode* can be selected from the constants
|
||||
:const:`Z_SYNC_FLUSH`, :const:`Z_FULL_FLUSH`, or :const:`Z_FINISH`,
|
||||
defaulting to :const:`Z_FINISH`. :const:`Z_SYNC_FLUSH` and
|
||||
:const:`Z_FULL_FLUSH` allow compressing further strings of data, while
|
||||
:const:`Z_FULL_FLUSH` allow compressing further bytestrings of data, while
|
||||
:const:`Z_FINISH` finishes the compressed stream and prevents compressing any
|
||||
more data. After calling :meth:`flush` with *mode* set to :const:`Z_FINISH`,
|
||||
the :meth:`compress` method cannot be called again; the only realistic action is
|
||||
|
|
@ -153,31 +153,31 @@ Decompression objects support the following methods, and two attributes:
|
|||
|
||||
.. attribute:: Decompress.unused_data
|
||||
|
||||
A string which contains any bytes past the end of the compressed data. That is,
|
||||
A bytes object which contains any bytes past the end of the compressed data. That is,
|
||||
this remains ``""`` until the last byte that contains compression data is
|
||||
available. If the whole string turned out to contain compressed data, this is
|
||||
``""``, the empty string.
|
||||
available. If the whole bytestring turned out to contain compressed data, this is
|
||||
``b""``, an empty bytes object.
|
||||
|
||||
The only way to determine where a string of compressed data ends is by actually
|
||||
The only way to determine where a bytestring of compressed data ends is by actually
|
||||
decompressing it. This means that when compressed data is contained part of a
|
||||
larger file, you can only find the end of it by reading data and feeding it
|
||||
followed by some non-empty string into a decompression object's
|
||||
followed by some non-empty bytestring into a decompression object's
|
||||
:meth:`decompress` method until the :attr:`unused_data` attribute is no longer
|
||||
the empty string.
|
||||
empty.
|
||||
|
||||
|
||||
.. attribute:: Decompress.unconsumed_tail
|
||||
|
||||
A string that contains any data that was not consumed by the last
|
||||
A bytes object that contains any data that was not consumed by the last
|
||||
:meth:`decompress` call because it exceeded the limit for the uncompressed data
|
||||
buffer. This data has not yet been seen by the zlib machinery, so you must feed
|
||||
it (possibly with further data concatenated to it) back to a subsequent
|
||||
:meth:`decompress` method call in order to get correct output.
|
||||
|
||||
|
||||
.. method:: Decompress.decompress(string[, max_length])
|
||||
.. method:: Decompress.decompress(data[, max_length])
|
||||
|
||||
Decompress *string*, returning a string containing the uncompressed data
|
||||
Decompress *data*, returning a bytes object containing the uncompressed data
|
||||
corresponding to at least part of the data in *string*. This data should be
|
||||
concatenated to the output produced by any preceding calls to the
|
||||
:meth:`decompress` method. Some of the input data may be preserved in internal
|
||||
|
|
@ -186,15 +186,15 @@ Decompression objects support the following methods, and two attributes:
|
|||
If the optional parameter *max_length* is supplied then the return value will be
|
||||
no longer than *max_length*. This may mean that not all of the compressed input
|
||||
can be processed; and unconsumed data will be stored in the attribute
|
||||
:attr:`unconsumed_tail`. This string must be passed to a subsequent call to
|
||||
:attr:`unconsumed_tail`. This bytestring must be passed to a subsequent call to
|
||||
:meth:`decompress` if decompression is to continue. If *max_length* is not
|
||||
supplied then the whole input is decompressed, and :attr:`unconsumed_tail` is an
|
||||
empty string.
|
||||
supplied then the whole input is decompressed, and :attr:`unconsumed_tail` is
|
||||
empty.
|
||||
|
||||
|
||||
.. method:: Decompress.flush([length])
|
||||
|
||||
All pending input is processed, and a string containing the remaining
|
||||
All pending input is processed, and a bytes object containing the remaining
|
||||
uncompressed output is returned. After calling :meth:`flush`, the
|
||||
:meth:`decompress` method cannot be called again; the only realistic action is
|
||||
to delete the object.
|
||||
|
|
|
|||
Loading…
Reference in New Issue