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

Doc/library/wave.rst

@@ -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)
@@ -196,6 +201,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`.