ENH: Allow to register standalone figures with pyplot #29855

timhoffm · 2025-04-01T21:42:07Z

It may be fundamentally nice not to have to create the figure though pyplot to be able to use it in pyplot afterwards. You can now do

from matplotlib.figure import Figure
import matplotlib.pyplot as plt

fig = Figure()
fig.subplots().plot([1, 3, 2])

plt.figure(fig)  # fig is now tracked in pyplot
plt.show()

This also opens up the possibility to more dynamically track and untrack figures in pyplot, which opens up the road to optimized figure tracking in pyplot (#29849)

Anybody, feel free to play around with this and try to break it.

rcomer · 2025-04-02T10:32:27Z

I was hoping I could modify the figure and show again, but that does not seem to be the case

import matplotlib.pyplot as plt
from matplotlib.figure import Figure

fig = Figure()
ax = fig.subplots()
ax.plot([0, 2])
plt.figure(fig)
plt.show()

ax.set_title('A cool line')
plt.figure(fig)
plt.show()

No title is shown 😕

anntzer · 2025-05-01T09:29:03Z

This would also close #19956.

It may be fundamentally nice not to have to create the figure though pyplot to be able to use it in pyplot afterwards. You can now do ``` from matplotlib.figure import Figure import matplotlib.pyplot as plt fig = Figure() fig.subplots().plot([1, 3, 2]) plt.figure(fig) # fig is now tracked in pyplot plt.show() ``` This also opens up the possibility to more dynamically track and untrack figures in pyplot, which opens up the road to optimized figure tracking in pyplot (matplotlib#29849)

timhoffm · 2025-07-27T21:45:07Z

Showing again now works properly. When destroying a figure manager, the figure's canvas is reset to a FigureCanvasBase.

Technical questions:

I've added resetting the canvas to the specific manager's destroy method (currently only implemented for Qt). This means, I have to add it to all gui-specific managers. But I feel it belongs there: The gui-specific managers replace the FigureCanvasBase when they are created, so they should undo this when they are destroyed. - One could in theory add it to FigureManagerBase.destroy(). However, that is currently empty and not called from any of the specific FigureManagerX.destroy(), so we'd need to inject super().destroy()` calls and then I think I'd rather keep it explicit. - Feedback welcome.
I've also not a good idea how to test this, i.e. the equivalent of ENH: Allow to register standalone figures with pyplot #29855 (comment). I suspect, I need to use a proper GUI backend with a real window and then somehow get the window to close. - Can this be done in tests? - After that, I could check that the fig.canvas is a FigureCanvasBase again.

timhoffm · 2025-07-27T22:17:47Z

Note: the failing tests are in test_interactive_backend, which saves the figure to file, closes it, and then saves it to file again, expecting exactly the same output.

matplotlib/lib/matplotlib/tests/test_backends_interactive.py

Lines 222 to 235 in 011d12f

    
           result = io.BytesIO() 
        
           fig.savefig(result, format='png') 
        
           plt.show() 
        
           # Ensure that the window is really closed. 
        
           plt.pause(0.5) 
        
           # Test that saving works after interactive window is closed, but the figure 
        
           # is not deleted. 
        
           result_after = io.BytesIO() 
        
           fig.savefig(result_after, format='png') 
        
           assert result.getvalue() == result_after.getvalue()

This is now no longer the case, as closing the figure resets the canvas to FigureCanvasBase, i.e. the images are genereated through different canvases - FigureCanvasBase and the backend-specific canvas, which do not necessarily have pixel-identical output. An example diff looks like this:

How should we handle this? I'm inclined to say that the previous expectation is no longer justified, and it makes sense that the canvas is reset. Should we try to fix this with tolerances? Or don't we need this image test at all anymore and instead it is sufficient to test that the figure has again a FigureCanvasBase (which imlies it can be saved with savefig, but we don't have to test the contents? Or are there other approaches?

anntzer · 2025-07-27T22:39:57Z

It's a bit strange that the end png result is not the same, as both should ultimately go through Agg for rasterizing... It would be nice to figure out what is going wrong, but I agree this isn't a blocker.

timhoffm · 2025-07-27T23:37:51Z

Failing tests are

FAILED lib/matplotlib/tests/test_backends_interactive.py::test_interactive_backend[toolbar2-MPLBACKEND=qtagg-QT_API=PyQt5-BACKEND_DEPS=PyQt5]
FAILED lib/matplotlib/tests/test_backends_interactive.py::test_interactive_backend[toolbar2-MPLBACKEND=qtcairo-QT_API=PyQt6-BACKEND_DEPS=PyQt6,cairocffi]
FAILED lib/matplotlib/tests/test_backends_interactive.py::test_interactive_backend[toolbar2-MPLBACKEND=qtcairo-QT_API=PySide6-BACKEND_DEPS=PySide6,cairocffi]
FAILED lib/matplotlib/tests/test_backends_interactive.py::test_interactive_backend[toolbar2-MPLBACKEND=qtcairo-QT_API=PyQt5-BACKEND_DEPS=PyQt5,cairocffi]
FAILED lib/matplotlib/tests/test_backends_interactive.py::test_interactive_backend[toolbar2-MPLBACKEND=qtcairo-QT_API=PySide2-BACKEND_DEPS=PySide2,cairocffi]

and the same again for toolmanager, which I left out for simplicity. So all cairocffi tests fail and addtionally the qtagg-PyQt5 test. But the agg-based tests for PyQt6, PySide2 and PySide6 pass. Interestingly, the qtagg-PyQt5 test passes on my local machine.

The above diff image was from qtcairo-PyQt5.

anntzer · 2025-07-28T23:19:11Z

At least for the cairo tests this is understandable: if you reset to FigureCanvasBase, then they will now rasterize using agg, whereas they rasterized with cairo prior to that. I guess that's probably fine?
No idea about the qt5agg test, though.

anntzer · 2025-07-29T09:38:26Z

I've added resetting the canvas to the specific manager's destroy method (currently only implemented for Qt). This means, I have to add it to all gui-specific managers. But I feel it belongs there: The gui-specific managers replace the FigureCanvasBase when they are created, so they should undo this when they are destroyed. - One could in theory add it to FigureManagerBase.destroy(). However, that is currently empty and not called from any of the specific FigureManagerX.destroy(), so we'd need to inject super().destroy()` calls and then I think I'd rather keep it explicit. - Feedback welcome.

I prefer adding doing this via super() calls: for the benefit of third-parties, it is relatively easier to document "one needs to call super().destroy() in subclasses" rather than "one needs to do this and that" (restore the default canvas, but who knows what else can change in the future).

timhoffm · 2025-07-29T15:48:19Z

My thought was that the specific FigureManager* classes override the canvas in their __init__ and hence they should undo what they did in their destroy(). But one could also argue that resetting to the base canvas is a universal property of destroying any manager.

When destroying a manager, replace the figure's canvas by a figure canvas base.

There in now machinery for all of the public API that takes a renderer is input to get it from the current canvas on the root figure. Use that machinery instead.

tacaswell · 2025-07-30T14:46:52Z

I took the liberty of fixing one of the tests. We probably should purge all of the canvas.get_renderer() calls from the tests, but that is a later problem.

tacaswell · 2025-09-03T21:12:11Z

"power-cycled" to re-trigger pinning away from the known-bad pytest-rerunner.

lib/matplotlib/tests/test_backends_interactive.py

anntzer · 2025-09-05T08:21:55Z

doc/release/next_whats_new/pyplot-register-figure.rst

+general, you should not store a reference to the canvas, but rather always
+obtain it from the figure with ``fig.canvas``. This will return the current
+canvas, which is either the original `.FigureCanvasBase` or a backend-dependent
+subclass, depending on whether the figure is registered with pyplot or not.


Maybe add a comment that there are currently known limitations wrt. blitting/widgets (#30503)? We can always edit that out once that issue is fixed.

Added

Additionally, the swapping of the canvas currently does not play well with
blitting of matplotlib widgets; in such cases either deactivate blitting or do not
continue to use the figure (e.g. saving it after closing the window).

anntzer

Modulo addressing the comments.

import must be local

timhoffm · 2025-09-08T21:35:31Z

src/_macosx.m

@@ -686,6 +686,7 @@ bool mpl_check_modifier(bool present, PyObject* list, char const* name)
 {
    [self->window close];
    self->window = NULL;
+    [super destroy];


I could need a bit of help here from someone with more Objective-C / Cpython knowledge. This is missing the equivalent of super.destroy(). The change here was a rather wild guess from pattern-matching other similar cases in the module, but is apparently not correct, because this now fails the build with

../../src/_macosx.m:689:6: error: use of undeclared identifier 'super'

Do you need to go into the objective C layer or can you stay at the Python layer (have not looked at the updates here in detail). But, we do have some multiple inheritance going on here, so you may have to explicitly call which super you want to interact with at this place. (I think the super().destroy() currently on these lines goes to the objective C implementation, and you want to go the FigureManagerBase implementation [we want to travel to both it sounds like])

matplotlib/lib/matplotlib/backends/backend_macosx.py

Lines 168 to 174 in 352b419

def destroy(self):

# We need to clear any pending timers that never fired, otherwise

# we get a memory leak from the timer callbacks holding a reference

while self.canvas._timers:

timer = self.canvas._timers.pop()

timer.stop()

super().destroy()

super() goes to the next class in MRO, and that covers the whole inheritance tree also in case of multiple inheritance if all classes in the hierarchy call it without explicitly stating the parent. That‘s what I want. I do not want to mess with calling any specific parent.

My quick suggestion would be to avoid trying to call super() from the C-layer. To avoid the multiple inheritance issue, you can rename the (PyCFunction)FigureManager_destroy to (PyCFunction)FigureManager__destroy or something else (its in a private module) and then call that method explicitly from the Python destroy() side. You can keep the super().destroy() already there which will still travel the tree as you want I think.

Maybe something along the lines of https://stackoverflow.com/questions/42201881/python-c-api-how-to-call-base-type-method-from-subtype would work?

timhoffm · 2025-09-10T09:02:49Z

src/_macosx.m

+    // call super().destroy()
+    PyObject *super_obj = PyObject_CallFunctionObjArgs(
+        (PyObject *)&PySuper_Type,
+        (PyObject *)&FigureManagerType,
+        self,
+        NULL
+    );
+    if (super_obj == NULL) {
+        return NULL; // error
+    }
+    PyObject *result = PyObject_CallMethod(super_obj, "destroy", NULL);
+    Py_DECREF(super_obj);
+    if (result == NULL) {
+        return NULL; // error
+    }
+    Py_DECREF(result);


There are two approvals already, but since this super() call is new and I'm not the most experienced C-API developer, I'd like someone to cross check this bit again.

src/_macosx.m

doc/release/next_whats_new/pyplot-register-figure.rst

lib/matplotlib/tests/test_backends_interactive.py

QuLogic

LGTM, but maybe someone on macOS should double-check that part.

github-actions bot added the topic: pyplot API label Apr 1, 2025

timhoffm force-pushed the pyplot-register-figure branch from 0e13c82 to 56f4ee1 Compare April 1, 2025 21:46

timhoffm mentioned this pull request Apr 1, 2025

ENH: mpl_gui to main library #29836

Closed

timhoffm force-pushed the pyplot-register-figure branch from 56f4ee1 to f97c262 Compare April 1, 2025 22:19

timhoffm marked this pull request as draft April 2, 2025 11:34

github-actions bot added the status: needs rebase label Apr 6, 2025

timhoffm added 2 commits July 27, 2025 22:20

Clarifying comment

c718eae

timhoffm force-pushed the pyplot-register-figure branch from f97c262 to d0958e4 Compare July 27, 2025 21:33

github-actions bot added GUI: Qt topic: figures and subfigures and removed status: needs rebase labels Jul 27, 2025

Fix: properly decouple from pyplot and specific backends when destroying

a38f9bb

When destroying a manager, replace the figure's canvas by a figure canvas base.

timhoffm force-pushed the pyplot-register-figure branch from d0958e4 to a38f9bb Compare July 29, 2025 18:04

github-actions bot added GUI: wx GUI: gtk GUI: tk GUI: nbagg topic: canvas and figure manager labels Jul 29, 2025

TST: do not use non-baseclass methods to get renderer in tests

eab4a89

There in now machinery for all of the public API that takes a renderer is input to get it from the current canvas on the root figure. Use that machinery instead.

tacaswell approved these changes Sep 1, 2025

View reviewed changes

tacaswell mentioned this pull request Sep 2, 2025

Make Widget.useblit robust against underlying canvas changes #30503

Open

tacaswell closed this Sep 3, 2025

tacaswell reopened this Sep 3, 2025

timhoffm mentioned this pull request Sep 5, 2025

[ENH]: Add mechanism for feature flags #30519

Open

anntzer reviewed Sep 5, 2025

View reviewed changes

lib/matplotlib/tests/test_backends_interactive.py Outdated Show resolved Hide resolved

anntzer reviewed Sep 5, 2025

View reviewed changes

anntzer approved these changes Sep 5, 2025

View reviewed changes

timhoffm force-pushed the pyplot-register-figure branch from 6ac7b60 to 3cb0681 Compare September 7, 2025 07:44

Add note on incompatibility with blitting of widgets

6af9062

timhoffm force-pushed the pyplot-register-figure branch 3 times, most recently from d420613 to 6dcd489 Compare September 8, 2025 19:48

Fix assertion error

6b1797b

import must be local

timhoffm force-pushed the pyplot-register-figure branch from 6dcd489 to 6b1797b Compare September 8, 2025 19:49

Fix macosx

b42ce64

github-actions bot added the GUI: MacOSX label Sep 8, 2025

timhoffm commented Sep 8, 2025

View reviewed changes

timhoffm force-pushed the pyplot-register-figure branch 2 times, most recently from a3e97f8 to 232e562 Compare September 9, 2025 20:59

Call super().destroy() in _maxosx.m FigureManager

774d02c

timhoffm force-pushed the pyplot-register-figure branch from 232e562 to 774d02c Compare September 9, 2025 21:30

timhoffm commented Sep 10, 2025

View reviewed changes

QuLogic reviewed Sep 11, 2025

View reviewed changes

src/_macosx.m Outdated Show resolved Hide resolved

src/_macosx.m Show resolved Hide resolved

src/_macosx.m Show resolved Hide resolved

Better document super call

ccf1994

timhoffm force-pushed the pyplot-register-figure branch from 6f596db to ccf1994 Compare September 11, 2025 09:10

QuLogic reviewed Sep 11, 2025

View reviewed changes

doc/release/next_whats_new/pyplot-register-figure.rst Outdated Show resolved Hide resolved

lib/matplotlib/tests/test_backends_interactive.py Outdated Show resolved Hide resolved

Fix typos

623fe4d

QuLogic approved these changes Sep 11, 2025

View reviewed changes

	def destroy(self):
	# We need to clear any pending timers that never fired, otherwise
	# we get a memory leak from the timer callbacks holding a reference
	while self.canvas._timers:
	timer = self.canvas._timers.pop()
	timer.stop()
	super().destroy()

Uh oh!

ENH: Allow to register standalone figures with pyplot #29855

Are you sure you want to change the base?

ENH: Allow to register standalone figures with pyplot #29855

Conversation

timhoffm commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rcomer commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anntzer commented May 1, 2025

Uh oh!

timhoffm commented Jul 27, 2025

Uh oh!

timhoffm commented Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anntzer commented Jul 27, 2025

Uh oh!

timhoffm commented Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anntzer commented Jul 28, 2025

Uh oh!

anntzer commented Jul 29, 2025

Uh oh!

timhoffm commented Jul 29, 2025

Uh oh!

tacaswell commented Jul 30, 2025

Uh oh!

tacaswell commented Sep 3, 2025

Uh oh!

Uh oh!

anntzer Sep 5, 2025

Choose a reason for hiding this comment

Uh oh!

timhoffm Sep 7, 2025

Choose a reason for hiding this comment

Uh oh!

anntzer left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

greglucas Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

greglucas Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

anntzer Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

timhoffm Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuLogic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

timhoffm commented Apr 1, 2025 •

edited

Loading

rcomer commented Apr 2, 2025 •

edited

Loading

timhoffm commented Jul 27, 2025 •

edited

Loading

timhoffm commented Jul 27, 2025 •

edited

Loading

greglucas Sep 8, 2025 •

edited

Loading