TST: Backend switching API (don't merge)

[timhoffm]

PR Summary

This PR creates a possible API for backend switching. The API is laid out in the last commit. Previous commits are from #11600 and only contain the actual switching logic.

The code is not fully tested. It's main purpose is to give an idea how the following API can be implemented:

• There is a new rcParams['default_backends'] that accepts a list of possible backends to try out.
• The current behavior for setting the default backend via rcParams['backend'] is deprecated.
• Reading rcParams['backend'] is deprecated. Users should use rcParams['default_backends']orget_backend()` depeding on their needs.
• matplotlib.use() is deprecated in favor of set_backend() -- this is independent of the other API changes but adds to consistency.

Typical use-cases:

Setting the default backend

new API:

rcParams['default_backends'] = ['qt5agg', 'qt4agg']

current API (deprecated):

rcParams['backend'] = 'qt5agg'  # only one supported
WARNING: The rcParam 'backend' is deprecated. Use 'default_backends' instead.

Setting the current backend

new API:

matplotlib.set_backend('qt5agg')

current API (deprecated):

matplotlib.use('qt5agg')
WARNING: matplotlib.use is deprecated. Use matplotlib.set_backend instead.

Querying the current backend:

new API:

matplotlib.get_backend()

current API (deprecated):

backend = matplotlib.rcParams['backend']  # returns the current or default backend
WARNING: The rcParam 'backend' is deprecated. Use the rcParam 'default_backends' to access the defaults. Use get_backend() to get the current backend."

[tacaswell]

The matplotlib.use API has been there from 2004 (goes all the way back to e34a333) and it is in a lot of code / documentation / examples. I am not convinced that the slight improvement in the verbiage is worth disrupting a considerable fraction of our users. While if we were going to be starting from a clean slate I agree set_backend is a better name, I am 👎 on deprecating use.

I am 50/50 on adding set_backend as an alias for use, it is a better more guessable name, but now we have 2 versions of the call...

Similarly, storing the current backend in rcParams has been there as long, ex the current implementation of get_backend is:

matplotlib/lib/matplotlib/__init__.py

Lines 1380 to 1382 in e3042ab

	def get_backend():
	"""Return the name of the current backend."""
	return rcParams['backend']

I think I am on board with pushing people to get_backend instead of rcParams['backend'], but that is going to need a long (multi-year) deprecation cycle.

I am 👍 on adding 'default_backends' as a parameter, but (as discussed on the call today) we may want to move things like backend, interactive, etc out of rcParams all together so we should have a plan for that before we put it in.

[timhoffm]

The changes are rather independent and could be introduced incrementally, if we are not sure about some of them:

1. Enabling backend switching itself does not need any new API. I can simply allow matplotlib.use() when there already is a backend.
2. Introducing set_backend() is optional and can be done anytime as this is just an alias of matplotlib.use().
3. Deprecating matplotlib.use() after introducing set_backend() is optional. I accept the argument that this would be disrupting existing users. One alternative approach would be a PendingDeprecation. This would tell new users, that they sould use set_backend() but could keep matplotlib.use() for a long time without nagging existing users with a deprecation warning.
   But it's also a fair decision to just keep matplotlib.use(). I just would not recommend to have both set_backend() and matplotlib.use() as pure aliases. There should be one recommended way, even if we allow both to exist.
4. Deprecating querying rcParams['backend'] to get the current backend in favor of get_backend() is optional. Could also start with a PendingDeprecation.
5. Introducing the support for a list of default backends is optional. I just recommend not to inject that functionality into rcParams['backend'], but first establish a distinct entity for holding the defaults (as opposed to the current value) - rcParams['default_backends'] would be one solution for this.

A reasonable minimal start for 3.0 could be just to do 1. (and maybe 4.) - acknowledging that the original PRs #11581 and #11600 are tagged 3.0 and release-critical. The other points seem to be more controversial and there is no need to rush it.

[anntzer]

probably need to do something if no backend is successfully imported.

[anntzer]

But then you need to store the current backend somewhere else and update the implementation of get_backend accordingly.

[jklymak]

@timhoffm I agree with your suggestions above. OTOH for now we want to get backend switching in, and the existing rcParam stuffing, while suboptimal, is the existing API. So for 3.0 I think we decided to move along w/ @anntzer PR (plus or minus any review changes) and then we can re-open the deprecation/API refinement for 3.1 (due December-ish).

[timhoffm]

Superseeded by #11600