gh-91217: deprecate-sndhdr (#91806)

Also inline necessary functionality from `sndhdr` into `email.mime.audio` for `MIMEAudio`.

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

6 files changed, 49 insertions, 16 deletions

diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst
index ab4f7bc..3fe5fe8 100644
--- a/Doc/library/email.mime.rst
+++ b/Doc/library/email.mime.rst
@@ -146,7 +146,7 @@ Here are the classes:
    A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
    :class:`MIMEAudio` class is used to create MIME message objects of major type
    :mimetype:`audio`. *_audiodata* is a string containing the raw audio data.  If
-   this data can be decoded by the standard Python module :mod:`sndhdr`, then the
+   this data can be decoded as au, wav, aiff, or aifc, then the
    subtype will be automatically included in the :mailheader:`Content-Type` header.
    Otherwise you can explicitly specify the audio subtype via the *_subtype*
    argument.  If the minor type could not be guessed and *_subtype* was not given,
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 75ea70b..653d32a 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -920,6 +920,7 @@ Deprecated
   * :mod:`nntplib`
   * :mod:`ossaudiodev`
   * :mod:`pipes`
+  * :mod:`sndhdr`
 
   (Contributed by Brett Cannon in :issue:`47061`.)
 
diff --git a/Lib/email/mime/audio.py b/Lib/email/mime/audio.py
index 4bcd7b2..e859c2e 100644
--- a/Lib/email/mime/audio.py
+++ b/Lib/email/mime/audio.py
@@ -6,19 +6,43 @@
 
 __all__ = ['MIMEAudio']
 
-import sndhdr
-
 from io import BytesIO
 from email import encoders
 from email.mime.nonmultipart import MIMENonMultipart
 
 
-
-_sndhdr_MIMEmap = {'au'  : 'basic',
-                   'wav' :'x-wav',
-                   'aiff':'x-aiff',
-                   'aifc':'x-aiff',
-                   }
+_tests = []
+
+def _test_aifc_aiff(h, f):
+    if not h.startswith(b'FORM'):
+        return None
+    if h[8:12] in {b'AIFC', b'AIFF'}:
+        return 'x-aiff'
+    else:
+        return None
+
+_tests.append(_test_aifc_aiff)
+
+
+def _test_au(h, f):
+    if h.startswith(b'.snd'):
+        return 'basic'
+    else:
+        return None
+
+_tests.append(_test_au)
+
+
+def _test_wav(h, f):
+    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 ':
+        return None
+    else:
+        return "x-wav"
+
+_tests.append(_test_wav)
+
 
 # There are others in sndhdr that don't have MIME types. :(
 # Additional ones to be added to sndhdr? midi, mp3, realaudio, wma??
@@ -31,14 +55,14 @@ def _whatsnd(data):
     """
     hdr = data[:512]
     fakefile = BytesIO(hdr)
-    for testfn in sndhdr.tests:
+    for testfn in _tests:
         res = testfn(hdr, fakefile)
         if res is not None:
-            return _sndhdr_MIMEmap.get(res[0])
-    return None
+            return res
+    else:
+        return None
 
 
-
 class MIMEAudio(MIMENonMultipart):
     """Class for generating audio/* MIME documents."""
 
@@ -47,7 +71,7 @@ class MIMEAudio(MIMENonMultipart):
         """Create an audio/* type MIME document.
 
         _audiodata is a string containing the raw audio data.  If this data
-        can be decoded by the standard Python `sndhdr' module, then the
+        can be decoded as au, wav, aiff, or aifc, then the
         subtype will be automatically included in the Content-Type header.
         Otherwise, you can specify  the specific audio subtype via the
         _subtype parameter.  If _subtype is not given, and no subtype can be
diff --git a/Lib/sndhdr.py b/Lib/sndhdr.py
index a63b6fd..98a7834 100644
--- a/Lib/sndhdr.py
+++ b/Lib/sndhdr.py
@@ -27,13 +27,16 @@ option -r tells it to recurse down directories found inside
 explicitly given directories.
 """
 
+import warnings
+
+warnings._deprecated(__name__, remove=(3, 13))
+
 # The file structure is top-down except that the test program and its
 # subroutine come last.
 
 __all__ = ['what', 'whathdr']
 
 from collections import namedtuple
-import warnings
 
 SndHeaders = namedtuple('SndHeaders',
                         'filetype framerate nchannels nframes sampwidth')
diff --git a/Lib/test/test_sndhdr.py b/Lib/test/test_sndhdr.py
index 426417c..4d97437 100644
--- a/Lib/test/test_sndhdr.py
+++ b/Lib/test/test_sndhdr.py
@@ -1,7 +1,10 @@
-import sndhdr
 import pickle
 import unittest
 from test.support import findfile
+from test.support import warnings_helper
+
+sndhdr = warnings_helper.import_deprecated("sndhdr")
+
 
 class TestFormats(unittest.TestCase):
     def test_data(self):
diff --git a/Misc/NEWS.d/next/Library/2022-04-17-12-27-46.gh-issue-91217.tNDWtK.rst b/Misc/NEWS.d/next/Library/2022-04-17-12-27-46.gh-issue-91217.tNDWtK.rst
new file mode 100644
index 0000000..4ee6ba2
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-04-17-12-27-46.gh-issue-91217.tNDWtK.rst
@@ -0,0 +1,2 @@
+Deprecate the sndhdr module, as well as inline needed functionality for
+``email.mime.MIMEAudio``.