summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2011-01-08 09:45:43 (GMT)
committerGeorg Brandl <georg@python.org>2011-01-08 09:45:43 (GMT)
commitd97b7b5158ce3149d4fc7d45a1d8af694ef3564c (patch)
tree2c1db2ef23bab34e8062f392714af2fc2fab298d
parent5254e9700ec0402d753e882d19d6df5522aa8cb5 (diff)
downloadcpython-d97b7b5158ce3149d4fc7d45a1d8af694ef3564c.zip
cpython-d97b7b5158ce3149d4fc7d45a1d8af694ef3564c.tar.gz
cpython-d97b7b5158ce3149d4fc7d45a1d8af694ef3564c.tar.bz2
#10855: document close() semantics of wave objects.
-rw-r--r--Doc/library/wave.rst24
1 files changed, 15 insertions, 9 deletions
diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index a79489c..bfb4e02 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=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`.