MNT: Deprecate changing Figure.number

Historically, pyplot dynamically added a number attribute to figure.
However, this number must stay in sync with the figure manger.
AFAICS overwriting the number attribute does not have the desired
effect for pyplot. But there are some repos in GitHub that do change
number. So let's take it slow and properly migrate away from writing.

Making the dynamic attribute private and wrapping it in a property
allows to maintain current behavior and deprecate write-access.

When the deprecation expires, there's no need for duplicate state
anymore and the private _number attribute can be replaced by
`self.canvas.manager.num` if that exists and None otherwise.

Also closes matplotlib#28994.

Author: timhoffm

doc/api/next_api_changes/deprecations/28007-TH.rst

@@ -0,0 +1,6 @@
+Changing ``Figure.number``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Changing ``Figure.number`` is deprecated. This value is used by `.pyplot`
+to identify figures. It must stay in sync with the pyplot internal state
+and is not intended to be modified by the user.

lib/matplotlib/_pylab_helpers.py

@@ -108,7 +108,7 @@ def _set_new_active_manager(cls, manager):
             manager._cidgcf = manager.canvas.mpl_connect(
                 "button_press_event", lambda event: cls.set_active(manager))
         fig = manager.canvas.figure
-        fig.number = manager.num
+        fig._number = manager.num
         label = fig.get_label()
         if label:
             manager.set_window_title(label)

lib/matplotlib/figure.py

@@ -2808,6 +2808,31 @@ def axes(self):
 
     get_axes = axes.fget
 
+    @property
+    def number(self):
+        """The figure id, used to identify figures in `.pyplot`."""
+        # Historically, pyplot dynamically added a number attribute to figure.
+        # However, this number must stay in sync with the figure manger.
+        # AFAICS overwriting the number attribute does not have the desired
+        # effect for pyplot. But there are some repos in GitHub that do change
+        # number. So let's take it slow and properly migrate away from writing.
+        #
+        # Making the dynamic attribute private and wrapping it in a property
+        # allows to maintain current behavior and deprecate write-access.
+        #
+        # When the deprecation expires, there's no need for duplicate state
+        # anymore and the private _number attribute can be replaced by
+        # `self.canvas.manager.num` if that exists and None otherwise.
+        if hasattr(self, '_number'):
+            return self._number
+        else:
+            raise AttributeError("'Figure' object has not attribute 'number'")
+
+    @property.setter
+    def number(self, num):
+        _api.warn_deprecated("3.10", message="Changing 'Figure.number' is deprecated")
+        self._number = num
+
     def _get_renderer(self):
         if hasattr(self.canvas, 'get_renderer'):
             return self.canvas.get_renderer()

lib/matplotlib/figure.pyi

@@ -24,6 +24,8 @@ from matplotlib.lines import Line2D
 from matplotlib.patches import Rectangle, Patch
 from matplotlib.text import Text
 from matplotlib.transforms import Affine2D, Bbox, BboxBase, Transform
+
+from .streamplot import streamplot
 from .typing import ColorType, HashableList
 
 _T = TypeVar("_T")
@@ -343,6 +345,10 @@ class Figure(FigureBase):
     def get_layout_engine(self) -> LayoutEngine | None: ...
     def _repr_html_(self) -> str | None: ...
     def show(self, warn: bool = ...) -> None: ...
+    @property
+    def number(self) -> int | str: ...
+    @number.setter
+    def number(self, num: int | str) -> None: ...
     @property  # type: ignore[misc]
     def axes(self) -> list[Axes]: ...  # type: ignore[override]
     def get_axes(self) -> list[Axes]: ...