From 0d995d45ea5e48fc8e3aa60e577db006871895bf Mon Sep 17 00:00:00 2001 From: Florian Rhiem Date: Thu, 23 Oct 2014 16:55:28 +0200 Subject: [PATCH 1/6] allow selecting the backend by setting the environment variable MPL_BACKEND --- lib/matplotlib/__init__.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 076895866604..765c221ecd29 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -1373,9 +1373,18 @@ def tk_window_focus(): if s.startswith(str('-d')) and len(s) > 2: # look for a -d flag try: use(s[2:]) + 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 MPL_BACKEND + if 'MPL_BACKEND' in os.environ: + try: + use(os.environ['MPL_BACKEND']) + except (KeyError, ValueError): + pass default_test_modules = [ 'matplotlib.tests.test_agg', From 0ead4b2862fc91613bc8f17e1979ec750f076964 Mon Sep 17 00:00:00 2001 From: Florian Rhiem Date: Mon, 27 Oct 2014 11:09:02 +0100 Subject: [PATCH 2/6] added documentation on backend selection methods --- CHANGELOG | 3 +++ doc/devel/coding_guide.rst | 15 ++++++++++----- doc/faq/environment_variables_faq.rst | 6 ++++++ doc/faq/usage_faq.rst | 26 ++++++++++++++++++++++---- doc/users/whats_new.rst | 7 +++++++ lib/matplotlib/__init__.py | 11 +++++------ 6 files changed, 53 insertions(+), 15 deletions(-) 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..fe832e0231d0 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 is 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..884f7a7e291e 100644 --- a/doc/faq/usage_faq.rst +++ b/doc/faq/usage_faq.rst @@ -302,19 +302,37 @@ 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 +There are a four ways to configure your backend. One is to set the ``backend`` parameter in your ``matplotlibrc`` file (see :ref:`customizing-matplotlib`):: backend : WXAgg # use wxpython with antigrain (agg) rendering -The other is to use the matplotlib :func:`~matplotlib.use` directive:: +Another way to do this is setting the :envvar:`MPLBACKEND` environment +variable, either globally or for a single script:: + + > export MPLBACKEND="module://my_backend" + > python simple_plot.py + +To set the backend for a single script, you can alternatively use the `-d` +command line argument:: + + > python script.py -dbackend + +You should be aware though that this might conflict with scripts which use the +command line arguments. + +If your script depends on a specific backend you can use the matplotlib +:func:`~matplotlib.use` directive:: import matplotlib matplotlib.use('PS') # generate postscript output by default If you use the ``use`` directive, this must be done before importing -:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`. +:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`. Using this function will +require a change in your code for users who would like to use a different +backend. Therefore you should avoid explicitly calling ``use`` unless +necessary. .. note:: Backend name specifications are not case-sensitive; e.g., 'GTKAgg' @@ -325,7 +343,7 @@ 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. +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 765c221ecd29..ee4517526cc9 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -1379,12 +1379,11 @@ def tk_window_focus(): # 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 MPL_BACKEND - if 'MPL_BACKEND' in os.environ: - try: - use(os.environ['MPL_BACKEND']) - except (KeyError, ValueError): - pass + # variable MPLBACKEND + try: + use(os.environ['MPLBACKEND']) + except (KeyError, ValueError): + pass default_test_modules = [ 'matplotlib.tests.test_agg', From fffa9c1888215d5935f5e3aae2ec93b620083dab Mon Sep 17 00:00:00 2001 From: Florian Rhiem Date: Tue, 28 Oct 2014 15:32:43 +0100 Subject: [PATCH 3/6] minor fix for the documentation on backend selection methods (either of the methods -> any of the methods) --- doc/faq/usage_faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst index 884f7a7e291e..0399a94db713 100644 --- a/doc/faq/usage_faq.rst +++ b/doc/faq/usage_faq.rst @@ -342,7 +342,7 @@ 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 +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 From 7290dc1d3546a1cba4ba0afcd4440454c87fe60a Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Tue, 28 Oct 2014 12:42:16 -0400 Subject: [PATCH 4/6] DOC : edits to copy of usage_faq.rst Made how to set backend an ordered list --- doc/faq/usage_faq.rst | 48 +++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst index 0399a94db713..21e7a00fc043 100644 --- a/doc/faq/usage_faq.rst +++ b/doc/faq/usage_faq.rst @@ -302,37 +302,41 @@ 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 four 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, in reversed order +of precedence: - backend : WXAgg # use wxpython with antigrain (agg) rendering +#. The ``backend`` parameter in your ``matplotlibrc`` file (see + :ref:`customizing-matplotlib`):: -Another way to do this is setting the :envvar:`MPLBACKEND` environment -variable, either globally or for a single script:: + backend : WXAgg # use wxpython with antigrain (agg) rendering - > export MPLBACKEND="module://my_backend" - > python simple_plot.py +#. Setting the :envvar:`MPLBACKEND` environment + variable, either globally or for a single script:: -To set the backend for a single script, you can alternatively use the `-d` -command line argument:: + > export MPLBACKEND="module://my_backend" + > python simple_plot.py - > python script.py -dbackend +#. To set the backend for a single script, you can alternatively use the `-d` + command line argument:: -You should be aware though that this might conflict with scripts which use the -command line arguments. + > python script.py -dbackend -If your script depends on a specific backend you can use the matplotlib -:func:`~matplotlib.use` directive:: + This might conflict with scripts which parse + command line arguments (see issue + `#1986 `_). - import matplotlib - matplotlib.use('PS') # generate postscript output by default +#. If your script depends on a specific backend you can use the + :func:`~matplotlib.use` function:: -If you use the ``use`` directive, this must be done before importing -:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`. Using this function will -require a change in your code for users who would like to use a different -backend. Therefore you should avoid explicitly calling ``use`` unless -necessary. + import matplotlib + matplotlib.use('PS') # generate postscript output by default + + If you use the ``use``, this must be done before importing + :mod:`matplotlib.pyplot`, calling :func:`~matplotlib.use` after pyplot + has been imported will have no effect. Using `use` will + require changes in your code if users want to use a different + backend. Therefore, you should avoid explicitly calling ``use`` unless + absolutely necessary. .. note:: Backend name specifications are not case-sensitive; e.g., 'GTKAgg' From 004245334429fb51789097f119b3ce45db90e62b Mon Sep 17 00:00:00 2001 From: Florian Rhiem Date: Tue, 18 Nov 2014 09:09:31 +0100 Subject: [PATCH 5/6] Added a warning about global use of MPLBACKEND or use of -dbackend --- doc/faq/usage_faq.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst index 21e7a00fc043..c4a704cdabc7 100644 --- a/doc/faq/usage_faq.rst +++ b/doc/faq/usage_faq.rst @@ -311,11 +311,19 @@ of precedence: backend : WXAgg # use wxpython with antigrain (agg) rendering #. Setting the :envvar:`MPLBACKEND` environment - variable, either globally or for a single script:: + 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:: @@ -323,7 +331,8 @@ of precedence: This might conflict with scripts which parse command line arguments (see issue - `#1986 `_). + `#1986 `_), so you + should use :envvar:`MPLBACKEND` instead. #. If your script depends on a specific backend you can use the :func:`~matplotlib.use` function:: From 40e40193b37d14afbbac7093a552dbb7d021250e Mon Sep 17 00:00:00 2001 From: Florian Rhiem Date: Tue, 18 Nov 2014 17:45:34 +0100 Subject: [PATCH 6/6] Added mplDeprecation warning when the -d argument is used. Minor improvements to the backend selection documentation. --- doc/devel/coding_guide.rst | 2 +- doc/faq/usage_faq.rst | 24 +++++++++++++----------- lib/matplotlib/__init__.py | 6 +++++- 3 files changed, 19 insertions(+), 13 deletions(-) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index fe832e0231d0..2ed7a0309720 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -280,7 +280,7 @@ external backend via the ``module`` directive. if > python simple_plot.py -dmodule://my_backend -* with the use directive is your script:: +* with the use directive in your script:: import matplotlib matplotlib.use('module://my_backend') diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst index c4a704cdabc7..7fc6b83441b1 100644 --- a/doc/faq/usage_faq.rst +++ b/doc/faq/usage_faq.rst @@ -302,8 +302,10 @@ 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 four ways to configure your backend, in reversed order -of precedence: +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``. + #. The ``backend`` parameter in your ``matplotlibrc`` file (see :ref:`customizing-matplotlib`):: @@ -329,9 +331,9 @@ of precedence: > python script.py -dbackend - This might conflict with scripts which parse - command line arguments (see issue - `#1986 `_), so you + 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 @@ -340,12 +342,12 @@ of precedence: import matplotlib matplotlib.use('PS') # generate postscript output by default - If you use the ``use``, this must be done before importing - :mod:`matplotlib.pyplot`, calling :func:`~matplotlib.use` after pyplot - has been imported will have no effect. Using `use` will - require changes in your code if users want to use a different - backend. Therefore, you should avoid explicitly calling ``use`` unless - absolutely necessary. + 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' diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index ee4517526cc9..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,6 +1373,10 @@ 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