Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 01b42f9

Browse filesBrowse files
vstinnervstinner
authored
[3.12] gh-105096: Reformat wave documentation (#105136) (#105138)
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 85e5d03)
1 parent c687946 commit 01b42f9
Copy full SHA for 01b42f9

File tree

3 files changed

+109
-102
lines changed
Filter options

3 files changed

+109
-102
lines changed

‎Doc/library/wave.rst

Copy file name to clipboardExpand all lines: Doc/library/wave.rst
+106-99Lines changed: 106 additions & 99 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

@@ -41,13 +42,12 @@ The :mod:`wave` module defines the following function and exception:
4142
value for *mode*.
4243

4344
If you pass in a file-like object, the wave object will not close it when its
44-
:meth:`close` method is called; it is the caller's responsibility to close
45+
``close()`` method is called; it is the caller's responsibility to close
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,192 @@ 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+
``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 :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 :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+
.. versionchanged:: 3.4
177+
Added support for unseekable files.
173178

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.
179+
Wave_write objects have the following methods:
178180

181+
.. method:: close()
179182

180-
.. method:: Wave_write.setnchannels(n)
183+
Make sure *nframes* is correct, and close the file if it was opened by
184+
:mod:`wave`. This method is called upon object collection. It will raise
185+
an exception if the output stream is not seekable and *nframes* does not
186+
match the number of frames actually written.
181187

182-
Set the number of channels.
183188

189+
.. method:: setnchannels(n)
184190

185-
.. method:: Wave_write.setsampwidth(n)
191+
Set the number of channels.
186192

187-
Set the sample width to *n* bytes.
188193

194+
.. method:: setsampwidth(n)
189195

190-
.. method:: Wave_write.setframerate(n)
196+
Set the sample width to *n* bytes.
191197

192-
Set the frame rate to *n*.
193198

194-
.. versionchanged:: 3.2
195-
A non-integral input to this method is rounded to the nearest
196-
integer.
199+
.. method:: setframerate(n)
197200

201+
Set the frame rate to *n*.
198202

199-
.. method:: Wave_write.setnframes(n)
203+
.. versionchanged:: 3.2
204+
A non-integral input to this method is rounded to the nearest
205+
integer.
200206

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).
204207

208+
.. method:: setnframes(n)
205209

206-
.. method:: Wave_write.setcomptype(type, name)
210+
Set the number of frames to *n*. This will be changed later if the number
211+
of frames actually written is different (this update attempt will
212+
raise an error if the output stream is not seekable).
207213

208-
Set the compression type and description. At the moment, only compression type
209-
``NONE`` is supported, meaning no compression.
210214

215+
.. method:: setcomptype(type, name)
211216

212-
.. method:: Wave_write.setparams(tuple)
217+
Set the compression type and description. At the moment, only compression type
218+
``NONE`` is supported, meaning no compression.
213219

214-
The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
215-
compname)``, with values valid for the :meth:`set\*` methods. Sets all
216-
parameters.
217220

221+
.. method:: setparams(tuple)
218222

219-
.. method:: Wave_write.tell()
223+
The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
224+
compname)``, with values valid for the ``set*()`` methods. Sets all
225+
parameters.
220226

221-
Return current position in the file, with the same disclaimer for the
222-
:meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
223227

228+
.. method:: tell()
224229

225-
.. method:: Wave_write.writeframesraw(data)
230+
Return current position in the file, with the same disclaimer for the
231+
:meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
226232

227-
Write audio frames, without correcting *nframes*.
228233

229-
.. versionchanged:: 3.4
230-
Any :term:`bytes-like object` is now accepted.
234+
.. method:: writeframesraw(data)
231235

236+
Write audio frames, without correcting *nframes*.
232237

233-
.. method:: Wave_write.writeframes(data)
238+
.. versionchanged:: 3.4
239+
Any :term:`bytes-like object` is now accepted.
234240

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*.
239241

240-
.. versionchanged:: 3.4
241-
Any :term:`bytes-like object` is now accepted.
242+
.. method:: writeframes(data)
242243

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

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`.
249+
.. versionchanged:: 3.4
250+
Any :term:`bytes-like object` is now accepted.
247251

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

‎Doc/tools/.nitignore

Copy file name to clipboardExpand all lines: Doc/tools/.nitignore
-1Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,6 @@ Doc/library/urllib.error.rst
236236
Doc/library/urllib.parse.rst
237237
Doc/library/urllib.request.rst
238238
Doc/library/uuid.rst
239-
Doc/library/wave.rst
240239
Doc/library/weakref.rst
241240
Doc/library/webbrowser.rst
242241
Doc/library/winreg.rst

‎Lib/wave.py

Copy file name to clipboardExpand all lines: Lib/wave.py
+3-2Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.