8000 Merge pull request #3710 from FlorianRhiem/master · pelson/matplotlib@180c6d8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 180c6d8

Browse files
WeatherGodWeatherGod
committed
Merge pull request matplotlib#3710 from FlorianRhiem/master
allow selecting the backend by setting the environment variable MPLBACKEND
2 parents d045fef + 40e4019 commit 180c6d8

File tree

6 files changed

+83
-17
lines changed

6 files changed

+83
-17
lines changed

‎CHANGELOG

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
2014-10-27 Allowed selection of the backend using the `MPLBACKEND` environment
2+
variable. Added documentation on backend selection methods.
3+
14
2014-09-27 Overhauled `colors.LightSource`. Added `LightSource.hillshade` to
25
allow the independent generation of illumination maps. Added new
36
types of blending for creating more visually appealing shaded relief

‎doc/devel/coding_guide.rst

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -270,15 +270,20 @@ external backend via the ``module`` directive. if
270270

271271
backend : module://my_backend
272272

273-
* with the use directive is your script::
274273

275-
import matplotlib
276-
matplotlib.use('module://my_backend')
274+
* with the :envvar:`MPLBACKEND` environment variable::
275+
276+
> export MPLBACKEND="module://my_backend"
277+
> python simple_plot.py
277278

278-
* from the command shell with the -d flag::
279+
* from the command shell with the `-d` flag::
279280

280-
> python simple_plot.py -d module://my_backend
281+
> python simple_plot.py -dmodule://my_backend
281282

283+
* with the use directive in your script::
284+
285+
import matplotlib
286+
matplotlib.use('module://my_backend')
282287

283288
.. _sample-data:
284289

‎doc/faq/environment_variables_faq.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,12 @@ Environment Variables
3030
used to find a base directory in which the :file:`matplotlib`
3131
subdirectory is created.
3232

33+
.. envvar:: MPLBACKEND
34+
35+
This optional variable can be set to choose the matplotlib backend. Using the
36+
`-d` command line parameter or the :func:`~matplotlib.use` function will
37+
override this value. See :ref:`what-is-a-backend`.
38+
3339
.. _setting-linux-osx-environment-variables:
3440

3541
Setting environment variables in Linux and OS-X

‎doc/faq/usage_faq.rst

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -302,19 +302,52 @@ pygtk, wxpython, tkinter, qt4, or macosx; also referred to as
302302
"interactive backends") and hardcopy backends to make image files
303303
(PNG, SVG, PDF, PS; also referred to as "non-interactive backends").
304304

305-
There are a two primary ways to configure your backend. One is to set
306-
the ``backend`` parameter in your ``matplotlibrc`` file (see
307-
:ref:`customizing-matplotlib`)::
305+
There are a four ways to configure your backend. If they conflict each other,
306+
the method mentioned last in the following list will be used, e.g. calling
307+
:func:`~matplotlib.use()` will override the setting in your ``matplotlibrc``.
308308

309-
backend : WXAgg # use wxpython with antigrain (agg) rendering
310309

311-
The other is to use the matplotlib :func:`~matplotlib.use` directive::
310+
#. The ``backend`` parameter in your ``matplotlibrc`` file (see
311+
:ref:`customizing-matplotlib`)::
312312

313-
import matplotlib
314-
matplotlib.use('PS') # generate postscript output by default
313+
backend : WXAgg # use wxpython with antigrain (agg) rendering
315314

316-
If you use the ``use`` directive, this must be done before importing
317-
:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
315+
#. Setting the :envvar:`MPLBACKEND` environment
316+
variable, either for your current shell or for a single script::
317+
318+
> export MPLBACKEND="module://my_backend"
319+
> python simple_plot.py
320+
321+
> MPLBACKEND="module://my_backend" python simple_plot.py
322+
323+
Setting this environment variable will override the ``backend`` parameter
324+
in *any* ``matplotlibrc``, even if there is a ``matplotlibrc`` in your
325+
current working directory. Therefore setting :envvar:`MPLBACKEND`
326+
globally, e.g. in your ``.bashrc`` or ``.profile``, is discouraged as it
327+
might lead to counter-intuitive behavior.
328+
329+
#. To set the backend for a single script, you can alternatively use the `-d`
330+
command line argument::
331+
332+
> python script.py -dbackend
333+
334+
This method is **deprecated** as the `-d` argument might conflict with
335+
scripts which parse command line arguments (see issue
336+
`#1986 <https://github.com/matplotlib/matplotlib/issues/1986>`_). You
337+
should use :envvar:`MPLBACKEND` instead.
338+
339+
#. If your script depends on a specific backend you can use the
340+
:func:`~matplotlib.use` function::
341+
342+
import matplotlib
343+
matplotlib.use('PS') # generate postscript output by default
344+
345+
If you use the :func:`~matplotlib.use` function, this must be done before
346+
importing :mod:`matplotlib.pyplot`. Calling :func:`~matplotlib.use` after
347+
pyplot has been imported will have no effect. Using
348+
:func:`~matplotlib.use` will require changes in your code if users want to
349+
use a different backend. Therefore, you should avoid explicitly calling
350+
:func:`~matplotlib.use` unless absolutely necessary.
318351

319352
.. note::
320353
Backend name specifications are not case-sensitive; e.g., 'GTKAgg'
@@ -324,8 +357,8 @@ With a typical installation of matplotlib, such as from a
324357
binary installer or a linux distribution package, a good default
325358
backend will already be set, allowing both interactive work and
326359
plotting from scripts, with output to the screen and/or to
327-
a file, so at least initially you will not need to use either of the
328-
two methods given above.
360+
a file, so at least initially you will not need to use any of the
361+
methods given above.
329362

330363
If, however, you want to write graphical user interfaces, or a web
331364
application server (:ref:`howto-webapp`), or need a better

‎doc/users/whats_new.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,13 @@ Added a :code:`pivot` kwarg to :func:`~mpl_toolkits.mplot3d.Axes3D.quiver`
6060
that controls the pivot point around which the quiver line rotates. This also
6161
determines the placement of the arrow head along the quiver line.
6262

63+
New backend selection
64+
---------------------
65+
66+
The environment variable :envvar:`MPLBACKEND` can now be used to set the
67+
matplotlib backend.
68+
69+
6370
.. _whats-new-1-4:
6471

6572
new in matplotlib-1.4

‎lib/matplotlib/__init__.py

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ def _forward_ilshift(self, other):
180180

181181
# cbook must import matplotlib only within function
182182
# definitions, so it is safe to import from it here.
183-
from matplotlib.cbook import is_string_like
183+
from matplotlib.cbook import is_string_like, mplDeprecation
184184
from matplotlib.compat import subprocess
185185

186186
try:
@@ -1373,9 +1373,21 @@ def tk_window_focus():
13731373
if s.startswith(str('-d')) and len(s) > 2: # look for a -d flag
13741374
try:
13751375
use(s[2:])
1376+
warnings.warn("Using the -d command line argument to select a "
1377+
"matplotlib backend is deprecated. Please use the "
1378+
"MPLBACKEND environment variable instead.",
1379+
mplDeprecation)
1380+
break
13761381
except (KeyError, ValueError):
13771382
pass
13781383
# we don't want to assume all -d flags are backends, e.g., -debug
1384+
else:
1385+
# no backend selected from the command line, so we check the environment
1386+
# variable MPLBACKEND
1387+
try:
1388+
use(os.environ['MPLBACKEND'])
1389+
except (KeyError, ValueError):
1390+
pass
13791391

13801392
default_test_modules = [
13811393
'matplotlib.tests.test_agg',

0 commit comments

Comments
 (0)
0