Deprecate some FT2Image methods.

anntzer · anntzer · commit 4b85a7ba8683 · 2019-08-10T16:31:33.000+02:00
FT2Image is a class in ft2font that's basically a numpy array (... but
predates Matplotlib's use of numpy...).  We can't completely remove it
yet because that requires adapating some methods implemented in C to
take a numpy array (technically, a Python buffer) rather than an
FT2Image, but we can start by deprecating some methods which should not
be specific to FT2Image, but just be normal operators working on
ndarrays.
diff --git a/doc/api/next_api_changes/2019-07-27-AL.rst b/doc/api/next_api_changes/2019-07-27-AL.rst
@@ -0,0 +1,6 @@
+Deprecations
+````````````
+
+The ``as_str``, ``as_rgba_str``, ``as_array``, ``get_width`` and ``get_height``
+methods of ``matplotlib.ft2font.FT2Image`` are deprecated.  Convert the ``FT2Image``
+to a numpy array with ``np.asarray`` before processing it.
diff --git a/examples/user_interfaces/mathtext_wx_sgskip.py b/examples/user_interfaces/mathtext_wx_sgskip.py
@@ -26,10 +26,8 @@
 
 
 def mathtext_to_wxbitmap(s):
-    ftimage, depth = mathtext_parser.parse(s, 150)
-    return wx.Bitmap.FromBufferRGBA(
-        ftimage.get_width(), ftimage.get_height(),
-        ftimage.as_rgba_str())
+    rgba, depth = mathtext_parser.to_rgba(s, dpi=150, fontsize=10)
+    return wx.Bitmap.FromBufferRGBA(rgba.shape[1], rgba.shape[0], rgba)
 ############################################################
 
 functions = [
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -249,7 +249,7 @@ def get_label_width(self, lev, fmt, fsize):
                 self._mathtext_parser = mathtext.MathTextParser('bitmap')
             img, _ = self._mathtext_parser.parse(lev, dpi=72,
                                                  prop=self.labelFontProps)
-            lw = img.get_width()  # at dpi=72, the units are PostScript points
+            _, lw = np.shape(img)  # at dpi=72, the units are PostScript points
         else:
             # width is much less than "font size"
             lw = len(lev) * fsize * 0.6
diff --git a/lib/matplotlib/mathtext.py b/lib/matplotlib/mathtext.py
@@ -3376,9 +3376,7 @@ def to_mask(self, texstr, dpi=120, fontsize=14):
         assert self._output == "bitmap"
         prop = FontProperties(size=fontsize)
         ftimage, depth = self.parse(texstr, dpi=dpi, prop=prop)
-
-        x = ftimage.as_array()
-        return x, depth
+        return np.asarray(ftimage), depth
 
     def to_rgba(self, texstr, color='black', dpi=120, fontsize=14):
         r"""
diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp
@@ -103,24 +103,39 @@ static PyObject *PyFT2Image_draw_rect_filled(PyFT2Image *self, PyObject *args, P
 const char *PyFT2Image_as_str__doc__ =
     "s = image.as_str()\n"
     "\n"
+    "[*Deprecated*]\n"
     "Return the image buffer as a string\n"
     "\n";
 
 static PyObject *PyFT2Image_as_str(PyFT2Image *self, PyObject *args, PyObject *kwds)
 {
-    // TODO: Use a buffer to avoid the copy
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "FT2Image.as_str is deprecated since Matplotlib 3.2 and "
+                     "will be removed in Matplotlib 3.4; convert the FT2Image "
+                     "to a NumPy array with np.asarray instead.",
+                     1)) {
+        return NULL;
+    }
     return PyBytes_FromStringAndSize((const char *)self->x->get_buffer(),
                                      self->x->get_width() * self->x->get_height());
 }
 
 const char *PyFT2Image_as_rgba_str__doc__ =
     "s = image.as_rgba_str()\n"
     "\n"
+    "[*Deprecated*]\n"
     "Return the image buffer as a RGBA string\n"
     "\n";
 
 static PyObject *PyFT2Image_as_rgba_str(PyFT2Image *self, PyObject *args, PyObject *kwds)
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "FT2Image.as_rgba_str is deprecated since Matplotlib 3.2 and "
+                     "will be removed in Matplotlib 3.4; convert the FT2Image "
+                     "to a NumPy array with np.asarray instead.",
+                     1)) {
+        return NULL;
+    }
     npy_intp dims[] = {(npy_intp)self->x->get_height(), (npy_intp)self->x->get_width(), 4 };
     numpy::array_view<unsigned char, 3> result(dims);
 
@@ -141,22 +156,44 @@ static PyObject *PyFT2Image_as_rgba_str(PyFT2Image *self, PyObject *args, PyObje
 const char *PyFT2Image_as_array__doc__ =
     "x = image.as_array()\n"
     "\n"
+    "[*Deprecated*]\n"
     "Return the image buffer as a width x height numpy array of ubyte \n"
     "\n";
 
 static PyObject *PyFT2Image_as_array(PyFT2Image *self, PyObject *args, PyObject *kwds)
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "FT2Image.as_array is deprecated since Matplotlib 3.2 and "
+                     "will be removed in Matplotlib 3.4; convert the FT2Image "
+                     "to a NumPy array with np.asarray instead.",
+                     1)) {
+        return NULL;
+    }
     npy_intp dims[] = {(npy_intp)self->x->get_height(), (npy_intp)self->x->get_width() };
     return PyArray_SimpleNewFromData(2, dims, NPY_UBYTE, self->x->get_buffer());
 }
 
 static PyObject *PyFT2Image_get_width(PyFT2Image *self, PyObject *args, PyObject *kwds)
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "FT2Image.get_width is deprecated since Matplotlib 3.2 and "
+                     "will be removed in Matplotlib 3.4; convert the FT2Image "
+                     "to a NumPy array with np.asarray instead.",
+                     1)) {
+        return NULL;
+    }
     return PyLong_FromLong(self->x->get_width());
 }
 
 static PyObject *PyFT2Image_get_height(PyFT2Image *self, PyObject *args, PyObject *kwds)
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "FT2Image.get_height is deprecated since Matplotlib 3.2 and "
+                     "will be removed in Matplotlib 3.4; convert the FT2Image "
+                     "to a NumPy array with np.asarray instead.",
+                     1)) {
+        return NULL;
+    }
     return PyLong_FromLong(self->x->get_height());
 }
 
