gh-149306: Improve error messages in wave module to include the offending value

Include the offending value in wave.Error messages raised by
Wave_read._read_fmt_chunk and Wave_write setters (setnchannels,
setsampwidth, setframerate). For setframerate, the original value is
shown rather than the rounded one to aid debugging.

Author: htjworld

Lib/test/test_wave.py

@@ -4,6 +4,7 @@
 from test.support.os_helper import FakePath, unlink
 import io
 import os
+import re
 import struct
 import tempfile
 import sys
@@ -323,14 +324,14 @@ def test_read_wrong_number_of_channels(self):
         b = b'RIFF' + struct.pack('<L', 36) + b'WAVE'
         b += b'fmt ' + struct.pack('<LHHLLHH', 16, 1, 0, 11025, 11025, 1, 8)
         b += b'data' + struct.pack('<L', 0)
-        with self.assertRaisesRegex(wave.Error, 'bad # of channels'):
+        with self.assertRaisesRegex(wave.Error, 'bad # of channels: 0'):
             wave.open(io.BytesIO(b))
 
     def test_read_wrong_sample_width(self):
         b = b'RIFF' + struct.pack('<L', 36) + b'WAVE'
         b += b'fmt ' + struct.pack('<LHHLLHH', 16, 1, 1, 11025, 11025, 1, 0)
         b += b'data' + struct.pack('<L', 0)
-        with self.assertRaisesRegex(wave.Error, 'bad sample width'):
+        with self.assertRaisesRegex(wave.Error, 'bad sample width: 0'):
             wave.open(io.BytesIO(b))
 
     def test_open_in_write_raises(self):
@@ -430,6 +431,36 @@ def test_setframerate_rounds(self, arg, expected):
             f.setframerate(arg)
             self.assertEqual(f.getframerate(), expected)
 
+    @support.subTests('nchannels', (0, -1))
+    def test_setnchannels_error_includes_value(self, nchannels):
+        with wave.open(io.BytesIO(), 'wb') as f:
+            with self.assertRaisesRegex(wave.Error,
+                                        re.escape(f'bad # of channels: {nchannels!r}')):
+                f.setnchannels(nchannels)
+            with self.assertRaises(wave.Error):
+                f.close()
+
+    @support.subTests('sampwidth', (0, 5))
+    def test_setsampwidth_error_includes_value(self, sampwidth):
+        with wave.open(io.BytesIO(), 'wb') as f:
+            f.setnchannels(1)
+            with self.assertRaisesRegex(wave.Error,
+                                        re.escape(f'bad sample width: {sampwidth!r}')):
+                f.setsampwidth(sampwidth)
+            with self.assertRaises(wave.Error):
+                f.close()
+
+    @support.subTests('arg', (-1, 0, 0.4))
+    def test_setframerate_error_includes_value(self, arg):
+        with wave.open(io.BytesIO(), 'wb') as f:
+            f.setnchannels(1)
+            f.setsampwidth(2)
+            with self.assertRaisesRegex(wave.Error,
+                                        re.escape(f'bad frame rate: {arg!r}')):
+                f.setframerate(arg)
+            with self.assertRaises(wave.Error):
+                f.close()
+
     def test_write_odd_data_chunk_pads_and_updates_riff_size(self):
         # gh-117716: odd-sized data chunks must be padded with one zero byte.
         with io.BytesIO() as output:

Lib/wave.py

@@ -388,7 +388,7 @@ def readframes(self, nframes):
 
     def _read_fmt_chunk(self, chunk):
         try:
-            self._format, self._nchannels, self._framerate, dwAvgBytesPerSec, wBlockAlign = struct.unpack_from('<HHLLH', chunk.read(14))
+            self._format, nchannels, self._framerate, dwAvgBytesPerSec, wBlockAlign = struct.unpack_from('<HHLLH', chunk.read(14))
         except struct.error:
             raise EOFError from None
         if self._format not in (WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT, WAVE_FORMAT_EXTENSIBLE):
@@ -415,9 +415,10 @@ def _read_fmt_chunk(self, chunk):
                 raise Error(subformat_msg)
         self._sampwidth = (sampwidth + 7) // 8
         if not self._sampwidth:
-            raise Error('bad sample width')
-        if not self._nchannels:
-            raise Error('bad # of channels')
+            raise Error(f'bad sample width: {sampwidth!r}')
+        if not nchannels:
+            raise Error(f'bad # of channels: {nchannels!r}')
+        self._nchannels = nchannels
         self._framesize = self._nchannels * self._sampwidth
         self._comptype = 'NONE'
         self._compname = 'not compressed'
@@ -495,7 +496,7 @@ def setnchannels(self, nchannels):
         if self._datawritten:
             raise Error('cannot change parameters after starting to write')
         if nchannels < 1:
-            raise Error('bad # of channels')
+            raise Error(f'bad # of channels: {nchannels!r}')
         self._nchannels = nchannels
 
     def getnchannels(self):
@@ -510,7 +511,7 @@ def setsampwidth(self, sampwidth):
             if sampwidth not in (4, 8):
                 raise Error('unsupported sample width for IEEE float format')
         elif sampwidth < 1 or sampwidth > 4:
-            raise Error('bad sample width')
+            raise Error(f'bad sample width: {sampwidth!r}')
         self._sampwidth = sampwidth
 
     def getsampwidth(self):
@@ -521,10 +522,10 @@ def getsampwidth(self):
     def setframerate(self, framerate):
         if self._datawritten:
             raise Error('cannot change parameters after starting to write')
-        framerate = int(round(framerate))
-        if framerate <= 0:
-            raise Error('bad frame rate')
-        self._framerate = framerate
+        rounded = int(round(framerate))
+        if rounded <= 0:
+            raise Error(f'bad frame rate: {framerate!r}')
+        self._framerate = rounded
 
     def getframerate(self):
         if not self._framerate:

Misc/NEWS.d/next/Library/2026-05-03-11-09-48.gh-issue-149306.jvi7uE.rst

@@ -0,0 +1,2 @@
+Error messages in :mod:`wave` for invalid channel count, sample width, and
+frame rate now include the offending value.