Change {FigureCanvasAgg,RendererAgg}.buffer_rgba to return a memoryview.

anntzer · anntzer · commit 54cd9ceeac50 · 2018-08-19T22:12:06.000+02:00
The `buffer_rgba` method now allows direct access to the renderer's
underlying buffer (as a `(m, n, 4)`-shape memoryview) rather than
copying the data to a new bytestring.  This is consistent with the
behavior on Py2, where a buffer object was returned.

While this is technically a backwards-incompatible change, memoryviews
are in fact quite compatible with bytes for most uses, and I'd argue
that the bigger compatibility break was the change from no-copy in Py2
to copy in Py3 (after all that's the main point of the method...).
diff --git a/doc/api/next_api_changes/2018-07-22-AL.rst b/doc/api/next_api_changes/2018-07-22-AL.rst
@@ -0,0 +1,7 @@
+`FigureCanvasAgg.buffer_rgba` and `RendererAgg.buffer_rgba` now return a memoryview
+```````````````````````````````````````````````````````````````````````````````````
+
+The ``buffer_rgba`` method now allows direct access to the renderer's
+underlying buffer (as a ``(m, n, 4)``-shape memoryview) rather than copying the
+data to a new bytestring.  This is consistent with the behavior on Py2, where a
+buffer object was returned.
diff --git a/examples/misc/agg_buffer_to_array.py b/examples/misc/agg_buffer_to_array.py
@@ -15,7 +15,7 @@
 fig.canvas.draw()
 
 # grab the pixel buffer and dump it into a numpy array
-X = np.array(fig.canvas.renderer._renderer)
+X = np.array(fig.canvas.renderer.buffer_rgba())
 
 # now display the array X as an Axes in a new figure
 fig2 = plt.figure()
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -272,7 +272,7 @@ def tostring_argb(self):
         return self._renderer.tostring_argb()
 
     def buffer_rgba(self):
-        return self._renderer.buffer_rgba()
+        return memoryview(self._renderer)
 
     def clear(self):
         self._renderer.clear()
@@ -421,40 +421,39 @@ def get_renderer(self, cleared=False):
         return self.renderer
 
     def tostring_rgb(self):
-        '''Get the image as an RGB byte string.
+        """Get the image as an RGB byte string.
 
         `draw` must be called at least once before this function will work and
         to update the renderer for any subsequent changes to the Figure.
 
         Returns
         -------
         bytes
-        '''
+        """
         return self.renderer.tostring_rgb()
 
     def tostring_argb(self):
-        '''Get the image as an ARGB byte string
+        """Get the image as an ARGB byte string.
 
         `draw` must be called at least once before this function will work and
         to update the renderer for any subsequent changes to the Figure.
 
         Returns
         -------
         bytes
-
-        '''
+        """
         return self.renderer.tostring_argb()
 
     def buffer_rgba(self):
-        '''Get the image as an RGBA byte string.
+        """Get the image as a memoryview to the renderer's buffer.
 
         `draw` must be called at least once before this function will work and
         to update the renderer for any subsequent changes to the Figure.
 
         Returns
         -------
-        bytes
-        '''
+        memoryview
+        """
         return self.renderer.buffer_rgba()
 
     def print_raw(self, filename_or_obj, *args, **kwargs):
