From d1ba7081e2f5e997fd94fc4fb89a21448c876fe5 Mon Sep 17 00:00:00 2001
From: htjworld <116538001+htjworld@users.noreply.github.com>
Date: Sun, 3 May 2026 11:10:03 +0900
Subject: [PATCH 1/2] 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.
---
 Lib/test/test_wave.py                         | 35 +++++++++++++++++--
 Lib/wave.py                                   | 21 +++++------
 ...-05-03-11-09-48.gh-issue-149306.jvi7uE.rst |  2 ++
 3 files changed, 46 insertions(+), 12 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2026-05-03-11-09-48.gh-issue-149306.jvi7uE.rst

diff --git a/Lib/test/test_wave.py b/Lib/test/test_wave.py
index d3723c04820d9d..9ad8f6862acaa2 100644
--- a/Lib/test/test_wave.py
+++ b/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:
diff --git a/Lib/wave.py b/Lib/wave.py
index c4e1a493a7ec7f..b0f58179eb34a7 100644
--- a/Lib/wave.py
+++ b/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:
diff --git a/Misc/NEWS.d/next/Library/2026-05-03-11-09-48.gh-issue-149306.jvi7uE.rst b/Misc/NEWS.d/next/Library/2026-05-03-11-09-48.gh-issue-149306.jvi7uE.rst
new file mode 100644
index 00000000000000..cff46aa60d0ff7
--- /dev/null
+++ b/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.

From 2d4c5e43537292b5cb02ecb7e7f878a7e8deb868 Mon Sep 17 00:00:00 2001
From: htjworld <116538001+htjworld@users.noreply.github.com>
Date: Sun, 3 May 2026 21:01:29 +0900
Subject: [PATCH 2/2] Address review: revert _read_fmt_chunk unpack, rename
 rounded_framerate, extract test messages

---
 Lib/test/test_wave.py | 12 ++++++------
 Lib/wave.py           | 13 ++++++-------
 2 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/Lib/test/test_wave.py b/Lib/test/test_wave.py
index 9ad8f6862acaa2..9067eb9c7d9f18 100644
--- a/Lib/test/test_wave.py
+++ b/Lib/test/test_wave.py
@@ -433,30 +433,30 @@ def test_setframerate_rounds(self, arg, expected):
 
     @support.subTests('nchannels', (0, -1))
     def test_setnchannels_error_includes_value(self, nchannels):
+        msg = re.escape(f'bad # of channels: {nchannels!r}')
         with wave.open(io.BytesIO(), 'wb') as f:
-            with self.assertRaisesRegex(wave.Error,
-                                        re.escape(f'bad # of channels: {nchannels!r}')):
+            with self.assertRaisesRegex(wave.Error, msg):
                 f.setnchannels(nchannels)
             with self.assertRaises(wave.Error):
                 f.close()
 
     @support.subTests('sampwidth', (0, 5))
     def test_setsampwidth_error_includes_value(self, sampwidth):
+        msg = re.escape(f'bad sample width: {sampwidth!r}')
         with wave.open(io.BytesIO(), 'wb') as f:
             f.setnchannels(1)
-            with self.assertRaisesRegex(wave.Error,
-                                        re.escape(f'bad sample width: {sampwidth!r}')):
+            with self.assertRaisesRegex(wave.Error, msg):
                 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):
+        msg = re.escape(f'bad frame rate: {arg!r}')
         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}')):
+            with self.assertRaisesRegex(wave.Error, msg):
                 f.setframerate(arg)
             with self.assertRaises(wave.Error):
                 f.close()
diff --git a/Lib/wave.py b/Lib/wave.py
index b0f58179eb34a7..961f3efb3dd8db 100644
--- a/Lib/wave.py
+++ b/Lib/wave.py
@@ -388,7 +388,7 @@ def readframes(self, nframes):
 
     def _read_fmt_chunk(self, chunk):
         try:
-            self._format, nchannels, self._framerate, dwAvgBytesPerSec, wBlockAlign = struct.unpack_from('<HHLLH', chunk.read(14))
+            self._format, self._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):
@@ -416,9 +416,8 @@ def _read_fmt_chunk(self, chunk):
         self._sampwidth = (sampwidth + 7) // 8
         if not self._sampwidth:
             raise Error(f'bad sample width: {sampwidth!r}')
-        if not nchannels:
-            raise Error(f'bad # of channels: {nchannels!r}')
-        self._nchannels = nchannels
+        if not self._nchannels:
+            raise Error(f'bad # of channels: {self._nchannels!r}')
         self._framesize = self._nchannels * self._sampwidth
         self._comptype = 'NONE'
         self._compname = 'not compressed'
@@ -522,10 +521,10 @@ def getsampwidth(self):
     def setframerate(self, framerate):
         if self._datawritten:
             raise Error('cannot change parameters after starting to write')
-        rounded = int(round(framerate))
-        if rounded <= 0:
+        rounded_framerate = int(round(framerate))
+        if rounded_framerate <= 0:
             raise Error(f'bad frame rate: {framerate!r}')
-        self._framerate = rounded
+        self._framerate = rounded_framerate
 
     def getframerate(self):
         if not self._framerate: