added support for external backends

jdh2358 · jdh2358 · commit 032cc0cd8b01 · 2008-07-12T21:33:54.000Z
svn path=/trunk/matplotlib/; revision=5754
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,6 @@
+2008-07-12 Added support for external backends with the
+           "module://my_backend" syntax - JDH
+
 2008-07-11 Fix memory leak related to shared axes.  Grouper should
            store weak references. - MGD
 
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -801,8 +801,11 @@ def use(arg, warn=True):
         if warn: warnings.warn(_use_error_msg)
         return
     arg = arg.lower()
-    be_parts = arg.split('.')
-    name = validate_backend(be_parts[0])
+    if arg.startswith('module://'):
+        name = arg
+    else:
+        be_parts = arg.split('.')
+        name = validate_backend(be_parts[0])
     rcParams['backend'] = name
     if name == 'cairo' and len(be_parts) > 1:
         rcParams['cairo.format'] = validate_cairo_format(be_parts[1])
diff --git a/lib/matplotlib/backends/__init__.py b/lib/matplotlib/backends/__init__.py
@@ -1,9 +1,6 @@
 
 import matplotlib
-from matplotlib.rcsetup import interactive_bk
-from matplotlib.rcsetup import non_interactive_bk
-from matplotlib.rcsetup import all_backends
-from matplotlib.rcsetup import validate_backend
+
 
 __all__ = ['backend','show','draw_if_interactive',
            'new_figure_manager', 'backend_version']
@@ -14,27 +11,23 @@ def pylab_setup():
     'return new_figure_manager, draw_if_interactive and show for pylab'
     # Import the requested backend into a generic module object
 
-    backend_name = 'backend_'+backend
-    backend_name = backend_name.lower() # until we banish mixed case
-    backend_mod = __import__('matplotlib.backends.'+backend_name,
+    if backend.startswith('module://'):
+        backend_name = backend[9:]
+    else:
+        backend_name = 'backend_'+backend
+        backend_name = backend_name.lower() # until we banish mixed case
+        backend_name = 'matplotlib.backends.%s'%backend_name.lower()
+    backend_mod = __import__(backend_name,
                              globals(),locals(),[backend_name])
 
     # Things we pull in from all backends
     new_figure_manager = backend_mod.new_figure_manager
 
-    if hasattr(backend_mod,'backend_version'):
-        backend_version = getattr(backend_mod,'backend_version')
-    else: backend_version = 'unknown'
-
-
 
-    # Now define the public API according to the kind of backend in use
-    if backend in interactive_bk:
-        show = backend_mod.show
-        draw_if_interactive = backend_mod.draw_if_interactive
-    else:  # non-interactive backends
-        def draw_if_interactive():  pass
-        def show(): pass
+    def do_nothing(*args, **kwargs): pass
+    backend_version = getattr(backend_mod,'backend_version', 'unknown')
+    show = getattr(backend_mod, 'show', do_nothing)
+    draw_if_interactive = getattr(backend_mod, 'draw_if_interactive', do_nothing)
 
     # Additional imports which only happen for certain backends.  This section
     # should probably disappear once all backends are uniform.
diff --git a/lib/matplotlib/backends/backend_template.py b/lib/matplotlib/backends/backend_template.py
@@ -17,14 +17,25 @@
 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 methon in
-matplotlib/__init__.py and you're off.  You can use your backend with
+matplotlib/__init__.py and you're off.  You can use your backend with::
 
   import matplotlib
   matplotlib.use('xxx')
   from pylab import *
   plot([1,2,3])
   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.  Thus syntax is also
+recognized in the rc file and in the -d argument in pylab, eg::
+
+  python simple_plot.py -dmodule://my_backend
+
 The files that are most relevant to backend_writers are
 
   matplotlib/backends/backend_your_backend.py
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -19,8 +19,12 @@
 # such as 0.75 - a legal html color name, eg red, blue, darkslategray
 
 #### CONFIGURATION BEGINS HERE
+
 # the default backend; one of GTK GTKAgg GTKCairo CocoaAgg FltkAgg
-# QtAgg Qt4Agg  TkAgg WX WXAgg Agg Cairo GDK PS PDF SVG Template
+# QtAgg Qt4Agg TkAgg WX WXAgg Agg Cairo GDK PS PDF SVG Template You
+# can also deploy your own backend outside of matplotlib by referring
+# to the module name (which must be in the PYTHONPATH) as
+# 'module://my_backend'
 backend      : %(backend)s
 numerix      : %(numerix)s  # numpy, Numeric or numarray
 #maskedarray : False       # True to use external maskedarray module
