#18615: Make sndhdr return namedtuples.

Patch by Claudiu Popa.

diff --git a/Doc/library/sndhdr.rst b/Doc/library/sndhdr.rst
index f36df68703474524877fa9a7c961fdf05b6925be..f8b5d8b2460ccbc42cd86e54752e436db28780a6 100644 (file)
--- a/Doc/library/sndhdr.rst
+++ b/Doc/library/sndhdr.rst
@@ -16,8 +16,9 @@
 
 The :mod:`sndhdr` provides utility functions which attempt to determine the type
 of sound data which is in a file.  When these functions are able to determine
-what type of sound data is stored in a file, they return a tuple ``(type,
-sampling_rate, channels, frames, bits_per_sample)``.  The value for *type*
+what type of sound data is stored in a file, they return a
+:func:`~collections.namedtuple`, containing five attributes: (``filetype``,
+``framerate``, ``nchannels``, ``nframes``, ``sampwidth``). The value for *type*
 indicates the data type and will be one of the strings ``'aifc'``, ``'aiff'``,
 ``'au'``, ``'hcom'``, ``'sndr'``, ``'sndt'``, ``'voc'``, ``'wav'``, ``'8svx'``,
 ``'sb'``, ``'ub'``, or ``'ul'``.  The *sampling_rate* will be either the actual
@@ -31,13 +32,19 @@ be the sample size in bits or ``'A'`` for A-LAW or ``'U'`` for u-LAW.
 .. function:: what(filename)
 
    Determines the type of sound data stored in the file *filename* using
-   :func:`whathdr`.  If it succeeds, returns a tuple as described above, otherwise
+   :func:`whathdr`.  If it succeeds, returns a namedtuple as described above, otherwise
    ``None`` is returned.
 
+   .. versionchanged:: 3.5
+      Result changed from a tuple to a namedtuple.
+
 
 .. function:: whathdr(filename)
 
    Determines the type of sound data stored in a file based on the file  header.
-   The name of the file is given by *filename*.  This function returns a tuple as
+   The name of the file is given by *filename*.  This function returns a namedtuple as
    described above on success, or ``None``.
 
+   .. versionchanged:: 3.5
+      Result changed from a tuple to a namedtuple.
+

diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index b40a6f3b8651d86cea31c71d7c6a3b8c5cc622e7..feca241cf0ac28d78afd65f5f739e556916ec541 100644 (file)
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -264,6 +264,13 @@ smtplib
   implement custom authentication mechanisms (contributed by Milan Oberkirch in
   :issue:`15014`).
 
+sndhdr
+------
+
+* :func:`~sndhdr.what` and :func:`~sndhdr.whathdr` now return
+  :func:`~collections.namedtuple` \s (contributed by Claudiu Popa in
+  :issue:`18615`).
+
 socket
 ------
 

diff --git a/Lib/sndhdr.py b/Lib/sndhdr.py
index 240e5072f8fdf383279c98905ecbe7816f3dee0e..e5901ec58338aaae1ed33d56573b4ca0ecc0cfa1 100644 (file)
--- a/Lib/sndhdr.py
+++ b/Lib/sndhdr.py
@@ -32,6 +32,11 @@ explicitly given directories.
 
 __all__ = ['what', 'whathdr']
 
+from collections import namedtuple
+
+SndHeaders = namedtuple('SndHeaders',
+                        'filetype framerate nchannels nframes sampwidth')
+
 def what(filename):
     """Guess the type of a sound file."""
     res = whathdr(filename)
@@ -45,7 +50,7 @@ def whathdr(filename):
         for tf in tests:
             res = tf(h, f)
             if res:
-                return res
+                return SndHeaders(*res)
         return None
 
 

diff --git a/Lib/test/test_sndhdr.py b/Lib/test/test_sndhdr.py
index 5e0abe0b363d80df975450739384e2531eab0c55..361f70f8889c63df177a64a75fbe078e6aa1fca8 100644 (file)
--- a/Lib/test/test_sndhdr.py
+++ b/Lib/test/test_sndhdr.py
@@ -1,4 +1,5 @@
 import sndhdr
+import pickle
 import unittest
 from test.support import findfile
 
@@ -18,6 +19,18 @@ class TestFormats(unittest.TestCase):
             what = sndhdr.what(filename)
             self.assertNotEqual(what, None, filename)
             self.assertSequenceEqual(what, expected)
+            self.assertEqual(what.filetype, expected[0])
+            self.assertEqual(what.framerate, expected[1])
+            self.assertEqual(what.nchannels, expected[2])
+            self.assertEqual(what.nframes, expected[3])
+            self.assertEqual(what.sampwidth, expected[4])
+
+    def test_pickleable(self):
+        filename = findfile('sndhdr.aifc', subdir="sndhdrdata")
+        what = sndhdr.what(filename)
+        dump = pickle.dumps(what)
+        self.assertEqual(pickle.loads(dump), what)
+
 
 if __name__ == '__main__':
     unittest.main()

diff --git a/Misc/NEWS b/Misc/NEWS
index 08de2029aa3983464ce9f79f24240f6379f58d47..21ee7b2cbf1c520a7ae0e5d35bad81fb177d3f5b 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -166,6 +166,8 @@ Core and Builtins
 Library
 -------
 
+- Issue $18615: sndhdr.what/whathdr now return a namedtuple.
+
 - Issue #22462: Fix pyexpat's creation of a dummy frame to make it
   appear in exception tracebacks.