[Python-checkins] cpython: whatsnew: Wave_write handles unseekable files. (#5202)
r.david.murray
python-checkins at python.org
Sat Mar 8 18:54:20 CET 2014
http://hg.python.org/cpython/rev/b861c7717c79
changeset: 89509:b861c7717c79
user: R David Murray <rdmurray at bitdance.com>
date: Sat Mar 08 11:14:29 2014 -0500
summary:
whatsnew: Wave_write handles unseekable files. (#5202)
Also clarify the documentation of this feature.
files:
Doc/library/wave.rst | 31 +++++++++++++++++++++++++------
Doc/whatsnew/3.4.rst | 4 ++++
2 files changed, 29 insertions(+), 6 deletions(-)
diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -150,14 +150,30 @@
Wave_write Objects
------------------
+For seekable output streams, the ``wave`` header will automatically be updated
+to reflect the number of frames actually written. For unseekable streams, the
+*nframes* value must be accurate when the first frame data is written. An
+accurate *nframes* value can be achieved either by calling
+:meth:`~Wave_write.setnframes` or :meth:`~Wave_write.setparams` with the number
+of frames that will be written before :meth:`~Wave_write.close` is called and
+then using :meth:`~Wave_write.writeframesraw` to write the frame data, or by
+calling :meth:`~Wave_write.writeframes` with all of the frame data to be
+written. In the latter case :meth:`~Wave_write.writeframes` will calculate
+the number of frames in the data and set *nframes* accordingly before writing
+the frame data.
+
Wave_write objects, as returned by :func:`.open`, have the following methods:
+.. versionchanged:: 3.4
+ Added support for unseekable files.
+
.. method:: Wave_write.close()
Make sure *nframes* is correct, and close the file if it was opened by
- :mod:`wave`. This method is called upon object collection. Can raise an
- exception if *nframes* is not correct and a file is not seekable.
+ :mod:`wave`. This method is called upon object collection. It will raise
+ an exception if the output stream is not seekable and *nframes* does not
+ match the number of frames actually written.
.. method:: Wave_write.setnchannels(n)
@@ -181,8 +197,9 @@
.. method:: Wave_write.setnframes(n)
- Set the number of frames to *n*. This will be changed later if more frames are
- written.
+ Set the number of frames to *n*. This will be changed later if the number
+ of frames actually written is different (this update attempt will
+ raise an error if the output stream is not seekable).
.. method:: Wave_write.setcomptype(type, name)
@@ -214,8 +231,10 @@
.. method:: Wave_write.writeframes(data)
- Write audio frames and make sure *nframes* is correct. Can raise an
- exception if a file is not seekable.
+ Write audio frames and make sure *nframes* is correct. It will raise an
+ error if the output stream is not seekable and the total number of frames
+ that have been written after *data* has been written does not match the
+ previously set value for *nframes*.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted.
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -1439,6 +1439,10 @@
:meth:`wave.open` now supports the context manager protocol. (Contributed
by Claudiu Popa in :issue:`17616`.)
+:mod:`wave` can now :ref:`write output to unssekable files
+<wave-write-objects>`. (Contributed by David Jones, Guilherme Polo, and Serhiy
+Storchaka in :issue:`5202`.)
+
weakref
-------
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list