Add Sound.copy and Sound.__copy__

Co-authored-by: Borishkof <[email protected]>

Author: oddbookworm

buildconfig/stubs/pygame/mixer.pyi

@@ -72,6 +72,8 @@ class Sound:
     def get_num_channels(self) -> int: ...
     def get_length(self) -> float: ...
     def get_raw(self) -> bytes: ...
+    def copy(self) -> Sound: ...
+    def __copy__(self) -> Sound: ...
 
 class Channel:
     def __init__(self, id: int) -> None: ...

docs/reST/ref/mixer.rst

@@ -500,6 +500,23 @@ The following file formats are supported
 
       .. ## Sound.get_raw ##
 
+   .. method:: copy
+
+      | :sl:`return a new Sound object that is a deep copy of this Sound`
+      | :sg:`copy() -> Sound`
+      | :sg:`copy.copy(original_sound) -> Sound`
+
+      Return a new Sound object that is a deep copy of this Sound. The new Sound
+      will be just as if you loaded it from the same file on disk as you did the
+      original Sound. If the copy fails, a ``TypeError`` or :meth:`pygame.error`
+      exception will be raised.
+
+      Also note that this functions as ``Sound.__copy__``.
+
+      .. versionadded:: 2.5.6
+
+      .. ## Sound.copy ##
+
    .. ## pygame.mixer.Sound ##
 
 .. class:: Channel

src_c/doc/mixer_doc.h

@@ -26,6 +26,7 @@
 #define DOC_MIXER_SOUND_GETNUMCHANNELS "get_num_channels() -> count\ncount how many times this Sound is playing"
 #define DOC_MIXER_SOUND_GETLENGTH "get_length() -> seconds\nget the length of the Sound"
 #define DOC_MIXER_SOUND_GETRAW "get_raw() -> bytes\nreturn a bytestring copy of the Sound samples."
+#define DOC_MIXER_SOUND_COPY "copy() -> Sound\ncopy.copy(original_sound) -> Sound\nreturn a new Sound object that is a deep copy of this Sound"
 #define DOC_MIXER_CHANNEL "Channel(id) -> Channel\nCreate a Channel object for controlling playback"
 #define DOC_MIXER_CHANNEL_ID "id -> int\nget the channel id for the Channel object"
 #define DOC_MIXER_CHANNEL_PLAY "play(Sound, loops=0, maxtime=0, fade_ms=0) -> None\nplay a Sound on a specific Channel"

src_c/mixer.c

@@ -89,6 +89,8 @@ pgChannel_New(int);
 #define pgChannel_Check(x) \
     (PyObject_IsInstance(x, (PyObject *)&pgChannel_Type))
 
+static PyObject *
+snd_get_arraystruct(PyObject *self, void *closure);
 static int
 snd_getbuffer(PyObject *, Py_buffer *, int);
 static void
@@ -801,6 +803,37 @@ snd_get_raw(PyObject *self, PyObject *_null)
                                      (Py_ssize_t)chunk->alen);
 }
 
+static PyObject *
+snd_copy(PyObject *self, PyObject *_null)
+{
+    MIXER_INIT_CHECK();
+
+    pgSoundObject *newSound =
+        (pgSoundObject *)pgSound_Type.tp_new(&pgSound_Type, NULL, NULL);
+
+    PyObject *kwargs = PyDict_New();
+    PyObject *key = PyUnicode_FromString("buffer");
+    PyObject *bytes = snd_get_raw(self, NULL);
+    if (PyDict_SetItem(kwargs, key, bytes) < 0) {
+        // exception set already
+        Py_DECREF(key);
+        Py_DECREF(bytes);
+        Py_DECREF(kwargs);
+        return NULL;
+    }
+    Py_DECREF(key);
+    Py_DECREF(bytes);
+
+    if (sound_init((PyObject *)newSound, NULL, kwargs) != 0) {
+        Py_DECREF(kwargs);
+        Py_DECREF(newSound);
+        return RAISE(pgExc_SDLError, "Failed to initialize copied sound");
+    }
+
+    Py_DECREF(kwargs);
+    return (PyObject *)newSound;
+}
+
 static PyObject *
 snd_get_arraystruct(PyObject *self, void *closure)
 {
@@ -858,6 +891,8 @@ PyMethodDef sound_methods[] = {
     {"get_volume", snd_get_volume, METH_NOARGS, DOC_MIXER_SOUND_GETVOLUME},
     {"get_length", snd_get_length, METH_NOARGS, DOC_MIXER_SOUND_GETLENGTH},
     {"get_raw", snd_get_raw, METH_NOARGS, DOC_MIXER_SOUND_GETRAW},
+    {"copy", snd_copy, METH_NOARGS, DOC_MIXER_SOUND_COPY},
+    {"__copy__", snd_copy, METH_NOARGS, DOC_MIXER_SOUND_COPY},
     {NULL, NULL, 0, NULL}};
 
 static PyGetSetDef sound_getset[] = {

test/mixer_test.py

@@ -1330,6 +1330,46 @@ def __init__(self):
 
         self.assertRaises(RuntimeError, incorrect.get_volume)
 
+    def test_snd_copy(self):
+        mixer.init()
+
+        filenames = [
+            "house_lo.ogg",
+            "house_lo.wav",
+            "house_lo.flac",
+            "house_lo.opus",
+            "surfonasinewave.xm",
+        ]
+        if pygame.mixer.get_sdl_mixer_version() >= (2, 6, 0):
+            filenames.append("house_lo.mp3")
+
+        for f in filenames:
+            filename = example_path(os.path.join("data", f))
+            try:
+                sound = mixer.Sound(file=filename)
+            except pygame.error as e:
+                continue
+            sound_copy = sound.copy()
+            self.assertEqual(sound.get_length(), sound_copy.get_length())
+            self.assertEqual(sound.get_num_channels(), sound_copy.get_num_channels())
+            self.assertEqual(sound.get_volume(), sound_copy.get_volume())
+            self.assertEqual(sound.get_raw(), sound_copy.get_raw())
+
+            sound.set_volume(0.5)
+            self.assertNotEqual(sound.get_volume(), sound_copy.get_volume())
+
+            del sound
+
+            # Test on the copy for playable sounds
+            channel = sound_copy.play()
+            if channel is None:
+                continue
+            self.assertTrue(channel.get_busy())
+            sound_copy.stop()
+            self.assertFalse(channel.get_busy())
+            sound_copy.play()
+            self.assertEqual(sound_copy.get_num_channels(), 1)
+
 
 ##################################### MAIN #####################################