Deprecate accessing QuiverKey internal Artists

QuLogic · QuLogic · commit abe033e0847b · 2024-03-26T06:20:30.000-04:00
diff --git a/doc/api/next_api_changes/deprecations/18794-ES.rst b/doc/api/next_api_changes/deprecations/18794-ES.rst
@@ -0,0 +1,10 @@
+``QuiverKey`` internal Artists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Access to the following `.quiver.QuiverKey` internal Artists is now deprecated.
+You may instead use `.quiver.QuiverKey`-level methods to modify these Artists.
+
+- ``QuiverKey.text``
+- ``QuiverKey.vector``
+- ``QuiverKey.verts``
+
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -238,6 +238,10 @@ class QuiverKey(martist.Artist):
     valign = {'N': 'bottom', 'S': 'top', 'E': 'center', 'W': 'center'}
     pivot = {'N': 'middle', 'S': 'middle', 'E': 'tip', 'W': 'tail'}
 
+    text = _api.deprecate_privatize_attribute('3.9', alternative='QuiverKey methods')
+    vector = _api.deprecate_privatize_attribute('3.9')
+    verts = _api.deprecate_privatize_attribute('3.9')
+
     def __init__(self, Q, X, Y, U, label,
                  *, angle=0, coordinates='axes', color=None, labelsep=0.1,
                  labelpos='N', labelcolor=None, fontproperties=None, **kwargs):
@@ -300,7 +304,7 @@ def __init__(self, Q, X, Y, U, label,
         self._labelpos = labelpos
         self.fontproperties = fontproperties or dict()
         self.kw = kwargs
-        self.text = mtext.Text(
+        self._text = mtext.Text(
             x=X, y=Y, text=label,
             horizontalalignment=self.halign[self._labelpos],
             verticalalignment=self.valign[self._labelpos],
@@ -311,7 +315,7 @@ def __init__(self, Q, X, Y, U, label,
 
     def get_x(self):
         """Return the *x* position of the QuiverKey."""
-        return self.text.get_position()[0]
+        return self._text.get_position()[0]
 
     def set_x(self, x):
         """
@@ -322,14 +326,14 @@ def set_x(self, x):
         x : float
             The *x* location of the key.
         """
-        self.text.set_x(x)
+        self._text.set_x(x)
         self.stale = True
 
     X = property(get_x, set_x)
 
     def get_y(self):
         """Return the *y* position of the QuiverKey."""
-        return self.text.get_position()[1]
+        return self._text.get_position()[1]
 
     def set_y(self, y):
         """
@@ -340,14 +344,14 @@ def set_y(self, y):
         y : float
             The *y* location of the key.
         """
-        self.text.set_y(y)
+        self._text.set_y(y)
         self.stale = True
 
     Y = property(get_y, set_y)
 
     def get_position(self):
         """Return the (x, y) position of the QuiverKey."""
-        return self.text.get_position()
+        return self._text.get_position()
 
     def set_position(self, xy):
         """
@@ -358,27 +362,27 @@ def set_position(self, xy):
         xy : (float, float)
             The (*x*, *y*) position of the QuiverKey.
         """
-        self.text.set_position(xy)
+        self._text.set_position(xy)
         self.stale = True
 
     def get_label_text(self):
         """Return the label string."""
-        return self.text.get_text()
+        return self._text.get_text()
 
     def set_label_text(self, text):
         """Set the label string."""
-        self.text.set_text(text)
+        self._text.set_text(text)
         self.stale = True
 
     label = property(get_label_text, set_label_text, doc="The label string.")
 
     def get_label_color(self):
         """Return the label color."""
-        return self.text.get_color()
+        return self._text.get_color()
 
     def set_label_color(self, labelcolor):
         """Set the label color."""
-        self.text.set_color(labelcolor)
+        self._text.set_color(labelcolor)
         self.stale = True
 
     labelcolor = property(get_label_color, set_label_color, doc="The label color.")
@@ -399,8 +403,8 @@ def set_label_pos(self, labelpos):
         """
         _api.check_in_list(['N', 'S', 'E', 'W'], labelpos=labelpos)
         self._labelpos = labelpos
-        self.text.set_horizontalalignment(self.halign[labelpos])
-        self.text.set_verticalalignment(self.valign[labelpos])
+        self._text.set_horizontalalignment(self.halign[labelpos])
+        self._text.set_verticalalignment(self.valign[labelpos])
         self._update_text_transform()
         self._initialized = False
         self.stale = True
@@ -432,19 +436,19 @@ def _init(self):
                                    Umask=ma.nomask):
                 u = self.U * np.cos(np.radians(self.angle))
                 v = self.U * np.sin(np.radians(self.angle))
-                self.verts = self.Q._make_verts([[0., 0.]],
+                self._verts = self.Q._make_verts([[0., 0.]],
                                                 np.array([u]), np.array([v]), 'uv')
             kwargs = self.Q.polykw
             kwargs.update(self.kw)
-            self.vector = mcollections.PolyCollection(
-                self.verts,
+            self._vector = mcollections.PolyCollection(
+                self._verts,
                 offsets=[(self.X, self.Y)],
                 offset_transform=self.get_transform(),
                 **kwargs)
             if self.color is not None:
-                self.vector.set_color(self.color)
-            self.vector.set_transform(self.Q.get_transform())
-            self.vector.set_figure(self.get_figure())
+                self._vector.set_color(self.color)
+            self._vector.set_transform(self.Q.get_transform())
+            self._vector.set_figure(self.get_figure())
             self._dpi_at_last_init = self.Q.axes.figure.dpi
 
     def _update_text_transform(self):
@@ -454,15 +458,15 @@ def _update_text_transform(self):
             "E": (+self._labelsep_inches, 0),
             "W": (-self._labelsep_inches, 0),
         }[self._labelpos]
-        self.text.set_transform(
+        self._text.set_transform(
             transforms.offset_copy(self.get_transform(), self.figure, x=x, y=y))
 
     @martist.allow_rasterization
     def draw(self, renderer):
         self._init()
-        self.vector.draw(renderer)
+        self._vector.draw(renderer)
         self._update_text_transform()
-        self.text.draw(renderer)
+        self._text.draw(renderer)
         self.stale = False
 
     def _set_transform(self):
@@ -475,15 +479,14 @@ def _set_transform(self):
 
     def set_figure(self, fig):
         super().set_figure(fig)
-        self.text.set_figure(fig)
+        self._text.set_figure(fig)
 
     def contains(self, mouseevent):
         if self._different_canvas(mouseevent):
             return False, {}
         # Maybe the dictionary should allow one to
         # distinguish between a text hit and a vector hit.
-        if (self.text.contains(mouseevent)[0] or
-                self.vector.contains(mouseevent)[0]):
+        if self._text.contains(mouseevent)[0] or self._vector.contains(mouseevent)[0]:
             return True, {}
         return False, {}
 
diff --git a/lib/matplotlib/tests/test_quiver.py b/lib/matplotlib/tests/test_quiver.py
@@ -267,7 +267,7 @@ def test_quiverkey_angles():
     qk = ax.quiverkey(q, 1, 1, 2, 'Label')
     # The arrows are only created when the key is drawn
     fig.canvas.draw()
-    assert len(qk.verts) == 1
+    assert len(qk._verts) == 1
 
 
 def test_quiverkey_angles_xy_aitoff():
@@ -296,7 +296,7 @@ def test_quiverkey_angles_xy_aitoff():
         qk = ax.quiverkey(q, 0, 0, 1, '1 units')
 
         fig.canvas.draw()
-        assert len(qk.verts) == 1
+        assert len(qk._verts) == 1
 
 
 def test_quiverkey_angles_scale_units_cartesian():
@@ -323,7 +323,7 @@ def test_quiverkey_angles_scale_units_cartesian():
         qk = ax.quiverkey(q, 0, 0, 1, '1 units')
 
         fig.canvas.draw()
-        assert len(qk.verts) == 1
+        assert len(qk._verts) == 1
 
 
 def test_quiver_setuvc_numbers():
