[3.12] gh-105096: Reformat wave documentation (#105136) (#105138)

gh-105096: Reformat wave documentation (#105136)

Add ".. class::" markups in the wave documentation.

* Reformat also wave.py (minor PEP 8 changes).
* Remove redundant "import struct": it's already imported at top
  level.
* Remove wave.rst from .nitignore

(cherry picked from commit 85e5d03)

Author: vstinner

Doc/library/wave.rst

@@ -11,8 +11,9 @@
 
 --------------
 
-The :mod:`wave` module provides a convenient interface to the WAV sound format.
-Only PCM encoded wave files are supported.
+The :mod:`wave` module provides a convenient interface to the Waveform Audio
+"WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are
+supported.
 
 .. versionchanged:: 3.12
 
@@ -41,13 +42,12 @@ The :mod:`wave` module defines the following function and exception:
    value for *mode*.
 
    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
+   ``close()`` method is called; it is the caller's responsibility to close
    the file object.
 
    The :func:`.open` function may be used in a :keyword:`with` statement.  When
-   the :keyword:`!with` block completes, the :meth:`Wave_read.close()
-   <wave.Wave_read.close>` or :meth:`Wave_write.close()
-   <wave.Wave_write.close()>` method is called.
+   the :keyword:`!with` block completes, the :meth:`Wave_read.close()` or
+   :meth:`Wave_write.close()` method is called.
 
    .. versionchanged:: 3.4
       Added support for unseekable files.
@@ -63,185 +63,192 @@ The :mod:`wave` module defines the following function and exception:
 Wave_read Objects
 -----------------
 
-Wave_read objects, as returned by :func:`.open`, have the following methods:
+.. class:: Wave_read
 
+   Read a WAV file.
 
-.. method:: Wave_read.close()
+   Wave_read objects, as returned by :func:`.open`, have the following methods:
 
-   Close the stream if it was opened by :mod:`wave`, and make the instance
-   unusable.  This is called automatically on object collection.
 
+   .. method:: close()
 
-.. method:: Wave_read.getnchannels()
+      Close the stream if it was opened by :mod:`wave`, and make the instance
+      unusable.  This is called automatically on object collection.
 
-   Returns number of audio channels (``1`` for mono, ``2`` for stereo).
 
+   .. method:: getnchannels()
 
-.. method:: Wave_read.getsampwidth()
+      Returns number of audio channels (``1`` for mono, ``2`` for stereo).
 
-   Returns sample width in bytes.
 
+   .. method:: getsampwidth()
 
-.. method:: Wave_read.getframerate()
+      Returns sample width in bytes.
 
-   Returns sampling frequency.
 
+   .. method:: getframerate()
 
-.. method:: Wave_read.getnframes()
+      Returns sampling frequency.
 
-   Returns number of audio frames.
 
+   .. method:: getnframes()
 
-.. method:: Wave_read.getcomptype()
+      Returns number of audio frames.
 
-   Returns compression type (``'NONE'`` is the only supported type).
 
+   .. method:: getcomptype()
 
-.. method:: Wave_read.getcompname()
+      Returns compression type (``'NONE'`` is the only supported type).
 
-   Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
-   parallels ``'NONE'``.
 
+   .. method:: getcompname()
 
-.. method:: Wave_read.getparams()
+      Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
+      parallels ``'NONE'``.
 
-   Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
-   framerate, nframes, comptype, compname)``, equivalent to output of the
-   :meth:`get\*` methods.
 
+   .. method:: getparams()
 
-.. method:: Wave_read.readframes(n)
+      Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
+      framerate, nframes, comptype, compname)``, equivalent to output of the
+      ``get*()`` methods.
 
-   Reads and returns at most *n* frames of audio, as a :class:`bytes` object.
 
+   .. method:: readframes(n)
 
-.. method:: Wave_read.rewind()
+      Reads and returns at most *n* frames of audio, as a :class:`bytes` object.
 
-   Rewind the file pointer to the beginning of the audio stream.
 
-The following two methods are defined for compatibility with the :mod:`aifc`
-module, and don't do anything interesting.
+   .. method:: rewind()
 
+      Rewind the file pointer to the beginning of the audio stream.
 
-.. method:: Wave_read.getmarkers()
+   The following two methods are defined for compatibility with the :mod:`aifc`
+   module, and don't do anything interesting.
 
-   Returns ``None``.
 
+   .. method:: getmarkers()
 
-.. method:: Wave_read.getmark(id)
+      Returns ``None``.
 
-   Raise an error.
 
-The following two methods define a term "position" which is compatible between
-them, and is otherwise implementation dependent.
+   .. method:: getmark(id)
 
+      Raise an error.
 
-.. method:: Wave_read.setpos(pos)
+   The following two methods define a term "position" which is compatible between
+   them, and is otherwise implementation dependent.
 
-   Set the file pointer to the specified position.
 
+   .. method:: setpos(pos)
 
-.. method:: Wave_read.tell()
+      Set the file pointer to the specified position.
 
-   Return current file pointer position.
+
+   .. method:: tell()
+
+      Return current file pointer position.
 
 
 .. _wave-write-objects:
 
 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.
+.. class:: Wave_write
 
-Wave_write objects, as returned by :func:`.open`, have the following methods:
+   Write a WAV file.
 
-.. versionchanged:: 3.4
-   Added support for unseekable files.
+   Wave_write objects, as returned by :func:`.open`.
 
+   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:`setnframes` or :meth:`setparams` with the number
+   of frames that will be written before :meth:`close` is called and
+   then using :meth:`writeframesraw` to write the frame data, or by
+   calling :meth:`writeframes` with all of the frame data to be
+   written.  In the latter case :meth:`writeframes` will calculate
+   the number of frames in the data and set *nframes* accordingly before writing
+   the frame data.
 
-.. method:: Wave_write.close()
+   .. versionchanged:: 3.4
+      Added support for unseekable files.
 
-   Make sure *nframes* is correct, and close the file if it was opened by
-   :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.
+   Wave_write objects have the following methods:
 
+   .. method:: close()
 
-.. method:: Wave_write.setnchannels(n)
+      Make sure *nframes* is correct, and close the file if it was opened by
+      :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.
 
-   Set the number of channels.
 
+   .. method:: setnchannels(n)
 
-.. method:: Wave_write.setsampwidth(n)
+      Set the number of channels.
 
-   Set the sample width to *n* bytes.
 
+   .. method:: setsampwidth(n)
 
-.. method:: Wave_write.setframerate(n)
+      Set the sample width to *n* bytes.
 
-   Set the frame rate to *n*.
 
-   .. versionchanged:: 3.2
-      A non-integral input to this method is rounded to the nearest
-      integer.
+   .. method:: setframerate(n)
 
+      Set the frame rate to *n*.
 
-.. method:: Wave_write.setnframes(n)
+      .. versionchanged:: 3.2
+         A non-integral input to this method is rounded to the nearest
+         integer.
 
-   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:: setnframes(n)
 
-.. method:: Wave_write.setcomptype(type, name)
+      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).
 
-   Set the compression type and description. At the moment, only compression type
-   ``NONE`` is supported, meaning no compression.
 
+   .. method:: setcomptype(type, name)
 
-.. method:: Wave_write.setparams(tuple)
+      Set the compression type and description. At the moment, only compression type
+      ``NONE`` is supported, meaning no compression.
 
-   The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
-   compname)``, with values valid for the :meth:`set\*` methods.  Sets all
-   parameters.
 
+   .. method:: setparams(tuple)
 
-.. method:: Wave_write.tell()
+      The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
+      compname)``, with values valid for the ``set*()`` methods.  Sets all
+      parameters.
 
-   Return current position in the file, with the same disclaimer for the
-   :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
 
+   .. method:: tell()
 
-.. method:: Wave_write.writeframesraw(data)
+      Return current position in the file, with the same disclaimer for the
+      :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
 
-   Write audio frames, without correcting *nframes*.
 
-   .. versionchanged:: 3.4
-      Any :term:`bytes-like object` is now accepted.
+   .. method:: writeframesraw(data)
 
+      Write audio frames, without correcting *nframes*.
 
-.. method:: Wave_write.writeframes(data)
+      .. versionchanged:: 3.4
+         Any :term:`bytes-like object` is now accepted.
 
-   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` is now accepted.
+   .. method:: writeframes(data)
 
+      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*.
 
-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`.
+      .. versionchanged:: 3.4
+         Any :term:`bytes-like object` is now accepted.
 
+      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`.

Doc/tools/.nitignore

@@ -236,7 +236,6 @@ Doc/library/urllib.error.rst
 Doc/library/urllib.parse.rst
 Doc/library/urllib.request.rst
 Doc/library/uuid.rst
-Doc/library/wave.rst
 Doc/library/weakref.rst
 Doc/library/webbrowser.rst
 Doc/library/winreg.rst

Lib/wave.py

@@ -92,6 +92,7 @@ class Error(Exception):
 _wave_params = namedtuple('_wave_params',
                      'nchannels sampwidth framerate nframes comptype compname')
 
+
 def _byteswap(data, width):
     swapped_data = bytearray(len(data))
 
@@ -104,7 +105,6 @@ def _byteswap(data, width):
 
 class _Chunk:
     def __init__(self, file, align=True, bigendian=True, inclheader=False):
-        import struct
         self.closed = False
         self.align = align      # whether to align to word (2-byte) boundaries
         if bigendian:
@@ -214,7 +214,6 @@ def skip(self):
                 raise EOFError
 
 
-
 class Wave_read:
     """Variables used in this class:
 
@@ -411,6 +410,7 @@ def _read_fmt_chunk(self, chunk):
         self._comptype = 'NONE'
         self._compname = 'not compressed'
 
+
 class Wave_write:
     """Variables used in this class:
 
@@ -638,6 +638,7 @@ def _patchheader(self):
         self._file.seek(curpos, 0)
         self._datalength = self._datawritten
 
+
 def open(f, mode=None):
     if mode is None:
         if hasattr(f, 'mode'):