diff --git a/CHANGELOG b/CHANGELOG index 4a1b1e45079d..28f743d13221 100644 --- a/CHANGELOG +++ b/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 diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 0d5eee9c6160..2ed7a0309720 100644 --- a/doc/devel/coding_guide.rst +++ b/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: diff --git a/doc/faq/environment_variables_faq.rst b/doc/faq/environment_variables_faq.rst index bcad4cb25635..eee47046be71 100644 --- a/doc/faq/environment_variables_faq.rst +++ b/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 diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst index c03454adbf2f..7fc6b83441b1 100644 --- a/doc/faq/usage_faq.rst +++ b/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 `_). 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 diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst index 5cc2832717e4..daf53fe68249 100644 --- a/doc/users/whats_new.rst +++ b/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 diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 076895866604..2cdb5117fb48 100644 --- a/lib/matplotlib/__init__.py +++ b/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',