update documentation of save_figure functions

Zybulon · Zybulon · commit 5bcaa23b4bc5 · 2024-02-11T11:05:38.000+01:00
diff --git a/doc/api/next_api_changes/behavior/27744-FM.rst b/doc/api/next_api_changes/behavior/27744-FM.rst
@@ -1,10 +1,10 @@
 ``NavigationToolbar2.save_figure`` now returns filepath of saved figure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``NavigationToolbar2.save_figure`` function may return the filename of the saved figure.  
+``NavigationToolbar2.save_figure`` function may return the filename of the saved figure.
 
 If a backend implements this functionality it should return `None` in the case where no
 figure is actually saved (because the user closed the dialog without saving).
 
-If the backend does not or can not implement this functionality (currently the Gtk4 backends 
+If the backend does not or can not implement this functionality (currently the Gtk4 backends
 and webagg backends do not) this this method will return `NavigationToolbar2.UNKNOWN_SAVED_STATUS`.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -3229,12 +3229,22 @@ def save_figure(self, *args):
         """
         Save the current figure.
 
+        Backend implementations may choose to return
+        the absolute path of the saved file, if any, as
+        a string.
+
+        If no file is created then `None` is returned.
+
+        If the backend does not implement this functionality
+        then `NavigationToolbar2.UNKNOWN_SAVED_STATUS` is returned.
+
         Returns
         -------
-        str or `None`
+        str or `None` or `NavigationToolbar2.UNKNOWN_SAVED_STATUS`
             The filepath of the saved figure.
-            For GTK4 and WebAgg backends it returns `None`.
             Returns `None` if figure is not saved.
+            For GTK4 and WebAgg backends it returns
+            `NavigationToolbar2.UNKNOWN_SAVED_STATUS`.
         """
         raise NotImplementedError
 
diff --git a/lib/matplotlib/backend_bases.pyi b/lib/matplotlib/backend_bases.pyi
@@ -406,6 +406,7 @@ class _Mode(str, Enum):
 
 class NavigationToolbar2:
     toolitems: tuple[tuple[str, ...] | tuple[None, ...], ...]
+    UNKNONW_SAVED_STATUS: object
     canvas: FigureCanvasBase
     mode: _Mode
     def __init__(self, canvas: FigureCanvasBase) -> None: ...
@@ -441,7 +442,7 @@ class NavigationToolbar2:
     def push_current(self) -> None: ...
     subplot_tool: widgets.SubplotTool
     def configure_subplots(self, *args): ...
-    def save_figure(self, *args) -> str | None | object: ...
+    def save_figure(self, *args) -> str | None | UNKNONW_SAVED_STATUS: ...
     def update(self) -> None: ...
     def set_history_buttons(self) -> None: ...
 
diff --git a/lib/matplotlib/backends/backend_wx.py b/lib/matplotlib/backends/backend_wx.py
@@ -1121,7 +1121,7 @@ def save_figure(self, *args):
                     caption='Matplotlib error')
                 dialog.ShowModal()
                 dialog.Destroy()
-    
+
     def draw_rubberband(self, event, x0, y0, x1, y1):
         height = self.canvas.figure.bbox.height
         self.canvas._rubberband_rect = (x0, height - y0, x1, height - y1)
