Move IPython backend mapping to Matplotlib and support entry points

[ianthomas23]

This is WIP to move IPython's backend mapping into Matplotlib and extends it to allow backends to register themselves via entry points. It is a coordinated effort across Matplotlib, IPython, matplotlib-inline and ipympl. Closes #27663.

The only functional changes to pure (non-IPython) Matplotlib are:

1. Backend names are now case-insensitive. Up to now IPython has used capitalised names. If you ask for QtAgg then get_backend() will now return qtagg.
2. There is a new BackendRegistry.list_all() function to list all known (built-in and dynamically-loaded) backends as this is needed by IPython. This could be made more public by exposing it in pyplot or the top-level matplotlib.__init__.py if desired.
3. Entry points allow backend modules to register themselves so they do not require explicit code to support them in Matplotlib or IPython. Example of how this is done: https://github.com/ipython/matplotlib-inline/blob/c5887eab4bf4b594be8f7cfd738bfff4d6fede88/pyproject.toml#L42-L43.

Functional improvements for IPython:

1. Supports the full set of Matplotlib built-in backends, including svg, pdf, qtcairo, tkcairo, etc.
2. Supports backends of the form module://some.backend such as module://mplcairo.qt.
3. Supports entry-point backends, currently inline and widget/ipympl.
4. The widget/jupyter backends behave like other non-interactive backends (e.g. agg) in pure IPython in that they can export to PNG, etc, but do not display an interactive window.

Jupyter inherits all these IPython benefits, displaying plots that use GUI frameworks in separate windows and the others within the notebook.

Because the four related projects are loosely coupled without direct dependencies on each other (except for ipython and matplotlib-inline), backward compatibility requires all possible combinations of projects before and after the new functionality (I will call these "old" and "new" from now on) to continue to work. I have tested these all locally, and the CI of this PR will test new Matplotlib against old IPython for example, but I need to add one or more new temporary CI runs to test new Matplotlib against new IPython etc. The identification of new versus old depends on version checks on the other libraries, so here is a table that I will update showing the current status of progress in the 4 projects:

Project	Relevant PRs	Possible release version
matplotlib-inline	ipython/matplotlib-inline#34, ipython/matplotlib-inline#35	0.1.7 released
ipympl	matplotlib/ipympl#549	0.9.4 released
Matplotlib	#27948 (this)	3.9.0
IPython	ipython/ipython#14371	8.24.0 released

The two widget projects can be released soon, once we are happy with the entry point approach. The other two projects' PRs will have to be synchronised as each includes version checks on each other.

Implementation details:

1. cbook._backend_module_name has moved to BackendRegistry. It was private, but if there are concerns about downstream use of this function I can put a shim back in.
2. For backward compatibility I have had to add synonyms notebook for nbagg, qt6agg for qtagg and qt6cairo for qtcairo. I am happy with notebook (it is a better name than nbagg anyway) but the qt6 ones are unfortunate as we are connecting a version-specific IPython GUI event loop (qt6) to a somewhat version-agnostic Matplotlib qtagg backend.
3. Entry points are only read if they really need to be. If you ask for a built-in or module:// backend then the entry points are not needed. They are if you call list_all().
4. Backend validation no longer has a list of valid string names, it checks if the supplied backend name is valid and only loads the entry points if necessary.
5. You cannot have multiple entry points with the same name, and an entry point cannot use the same name as a built-in backend.
6. There are a number of code blocks that do version checks on IPython, matplotlib-inline or ipympl for backward compatibility. These need to remain in place for 3+ years until the lowest version of Python supported by Matplotlib is higher than the highest versions of those libraries released before these changes. Probably I should add a specific comment to each code block stating the conditions required for it to be removed.

To do

• Add temporary CI runs against the new PR branches of the other projects.
• Support mac-specific backends (a0cac93).
• Add comments for conditions required for backward-compatibility code blocks to be removed.
• Update documentation on backends, for both users and developers.
• Update Whats New docs.
• Update version checks before merging.
• Inform downstream backend libraries (e.g. mplcairo) about entry points and deprecation of IPythons backend2gui which is now performed in Matplotlib.

[ianthomas23]

The macOS-specific backend works now. The name of the backend remains as "macosx" (case insensitive) and the GUI loop as "osx".

matplotlib.use("macosx")

works on all permutations of main and entry_point branches of Matplotlib and IPython.

In IPython,

%matplotlib osx

works of all the permutations. In addition

%matplotlib macosx

works if using both of the Matplotlib and IPython entry_point branches. This is consistent with other usage in IPython where the string argument to %matplotlib may be either a GUI framework or a backend name.

There is a "CocoaAgg" backend mentioned in IPython
https://github.com/ipython/ipython/blob/a3074b8cf3fbb20482732a5602c20cf7bac0a215/IPython/core/pylabtools.py#L51
but this was removed from Matplotlib in #6582 (June 2016). No extra code changes are required for this, anyone attempting to use such a backend will continue to get an "backend not recognised" error message.

The "macos" backend does not work in JupyterLab either before or after these changes. Fixing that, if it is desired, will be a different piece of work.

[ianthomas23]

This is now ready for review, barring a few CI tweaks.

matplotlib-inline 0.1.7 and ipympl 0.9.4 have both been released with entry_points defined in their pyproject.toml files. These will have no effect until this PR is merged to read the entry_points. The corresponding PR in ipython has been merged and will be released in version 8.24.0, expected at the end of this month. That will have no effect until this PR is merged and released as it checks for the existence of BackendRegistry.resolve_gui_or_backend

https://github.com/ipython/ipython/blob/8ff4109a184d242bbc8cdd08750d9a192b854784/IPython/core/pylabtools.py#L481

rather than checking the version of Matplotlib installed, hence avoiding hard-coding the check of a version that hasn't been decided yet.

Ideally this targets Matplotlib 3.9.1 rather than waiting for 3.10.0. It is adding to the BackendRegistry API, but that is effectively an internal API between Matplotlib and IPython.

[tacaswell]

I think we should consider sneaking this is for 3.9.0 if we can get the reviews done ASAP.

[QuLogic]

Why did this change from macosx to osx? Actually, what would check that?

[ianthomas23]

I changed it because IPython uses osx for the GUI framework and macosx for the backend. I thought this was fine for non-IPython Matplotlib but that isn't correct as FigureCanvasMac.required_interactive_framework = "macosx". I have been lucky to get away with these two different names for the same GUI framework; non-IPython Matplotlib never looks at this code, it only needs the required_interactive_framework to be consistent with cbook._get_running_interactive_framework. But it cannot stay like this, we can't have a declaration that the macOS GUI framework is osx when sometimes it isn't.

It would be possible to special case the osx GUI framework to mean macosx on input, but on output we have no way of knowing if the caller prefers osx to macosx. So I think the least bad solution here is to change this back to macosx and be entirely consistent within Matplotlib, and I will special case the osx <-> macosx in IPython.

[ianthomas23]

Done. I'll submit the IPython PR shortly.

[QuLogic]

Do we need to commit this whole output?

[ianthomas23]

No, I can clean the notebook to remove the outputs. I kept it in to be consistent with test_nbagg_01.ipynb, which is what this is based on. But neither actually compare the output image pixels.

As an aside it would be great to have some image-comparison testing of some combination of Matplotlib and IPython/Jupyter, but I cannot find a good place to put them. There is an excellent image-based testing framework used in Jupyter projects but it would bring in some complicated test dependencies so it is not appropriate here.

[ianthomas23]

Done

[QuLogic]

It would be best if this were removed on the initial commit instead of a later one, unless you intend for this entire PR to be squashed.

[ianthomas23]

I'll squash.

[ianthomas23]

The macOS failures of

FAILED lib/matplotlib/tests/test_backend_macosx.py::test_ipython - subprocess...

are now expected when using latest IPython (8.24.0) but will not be errors when ipython/ipython#14420 is merged and released (I manually checked this now on my dev machine). I am already version-checking the result according to IPython < 8.24 or >= 8.24:

https://github.com/ianthomas23/matplotlib/blob/1078cab2e7cdc518dd0332af0a32c7eaa2d866ee/lib/matplotlib/testing/__init__.py#L182-L186

so I could just expand this and check for different results for IPython < 8.24, == 8.24 and > 8.24.

[ianthomas23]

I have:

• Disabled the IPython macos test if ipython == 8.24.0 as it is not possible to make it pass without a nasty hack in Matplotlib, and IPython 8.24.1 should be released shortly with the required fix at that end.
• Squashed all the commits.
• Disabled the IPython qt test on Windows as running it in a subprocess causes it to fail. It works fine for me locally in a Windows dev environment which is good enough for me.

I've restarted the AppVeyor run as it was failing to get freetype.

[ksunden]

Take or leave the comments about "headless"/extra if condition.

I do not particularly wish to block on either of these.

Summary of small action items if you wish:

• remove extra condition is_valid_backend
• remove reference to "headless" in docstrings for the return of both resolve_[gui_or_]backend methods.
• make reg.resolve_gui_or_backend("headless") return ('agg', None) rather than ('agg', 'headless') (or potentially error if you do not want headless to be valid)

[ianthomas23]

Take or leave the comments about "headless"/extra if condition.

I do not particularly wish to block on either of these.

Summary of small action items if you wish:

• remove extra condition is_valid_backend
• remove reference to "headless" in docstrings for the return of both resolve_[gui_or_]backend methods.
• make reg.resolve_gui_or_backend("headless") return ('agg', None) rather than ('agg', 'headless') (or potentially error if you do not want headless to be valid)

I've done all 3 of these.