Skip to content

Commit

Permalink
[3.12] pythongh-105096: Reformat wave documentation (python#105136) (p…
Browse files Browse the repository at this point in the history 
…ython#105138)

pythongh-105096: Reformat wave documentation (python#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)
(cherry picked from commit 01b42f9)
  • Loading branch information
@vstinner
vstinner committed May 31, 2023
1 parent 67a8469 commit 6874b65
Show file tree
Hide file tree
Showing 2 changed files with 108 additions and 100 deletions.
203 changes: 105 additions & 98 deletions Doc/library/wave.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@

--------------

The :mod:`wave` module provides a convenient interface to the WAV sound format.
The :mod:`wave` module provides a convenient interface to the Waveform Audio
"WAVE" (or "WAV") file format.
Only files using ``WAVE_FORMAT_PCM`` are supported. Note that this does not
include files using ``WAVE_FORMAT_EXTENSIBLE`` even if the subformat is PCM.

Expand All @@ -37,13 +38,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.
Expand All @@ -59,185 +59,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`.
5 changes: 3 additions & 2 deletions Lib/wave.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ class Error(Exception):
_wave_params = namedtuple('_wave_params',
'nchannels sampwidth framerate nframes comptype compname')


def _byteswap(data, width):
swapped_data = bytearray(len(data))

Expand All @@ -101,7 +102,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:
Expand Down Expand Up @@ -211,7 +211,6 @@ def skip(self):
raise EOFError



class Wave_read:
"""Variables used in this class:
Expand Down Expand Up @@ -393,6 +392,7 @@ def _read_fmt_chunk(self, chunk):
self._comptype = 'NONE'
self._compname = 'not compressed'


class Wave_write:
"""Variables used in this class:
Expand Down Expand Up @@ -620,6 +620,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'):
Expand Down

0 comments on commit 6874b65

Please sign in to comment.