Merge pull request #1984 from oddbookworm/scrap

deprecated existing scrap API and replaced it with simpler API

Author: Starbuck5

buildconfig/stubs/pygame/scrap.pyi

@@ -9,3 +9,6 @@ def put(data_type: str, data: ByteString) -> None: ...
 def contains(data_type: str) -> bool: ...
 def lost() -> bool: ...
 def set_mode(mode: int) -> None: ...
+def put_text(text: str) -> None: ...
+def get_text() -> str: ...
+def has_text() -> bool: ...

docs/reST/ref/scrap.rst

@@ -11,6 +11,18 @@
 **EXPERIMENTAL!**: This API may change or disappear in later pygame releases. If
 you use this, your code may break with the next pygame release.
 
+The scrap module is for transferring data to/from the clipboard. This allows for
+transferring of strings between pygame and other applications. Currently, only strings
+are supported with the ``scrap.put_text``, ``scrap.get_text``, and ``scrap.has_text``
+functions. All other functions are deprecated as of pygame 2.2.0 and will be removed
+in a future release of pygame.
+
+.. note:: ``scrap.put_text``, ``scrap.get_text``, and ``scrap.has_text`` use the same
+   clipboard as the rest of the current API, but only strings are compatible with the 
+   new API as of right now.
+
+**THE BELOW INFORMATION IS DEPRECATED IN PYGAME 2.2.0 AND WILL BE REMOVED IN THE FUTURE.**
+
 The scrap module is for transferring data to/from the clipboard. This allows
 for cutting and pasting data between pygame and other applications. Some basic
 data (MIME) types are defined and registered:
@@ -80,6 +92,8 @@ For an example of how the scrap module works refer to the examples page
 
    .. note:: The scrap module requires :func:`pygame.display.set_mode()` be
       called before being initialized.
+   
+   .. deprecated:: 2.2.0
 
    .. ## pygame.scrap.init ##
 
@@ -95,6 +109,7 @@ For an example of how the scrap module works refer to the examples page
    :rtype: bool
 
    .. versionadded:: 1.9.5
+   .. deprecated:: 2.2.0
 
    .. ## pygame.scrap.get_init ##
 
@@ -113,6 +128,8 @@ For an example of how the scrap module works refer to the examples page
       no data for the given type is available
    :rtype: bytes | None
 
+   .. deprecated:: 2.2.0
+
    ::
 
      text = pygame.scrap.get(pygame.SCRAP_TEXT)
@@ -137,6 +154,8 @@ For an example of how the scrap module works refer to the examples page
       is no data in the clipboard an empty list is returned
    :rtype: list
 
+   .. deprecated:: 2.2.0
+
    ::
 
      for t in pygame.scrap.get_types():
@@ -164,6 +183,8 @@ For an example of how the scrap module works refer to the examples page
 
    :raises pygame.error: if unable to put the data into the clipboard
 
+   .. deprecated:: 2.2.0
+
    ::
 
      with open("example.bmp", "rb") as fp:
@@ -189,6 +210,8 @@ For an example of how the scrap module works refer to the examples page
       clipboard, ``False`` otherwise
    :rtype: bool
 
+   .. deprecated:: 2.2.0
+
    ::
 
      if pygame.scrap.contains(pygame.SCRAP_TEXT):
@@ -210,6 +233,8 @@ For an example of how the scrap module works refer to the examples page
       application, ``False`` if the pygame application still owns the clipboard
    :rtype: bool
 
+   .. deprecated:: 2.2.0
+
    ::
 
      if pygame.scrap.lost():
@@ -235,6 +260,55 @@ For an example of how the scrap module works refer to the examples page
    :raises ValueError: if the ``mode`` parameter is not
       ``pygame.SCRAP_CLIPBOARD`` or ``pygame.SCRAP_SELECTION``
 
+   .. deprecated:: 2.2.0
+
    .. ## pygame.scrap.set_mode ##
 
-.. ## pygame.scrap ##
+.. function:: put_text
+
+   | :sl:`Places text into the clipboard.`
+   | :sg:`put_text(text) -> None`
+
+   Places the input text into the clipboard. The data should be a string.
+   This is the same clipboard as the legacy scrap API when using ``SCRAP_TEXT``.
+
+   :param string text: String to be placed into the clipboard
+   :rtype: None
+
+   :raises pygame.error: if video mode has not been set_mode
+
+   .. note:: ``pygame.display.set_mode()`` should be called before using the ``scrap`` module
+
+   .. versionadded:: 2.2.0
+
+   .. ## pygame.scrap.put_text
+
+.. function:: get_text
+   
+   | :sl:`Gets text from the clipboard.`
+   | :sg:`get_text() -> str`
+
+   Gets text from the clipboard and returns it. If the clipboard is empty,
+   returns an empty string. This is the same clipboard as the legacy scrap
+   API when using ``SCRAP_TEXT``.
+
+   :rtype: str
+
+   .. versionadded:: 2.2.0
+
+   .. ## pygame.scrap.get_text
+
+.. function:: has_text
+   
+   | :sl:`Checks if text is in the clipboard.`
+   | :sg:`has_text() -> bool`
+
+   Returns ``True`` if the clipboard has a string, otherwise returns ``False``.
+   This is the same clipboard as the legacy scrap API when using ``SCRAP_TEXT``.
+
+   :rtype: bool
+
+   .. versionadded:: 2.2.0
+
+   .. ## pygame.scrap.has_text
+.. ## pygame.scrap ##

src_c/doc/scrap_doc.h

@@ -8,3 +8,6 @@
 #define DOC_SCRAP_CONTAINS "contains(type) -> bool\nChecks whether data for a given type is available in the clipboard."
 #define DOC_SCRAP_LOST "lost() -> bool\nIndicates if the clipboard ownership has been lost by the pygame application."
 #define DOC_SCRAP_SETMODE "set_mode(mode) -> None\nSets the clipboard access mode."
+#define DOC_SCRAP_PUTTEXT "put_text(text) -> None\nPlaces text into the clipboard."
+#define DOC_SCRAP_GETTEXT "get_text() -> str\nGets text from the clipboard."
+#define DOC_SCRAP_HASTEXT "has_text() -> bool\nChecks if text is in the clipboard."

src_c/scrap.c

@@ -61,6 +61,13 @@ _scrap_lost_scrap(PyObject *self, PyObject *args);
 static PyObject *
 _scrap_set_mode(PyObject *self, PyObject *args);
 
+static PyObject *
+_scrap_get_text(PyObject *self, PyObject *args);
+static PyObject *
+_scrap_put_text(PyObject *self, PyObject *args);
+static PyObject *
+_scrap_has_text(PyObject *self, PyObject *args);
+
 /* Determine what type of clipboard we are using */
 #if !defined(__WIN32__)
 #define SDL2_SCRAP
@@ -93,6 +100,11 @@ _scrap_init(PyObject *self, PyObject *args)
 {
     VIDEO_INIT_CHECK();
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "pygame.scrap.init deprecated since 2.2.0", 1) == -1) {
+        return NULL;
+    }
+
     if (!pygame_scrap_initialized()) {
         Py_XDECREF(_clipdata);
         Py_XDECREF(_selectiondata);
@@ -120,6 +132,12 @@ _scrap_init(PyObject *self, PyObject *args)
 static PyObject *
 _scrap_get_init(PyObject *self, PyObject *_null)
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "pygame.scrap.get_init deprecated since 2.2.0",
+                     1) == -1) {
+        return NULL;
+    }
+
     return PyBool_FromLong(pygame_scrap_initialized());
 }
 
@@ -135,6 +153,12 @@ _scrap_get_types(PyObject *self, PyObject *_null)
     PyObject *list;
     PyObject *tmp;
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "pygame.scrap.get_types deprecated since 2.2.0",
+                     1) == -1) {
+        return NULL;
+    }
+
     PYGAME_SCRAP_INIT_CHECK();
     if (!pygame_scrap_lost()) {
         switch (_currentmode) {
@@ -176,6 +200,12 @@ _scrap_contains(PyObject *self, PyObject *args)
 {
     char *type = NULL;
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "pygame.scrap.contains deprecated since 2.2.0",
+                     1) == -1) {
+        return NULL;
+    }
+
     if (!PyArg_ParseTuple(args, "s", &type))
         return NULL;
     if (pygame_scrap_contains(type))
@@ -194,6 +224,13 @@ _scrap_get_scrap(PyObject *self, PyObject *args)
     char *scrap_type;
     size_t count;
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "pygame.scrap.get deprecated since 2.2.0. Consider using"
+                     " pygame.scrap.get_text instead.",
+                     1) == -1) {
+        return NULL;
+    }
+
     PYGAME_SCRAP_INIT_CHECK();
 
     if (!PyArg_ParseTuple(args, "s", &scrap_type))
@@ -266,6 +303,13 @@ _scrap_put_scrap(PyObject *self, PyObject *args)
     PyObject *tmp;
     static const char argfmt[] = "sy#";
 
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "pygame.scrap.put deprecated since 2.2.0. Consider using"
+                     " pygame.scrap.put_text instead.",
+                     1) == -1) {
+        return NULL;
+    }
+
     PYGAME_SCRAP_INIT_CHECK();
 
     if (!PyArg_ParseTuple(args, argfmt, &scrap_type, &scrap, &scraplen)) {
@@ -318,6 +362,13 @@ static PyObject *
 _scrap_set_mode(PyObject *self, PyObject *args)
 {
     PYGAME_SCRAP_INIT_CHECK();
+
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "pygame.scrap.set_mode deprecated since 2.2.0",
+                     1) == -1) {
+        return NULL;
+    }
+
     if (!PyArg_ParseTuple(args, "i", &_currentmode))
         return NULL;
 
@@ -329,6 +380,75 @@ _scrap_set_mode(PyObject *self, PyObject *args)
     Py_RETURN_NONE;
 }
 
+/**
+ * @brief Fetches a python string from the SDL clipboard. If
+ *        there is nothing in the clipboard, it will return empty
+ *
+ * @return PyObject*
+ */
+static PyObject *
+_scrap_get_text(PyObject *self, PyObject *args)
+{
+    const SDL_bool hasText = SDL_HasClipboardText();
+
+    char *text = SDL_GetClipboardText();
+
+    // if SDL_GetClipboardText fails, it returns an empty string
+    // hasText helps determine if an actual error occurred
+    // vs just an empty string in the clipboard
+    if (*text == '\0' && hasText == SDL_TRUE) {
+        SDL_free(text);
+        PyErr_SetString(pgExc_SDLError, SDL_GetError());
+        return NULL;
+    }
+
+    PyObject *returnValue = PyUnicode_FromString(text);
+    SDL_free(text);
+
+    return returnValue;
+}
+
+/**
+ * @brief Puts a python string into the SDL clipboard
+ *
+ * @param args A python string to be put into the clipboard
+ *
+ * @return PyObject*
+ */
+static PyObject *
+_scrap_put_text(PyObject *self, PyObject *args)
+{
+    char *text;
+
+    if (!PyArg_ParseTuple(args, "s", &text)) {
+        return NULL;
+    }
+
+    if (SDL_SetClipboardText(text)) {
+        return RAISE(pgExc_SDLError, SDL_GetError());
+    }
+
+    Py_RETURN_NONE;
+}
+
+/**
+ * @brief If the SDL clipboard has something in it, will return True.
+ *          Else it returns False.
+ *
+ * @return PyObject*
+ */
+static PyObject *
+_scrap_has_text(PyObject *self, PyObject *args)
+{
+    const SDL_bool hasText = SDL_HasClipboardText();
+
+    if (hasText) {
+        Py_RETURN_TRUE;
+    }
+
+    Py_RETURN_FALSE;
+}
+
 static PyMethodDef scrap_builtins[] = {
 /*
  * Only initialise these functions for ones we know about.
@@ -347,6 +467,9 @@ static PyMethodDef scrap_builtins[] = {
     {"set_mode", _scrap_set_mode, METH_VARARGS, DOC_SCRAP_SETMODE},
 
 #endif
+    {"get_text", _scrap_get_text, METH_NOARGS, DOC_SCRAP_GETTEXT},
+    {"has_text", _scrap_has_text, METH_NOARGS, DOC_SCRAP_HASTEXT},
+    {"put_text", _scrap_put_text, METH_VARARGS, DOC_SCRAP_PUTTEXT},
     {NULL, NULL, 0, NULL}};
 
 MODINIT_DEFINE(scrap)

test/scrap_tags.py

@@ -1,4 +1,4 @@
-__tags__ = ["ignore", "subprocess_ignore"]
+# __tags__ = ["ignore", "subprocess_ignore"]
 
 # TODO: make scrap_test.py work
 # This test used to work only on linux and windows.

test/scrap_test.py

@@ -115,6 +115,19 @@ def test_put(self):
 
         self.assertEqual(r, b"buf")
 
+    def test_new_put(self):
+        """Ensures that text can be placed into the clipboard"""
+        text = "Welcome to scrap!"
+        scrap.put_text(text)
+        self.assertTrue(scrap.has_text())
+        self.assertEqual(scrap.get_text(), text)
+
+    def test_has_text_when_empty(self):
+        """Ensures that has_text returns False when clipboard is empty"""
+        scrap.put_text("")
+        self.assertFalse(scrap.has_text())
+        self.assertEqual(scrap.get_text(), "")
+
 
 class ScrapModuleClipboardNotOwnedTest(unittest.TestCase):
     """Test the scrap module's functionality when the pygame application is