allow selecting the backend by setting the environment variable MPLBACKEND

[FlorianRhiem]

This commit adds a new way of selecting the matplotlib backend. The -d flag can cause problems with scripts that use the command line arguments as parameters and don't ignore unknown ones. An environment variable MPL_BACKEND can be set by the user (or in the code) and is far less likely to cause problems than using the -d flag.

[tacaswell]

Interesting, we look at envs when setting up the QT backend stuff, I assumed we already had something that did this...

[WeatherGod]

Another reason to like this... explicit setting of backends can be
difficult when third-party packages imports matplotlib prior to your
import. Of course, then there is the matplotlibrc file where one could set
this, so I think there needs to be careful consideration of what should
have precedence over what.

On Thu, Oct 23, 2014 at 4:08 PM, Thomas A Caswell notifications@github.com
wrote:

Interesting, we look at envs when setting up the QT backend stuff, I
assumed we already had something that did this...

—
Reply to this email directly or view it on GitHub
#3710 (comment)
.

[FlorianRhiem]

• The backend from the matplotlibrc file is a global setting; it applies to all scripts equally and changing this file whenenver you want to use a different backend in an application would be silly.
• An environment variable can be set either globally or for a single command, so it should have precendence over matplotlibrc.
• The -d command line parameter can only be set for a single command (usually), so it should have precendence over a (potentially global) environment variable.
• use() requires a code change whenever you want something different. I think that this should have the highest precendence, and also that developers should avoid it unless they really depend on the specific backend.

[tacaswell]

I am tentatively 👍 on merging this.

Don't understand all of this machinery well enough.

[tacaswell]

This needs to be mentioned in the docs (someplace) and an entry in what's new.

Someplace in the FAQ would probably be a good place "How do I control the backend" followed by the bullet points you have above.

[efiring]

It looks like this line is superfluous, since you are catching KeyError.

[FlorianRhiem]

I added some documentation in the Usage FAQ, where matplotlibrc and use() were already documented, in the enviroment variable FAQ and in the coding guide. I also added this change to the changelog and the what's new.

Also, I changed the name for the variable from MPL_BACKEND to MPLBACKEND. I had previously seen an MPL_ variable (MPL_REPO_DIR), but since the only other documented MPL environment variable, MPLCONFIGDIR, doesn't use an underscore, this seemed to be the more consistent choice.

[tacaswell]

change either -> any

[FlorianRhiem]

Commit d57c930 only changed "either" to "any". I have no idea how this could have caused the Travis build to fail, since the previous commit 4f65b7f passed. I have no previous experience with Travis. Any suggestions what I did wrong and what I should change?

[jenshnielsen]

The failure is not related to any of your changes. I have restarted the failed job.

[tacaswell]

I am working on some edits to the docs as well..

[tacaswell]

@FlorianRhiem There should be a PR against your branch from me with some more doc edits

[pelson]

👍 in principle. Implementation looks good too but it does need a rebase.

[FlorianRhiem]

I rebased the commits (only the punctuation in an inline comment was conflicting). All test jobs pass except for the first one, which seems to be a problem on Travis' side:
github.com: Temporary failure in name resolution

[jenshnielsen]

I restated the failing job

[WeatherGod]

Just one last sanity check... doesn't matplotlib also support loading a
matplotlibrc file from the current working directory as well? I could have
sworn I saw that feature once... if so, that does make the hierarchy a
little bit trickier.

On Mon, Nov 17, 2014 at 6:59 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:

I restated the failing job

—
Reply to this email directly or view it on GitHub
#3710 (comment)
.

[mdboom]

@WeatherGod: Yes, the rc file is looked for in this order:

• current working directory
• home directory (~/.matplotlib or ~/.config/matpotlib)
• install directory

How does that impact this, though?

[WeatherGod]

@FlorianRhiem 's rationale for deciding on the priority of the setting:

• The backend from the matplotlibrc file is a global setting; it applies to all scripts equally and changing this file whenenver you want to use a different backend in an application would be silly.
• An environment variable can be set either globally or for a single command, so it should have precendence over matplotlibrc.
• The -d command line parameter can only be set for a single command (usually), so it should have precendence over a (potentially global) environment variable.
• use() requires a code change whenever you want something different. I think that this should have the highest precendence, and also that developers should avoid it unless they really depend on the specific backend.

The rcparam isn't as "global" as originally conceived because it might even be as specific as for the particular script in the directory. What priority should an environment variable have over a local matplotlibrc file?

[mdboom]

@WeatherGod: Thanks for clarifying, and I see your point. Don't have a good answer though -- maybe others here do. Regardless, we should probably document the whole priorities of the multitude of ways to set a backend in one place.

[FlorianRhiem]

So backend: inside a matplotlibrc in the current working directory should take precendence over the environment variable?

• If the user would define the environment variable globally, I would agree, because the matplotlibrc would be more project-specific than the environment variable.
• If the user would define the environment variable locally, e.g. by calling the program as MPLBACKEND=??? python main.py, I would disagree.

In my opinion the latter case is the most useful application for an environment variable, because it allows the user to switch backends without editing a text file or adding a command line argument (and making sure it doesn't cause problems with argparse or alike).

I think most users will set the global default backend in an matplotlibrc file and not in an environment variable in their shell rc file, so the case of a global environment variable and a local matplotlibrc file seems less likely to me.

[WeatherGod]

I don't see it the same way. It is very easy to add an environment variable to my bashrc file, as it is very typical to add such things there. I rarely set an environment variable for a particular command instance (although, I do admit that it is a much better alternative than the very bad argparse hijacking that we do).

I would wager that very few people know about matplotlibrc, and fewer still know about per-directory matplotlibrc. But those who do know those things might expect the per-directory param to override the environment variable that was set in their bashrc file (because those are typically considered "global" in nature). Your use-case of setting the environment variable on a per-execution basis is entirely plausible, and it is entirely reasonable for the environment variable to override the rc param in such a case. It is entirely a problem with discerning intent from mixed information sources. We simply can't distinguish between an environment variable in a bashrc versus on given at the command-line.

Perhaps we need two possible environment variables to cater to the two different use-cases. A low-priority, longer "global" variable for use in a bashrc, and a higher-priority, short variable (easy for typing) for per-execution uses?

[FlorianRhiem]

Those who know the environment variable should know the matplotlibrc file as well and changing application behavior in the bashrc when an application-specific rc file can be used doesn't seem intuitive to me, but I see your point and I agree that using two environent variables, e.g. MPLDEFAULTBACKEND and MPLBACKEND, might be the clearest solution. MPLBACKEND would override the local matplotlibrc backend and MPLDEFAULTBACKEND would not. It would still override any global matplotlibrc, to avoid making it useless because of the backend setting in the matplotlibrc that is installed along with matplotlib.

This does seem to make matters even more complicated though. So an alternative: The documentation should specifically and clearly recommend using the environment variable only locally (instead of the -d argument), because global settings are well handled by matplotlibrc and in comparison to -d, there is not really any need for an alternative to this.

[WeatherGod]

Ah, good point about the default backend variable always getting overriden by the default rc file installed by matplotlib. Ok, I think you have the right idea: offer the environment variable as the prefered alternative to the command line option (possibly even deprecating it, maybe?!), and making it clear the priorities. I would even go so far as to note in the documentation that the environment variable in a bashrc file would therefore override any backend settings in a per-directory matplotlibrc.

[tacaswell]

I am in concurrence with the current order.

This will also be very useful for people trying to run mpl behind djanjo
and running tests on Travis to be able to set the back end via env.

On Mon, Nov 17, 2014, 13:33 Benjamin Root notifications@github.com wrote:

Ah, good point about the default backend variable always getting overriden
by the default rc file installed by matplotlib. Ok, I think you have the
right idea: offer the environment variable as the prefered alternative
to the command line option (possibly even deprecating it, maybe?!), and
making it clear the priorities. I would even go so far as to note in the
documentation that the environment variable in a bashrc file would
therefore override any backend settings in a per-directory matplotlibrc.

—
Reply to this email directly or view it on GitHub
#3710 (comment)
.

[WeatherGod]

is -> in

[WeatherGod]

Alright, I am +1 on this. Just a last check, @tacaswell, aren't "whats_new" entries supposed to go someplace else to reduce the need for other PRs to rebase? If it isn't that big of an issue, I can go ahead and press the green button.

[tacaswell]

There is a whats_new folder that has a README to explain how it should work full of rst files that has been followed inconsistently.

My current plan is to clean it up by hand next time we release anyway and be better about enforcing it going forward. I would not worry about that for this PR.

[WeatherGod]

Ok, understood. Merging!