Cleanup QuiverKey init and deprecate some attributes.

anntzer · anntzer · commit e0b151a3f554 · 2026-02-17T17:46:14.000+01:00
Ensure that QuiverKey.vector exists as soon as the constructor exits,
rather than waiting for the first draw.

Deprecate the `fontproperties`, `labelcolor`, and `verts` attribute
(overwriting them would not actually update the underlying artist
(except before the first draw) anyways).  Also deprecate `kw` (which
*could* be updated with effect, but it seems simpler to directly update
the underlying artist here too, if really needed; moreover the old
version, which mutated `self.Q.polykw` *in-place*, likely led to weird
side-effects e.g. if a key is first added to `kw`, a draw is triggered,
mutating `self.Q.polykw`, then the key is removed).
diff --git a/doc/api/next_api_changes/deprecations/31170-AL.rst b/doc/api/next_api_changes/deprecations/31170-AL.rst
@@ -0,0 +1,6 @@
+``kw``, ``fontproperties``, ``labelcolor``, and ``verts`` attributes of ``QuiverKey``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These attributes are deprecated (note that ``fontproperties``, ``labelcolor``,
+or ``verts`` after the first draw had no effect previously).  Directly
+access the relevant attributes on the sub-artists ``QuiverKey.vector`` and
+``QuiverKey.text``, instead.
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -345,47 +345,57 @@ def __init__(self, Q, X, Y, U, label,
         self._labelsep_inches = labelsep
 
         self.labelpos = labelpos
-        self.labelcolor = labelcolor
-        self.fontproperties = fontproperties or dict()
-        self.kw = kwargs
+        self._kw = kwargs  # Remove when kw deprecation elapses.
+        self.vector = mcollections.PolyCollection(
+            [], **{**self.Q.polykw, **kwargs})
         self.text = mtext.Text(
             text=label,
             horizontalalignment=self.halign[self.labelpos],
             verticalalignment=self.valign[self.labelpos],
-            fontproperties=self.fontproperties)
-        if self.labelcolor is not None:
-            self.text.set_color(self.labelcolor)
+            fontproperties=fontproperties or {})
+        if labelcolor is not None:
+            self.text.set_color(labelcolor)
         self._dpi_at_last_init = None
         self.zorder = zorder if zorder is not None else Q.zorder + 0.1
 
+    kw = _api.deprecated("3.11")(  # Also remove self._kw when deprecation elapses.
+        property(lambda self: self._kw))
+    fontproperties = _api.deprecated(
+        "3.11", alternative="quiverkey.text.get_fontproperties()")(
+            property(lambda self: self.text.get_fontproperties()))
+    labelcolor = _api.deprecated(
+        "3.11", alternative="quiverkey.text.get_color()")(
+            property(lambda self: self.text.get_color()))
+    verts = _api.deprecated(
+        "3.11", alternative="[p.vertices for p in quiverkey.vector.get_paths()]")(
+            property(lambda self: [p.vertices for p in self.vector.get_paths()]))
+
     @property
     def labelsep(self):
         return self._labelsep_inches * self.Q.axes.get_figure(root=True).dpi
 
     def _init(self):
-        if True:  # self._dpi_at_last_init != self.axes.get_figure().dpi
-            if self.Q._dpi_at_last_init != self.Q.axes.get_figure(root=True).dpi:
-                self.Q._init()
-            self._set_transform()
-            with cbook._setattr_cm(self.Q, pivot=self.pivot[self.labelpos],
-                                   # Hack: save and restore the Umask
-                                   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.]],
-                                                np.array([u]), np.array([v]), 'uv')
-            kwargs = self.Q.polykw
-            kwargs.update(self.kw)
-            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._dpi_at_last_init = self.Q.axes.get_figure(root=True).dpi
+        if False:  # self._dpi_at_last_init == self.axes.get_figure().dpi
+            return
+        if self.Q._dpi_at_last_init != self.Q.axes.get_figure(root=True).dpi:
+            self.Q._init()
+        self._set_transform()
+        with cbook._setattr_cm(self.Q, pivot=self.pivot[self.labelpos],
+                               # Hack: save and restore the Umask
+                               Umask=ma.nomask):
+            u = self.U * np.cos(np.radians([self.angle]))
+            v = self.U * np.sin(np.radians([self.angle]))
+            verts = self.Q._make_verts([[0., 0.]], u, v, 'uv')
+        self.vector.set(
+            verts=verts,
+            offsets=[(self.X, self.Y)],
+            offset_transform=self.get_transform(),
+            transform=self.Q.get_transform(),
+            figure=self.get_figure(),
+        )
+        if self.color is not None:
+            self.vector.set_color(self.color)
+        self._dpi_at_last_init = self.Q.axes.get_figure(root=True).dpi
 
     def _text_shift(self):
         return {
diff --git a/lib/matplotlib/quiver.pyi b/lib/matplotlib/quiver.pyi
@@ -25,9 +25,6 @@ class QuiverKey(martist.Artist):
     color: ColorType | None
     label: str
     labelpos: Literal["N", "S", "E", "W"]
-    labelcolor: ColorType | None
-    fontproperties: dict[str, Any]
-    kw: dict[str, Any]
     text: Text
     zorder: float
     def __init__(
@@ -49,6 +46,14 @@ class QuiverKey(martist.Artist):
         **kwargs
     ) -> None: ...
     @property
+    def kw(self) -> dict[str, Any]: ...
+    @property
+    def fontproperties(self) -> dict[str, Any]: ...
+    @property
+    def labelcolor(self) -> ColorType | None: ...
+    @property
+    def verts(self) -> Sequence[ArrayLike]: ...
+    @property
     def labelsep(self) -> float: ...
     def set_figure(self, fig: Figure | SubFigure) -> None: ...
 
diff --git a/lib/matplotlib/tests/test_quiver.py b/lib/matplotlib/tests/test_quiver.py
@@ -266,7 +266,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.vector.get_paths()) == 1
 
 
 def test_quiverkey_angles_xy_aitoff():
@@ -295,7 +295,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.vector.get_paths()) == 1
 
 
 def test_quiverkey_angles_scale_units_cartesian():
@@ -322,7 +322,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.vector.get_paths()) == 1
 
 
 def test_quiver_setuvc_numbers():
