ENH: Allow to register standalone figures with pyplot

timhoffm · timhoffm · commit bc3117798d70 · 2025-07-27T22:20:12.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
@@ -933,6 +933,10 @@ def figure(
         window title is set to this value.  If num is a ``SubFigure``, its
         parent ``Figure`` is activated.
 
+        If *num* is a Figure instance that is already tracked in pyplot, it is
+        activated. If *num* is a Figure instance that is not tracked in pyplot,
+        it is added to the tracked figures and activated.
+
     figsize : (float, float) or (float, float, str), default: :rc:`figure.figsize`
         The figure dimensions. This can be
 
@@ -1019,21 +1023,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_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -147,8 +147,6 @@ def test_figure_label():
     assert plt.get_figlabels() == ['', 'today']
     plt.figure(fig_today)
     assert plt.gcf() == fig_today
-    with pytest.raises(ValueError):
-        plt.figure(Figure())
 
 
 def test_figure_label_replaced():
diff --git a/lib/matplotlib/tests/test_pyplot.py b/lib/matplotlib/tests/test_pyplot.py
@@ -471,6 +471,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()
 
