Deprecate BufferRegion.to_string{,_argb}.

anntzer · chahak13 · commit 709d7e3432b4 · 2022-10-20T11:54:16.000-05:00
These methods are unused; it is better to directly get array views (this
saves a copy); and removing them prepares for a possible future where
BufferRegions mostly go away and copy_from_bbox/restore_region directly
operate on numpy arrays.
diff --git a/doc/api/next_api_changes/deprecations/24221-AL.rst b/doc/api/next_api_changes/deprecations/24221-AL.rst
@@ -0,0 +1,5 @@
+``BufferRegion.to_string`` and ``BufferRegion.to_string_argb``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... are deprecated.  Use ``np.asarray(buffer_region)`` to get an array view on
+a buffer region without making a copy; to convert that view from RGBA (the
+default) to ARGB, use ``np.take(..., [2, 1, 0, 3], axis=2)``.
diff --git a/src/_backend_agg_wrapper.cpp b/src/_backend_agg_wrapper.cpp
@@ -46,6 +46,12 @@ static void PyBufferRegion_dealloc(PyBufferRegion *self)
 
 static PyObject *PyBufferRegion_to_string(PyBufferRegion *self, PyObject *args)
 {
+    char const* msg =
+        "BufferRegion.to_string is deprecated since Matplotlib 3.7 and will "
+        "be removed two minor releases later; use np.asarray(region) instead.";
+    if (PyErr_WarnEx(PyExc_DeprecationWarning, msg, 1)) {
+        return NULL;
+    }
     return PyBytes_FromStringAndSize((const char *)self->x->get_data(),
                                      self->x->get_height() * self->x->get_stride());
 }
@@ -83,6 +89,13 @@ static PyObject *PyBufferRegion_get_extents(PyBufferRegion *self, PyObject *args
 
 static PyObject *PyBufferRegion_to_string_argb(PyBufferRegion *self, PyObject *args)
 {
+    char const* msg =
+        "BufferRegion.to_string_argb is deprecated since Matplotlib 3.7 and "
+        "will be removed two minor releases later; use "
+        "np.take(region, [2, 1, 0, 3], axis=2) instead.";
+    if (PyErr_WarnEx(PyExc_DeprecationWarning, msg, 1)) {
+        return NULL;
+    }
     PyObject *bufobj;
     uint8_t *buf;
 
