changeset:   92895:ef72142eb8a2
user:        R David Murray <rdmurray@bitdance.com>
date:        Thu Oct 09 16:59:30 2014 -0400
files:       Doc/library/sndhdr.rst Doc/whatsnew/3.5.rst Lib/sndhdr.py Lib/test/test_sndhdr.py Misc/NEWS
description:
#18615: Make sndhdr return namedtuples.

Patch by Claudiu Popa.


diff -r 54ef5af2e919 -r ef72142eb8a2 Doc/library/sndhdr.rst
--- a/Doc/library/sndhdr.rst	Thu Oct 09 22:16:15 2014 +0200
+++ b/Doc/library/sndhdr.rst	Thu Oct 09 16:59:30 2014 -0400
@@ -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 @@
 .. 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 -r 54ef5af2e919 -r ef72142eb8a2 Doc/whatsnew/3.5.rst
--- a/Doc/whatsnew/3.5.rst	Thu Oct 09 22:16:15 2014 +0200
+++ b/Doc/whatsnew/3.5.rst	Thu Oct 09 16:59:30 2014 -0400
@@ -264,6 +264,13 @@
   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 -r 54ef5af2e919 -r ef72142eb8a2 Lib/sndhdr.py
--- a/Lib/sndhdr.py	Thu Oct 09 22:16:15 2014 +0200
+++ b/Lib/sndhdr.py	Thu Oct 09 16:59:30 2014 -0400
@@ -32,6 +32,11 @@
 
 __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 @@
         for tf in tests:
             res = tf(h, f)
             if res:
-                return res
+                return SndHeaders(*res)
         return None
 
 
diff -r 54ef5af2e919 -r ef72142eb8a2 Lib/test/test_sndhdr.py
--- a/Lib/test/test_sndhdr.py	Thu Oct 09 22:16:15 2014 +0200
+++ b/Lib/test/test_sndhdr.py	Thu Oct 09 16:59:30 2014 -0400
@@ -1,4 +1,5 @@
 import sndhdr
+import pickle
 import unittest
 from test.support import findfile
 
@@ -18,6 +19,18 @@
             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 -r 54ef5af2e919 -r ef72142eb8a2 Misc/NEWS
--- a/Misc/NEWS	Thu Oct 09 22:16:15 2014 +0200
+++ b/Misc/NEWS	Thu Oct 09 16:59:30 2014 -0400
@@ -166,6 +166,8 @@
 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.