Deprecate cbook.Stack.

It's really not something we need to provide as public API.

Author: anntzer

doc/api/next_api_changes/deprecations/26294-AL.rst

@@ -0,0 +1,3 @@
+``cbook.Stack`` is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... with no replacement.

lib/matplotlib/backend_bases.py

@@ -2835,7 +2835,7 @@ class NavigationToolbar2:
     def __init__(self, canvas):
         self.canvas = canvas
         canvas.toolbar = self
-        self._nav_stack = cbook.Stack()
+        self._nav_stack = cbook._Stack()
         # This cursor will be set after the initial draw.
         self._last_cursor = tools.Cursors.POINTER
 

lib/matplotlib/backend_tools.py

@@ -479,8 +479,8 @@ def add_figure(self, figure):
         """Add the current figure to the stack of views and positions."""
 
         if figure not in self.views:
-            self.views[figure] = cbook.Stack()
-            self.positions[figure] = cbook.Stack()
+            self.views[figure] = cbook._Stack()
+            self.positions[figure] = cbook._Stack()
             self.home_views[figure] = WeakKeyDictionary()
             # Define Home
             self.push_current(figure)

lib/matplotlib/backends/_backend_gtk.py

@@ -301,7 +301,7 @@ def zoom(self, *args):
 
     def set_history_buttons(self):
         can_backward = self._nav_stack._pos > 0
-        can_forward = self._nav_stack._pos < len(self._nav_stack._elements) - 1
+        can_forward = self._nav_stack._pos < len(self._nav_stack) - 1
         if 'Back' in self._gtk_ids:
             self._gtk_ids['Back'].set_sensitive(can_backward)
         if 'Forward' in self._gtk_ids:

lib/matplotlib/backends/_backend_tk.py

@@ -891,7 +891,7 @@ def save_figure(self, *args):
     def set_history_buttons(self):
         state_map = {True: tk.NORMAL, False: tk.DISABLED}
         can_back = self._nav_stack._pos > 0
-        can_forward = self._nav_stack._pos < len(self._nav_stack._elements) - 1
+        can_forward = self._nav_stack._pos < len(self._nav_stack) - 1
 
         if "Back" in self._buttons:
             self._buttons['Back']['state'] = state_map[can_back]

lib/matplotlib/backends/backend_qt.py

@@ -798,7 +798,7 @@ def save_figure(self, *args):
 
     def set_history_buttons(self):
         can_backward = self._nav_stack._pos > 0
-        can_forward = self._nav_stack._pos < len(self._nav_stack._elements) - 1
+        can_forward = self._nav_stack._pos < len(self._nav_stack) - 1
         if 'back' in self._actions:
             self._actions['back'].setEnabled(can_backward)
         if 'forward' in self._actions:

lib/matplotlib/backends/backend_webagg_core.py

@@ -418,7 +418,7 @@ def zoom(self):
 
     def set_history_buttons(self):
         can_backward = self._nav_stack._pos > 0
-        can_forward = self._nav_stack._pos < len(self._nav_stack._elements) - 1
+        can_forward = self._nav_stack._pos < len(self._nav_stack) - 1
         self.canvas.send_event('history_buttons',
                                Back=can_backward, Forward=can_forward)
 

lib/matplotlib/backends/backend_wx.py

@@ -1136,7 +1136,7 @@ def set_message(self, s):
 
     def set_history_buttons(self):
         can_backward = self._nav_stack._pos > 0
-        can_forward = self._nav_stack._pos < len(self._nav_stack._elements) - 1
+        can_forward = self._nav_stack._pos < len(self._nav_stack) - 1
         if 'Back' in self.wx_ids:
             self.EnableTool(self.wx_ids['Back'], can_backward)
         if 'Forward' in self.wx_ids:

lib/matplotlib/cbook.py

@@ -562,6 +562,7 @@ def flatten(seq, scalarp=is_scalar_or_string):
             yield from flatten(item, scalarp)
 
 
+@_api.deprecated("3.8")
 class Stack:
     """
     Stack of elements with a movable cursor.
@@ -668,6 +669,61 @@ def remove(self, o):
                 self.push(elem)
 
 
+class _Stack:
+    """
+    Stack of elements with a movable cursor.
+
+    Mimics home/back/forward in a web browser.
+    """
+
+    def __init__(self):
+        self._pos = -1
+        self._elements = []
+
+    def clear(self):
+        """Empty the stack."""
+        self._pos = -1
+        self._elements = []
+
+    def __call__(self):
+        """Return the current element, or None."""
+        return self._elements[self._pos] if self._elements else None
+
+    def __len__(self):
+        return len(self._elements)
+
+    def __getitem__(self, ind):
+        return self._elements[ind]
+
+    def forward(self):
+        """Move the position forward and return the current element."""
+        self._pos = min(self._pos + 1, len(self._elements) - 1)
+        return self()
+
+    def back(self):
+        """Move the position back and return the current element."""
+        self._pos = max(self._pos - 1, 0)
+        return self()
+
+    def push(self, o):
+        """
+        Push *o* to the stack after the current position, and return *o*.
+
+        Discard all later elements.
+        """
+        self._elements[self._pos + 1:] = [o]
+        self._pos = len(self._elements) - 1
+        return o
+
+    def home(self):
+        """
+        Push the first element onto the top of the stack.
+
+        The first element is returned.
+        """
+        return self.push(self._elements[0]) if self._elements else None
+
+
 def safe_masked_invalid(x, copy=False):
     x = np.array(x, subok=True, copy=copy)
     if not x.dtype.isnative: