backend_template fix.

anntzer · anntzer · commit 23f2c3b7ac83 · 2019-06-03T13:46:34.000+02:00
Update the docs to be mildly more relevant to third-party backend
implementers.  Add entry for rendered docs.

Make backend_template "work" (in the do-nothing sense) with usetex, by
super-initing the Renderer class and by not assuming the presence of a
`.height` attribute in FigureCanvasBase.
diff --git a/doc/api/backend_template_api.rst b/doc/api/backend_template_api.rst
@@ -0,0 +1,8 @@
+
+:mod:`matplotlib.backends.backend_template`
+===========================================
+
+.. automodule:: matplotlib.backends.backend_template
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/index_backend_api.rst b/doc/api/index_backend_api.rst
@@ -6,6 +6,7 @@
    :maxdepth: 1
 
    backend_mixed_api.rst
+   backend_template_api.rst
    backend_agg_api.rst
    backend_cairo_api.rst
    backend_gtk3agg_api.rst
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -569,9 +569,10 @@ def _get_text_path_transform(self, x, y, s, prop, angle, ismath):
         path = Path(verts, codes)
         angle = np.deg2rad(angle)
         if self.flipy():
+            width, height = self.get_canvas_width_height()
             transform = Affine2D().scale(fontsize / text2path.FONT_SCALE,
                                          fontsize / text2path.FONT_SCALE)
-            transform = transform.rotate(angle).translate(x, self.height - y)
+            transform = transform.rotate(angle).translate(x, height - y)
         else:
             transform = Affine2D().scale(fontsize / text2path.FONT_SCALE,
                                          fontsize / text2path.FONT_SCALE)
@@ -2467,7 +2468,7 @@ class NonGuiException(Exception):
 
 class FigureManagerBase:
     """
-    Helper class for pyplot mode, wraps everything up into a neat bundle
+    Helper class for pyplot mode, wraps everything up into a neat bundle.
 
     Attributes
     ----------
@@ -3278,8 +3279,7 @@ class _Backend:
 
     @classmethod
     def new_figure_manager(cls, num, *args, **kwargs):
-        """Create a new figure manager instance.
-        """
+        """Create a new figure manager instance."""
         # This import needs to happen here due to circular imports.
         from matplotlib.figure import Figure
         fig_cls = kwargs.pop('FigureClass', Figure)
@@ -3288,8 +3288,7 @@ def new_figure_manager(cls, num, *args, **kwargs):
 
     @classmethod
     def new_figure_manager_given_figure(cls, num, figure):
-        """Create a new figure manager instance for the given figure.
-        """
+        """Create a new figure manager instance for the given figure."""
         canvas = cls.FigureCanvas(figure)
         manager = cls.FigureManager(canvas, num)
         return manager
diff --git a/lib/matplotlib/backends/backend_template.py b/lib/matplotlib/backends/backend_template.py
@@ -1,65 +1,32 @@
 """
-This is a fully functional do nothing backend to provide a template to
-backend writers.  It is fully functional in that you can select it as
-a backend with
-
-  import matplotlib
-  matplotlib.use('Template')
-
-and your matplotlib scripts will (should!) run without error, though
-no output is produced.  This provides a nice starting point for
-backend writers because you can selectively implement methods
-(draw_rectangle, draw_lines, etc...) and slowly see your figure come
-to life w/o having to have a full blown implementation before getting
-any results.
-
-Copy this to backend_xxx.py and replace all instances of 'template'
-with 'xxx'.  Then implement the class methods and functions below, and
-add 'xxx' to the switchyard in matplotlib/backends/__init__.py and
-'xxx' to the backends list in the validate_backend method in
-matplotlib/__init__.py and you're off.  You can use your backend with::
-
-  import matplotlib
-  matplotlib.use('xxx')
-  import matplotlib.pyplot as plt
-  plt.plot([1,2,3])
-  plt.show()
-
-matplotlib also supports external backends, so you can place you can
-use any module in your PYTHONPATH with the syntax::
-
-  import matplotlib
-  matplotlib.use('module://my_backend')
-
-where my_backend.py is your module name.  This syntax is also
-recognized in the rc file and in the -d argument in pylab, e.g.,::
-
-  python simple_plot.py -dmodule://my_backend
-
-If your backend implements support for saving figures (i.e. has a print_xyz()
-method) you can register it as the default handler for a given file type
-
-  from matplotlib.backend_bases import register_backend
-  register_backend('xyz', 'my_backend', 'XYZ File Format')
-  ...
-  plt.savefig("figure.xyz")
-
-The files that are most relevant to backend_writers are
-
-  matplotlib/backends/backend_your_backend.py
-  matplotlib/backend_bases.py
-  matplotlib/backends/__init__.py
-  matplotlib/__init__.py
-  matplotlib/_pylab_helpers.py
-
-Naming Conventions
-
-  * classes Upper or MixedUpperCase
-
-  * variables lower or lowerUpper
-
-  * functions lower or underscore_separated
-
+This is a fully functional do nothing backend to provide a template to backend
+writers.  It is fully functional in that you can select it as a backend e.g.
+with ::
+
+    import matplotlib
+    matplotlib.use("template")
+
+and your program will (should!) run without error, though no output is
+produced.  This provides a starting point for backend writers; you can
+selectively implement drawing methods (`draw_path`, `draw_image`, etc.) and
+slowly see your figure come to life instead having to have a full blown
+implementation before getting any results.
+
+Copy this file to a directory outside of the Matplotlib source tree, somewhere
+where Python can import it (by adding the directory to your ``sys.path`` or by
+packaging it as a normal Python package); if the backend is importable as
+``import my.backend`` you can then select it using ::
+
+    import matplotlib
+    matplotlib.use("module://my.backend")
+
+If your backend implements support for saving figures (i.e. has a `print_xyz`
+method), you can register it as the default handler for a given file type::
+
+    from matplotlib.backend_bases import register_backend
+    register_backend('xyz', 'my_backend', 'XYZ File Format')
+    ...
+    plt.savefig("figure.xyz")
 """
 
 from matplotlib._pylab_helpers import Gcf
@@ -73,10 +40,12 @@ class RendererTemplate(RendererBase):
     The renderer handles drawing/rendering operations.
 
     This is a minimal do-nothing class that can be used to get started when
-    writing a new backend. Refer to backend_bases.RendererBase for
-    documentation of the classes methods.
+    writing a new backend.  Refer to `backend_bases.RendererBase` for
+    documentation of the methods.
     """
+
     def __init__(self, dpi):
+        super().__init__()
         self.dpi = dpi
 
     def draw_path(self, gc, path, transform, rgbFace=None):
@@ -160,11 +129,12 @@ class GraphicsContextTemplate(GraphicsContextBase):
 
 ########################################################################
 #
-# The following functions and classes are for pylab and implement
+# The following functions and classes are for pyplot and implement
 # window/figure managers, etc...
 #
 ########################################################################
 
+
 def draw_if_interactive():
     """
     For image backends - is not required.
@@ -186,9 +156,7 @@ def show(*, block=None):
 
 
 def new_figure_manager(num, *args, FigureClass=Figure, **kwargs):
-    """
-    Create a new figure manager instance
-    """
+    """Create a new figure manager instance."""
     # If a main-level app must be created, this (and
     # new_figure_manager_given_figure) is the usual place to do it -- see
     # backend_wx, backend_wxagg and backend_tkagg for examples.  Not all GUIs
@@ -199,9 +167,7 @@ def new_figure_manager(num, *args, FigureClass=Figure, **kwargs):
 
 
 def new_figure_manager_given_figure(num, figure):
-    """
-    Create a new figure manager instance for the given figure.
-    """
+    """Create a new figure manager instance for the given figure."""
     canvas = FigureCanvasTemplate(figure)
     manager = FigureManagerTemplate(canvas, num)
     return manager
@@ -225,9 +191,7 @@ class methods button_press_event, button_release_event,
     """
 
     def draw(self):
-        """
-        Draw the figure using the renderer
-        """
+        """Draw the figure using the renderer."""
         renderer = RendererTemplate(self.figure.dpi)
         self.figure.draw(renderer)
 
@@ -245,19 +209,18 @@ def print_foo(self, filename, *args, **kwargs):
         to their original values after this call, so you don't need to
         save and restore them.
         """
-        pass
 
     def get_default_filetype(self):
         return 'foo'
 
 
 class FigureManagerTemplate(FigureManagerBase):
     """
-    Wrap everything up into a window for the pylab interface
+    Helper class for pyplot mode, wraps everything up into a neat bundle.
 
-    For non interactive backends, the base class does all the work
+    For non-interactive backends, the base class is sufficient.
     """
-    pass
+
 
 ########################################################################
 #
diff --git a/lib/matplotlib/patheffects.py b/lib/matplotlib/patheffects.py
@@ -93,10 +93,6 @@ def __init__(self, path_effects, renderer):
         self._path_effects = path_effects
         self._renderer = renderer
 
-    def new_gc(self):
-        # docstring inherited
-        return self._renderer.new_gc()
-
     def copy_with_path_effect(self, path_effects):
         return self.__class__(path_effects, self._renderer)
 
@@ -143,10 +139,6 @@ def draw_path_collection(self, gc, master_transform, paths, *args,
             renderer.draw_path_collection(gc, master_transform, paths,
                                           *args, **kwargs)
 
-    def points_to_pixels(self, points):
-        # docstring inherited
-        return self._renderer.points_to_pixels(points)
-
     def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath):
         # Implements the naive text drawing as is found in RendererBase.
         path, transform = self._get_text_path_transform(x, y, s, prop,
@@ -156,7 +148,8 @@ def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath):
         self.draw_path(gc, path, transform, rgbFace=color)
 
     def __getattribute__(self, name):
-        if name in ['_text2path', 'flipy', 'height', 'width']:
+        if name in ['flipy', 'get_canvas_width_height', 'new_gc',
+                    'points_to_pixels', '_text2path', 'height', 'width']:
             return getattr(self._renderer, name)
         else:
             return object.__getattribute__(self, name)
