Merge pull request #3710 from FlorianRhiem/master

allow selecting the backend by setting the environment variable MPLBACKEND

CHANGELOG

@@ -1,3 +1,6 @@
+2014-10-27 Allowed selection of the backend using the `MPLBACKEND` environment
+           variable. Added documentation on backend selection methods.
+
 2014-09-27 Overhauled `colors.LightSource`.  Added `LightSource.hillshade` to
 	   allow the independent generation of illumination maps. Added new
 	   types of blending for creating more visually appealing shaded relief

doc/devel/coding_guide.rst

@@ -270,15 +270,20 @@ external backend via the ``module`` directive.  if
 
     backend : module://my_backend
 
-* with the use directive is your script::
 
-    import matplotlib
-    matplotlib.use('module://my_backend')
+* with the :envvar:`MPLBACKEND` environment variable::
+
+    > export MPLBACKEND="module://my_backend"
+    > python simple_plot.py
 
-* from the command shell with the -d flag::
+* from the command shell with the `-d` flag::
 
-    > python simple_plot.py -d module://my_backend
+    > python simple_plot.py -dmodule://my_backend
 
+* with the use directive in your script::
+
+    import matplotlib
+    matplotlib.use('module://my_backend')
 
 .. _sample-data:
 

doc/faq/environment_variables_faq.rst

@@ -30,6 +30,12 @@ Environment Variables
   used to find a base directory in which the :file:`matplotlib`
   subdirectory is created.
 
+.. envvar:: MPLBACKEND
+
+  This optional variable can be set to choose the matplotlib backend. Using the
+  `-d` command line parameter or the :func:`~matplotlib.use` function will
+  override this value. See :ref:`what-is-a-backend`.
+
 .. _setting-linux-osx-environment-variables:
 
 Setting environment variables in Linux and OS-X

doc/faq/usage_faq.rst

@@ -302,19 +302,52 @@ pygtk, wxpython, tkinter, qt4, or macosx; also referred to as
 "interactive backends") and hardcopy backends to make image files
 (PNG, SVG, PDF, PS; also referred to as "non-interactive backends").
 
-There are a two primary ways to configure your backend.  One is to set
-the ``backend`` parameter in your ``matplotlibrc`` file (see
-:ref:`customizing-matplotlib`)::
+There are a four ways to configure your backend. If they conflict each other,
+the method mentioned last in the following list will be used, e.g. calling
+:func:`~matplotlib.use()` will override the setting in your ``matplotlibrc``.
 
-    backend : WXAgg   # use wxpython with antigrain (agg) rendering
 
-The other is to use the matplotlib :func:`~matplotlib.use` directive::
+#. The ``backend`` parameter in your ``matplotlibrc`` file (see
+   :ref:`customizing-matplotlib`)::
 
-    import matplotlib
-    matplotlib.use('PS')   # generate postscript output by default
+       backend : WXAgg   # use wxpython with antigrain (agg) rendering
 
-If you use the ``use`` directive, this must be done before importing
-:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
+#. Setting the :envvar:`MPLBACKEND` environment
+   variable, either for your current shell or for a single script::
+
+        > export MPLBACKEND="module://my_backend"
+        > python simple_plot.py
+
+        > MPLBACKEND="module://my_backend" python simple_plot.py
+
+   Setting this environment variable will override the ``backend`` parameter
+   in *any* ``matplotlibrc``, even if there is a ``matplotlibrc`` in your
+   current working directory. Therefore setting :envvar:`MPLBACKEND`
+   globally, e.g. in your ``.bashrc`` or ``.profile``, is discouraged as it
+   might lead to counter-intuitive behavior.
+
+#. To set the backend for a single script, you can alternatively use the `-d`
+   command line argument::
+
+       > python script.py -dbackend
+
+   This method is **deprecated** as the `-d` argument might conflict with
+   scripts which parse command line arguments (see issue
+   `#1986 <https://github.com/matplotlib/matplotlib/issues/1986>`_). You
+   should use :envvar:`MPLBACKEND` instead.
+
+#. If your script depends on a specific backend you can use the
+   :func:`~matplotlib.use` function::
+
+      import matplotlib
+      matplotlib.use('PS')   # generate postscript output by default
+
+   If you use the :func:`~matplotlib.use` function, this must be done before
+   importing :mod:`matplotlib.pyplot`. Calling :func:`~matplotlib.use` after
+   pyplot has been imported will have no effect.  Using
+   :func:`~matplotlib.use` will require changes in your code if users want to
+   use a different backend.  Therefore, you should avoid explicitly calling
+   :func:`~matplotlib.use` unless absolutely necessary.
 
 .. note::
    Backend name specifications are not case-sensitive; e.g., 'GTKAgg'
@@ -324,8 +357,8 @@ With a typical installation of matplotlib, such as from a
 binary installer or a linux distribution package, a good default
 backend will already be set, allowing both interactive work and
 plotting from scripts, with output to the screen and/or to
-a file, so at least initially you will not need to use either of the
-two methods given above.
+a file, so at least initially you will not need to use any of the
+methods given above.
 
 If, however, you want to write graphical user interfaces, or a web
 application server (:ref:`howto-webapp`), or need a better

doc/users/whats_new.rst

@@ -60,6 +60,13 @@ Added a :code:`pivot` kwarg to :func:`~mpl_toolkits.mplot3d.Axes3D.quiver`
 that controls the pivot point around which the quiver line rotates. This also
 determines the placement of the arrow head along the quiver line.
 
+New backend selection
+---------------------
+
+The environment variable :envvar:`MPLBACKEND` can now be used to set the
+matplotlib backend.
+
+
 .. _whats-new-1-4:
 
 new in matplotlib-1.4

lib/matplotlib/__init__.py

@@ -180,7 +180,7 @@ def _forward_ilshift(self, other):
 
 # cbook must import matplotlib only within function
 # definitions, so it is safe to import from it here.
-from matplotlib.cbook import is_string_like
+from matplotlib.cbook import is_string_like, mplDeprecation
 from matplotlib.compat import subprocess
 
 try:
@@ -1373,9 +1373,21 @@ def tk_window_focus():
     if s.startswith(str('-d')) and len(s) > 2:  # look for a -d flag
         try:
             use(s[2:])
+            warnings.warn("Using the -d command line argument to select a "
+                          "matplotlib backend is deprecated. Please use the "
+                          "MPLBACKEND environment variable instead.",
+                          mplDeprecation)
+            break
         except (KeyError, ValueError):
             pass
         # we don't want to assume all -d flags are backends, e.g., -debug
+else:
+    # no backend selected from the command line, so we check the environment
+    # variable MPLBACKEND
+    try:
+        use(os.environ['MPLBACKEND'])
+    except (KeyError, ValueError):
+        pass
 
 default_test_modules = [
     'matplotlib.tests.test_agg',