From 7f4c3e528a083a8a5f1f1c70dc38550b86cfbd17 Mon Sep 17 00:00:00 2001
From: Victor Stinner <vstinner@python.org>
Date: Tue, 30 May 2023 17:36:13 +0200
Subject: [PATCH] gh-105096: Deprecate wave getmarkers() method

wave: Deprecate the getmark(), setmark() and getmarkers() methods of
the Wave_read and Wave_write classes. They will be removed in Python
3.15.
---
 Doc/library/wave.rst                          |  8 ++++++
 Doc/whatsnew/3.13.rst                         |  4 +++
 Lib/test/test_wave.py                         | 26 +++++++++++++++++++
 Lib/wave.py                                   | 10 +++++++
 ...-05-30-17-39-03.gh-issue-105096.pw00FW.rst |  3 +++
 5 files changed, 51 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Library/2023-05-30-17-39-03.gh-issue-105096.pw00FW.rst

diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index 4dcbc3d4c2d1827..21178b7e39813db 100644
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -127,11 +127,19 @@ module, and don't do anything interesting.
 
    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:: Wave_read.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 8c81ac76a56b463..55a9d1cbb9dd8cd 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -103,6 +103,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 6c3362857fc2ba2..5e771c8de969ec6 100644
--- a/Lib/test/test_wave.py
+++ b/Lib/test/test_wave.py
@@ -136,6 +136,32 @@ def test__all__(self):
         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 76b73de1d67ad80..c7085176fa97b94 100644
--- a/Lib/wave.py
+++ b/Lib/wave.py
@@ -343,9 +343,13 @@ def getparams(self):
                        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 @@ def getparams(self):
               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 000000000000000..bc82c13081f140f
--- /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.