whatsnew: Wave_write handles unseekable files. (#5202)

Also clarify the documentation of this feature.

1 files changed, 25 insertions, 6 deletions

diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index c32e1fc..b514ff3 100644
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -150,14 +150,30 @@ them, and is otherwise implementation dependent.
 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 @@ Wave_write objects, as returned by :func:`.open`, have the following methods:
 
 .. 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 @@ Wave_write objects, as returned by :func:`.open`, have the following methods:
 
 .. 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.