diff options
author | Georg Brandl <georg@python.org> | 2011-01-08 09:45:43 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2011-01-08 09:45:43 (GMT) |
commit | d97b7b5158ce3149d4fc7d45a1d8af694ef3564c (patch) | |
tree | 2c1db2ef23bab34e8062f392714af2fc2fab298d | |
parent | 5254e9700ec0402d753e882d19d6df5522aa8cb5 (diff) | |
download | cpython-d97b7b5158ce3149d4fc7d45a1d8af694ef3564c.zip cpython-d97b7b5158ce3149d4fc7d45a1d8af694ef3564c.tar.gz cpython-d97b7b5158ce3149d4fc7d45a1d8af694ef3564c.tar.bz2 |
#10855: document close() semantics of wave objects.
-rw-r--r-- | Doc/library/wave.rst | 24 |
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`. |