gh-105096: Deprecate wave getmarkers() method (#105098)

wave: Deprecate the getmark(), setmark() and getmarkers() methods of
the Wave_read and Wave_write classes. They will be removed in Python
3.15.

5 files changed, 51 insertions, 0 deletions

diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index 9565ed9..55b029b 100644
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -131,11 +131,19 @@ Wave_read Objects
 
       Returns ``None``.
 
+      .. deprecated-removed:: 3.13 3.15
+         The method only existed for compatibility with the :mod:`!aifc` module
+         which has been removed in Python 3.13.
+
 
    .. method:: getmark(id)
 
       Raise an error.
 
+      .. deprecated-removed:: 3.13 3.15
+         The method only existed for compatibility with the :mod:`!aifc` module
+         which has been removed in Python 3.13.
+
    The following two methods define a term "position" which is compatible between
    them, and is otherwise implementation dependent.
 
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 0fd82d6..6d0be3b 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -115,6 +115,10 @@ Optimizations
 Deprecated
 ==========
 
+* :mod:`wave`: Deprecate the ``getmark()``, ``setmark()`` and ``getmarkers()``
+  methods of the :class:`wave.Wave_read` and :class:`wave.Wave_write` classes.
+  They will be removed in Python 3.15.
+  (Contributed by Victor Stinner in :gh:`105096`.)
 
 
 Removed
diff --git a/Lib/test/test_wave.py b/Lib/test/test_wave.py
index 6c33628..5e771c8 100644
--- a/Lib/test/test_wave.py
+++ b/Lib/test/test_wave.py
@@ -136,6 +136,32 @@ class MiscTestCase(unittest.TestCase):
         not_exported = {'WAVE_FORMAT_PCM', 'WAVE_FORMAT_EXTENSIBLE', 'KSDATAFORMAT_SUBTYPE_PCM'}
         support.check__all__(self, wave, not_exported=not_exported)
 
+    def test_read_deprecations(self):
+        filename = support.findfile('pluck-pcm8.wav', subdir='audiodata')
+        with wave.open(filename) as reader:
+            with self.assertWarns(DeprecationWarning):
+                with self.assertRaises(wave.Error):
+                    reader.getmark('mark')
+            with self.assertWarns(DeprecationWarning):
+                self.assertIsNone(reader.getmarkers())
+
+    def test_write_deprecations(self):
+        with io.BytesIO(b'') as tmpfile:
+            with wave.open(tmpfile, 'wb') as writer:
+                writer.setnchannels(1)
+                writer.setsampwidth(1)
+                writer.setframerate(1)
+                writer.setcomptype('NONE', 'not compressed')
+
+                with self.assertWarns(DeprecationWarning):
+                    with self.assertRaises(wave.Error):
+                        writer.setmark(0, 0, 'mark')
+                with self.assertWarns(DeprecationWarning):
+                    with self.assertRaises(wave.Error):
+                        writer.getmark('mark')
+                with self.assertWarns(DeprecationWarning):
+                    self.assertIsNone(writer.getmarkers())
+
 
 class WaveLowLevelTest(unittest.TestCase):
 
diff --git a/Lib/wave.py b/Lib/wave.py
index 5177ecb..a34af24 100644
--- a/Lib/wave.py
+++ b/Lib/wave.py
@@ -342,9 +342,13 @@ class Wave_read:
                        self.getcomptype(), self.getcompname())
 
     def getmarkers(self):
+        import warnings
+        warnings._deprecated("Wave_read.getmarkers", remove=(3, 15))
         return None
 
     def getmark(self, id):
+        import warnings
+        warnings._deprecated("Wave_read.getmark", remove=(3, 15))
         raise Error('no marks')
 
     def setpos(self, pos):
@@ -548,12 +552,18 @@ class Wave_write:
               self._nframes, self._comptype, self._compname)
 
     def setmark(self, id, pos, name):
+        import warnings
+        warnings._deprecated("Wave_write.setmark", remove=(3, 15))
         raise Error('setmark() not supported')
 
     def getmark(self, id):
+        import warnings
+        warnings._deprecated("Wave_write.getmark", remove=(3, 15))
         raise Error('no marks')
 
     def getmarkers(self):
+        import warnings
+        warnings._deprecated("Wave_write.getmarkers", remove=(3, 15))
         return None
 
     def tell(self):
diff --git a/Misc/NEWS.d/next/Library/2023-05-30-17-39-03.gh-issue-105096.pw00FW.rst b/Misc/NEWS.d/next/Library/2023-05-30-17-39-03.gh-issue-105096.pw00FW.rst
new file mode 100644
index 0000000..bc82c13
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2023-05-30-17-39-03.gh-issue-105096.pw00FW.rst
@@ -0,0 +1,3 @@
+:mod:`wave`: Deprecate the ``getmark()``, ``setmark()`` and ``getmarkers()``
+methods of the :class:`wave.Wave_read` and :class:`wave.Wave_write` classes.
+They will be removed in Python 3.15. Patch by Victor Stinner.