Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

gh-105096: Reformat wave documentation #105136

Merged
merged 4 commits into from
May 31, 2023
Merged

gh-105096: Reformat wave documentation #105136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
54825f4
gh-105096: Reformat wave documentation
vstinner May 31, 2023
fc2b220
Fix 3 Sphinx warnings
vstinner May 31, 2023
d6a87cf
Fix formatting
vstinner May 31, 2023
1c848ba
Remove wave.rst from .nitignore
vstinner May 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 106 additions & 99 deletions Doc/library/wave.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The wave.py file only uses "WAVE" name, whereas the doc only uses "WAV" name. The Wikipedia article is called "WAV" and says that the format is called "WAVE". The Python module is called "wave". I'm confused :-) https://en.wikipedia.org/wiki/WAV

supported.

.. versionchanged:: 3.12

Expand Down Expand Up @@ -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.
Expand All @@ -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 old :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 old :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`.
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions Lib/wave.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))

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



class Wave_read:
"""Variables used in this class:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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'):
Expand Down