Skip to content

Commit 54825f4

Browse files
vstinnervstinner
committed
pythongh-105096: Reformat wave documentation
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.
1 parent adccff3 commit 54825f4

2 files changed

Lines changed: 109 additions & 100 deletions

File tree

‎Doc/library/wave.rst‎

Lines changed: 106 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,9 @@
1111

1212
--------------
1313

14-
The :mod:`wave` module provides a convenient interface to the WAV sound format.
15-
Only PCM encoded wave files are supported.
14+
The :mod:`wave` module provides a convenient interface to the Waveform Audio
15+
"WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are
16+
supported.
1617

1718
.. versionchanged:: 3.12
1819

@@ -45,9 +46,8 @@ The :mod:`wave` module defines the following function and exception:
4546
the file object.
4647

4748
The :func:`.open` function may be used in a :keyword:`with` statement. When
48-
the :keyword:`!with` block completes, the :meth:`Wave_read.close()
49-
<wave.Wave_read.close>` or :meth:`Wave_write.close()
50-
<wave.Wave_write.close()>` method is called.
49+
the :keyword:`!with` block completes, the :meth:`Wave_read.close()` or
50+
:meth:`Wave_write.close()` method is called.
5151

5252
.. versionchanged:: 3.4
5353
Added support for unseekable files.
@@ -63,185 +63,193 @@ The :mod:`wave` module defines the following function and exception:
6363
Wave_read Objects
6464
-----------------
6565

66-
Wave_read objects, as returned by :func:`.open`, have the following methods:
66+
.. class:: Wave_read
6767

68+
Read a WAV file.
6869

69-
.. method:: Wave_read.close()
70+
Wave_read objects, as returned by :func:`.open`, have the following methods:
7071

71-
Close the stream if it was opened by :mod:`wave`, and make the instance
72-
unusable. This is called automatically on object collection.
7372

73+
.. method:: close()
7474

75-
.. method:: Wave_read.getnchannels()
75+
Close the stream if it was opened by :mod:`wave`, and make the instance
76+
unusable. This is called automatically on object collection.
7677

77-
Returns number of audio channels (``1`` for mono, ``2`` for stereo).
7878

79+
.. method:: getnchannels()
7980

80-
.. method:: Wave_read.getsampwidth()
81+
Returns number of audio channels (``1`` for mono, ``2`` for stereo).
8182

82-
Returns sample width in bytes.
8383

84+
.. method:: getsampwidth()
8485

85-
.. method:: Wave_read.getframerate()
86+
Returns sample width in bytes.
8687

87-
Returns sampling frequency.
8888

89+
.. method:: getframerate()
8990

90-
.. method:: Wave_read.getnframes()
91+
Returns sampling frequency.
9192

92-
Returns number of audio frames.
9393

94+
.. method:: getnframes()
9495

95-
.. method:: Wave_read.getcomptype()
96+
Returns number of audio frames.
9697

97-
Returns compression type (``'NONE'`` is the only supported type).
9898

99+
.. method:: getcomptype()
99100

100-
.. method:: Wave_read.getcompname()
101+
Returns compression type (``'NONE'`` is the only supported type).
101102

102-
Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
103-
parallels ``'NONE'``.
104103

104+
.. method:: getcompname()
105105

106-
.. method:: Wave_read.getparams()
106+
Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
107+
parallels ``'NONE'``.
107108

108-
Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
109-
framerate, nframes, comptype, compname)``, equivalent to output of the
110-
:meth:`get\*` methods.
111109

110+
.. method:: getparams()
112111

113-
.. method:: Wave_read.readframes(n)
112+
Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
113+
framerate, nframes, comptype, compname)``, equivalent to output of the
114+
:meth:`get\*` methods.
114115

115-
Reads and returns at most *n* frames of audio, as a :class:`bytes` object.
116116

117+
.. method:: readframes(n)
117118

118-
.. method:: Wave_read.rewind()
119+
Reads and returns at most *n* frames of audio, as a :class:`bytes` object.
119120

120-
Rewind the file pointer to the beginning of the audio stream.
121121

122-
The following two methods are defined for compatibility with the old :mod:`!aifc`
123-
module, and don't do anything interesting.
122+
.. method:: rewind()
124123

124+
Rewind the file pointer to the beginning of the audio stream.
125125

126-
.. method:: Wave_read.getmarkers()
126+
The following two methods are defined for compatibility with the old :mod:`!aifc`
127+
module, and don't do anything interesting.
127128

128-
Returns ``None``.
129129

130+
.. method:: getmarkers()
130131

131-
.. method:: Wave_read.getmark(id)
132+
Returns ``None``.
132133

133-
Raise an error.
134134

135-
The following two methods define a term "position" which is compatible between
136-
them, and is otherwise implementation dependent.
135+
.. method:: getmark(id)
137136

137+
Raise an error.
138138

139-
.. method:: Wave_read.setpos(pos)
139+
The following two methods define a term "position" which is compatible between
140+
them, and is otherwise implementation dependent.
140141

141-
Set the file pointer to the specified position.
142142

143+
.. method:: setpos(pos)
143144

144-
.. method:: Wave_read.tell()
145+
Set the file pointer to the specified position.
145146

146-
Return current file pointer position.
147+
148+
.. method:: tell()
149+
150+
Return current file pointer position.
147151

148152

149153
.. _wave-write-objects:
150154

151155
Wave_write Objects
152156
------------------
153157

154-
For seekable output streams, the ``wave`` header will automatically be updated
155-
to reflect the number of frames actually written. For unseekable streams, the
156-
*nframes* value must be accurate when the first frame data is written. An
157-
accurate *nframes* value can be achieved either by calling
158-
:meth:`~Wave_write.setnframes` or :meth:`~Wave_write.setparams` with the number
159-
of frames that will be written before :meth:`~Wave_write.close` is called and
160-
then using :meth:`~Wave_write.writeframesraw` to write the frame data, or by
161-
calling :meth:`~Wave_write.writeframes` with all of the frame data to be
162-
written. In the latter case :meth:`~Wave_write.writeframes` will calculate
163-
the number of frames in the data and set *nframes* accordingly before writing
164-
the frame data.
158+
.. class:: Wave_write
165159

166-
Wave_write objects, as returned by :func:`.open`, have the following methods:
160+
Write a WAV file.
167161

168-
.. versionchanged:: 3.4
169-
Added support for unseekable files.
162+
Wave_write objects, as returned by :func:`.open`:
170163

164+
For seekable output streams, the ``wave`` header will automatically be updated
165+
to reflect the number of frames actually written. For unseekable streams, the
166+
*nframes* value must be accurate when the first frame data is written. An
167+
accurate *nframes* value can be achieved either by calling
168+
:meth:`setnframes` or :meth:`setparams` with the number
169+
of frames that will be written before :meth:`close` is called and
170+
then using :meth:`writeframesraw` to write the frame data, or by
171+
calling :meth:`writeframes` with all of the frame data to be
172+
written. In the latter case :meth:`writeframes` will calculate
173+
the number of frames in the data and set *nframes* accordingly before writing
174+
the frame data.
171175

172-
.. method:: Wave_write.close()
176+
Wave_write objects have the following methods:
173177

174-
Make sure *nframes* is correct, and close the file if it was opened by
175-
:mod:`wave`. This method is called upon object collection. It will raise
176-
an exception if the output stream is not seekable and *nframes* does not
177-
match the number of frames actually written.
178+
.. versionchanged:: 3.4
179+
Added support for unseekable files.
178180

179181

180-
.. method:: Wave_write.setnchannels(n)
182+
.. method:: close()
181183

182-
Set the number of channels.
184+
Make sure *nframes* is correct, and close the file if it was opened by
185+
:mod:`wave`. This method is called upon object collection. It will raise
186+
an exception if the output stream is not seekable and *nframes* does not
187+
match the number of frames actually written.
183188

184189

185-
.. method:: Wave_write.setsampwidth(n)
190+
.. method:: setnchannels(n)
186191

187-
Set the sample width to *n* bytes.
192+
Set the number of channels.
188193

189194

190-
.. method:: Wave_write.setframerate(n)
195+
.. method:: setsampwidth(n)
191196

192-
Set the frame rate to *n*.
197+
Set the sample width to *n* bytes.
193198

194-
.. versionchanged:: 3.2
195-
A non-integral input to this method is rounded to the nearest
196-
integer.
197199

200+
.. method:: setframerate(n)
198201

199-
.. method:: Wave_write.setnframes(n)
202+
Set the frame rate to *n*.
200203

201-
Set the number of frames to *n*. This will be changed later if the number
202-
of frames actually written is different (this update attempt will
203-
raise an error if the output stream is not seekable).
204+
.. versionchanged:: 3.2
205+
A non-integral input to this method is rounded to the nearest
206+
integer.
204207

205208

206-
.. method:: Wave_write.setcomptype(type, name)
209+
.. method:: setnframes(n)
207210

208-
Set the compression type and description. At the moment, only compression type
209-
``NONE`` is supported, meaning no compression.
211+
Set the number of frames to *n*. This will be changed later if the number
212+
of frames actually written is different (this update attempt will
213+
raise an error if the output stream is not seekable).
210214

211215

212-
.. method:: Wave_write.setparams(tuple)
216+
.. method:: setcomptype(type, name)
213217

214-
The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
215-
compname)``, with values valid for the :meth:`set\*` methods. Sets all
216-
parameters.
218+
Set the compression type and description. At the moment, only compression type
219+
``NONE`` is supported, meaning no compression.
217220

218221

219-
.. method:: Wave_write.tell()
222+
.. method:: setparams(tuple)
220223

221-
Return current position in the file, with the same disclaimer for the
222-
:meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
224+
The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
225+
compname)``, with values valid for the :meth:`set\*` methods. Sets all
226+
parameters.
223227

224228

225-
.. method:: Wave_write.writeframesraw(data)
229+
.. method:: tell()
226230

227-
Write audio frames, without correcting *nframes*.
231+
Return current position in the file, with the same disclaimer for the
232+
:meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
228233

229-
.. versionchanged:: 3.4
230-
Any :term:`bytes-like object` is now accepted.
231234

235+
.. method:: writeframesraw(data)
232236

233-
.. method:: Wave_write.writeframes(data)
237+
Write audio frames, without correcting *nframes*.
234238

235-
Write audio frames and make sure *nframes* is correct. It will raise an
236-
error if the output stream is not seekable and the total number of frames
237-
that have been written after *data* has been written does not match the
238-
previously set value for *nframes*.
239+
.. versionchanged:: 3.4
240+
Any :term:`bytes-like object` is now accepted.
239241

240-
.. versionchanged:: 3.4
241-
Any :term:`bytes-like object` is now accepted.
242242

243+
.. method:: writeframes(data)
244+
245+
Write audio frames and make sure *nframes* is correct. It will raise an
246+
error if the output stream is not seekable and the total number of frames
247+
that have been written after *data* has been written does not match the
248+
previously set value for *nframes*.
243249

244-
Note that it is invalid to set any parameters after calling :meth:`writeframes`
245-
or :meth:`writeframesraw`, and any attempt to do so will raise
246-
:exc:`wave.Error`.
250+
.. versionchanged:: 3.4
251+
Any :term:`bytes-like object` is now accepted.
247252

253+
Note that it is invalid to set any parameters after calling :meth:`writeframes`
254+
or :meth:`writeframesraw`, and any attempt to do so will raise
255+
:exc:`wave.Error`.

‎Lib/wave.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ class Error(Exception):
9292
_wave_params = namedtuple('_wave_params',
9393
'nchannels sampwidth framerate nframes comptype compname')
9494

95+
9596
def _byteswap(data, width):
9697
swapped_data = bytearray(len(data))
9798

@@ -104,7 +105,6 @@ def _byteswap(data, width):
104105

105106
class _Chunk:
106107
def __init__(self, file, align=True, bigendian=True, inclheader=False):
107-
import struct
108108
self.closed = False
109109
self.align = align # whether to align to word (2-byte) boundaries
110110
if bigendian:
@@ -214,7 +214,6 @@ def skip(self):
214214
raise EOFError
215215

216216

217-
218217
class Wave_read:
219218
"""Variables used in this class:
220219
@@ -411,6 +410,7 @@ def _read_fmt_chunk(self, chunk):
411410
self._comptype = 'NONE'
412411
self._compname = 'not compressed'
413412

413+
414414
class Wave_write:
415415
"""Variables used in this class:
416416
@@ -638,6 +638,7 @@ def _patchheader(self):
638638
self._file.seek(curpos, 0)
639639
self._datalength = self._datawritten
640640

641+
641642
def open(f, mode=None):
642643
if mode is None:
643644
if hasattr(f, 'mode'):

0 commit comments

Comments
 (0)