mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-06 01:49:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

Browse source 
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 85e5d03163)
This commit is contained in:
Victor Stinner 2023-05-31 14:04:21 +02:00 • committed by GitHub
parent c687946f68
commit 01b42f9559
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 136 additions and 129 deletions
Download patch file Download diff file Expand all files Collapse all files

259
Doc/library/wave.rst
View file

@ -11,8 +11,9 @@
-------------- --------------
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
Only PCM encoded wave files are supported. "WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are
supported.
.. versionchanged:: 3.12 .. versionchanged:: 3.12
@ -41,13 +42,12 @@ The :mod:`wave` module defines the following function and exception:
value for *mode*. value for *mode*.
If you pass in a file-like object, the wave object will not close it when its 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 file object.
The :func:`.open` function may be used in a :keyword:`with` statement. When The :func:`.open` function may be used in a :keyword:`with` statement. When
the :keyword:`!with` block completes, the :meth:`Wave_read.close() the :keyword:`!with` block completes, the :meth:`Wave_read.close()` or
<wave.Wave_read.close>` or :meth:`Wave_write.close() :meth:`Wave_write.close()` method is called.
<wave.Wave_write.close()>` method is called.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
Added support for unseekable files. 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
----------------- -----------------
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 Close the stream if it was opened by :mod:`wave`, and make the instance
unusable. This is called automatically on object collection. 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'`` Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
parallels ``'NONE'``. parallels ``'NONE'``.
.. method:: Wave_read.getparams() .. method:: getparams()
Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
framerate, nframes, comptype, compname)``, equivalent to output of the framerate, nframes, comptype, compname)``, equivalent to output of the
:meth:`get\*` methods. ``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 :mod:`aifc` The following two methods are defined for compatibility with the :mod:`aifc`
module, and don't do anything interesting. 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 The following two methods define a term "position" which is compatible between
them, and is otherwise implementation dependent. 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: .. _wave-write-objects:
@ -151,97 +155,100 @@ them, and is otherwise implementation dependent.
Wave_write Objects Wave_write Objects
------------------ ------------------
For seekable output streams, the ``wave`` header will automatically be updated .. class:: Wave_write
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.
Wave_write objects, as returned by :func:`.open`, have the following methods: Write a WAV file.
.. versionchanged:: 3.4 Wave_write objects, as returned by :func:`.open`.
Added support for unseekable files.
For seekable output streams, the ``wave`` header will automatically be updated
.. method:: Wave_write.close() 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
Make sure *nframes* is correct, and close the file if it was opened by accurate *nframes* value can be achieved either by calling
:mod:`wave`. This method is called upon object collection. It will raise :meth:`setnframes` or :meth:`setparams` with the number
an exception if the output stream is not seekable and *nframes* does not of frames that will be written before :meth:`close` is called and
match the number of frames actually written. 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
.. method:: Wave_write.setnchannels(n) the number of frames in the data and set *nframes* accordingly before writing
the frame data.
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*.
.. versionchanged:: 3.4 .. 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 Set the number of channels.
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` .. method:: setsampwidth(n)
or :meth:`writeframesraw`, and any attempt to do so will raise
:exc:`wave.Error`.
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`.

1
Doc/tools/.nitignore
View file

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

5
Lib/wave.py
View file

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