wave: rename encoding API to format

'format' is the term used in the wave audio specification

Author: mbeijen

Lib/test/audiotests.py

@@ -27,14 +27,14 @@ def tearDown(self):
         unlink(TESTFN)
 
     def check_params(self, f, nchannels, sampwidth, framerate, nframes,
-                     comptype, compname, encoding):
+                     comptype, compname, format):
         self.assertEqual(f.getnchannels(), nchannels)
         self.assertEqual(f.getsampwidth(), sampwidth)
         self.assertEqual(f.getframerate(), framerate)
         self.assertEqual(f.getnframes(), nframes)
         self.assertEqual(f.getcomptype(), comptype)
         self.assertEqual(f.getcompname(), compname)
-        self.assertEqual(f.getencoding(), encoding)
+        self.assertEqual(f.getformat(), format)
 
         params = f.getparams()
         self.assertEqual(params,
@@ -62,7 +62,7 @@ def create_file(self, testfile):
         f.setsampwidth(self.sampwidth)
         f.setframerate(self.framerate)
         f.setcomptype(self.comptype, self.compname)
-        f.setencoding(self.encoding)
+        f.setformat(self.format)
         return f
 
     def check_file(self, testfile, nframes, frames):
@@ -72,14 +72,14 @@ def check_file(self, testfile, nframes, frames):
             self.assertEqual(f.getframerate(), self.framerate)
             self.assertEqual(f.getnframes(), nframes)
             self.assertEqual(f.readframes(nframes), frames)
-            self.assertEqual(f.getencoding(), self.encoding)
+            self.assertEqual(f.getformat(), self.format)
 
     def test_write_params(self):
         f = self.create_file(TESTFN)
         f.setnframes(self.nframes)
         f.writeframes(self.frames)
         self.check_params(f, self.nchannels, self.sampwidth, self.framerate,
-                          self.nframes, self.comptype, self.compname, self.encoding)
+                          self.nframes, self.comptype, self.compname, self.format)
         f.close()
 
     def test_write_context_manager_calls_close(self):
@@ -263,7 +263,7 @@ def test_read_params(self):
         f = self.f = self.module.open(self.sndfilepath)
         #self.assertEqual(f.getfp().name, self.sndfilepath)
         self.check_params(f, self.nchannels, self.sampwidth, self.framerate,
-                          self.sndfilenframes, self.comptype, self.compname, self.encoding)
+                          self.sndfilenframes, self.comptype, self.compname, self.format)
 
     def test_close(self):
         with open(self.sndfilepath, 'rb') as testfile:

Lib/test/test_wave.py

@@ -1,7 +1,7 @@
 import unittest
 from test import audiotests
 from test import support
-from test.support.os_helper import FakePath
+from test.support.os_helper import FakePath, unlink
 import io
 import os
 import struct
@@ -22,7 +22,7 @@ class WavePCM8Test(WaveTest, unittest.TestCase):
     sampwidth = 1
     framerate = 11025
     nframes = 48
-    encoding = wave.WAVE_FORMAT_PCM
+    format = wave.WAVE_FORMAT_PCM
     comptype = 'NONE'
     compname = 'not compressed'
     frames = bytes.fromhex("""\
@@ -40,7 +40,7 @@ class WavePCM16Test(WaveTest, unittest.TestCase):
     sampwidth = 2
     framerate = 11025
     nframes = 48
-    encoding = wave.WAVE_FORMAT_PCM
+    format = wave.WAVE_FORMAT_PCM
     comptype = 'NONE'
     compname = 'not compressed'
     frames = bytes.fromhex("""\
@@ -62,7 +62,7 @@ class WavePCM24Test(WaveTest, unittest.TestCase):
     sampwidth = 3
     framerate = 11025
     nframes = 48
-    encoding = wave.WAVE_FORMAT_PCM
+    format = wave.WAVE_FORMAT_PCM
     comptype = 'NONE'
     compname = 'not compressed'
     frames = bytes.fromhex("""\
@@ -90,7 +90,7 @@ class WavePCM24ExtTest(WaveTest, unittest.TestCase):
     sampwidth = 3
     framerate = 11025
     nframes = 48
-    encoding = wave.WAVE_FORMAT_EXTENSIBLE
+    format = wave.WAVE_FORMAT_EXTENSIBLE
     readonly = True  # Writing EXTENSIBLE wave format is not supported.
     comptype = 'NONE'
     compname = 'not compressed'
@@ -119,7 +119,7 @@ class WavePCM32Test(WaveTest, unittest.TestCase):
     sampwidth = 4
     framerate = 11025
     nframes = 48
-    encoding = wave.WAVE_FORMAT_PCM
+    format = wave.WAVE_FORMAT_PCM
     comptype = 'NONE'
     compname = 'not compressed'
     frames = bytes.fromhex("""\
@@ -147,7 +147,7 @@ class WaveIeeeFloatingPointTest(WaveTest, unittest.TestCase):
     sampwidth = 4
     framerate = 11025
     nframes = 48
-    encoding = wave.WAVE_FORMAT_IEEE_FLOAT
+    format = wave.WAVE_FORMAT_IEEE_FLOAT
     comptype = 'NONE'
     compname = 'not compressed'
     frames = bytes.fromhex("""\
@@ -173,6 +173,26 @@ def test__all__(self):
 
 class WaveLowLevelTest(unittest.TestCase):
 
+    def test_getformat_setformat(self):
+        with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
+            filename = fp.name
+        self.addCleanup(unlink, filename)
+
+        with wave.open(filename, 'wb') as w:
+            w.setnchannels(1)
+            w.setsampwidth(2)
+            w.setframerate(22050)
+            self.assertEqual(w.getformat(), wave.WAVE_FORMAT_PCM)
+            w.setformat(wave.WAVE_FORMAT_IEEE_FLOAT)
+            self.assertEqual(w.getformat(), wave.WAVE_FORMAT_IEEE_FLOAT)
+
+    def test_read_getformat(self):
+        b = b'RIFF' + struct.pack('<L', 36) + b'WAVE'
+        b += b'fmt ' + struct.pack('<LHHLLHH', 16, 1, 1, 11025, 11025, 1, 8)
+        b += b'data' + struct.pack('<L', 0)
+        with wave.open(io.BytesIO(b), 'rb') as r:
+            self.assertEqual(r.getformat(), wave.WAVE_FORMAT_PCM)
+
     def test_read_no_chunks(self):
         b = b'SPAM'
         with self.assertRaises(EOFError):

Lib/wave.py

@@ -15,7 +15,7 @@
       getsampwidth()  -- returns sample width in bytes
       getframerate()  -- returns sampling frequency
       getnframes()    -- returns number of audio frames
-      getencoding()   -- returns frame encoding (WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT
+      getformat()     -- returns frame encoding (WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT
                          or WAVE_FORMAT_EXTENSIBLE)
       getcomptype()   -- returns compression type ('NONE' for linear samples)
       getcompname()   -- returns human-readable version of
@@ -44,8 +44,8 @@
       setsampwidth(n) -- set the sample width
       setframerate(n) -- set the frame rate
       setnframes(n)   -- set the number of frames
-      setencoding(encoding)
-                      -- set the frame encoding. Only WAVE_FORMAT_PCM,
+      setformat(format)
+                      -- set the frame format. Only WAVE_FORMAT_PCM and
                          WAVE_FORMAT_IEEE_FLOAT are supported.
       setcomptype(type, name)
                       -- set the compression type and the
@@ -232,10 +232,10 @@ class Wave_read:
               available through the getsampwidth() method
     _framerate -- the sampling frequency
               available through the getframerate() method
-    _encoding -- frame encoding
+    _format -- frame format
               One of WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT
               or WAVE_FORMAT_EXTENSIBLE available through
-              getencoding() method
+              getformat() method
     _comptype -- the AIFF-C compression type ('NONE' if AIFF)
               available through the getcomptype() method
     _compname -- the human-readable AIFF-C compression type
@@ -337,6 +337,9 @@ def getsampwidth(self):
     def getframerate(self):
         return self._framerate
 
+    def getformat(self):
+        return self._format
+
     def getcomptype(self):
         return self._comptype
 
@@ -348,9 +351,6 @@ def getparams(self):
                        self.getframerate(), self.getnframes(),
                        self.getcomptype(), self.getcompname())
 
-    def getencoding(self):
-        return self._encoding
-
     def setpos(self, pos):
         if pos < 0 or pos > self._nframes:
             raise Error('position not in range')
@@ -380,16 +380,16 @@ def readframes(self, nframes):
 
     def _read_fmt_chunk(self, chunk):
         try:
-            self._encoding, self._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._encoding not in (WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT, WAVE_FORMAT_EXTENSIBLE):
-            raise Error('unknown format: %r' % (self._encoding,))
+        if self._format not in (WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT, WAVE_FORMAT_EXTENSIBLE):
+            raise Error('unknown format: %r' % (self._format,))
         try:
             sampwidth = struct.unpack_from('<H', chunk.read(2))[0]
         except struct.error:
             raise EOFError from None
-        if self._encoding == WAVE_FORMAT_EXTENSIBLE:
+        if self._format == WAVE_FORMAT_EXTENSIBLE:
             try:
                 cbSize, wValidBitsPerSample, dwChannelMask = struct.unpack_from('<HHL', chunk.read(8))
                 # Read the entire UUID from the chunk
@@ -432,8 +432,8 @@ class Wave_write:
               set through the setsampwidth() or setparams() method
     _framerate -- the sampling frequency
               set through the setframerate() or setparams() method
-    _encoding -- frame encoding
-              set through setencoding() method
+    _format -- frame format
+              set through setformat() method
     _nframes -- the number of audio frames written to the header
               set through the setnframes() or setparams() method
 
@@ -461,7 +461,7 @@ def initfp(self, file):
         self._file = file
         self._convert = None
         self._nchannels = 0
-        self._encoding = WAVE_FORMAT_PCM
+        self._format = WAVE_FORMAT_PCM
         self._sampwidth = 0
         self._framerate = 0
         self._nframes = 0
@@ -534,15 +534,15 @@ def setcomptype(self, comptype, compname):
         self._comptype = comptype
         self._compname = compname
 
-    def setencoding(self, encoding):
+    def setformat(self, format):
         if self._datawritten:
             raise Error('cannot change parameters after starting to write')
-        if encoding not in (WAVE_FORMAT_IEEE_FLOAT, WAVE_FORMAT_PCM):
+        if format not in (WAVE_FORMAT_IEEE_FLOAT, WAVE_FORMAT_PCM):
             raise Error('unsupported wave format')
-        self._encoding = encoding
+        self._format = format
 
-    def getencoding(self):
-        return self._encoding
+    def getformat(self):
+        return self._format
 
     def getcomptype(self):
         return self._comptype
@@ -627,7 +627,7 @@ def _write_header(self, initlength):
             self._form_length_pos = None
         self._file.write(struct.pack('<L4s4sLHHLLHH4s',
             36 + self._datalength, b'WAVE', b'fmt ', 16,
-            self._encoding, self._nchannels, self._framerate,
+            self._format, self._nchannels, self._framerate,
             self._nchannels * self._framerate * self._sampwidth,
             self._nchannels * self._sampwidth,
             self._sampwidth * 8, b'data'))