whatsnew: Wave_write handles unseekable files. (#5202)

Also clarify the documentation of this feature.

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.

Doc/whatsnew/3.4.rst

@@ -1439,6 +1439,10 @@ plain tuple.  (Contributed by Claudiu Popa in :issue:`17487`.)
 :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
 -------