ENH: Allow to register standalone figures with pyplot

timhoffm · timhoffm · commit 0e13c827e510 · 2025-04-01T23:41:13.000+02:00
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)
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -990,21 +990,32 @@ def figure(
     in the matplotlibrc file.
     """
     allnums = get_fignums()
+    next_num = max(allnums) + 1 if allnums else 1
 
     if isinstance(num, FigureBase):
         # type narrowed to `Figure | SubFigure` by combination of input and isinstance
+        has_figure_property_parameters = (
+            any(param is not None for param in [figsize, dpi, facecolor, edgecolor])
+            or not frameon or kwargs
+        )
+
         root_fig = num.get_figure(root=True)
         if root_fig.canvas.manager is None:
-            raise ValueError("The passed figure is not managed by pyplot")
-        elif (any(param is not None for param in [figsize, dpi, facecolor, edgecolor])
-              or not frameon or kwargs) and root_fig.canvas.manager.num in allnums:
+            if has_figure_property_parameters:
+                raise ValueError(
+                    "You cannot pass figure properties when calling figure() with "
+                    "an existing Figure instance")
+            backend = _get_backend_mod()
+            manager_ = backend.new_figure_manager_given_figure(next_num, root_fig)
+            _pylab_helpers.Gcf._set_new_active_manager(manager_)
+            return manager_.canvas.figure
+        elif has_figure_property_parameters and root_fig.canvas.manager.num in allnums:
             _api.warn_external(
                 "Ignoring specified arguments in this call because figure "
                 f"with num: {root_fig.canvas.manager.num} already exists")
         _pylab_helpers.Gcf.set_active(root_fig.canvas.manager)
         return root_fig
 
-    next_num = max(allnums) + 1 if allnums else 1
     fig_label = ''
     if num is None:
         num = next_num
diff --git a/lib/matplotlib/tests/test_pyplot.py b/lib/matplotlib/tests/test_pyplot.py
@@ -470,6 +470,30 @@ def test_multiple_same_figure_calls():
     assert fig is fig3
 
 
+def test_register_existing_figure_with_pyplot():
+    from matplotlib.figure import Figure
+    # start with a standalone figure
+    fig = Figure()
+    assert fig.canvas.manager is None
+    with pytest.raises(AttributeError):
+        # Heads-up: This will change to returning None in the future
+        # See docstring for the Figure.number property
+        fig.number
+    # register the Figure with pyplot
+    plt.figure(fig)
+    assert fig.number == 1
+    # the figure can now be used in pyplot
+    plt.suptitle("my title")
+    assert fig.get_suptitle() == "my title"
+    # it also has a manager that is properly wired up in the pyplot state
+    assert plt._pylab_helpers.Gcf.get_fig_manager(fig.number) is fig.canvas.manager
+    # and we can regularly switch the pyplot state
+    fig2 = plt.figure()
+    assert fig2.number == 2
+    assert plt.figure(1) is fig
+    assert plt.gcf() is fig
+
+
 def test_close_all_warning():
     fig1 = plt.figure()
 
