[Python-checkins] r87859 - python/branches/py3k/Doc/library/wave.rst

[georg.brandl]

Author: georg.brandl
Date: Sat Jan  8 10:45:43 2011
New Revision: 87859

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

Modified:
   python/branches/py3k/Doc/library/wave.rst

Modified: python/branches/py3k/Doc/library/wave.rst
==============================================================================
--- python/branches/py3k/Doc/library/wave.rst	(original)
+++ python/branches/py3k/Doc/library/wave.rst	Sat Jan  8 10:45:43 2011
@@ -14,8 +14,8 @@
 
 .. 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 @@
    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 @@
 
 .. 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 @@
 
 .. 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)
@@ -196,6 +201,7 @@
 
    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`.