8000 allow selecting the backend by setting the environment variable MPLBACKEND by FlorianRhiem · Pull Request #3710 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

allow selecting the backend by setting the environment variable MPLBACKEND #3710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 18, 2014
Merged

allow selecting the backend by setting the environment variable MPLBACKEND #3710

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0d995d4
allow selecting the backend by setting the environment variable MPL_B…
FlorianRhiem Oct 23, 2014
0ead4b2
added documentation on backend selection methods
FlorianRhiem Oct 27, 2014
fffa9c1
minor fix for the documentation on backend selection methods (either …
FlorianRhiem Oct 28, 2014
7290dc1
DOC : edits to copy of usage_faq.rst
tacaswell Oct 28, 2014
0042453
Added a warning about global use of MPLBACKEND or use of -dbackend
FlorianRhiem Nov 18, 2014
40e4019
Added mplDeprecation warning when the -d argument is used. Minor impr…
FlorianRhiem Nov 18, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
DOC : edits to copy of usage_faq.rst 
Made how to set backend an ordered list
  • Loading branch information
@tacaswell @FlorianRhiem
tacaswell authored and FlorianRhiem committed Nov 17, 2014
commit 7290dc1d3546a1cba4ba0afcd4440454c87fe60a
48 changes: 26 additions & 22 deletions doc/faq/usage_faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"reversed order of precedence" when I think of "reversed order", I am usually thinking of things decreasing. This could be reworded better.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@WeatherGod How about this:

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 settings in your ``matplotlibrc``.

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`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am ambivalent about advertising this feature. I do see the warning below, but I'd much rather go the route of deprecating this feature in favor of the environment variable.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah -- maybe we should start the deprecation process for this now?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the idea of completely leaving -d out of the documentation as long as it still works. How about replacing the previous warning about issue 1986 with the following:

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.

Should using the -d flag also cause a runtime warning?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes please

On Tue, Nov 18, 2014 at 11:29 AM, Florian Rhiem notifications@github.com
wrote:

In doc/faq/usage_faq.rst:

-If you use the use directive, this must be done before importing
-:mod:matplotlib.pyplot or :mod:matplotlib.pylab.

  •    > 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

I don't like the idea of completely leaving -d out of the documentation
as long as it is still supported. How about replacing the previous warning
about issue 1986 #1986
with the following:

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.

Should using the -d flag also cause a runtime warning?

—
Reply to this email directly or view it on GitHub
https://github.com/matplotlib/matplotlib/pull/3710/files#r20517466.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should probably raise a mplDeprecation warning. Like #3812

command line argument::

You should be aware though that this might conflict with scripts which use the
command line arguments.
> python script.py -dbackend
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

space


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 <https://github.com/matplotlib/matplotlib/issues/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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comma to period, and "calling" --> "Calling"

has been imported will have no effect. Using `use` will
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

double backticks? or should it be single backticks earlier in this paragraph?

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'
Expand Down
0