mirror of https://github.com/python/cpython
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
This commit is contained in:
Victor Stinner
GitHub
parent
579c41c102
commit
85e5d03163
|
|
@ -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,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`.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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'):
|
||||
|
|
|
|||
Loading…
Reference in New Issue