Improved backend specification

efiring · efiring · commit 6715f4cc0548 · 2007-07-06T19:35:25.000Z
svn path=/trunk/matplotlib/; revision=3472
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -776,28 +776,28 @@ def rcdefaults():
     """
     rcParams.update(rcParamsDefault)
 
-# Now allow command line to override
-
-# Allow command line access to the backend with -d (matlab compatible
-# flag)
-
-for s in sys.argv[1:]:
-    if s.startswith('-d') and len(s) > 2:  # look for a -d flag
-        be_parts = s[2:].split('.')
-        try:
-            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])
-        except (KeyError, ValueError):
-            pass
-        # we don't want to assume all -d flags are backends, eg -debug
 
 def use(arg):
     """
-    Set the matplotlib backend to one of the known backends
+    Set the matplotlib backend to one of the known backends.
+
+    The argument is case-insensitive.  For the Cairo backend,
+    the argument can have an extension to indicate the type of
+    output.  Example:
+
+        use('cairo.pdf')
+
+    will specify a default of pdf output generated by Cairo.
+
+    Note: this function must be called *before* importing pylab
+    for the first time; or, if you are not using pylab, it must
+    be called before importing matplotlib.backends.
     """
-    rcParams['backend'] = validate_backend(arg)
+    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])
 
 def get_backend():
     return rcParams['backend']
@@ -823,6 +823,18 @@ def tk_window_focus():
         return False
     return rcParams['tk.window_focus']
 
+# Now allow command line to override
+
+# Allow command line access to the backend with -d (matlab compatible
+# flag)
+
+for s in sys.argv[1:]:
+    if s.startswith('-d') and len(s) > 2:  # look for a -d flag
+        try:
+            use(s[2:])
+        except (KeyError, ValueError):
+            pass
+        # we don't want to assume all -d flags are backends, eg -debug
 
 
 verbose.report('matplotlib version %s'%__version__)
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -244,6 +244,8 @@ numerix      : numpy  # numpy, Numeric or numarray
 #savefig.facecolor : white    # figure facecolor when saving
 #savefig.edgecolor : white    # figure edgecolor when saving
 
+#cairo.format      : png      # png, ps, pdf, svg
+
 # tk backend params
 #tk.window_focus   : False    # Maintain shell focus for TkAgg
 #tk.pythoninspect  : False    # tk sets PYTHONINSEPCT
