From 85e5d03163cac106ac8ec142ef03f1349a48948b Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 31 May 2023 13:29:10 +0200 Subject: [PATCH] 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 --- Doc/library/wave.rst | 259 ++++++++++++++++++++++--------------------- Doc/tools/.nitignore | 1 - Lib/wave.py | 5 +- 3 files changed, 136 insertions(+), 129 deletions(-) diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst index 4dcbc3d4c2d..9565ed92657 100644 --- a/Doc/library/wave.rst +++ b/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() - ` or :meth:`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,87 +63,91 @@ 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. + + Wave_read objects, as returned by :func:`.open`, have the following methods: -.. method:: Wave_read.close() + .. method:: close() - Close the stream if it was opened by :mod:`wave`, 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() + .. method:: getnchannels() - Returns number of audio channels (``1`` for mono, ``2`` for stereo). + Returns number of audio channels (``1`` for mono, ``2`` for stereo). -.. method:: Wave_read.getsampwidth() + .. method:: getsampwidth() - Returns sample width in bytes. + Returns sample width in bytes. -.. method:: Wave_read.getframerate() + .. method:: getframerate() - Returns sampling frequency. + Returns sampling frequency. -.. method:: Wave_read.getnframes() + .. method:: getnframes() - Returns number of audio frames. + Returns number of audio frames. -.. method:: Wave_read.getcomptype() + .. method:: getcomptype() - Returns compression type (``'NONE'`` is the only supported type). + Returns compression type (``'NONE'`` is the only supported type). -.. method:: Wave_read.getcompname() + .. method:: getcompname() - Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'`` - parallels ``'NONE'``. + Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'`` + parallels ``'NONE'``. -.. method:: Wave_read.getparams() + .. method:: getparams() - Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, - framerate, nframes, comptype, compname)``, equivalent to output of the - :meth:`get\*` methods. + Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, + framerate, nframes, comptype, compname)``, equivalent to output of the + ``get*()`` methods. -.. method:: Wave_read.readframes(n) + .. method:: readframes(n) - Reads and returns at most *n* frames of audio, as a :class:`bytes` object. + Reads and returns at most *n* frames of audio, as a :class:`bytes` object. -.. method:: Wave_read.rewind() + .. method:: rewind() - Rewind the file pointer to the beginning of the audio stream. + Rewind the file pointer to the beginning of the audio stream. -The following two methods are defined for compatibility with the old :mod:`!aifc` -module, and don't do anything interesting. + The following two methods are defined for compatibility with the old :mod:`!aifc` + module, and don't do anything interesting. -.. method:: Wave_read.getmarkers() + .. method:: getmarkers() - Returns ``None``. + Returns ``None``. -.. method:: Wave_read.getmark(id) + .. method:: getmark(id) - Raise an error. + Raise an error. -The following two methods define a term "position" which is compatible between -them, and is otherwise implementation dependent. + The following two methods define a term "position" which is compatible between + them, and is otherwise implementation dependent. -.. method:: Wave_read.setpos(pos) + .. method:: setpos(pos) - Set the file pointer to the specified position. + Set the file pointer to the specified position. -.. method:: Wave_read.tell() + .. method:: tell() - Return current file pointer position. + Return current file pointer position. .. _wave-write-objects: @@ -151,97 +155,100 @@ 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. +.. 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`. - -.. 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. 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) - - Set the number of channels. - - -.. method:: Wave_write.setsampwidth(n) - - Set the sample width to *n* bytes. - - -.. method:: Wave_write.setframerate(n) - - Set the frame rate to *n*. - - .. versionchanged:: 3.2 - A non-integral input to this method is rounded to the nearest - integer. - - -.. method:: Wave_write.setnframes(n) - - 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) - - Set the compression type and description. At the moment, only compression type - ``NONE`` is supported, meaning no compression. - - -.. method:: Wave_write.setparams(tuple) - - The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype, - compname)``, with values valid for the :meth:`set\*` methods. Sets all - parameters. - - -.. method:: Wave_write.tell() - - Return current position in the file, with the same disclaimer for the - :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods. - - -.. method:: Wave_write.writeframesraw(data) - - Write audio frames, without correcting *nframes*. + 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. .. versionchanged:: 3.4 - Any :term:`bytes-like object` is now accepted. + Added support for unseekable files. + + Wave_write objects have the following methods: + + .. method:: close() + + 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. -.. method:: Wave_write.writeframes(data) + .. method:: setnchannels(n) - 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. + Set the number of channels. -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`. + .. method:: setsampwidth(n) + Set the sample width to *n* bytes. + + + .. method:: setframerate(n) + + Set the frame rate to *n*. + + .. versionchanged:: 3.2 + A non-integral input to this method is rounded to the nearest + integer. + + + .. method:: setnframes(n) + + 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:: setcomptype(type, name) + + Set the compression type and description. At the moment, only compression type + ``NONE`` is supported, meaning no compression. + + + .. method:: setparams(tuple) + + The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype, + compname)``, with values valid for the ``set*()`` methods. Sets all + parameters. + + + .. method:: tell() + + Return current position in the file, with the same disclaimer for the + :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods. + + + .. method:: writeframesraw(data) + + Write audio frames, without correcting *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*. + + .. 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`. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 2b1fc2bdce4..23aa30c956b 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -226,7 +226,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/winreg.rst Doc/library/winsound.rst diff --git a/Lib/wave.py b/Lib/wave.py index 76b73de1d67..5177ecbef82 100644 --- a/Lib/wave.py +++ b/Lib/wave.py @@ -92,6 +92,7 @@ _array_fmts = None, 'b', 'h', None, 'i' _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 @@ class _Chunk: raise EOFError - class Wave_read: """Variables used in this class: @@ -411,6 +410,7 @@ class Wave_read: self._comptype = 'NONE' self._compname = 'not compressed' + class Wave_write: """Variables used in this class: @@ -638,6 +638,7 @@ class Wave_write: self._file.seek(curpos, 0) self._datalength = self._datawritten + def open(f, mode=None): if mode is None: if hasattr(f, 'mode'):