From 4487dd0ed5482d619279aa45099a22d0abc9615d Mon Sep 17 00:00:00 2001
From: R David Murray <rdmurray@bitdance.com>
Date: Thu, 9 Oct 2014 16:59:30 -0400
Subject: #18615: Make sndhdr return namedtuples.

Patch by Claudiu Popa.
---
 Doc/library/sndhdr.rst  | 15 +++++++++++----
 Doc/whatsnew/3.5.rst    |  7 +++++++
 Lib/sndhdr.py           |  7 ++++++-
 Lib/test/test_sndhdr.py | 13 +++++++++++++
 Misc/NEWS               |  2 ++
 5 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/Doc/library/sndhdr.rst b/Doc/library/sndhdr.rst
index f36df68..f8b5d8b 100644
--- 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 b40a6f3..feca241 100644
--- 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 240e507..e5901ec 100644
--- 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 5e0abe0..361f70f 100644
--- 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 08de202..21ee7b2 100644
--- 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.
 
-- 
cgit v0.12