[Python-checkins] gh-105096: Deprecate wave getmarkers() method (#105098)

[vstinner]

https://github.com/python/cpython/commit/03ad6624c2b4a30cccf6d5b7e2b9999e104444ae
commit: 03ad6624c2b4a30cccf6d5b7e2b9999e104444ae
branch: main
author: Victor Stinner <vstinner at python.org>
committer: vstinner <vstinner at python.org>
date: 2023-05-31T12:09:41Z
summary:

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.

files:
A Misc/NEWS.d/next/Library/2023-05-30-17-39-03.gh-issue-105096.pw00FW.rst
M Doc/library/wave.rst
M Doc/whatsnew/3.13.rst
M Lib/test/test_wave.py
M Lib/wave.py

diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index 9565ed926576..55b029bc742b 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 0fd82d6188b3..6d0be3b258f6 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 6c3362857fc2..5e771c8de969 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 5177ecbef820..a34af244c3e2 100644
--- a/Lib/wave.py
+++ b/Lib/wave.py
@@ -342,9 +342,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 000000000000..bc82c13081f1
--- /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.