gh-85525: Indicate supported sound header formats (#21575)

* Indicate supported sound header formats

* modify file names

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

2 files changed, 57 insertions, 0 deletions

diff --git a/Doc/library/sndhdr.rst b/Doc/library/sndhdr.rst
index e1dbe4a..8c5c0bf 100644
--- a/Doc/library/sndhdr.rst
+++ b/Doc/library/sndhdr.rst
@@ -54,3 +54,52 @@ be the sample size in bits or ``'A'`` for A-LAW or ``'U'`` for u-LAW.
    .. versionchanged:: 3.5
       Result changed from a tuple to a namedtuple.
 
+The following sound header types are recognized, as listed below with the return value
+from :func:`whathdr`: and :func:`what`:
+
++------------+------------------------------------+
+| Value      | Sound header format                |
++============+====================================+
+| ``'aifc'`` | Compressed Audio Interchange Files |
++------------+------------------------------------+
+| ``'aiff'`` | Audio Interchange Files            |
++------------+------------------------------------+
+| ``'au'``   | Au Files                           |
++------------+------------------------------------+
+| ``'hcom'`` | HCOM Files                         |
++------------+------------------------------------+
++------------+------------------------------------+
+| ``'sndt'`` | Sndtool Sound Files                |
++------------+------------------------------------+
+| ``'voc'``  | Creative Labs Audio Files          |
++------------+------------------------------------+
+| ``'wav'``  | Waveform Audio File Format Files   |
++------------+------------------------------------+
+| ``'8svx'`` | 8-Bit Sampled Voice Files          |
++------------+------------------------------------+
+| ``'sb'``   | Signed Byte Audio Data Files       |
++------------+------------------------------------+
+| ``'ub'``   | UB Files                           |
++------------+------------------------------------+
+| ``'ul'``   | uLAW Audio Files                   |
++------------+------------------------------------+
+
+.. data:: tests
+
+   A list of functions performing the individual tests.  Each function takes two
+   arguments: the byte-stream and an open file-like object. When :func:`what` is
+   called with a byte-stream, the file-like object will be ``None``.
+
+   The test function should return a string describing the image type if the test
+   succeeded, or ``None`` if it failed.
+
+Example:
+
+.. code-block:: pycon
+
+   >>> import sndhdr
+   >>> imghdr.what('bass.wav')
+   'wav'
+   >>> imghdr.whathdr('bass.wav')
+   'wav'
+
diff --git a/Lib/sndhdr.py b/Lib/sndhdr.py
index 98a7834..45def9a 100644
--- a/Lib/sndhdr.py
+++ b/Lib/sndhdr.py
@@ -77,6 +77,7 @@ def whathdr(filename):
 tests = []
 
 def test_aifc(h, f):
+    """AIFC and AIFF files"""
     with warnings.catch_warnings():
         warnings.simplefilter('ignore', category=DeprecationWarning)
         import aifc
@@ -100,6 +101,7 @@ tests.append(test_aifc)
 
 
 def test_au(h, f):
+    """AU and SND files"""
     if h.startswith(b'.snd'):
         func = get_long_be
     elif h[:4] in (b'\0ds.', b'dns.'):
@@ -133,6 +135,7 @@ tests.append(test_au)
 
 
 def test_hcom(h, f):
+    """HCOM file"""
     if h[65:69] != b'FSSD' or h[128:132] != b'HCOM':
         return None
     divisor = get_long_be(h[144:148])
@@ -146,6 +149,7 @@ tests.append(test_hcom)
 
 
 def test_voc(h, f):
+    """VOC file"""
     if not h.startswith(b'Creative Voice File\032'):
         return None
     sbseek = get_short_le(h[20:22])
@@ -160,6 +164,7 @@ tests.append(test_voc)
 
 
 def test_wav(h, f):
+    """WAV file"""
     import wave
     # 'RIFF' <len> 'WAVE' 'fmt ' <len>
     if not h.startswith(b'RIFF') or h[8:12] != b'WAVE' or h[12:16] != b'fmt ':
@@ -176,6 +181,7 @@ tests.append(test_wav)
 
 
 def test_8svx(h, f):
+    """8SVX file"""
     if not h.startswith(b'FORM') or h[8:12] != b'8SVX':
         return None
     # Should decode it to get #channels -- assume always 1
@@ -185,6 +191,7 @@ tests.append(test_8svx)
 
 
 def test_sndt(h, f):
+    """SNDT file"""
     if h.startswith(b'SOUND'):
         nsamples = get_long_le(h[8:12])
         rate = get_short_le(h[20:22])
@@ -194,6 +201,7 @@ tests.append(test_sndt)
 
 
 def test_sndr(h, f):
+    """SNDR file"""
     if h.startswith(b'\0\0'):
         rate = get_short_le(h[2:4])
         if 4000 <= rate <= 25000: