[Bug]: Setting backend in custom style sheet raises UserWarning

[andthum]

Bug summary

Importing a custom style sheet where the backend rcParam is set with plt.style.use("custom_style.mplstyle") raises the following warning and the backend remains Agg although it was set to PDF in custom_style.mplstyle.

UserWarning: Style includes a parameter, 'backend', that is not related to style.  Ignoring plt.style.use("custom_style.mplstyle")

This is quite strange, because the latest docs suggest to switch the backend via a (custom) style sheet (https://matplotlib.org/stable/tutorials/introductory/customizing.html, https://matplotlib.org/stable/tutorials/introductory/usage.html#selecting-a-backend) and backend is listed as valid rcParam (https://matplotlib.org/stable/api/matplotlib_configuration_api.html#matplotlib.RcParams).

Other rcParams (e.g. backend_fallback, interactive or savefig.directory) trigger a UserWarning, too.

This is related too Issue #5777 which describes the same problem for the default style sheet.

Code for reproduction

# Content of `custom_style.mplstyle`
backend: PDF


# Content of `plot.py`
import numpy as np
import matplotlib
import matplotlib.pyplot as plt

x = np.arange(-np.pi, np.pi, 0.01)
y = np.sin(x)

plt.style.use("custom_style.mplstyle")
print(matplotlib.get_backend())
plt.plot(x, y)
plt.savefig("plot.pdf")

Actual outcome

The above mentioned UserWarning is raised, the backend remains Agg.

Expected outcome

The PDF backend should be loaded silently.

Operating system

Ubuntu 20.04.2

Matplotlib Version

3.4.2

Matplotlib Backend

Agg, PDF

Python version

3.8.10

Jupyter version

No response

Other libraries

Clean install of matplotlib in a fresh virtual environment:

python3 -m virtualenv env
source env/bin/activate
python3 -m pip install --upgrage pip setuptools wheel
python3 -m pip install --upgrade matplotlib

Installation

pip

Conda channel

No response

[jklymak]

rcParams can be set with your matplotlibrc file, but as you can see some are expressly forbidden from the style files, which are meant for machine-independent styling. Maybe reread the docs, and get back to us with how we can make it more clear?

[andthum]

Thank you for your reply.

In Selecting a backend, the first of the three options says that you can set "The rcParams["backend"] parameter in your matplotlibrc file". An explicit example is following, where the backend keyword in the matplotlibrc file is set to backend : qt5agg. I thought the matplotlibrc file is the (custom) style file that I have used in my MWE, but maybe I'm wrong here. If the matplotlibrc file is not the same as the style file mentioned here, you maybe should remove the "See also Customizing Matplotlib with style sheets and rcParams" note below the example in Selecting a backend.

Edit:
Ah, after re-reading Customizing Matplotlib with style sheets and rcParams, I think matplotlibrc is a special file different from the style sheets, which must be named matplotlibrc and put in any location listed in The matplotlibrc file. This was not clear to me. I though the style sheets are the same as the matplotlibrc file, but maybe I have just read the docs not careful enough.

Edit 2:
After re-reading the docs, I think it was my fault that I have not seen that the style sheets are something different than the matplotlib rc file. I would just propose some minor changes to the docs.

First, the sentence

The style package adds support for easy-to-switch plotting "styles" with the same parameters as a matplotlib rc file (which is read at startup to configure Matplotlib).

in Using style sheets could be changed to something like this:

The style package adds support for easy-to-switch plotting "styles" with the almost same parameters as a matplotlib rc file (which is read at startup to configure Matplotlib).

Second, the link to Customizing Matplotlib with style sheets and rcParams in the first example in Selecting a backend could be changed to directly link to The matplotlibrc file.

But anyhow, this is just my opinion. Feel free to close this issue.

[tacaswell]

@andthum You are currently in the best position to understand how to fix the Matplotlib docs! Maintainers tend to end up being too steeped in the library to clearly see what is confusing (because there is too much other context in our heads).

Sorry this tripped you up, it is indeed confusing. The matplotlibrc contains a lot of parameters related to style, however it also contains some keys that are not "style" so we ignore them in style. They are mostly things about the GUIs/backends. See

matplotlib/lib/matplotlib/style/core.py

Lines 43 to 48 in 3e32cc7

	STYLE_BLACKLIST = {
	'interactive', 'backend', 'webagg.port', 'webagg.address',
	'webagg.port_retries', 'webagg.open_in_browser', 'backend_fallback',
	'toolbar', 'timezone', 'datapath', 'figure.max_open_warning',
	'figure.raise_window', 'savefig.directory', 'tk.window_focus',
	'docstring.hardcopy', 'date.epoch'}

for the list of banned keys.

I'm not sure what the best approach here is. Adding a hedge is not great (because then the reader is unsure about what keys will work), but listing out all of the keys that don't work inline is also not great (because many users reading this may need to even know that these keys exist!). Probably in the style module we should document the full banned list (maybe in the docstring of use ?)

I think there are two actionable things to be done here:

1. tweak that warning a bit so that it is clearer that we are only ignoring that key and the rest of the style is being applied
2. make sure the list of ignored keys is documented someplace that is not "look at the code"

Would you be interested in taking those on @andthum ?

---

As a side point, as long as you are not using a GUI the backend does not super matter because fig.savefig('blah.svg') will temporarily switch the backend to save the svg.

[andthum]

@tacaswell Yes, I can try to clarify the docs and the warning message. Maybe tomorrow I can find time to do this.

I will document the style blacklist in the docstring of matplotlib.style.use, as you suggested.