Backport PR matplotlib#31691: DOC: Add a warning on methods to access Tick parts (lines, labels, grid)

Author: timhoffm

lib/matplotlib/axis.py

@@ -1492,7 +1492,18 @@ def draw(self, renderer):
         self.stale = False
 
     def get_gridlines(self):
-        r"""Return this Axis' grid lines as a list of `.Line2D`\s."""
+        """
+        Return this Axis' grid lines as a list of `.Line2D`.
+
+        .. warning::
+
+            Ticks and their constituent parts, including grid lines, are not
+            persistent. Various operations can create, delete, and modify the tick
+            instances; see :ref:`axes-tick-objects`.
+
+            You should generally use `.Axis.set_tick_params` / `.Axis.get_tick_params`
+            to define and query grid styling; see :ref:`axes-ticks-styling`.
+        """
         ticks = self.get_major_ticks()
         return cbook.silent_list('Line2D gridline',
                                  [tick.gridline for tick in ticks])
@@ -1523,15 +1534,37 @@ def get_pickradius(self):
         return self._pickradius
 
     def get_majorticklabels(self):
-        """Return this Axis' major tick labels, as a list of `~.text.Text`."""
+        """
+        Return this Axis' major tick labels, as a list of `~.text.Text`.
+
+        .. warning::
+
+            Ticks and their constituent parts, including tick labels, are not
+            persistent. Various operations can create, delete, and modify the tick
+            instances; see :ref:`axes-tick-objects`.
+
+            You should generally use `.Axis.set_tick_params` / `.Axis.get_tick_params`
+            to define and query tick styling; see :ref:`axes-ticks-styling`.
+        """
         self._update_ticks()
         ticks = self.get_major_ticks()
         labels1 = [tick.label1 for tick in ticks if tick.label1.get_visible()]
         labels2 = [tick.label2 for tick in ticks if tick.label2.get_visible()]
         return labels1 + labels2
 
     def get_minorticklabels(self):
-        """Return this Axis' minor tick labels, as a list of `~.text.Text`."""
+        """
+        Return this Axis' minor tick labels, as a list of `~.text.Text`.
+
+        .. warning::
+
+            Ticks and their constituent parts, including tick labels, are not
+            persistent. Various operations can create, delete, and modify the tick
+            instances; see :ref:`axes-tick-objects`.
+
+            You should generally use `.Axis.set_tick_params` / `.Axis.get_tick_params`
+            to define and query tick styling; see :ref:`axes-ticks-styling`.
+        """
         self._update_ticks()
         ticks = self.get_minor_ticks()
         labels1 = [tick.label1 for tick in ticks if tick.label1.get_visible()]
@@ -1542,6 +1575,15 @@ def get_ticklabels(self, minor=False, which=None):
         """
         Get this Axis' tick labels.
 
+        .. warning::
+
+            Ticks and their constituent parts, including tick labels, are not
+            persistent. Various operations can create, delete, and modify the tick
+            instances; see :ref:`axes-tick-objects`.
+
+            You should generally use `.Axis.set_tick_params` / `.Axis.get_tick_params`
+            to define and query tick styling; see :ref:`axes-ticks-styling`.
+
         Parameters
         ----------
         minor : bool
@@ -1570,7 +1612,18 @@ def get_ticklabels(self, minor=False, which=None):
         return self.get_majorticklabels()
 
     def get_majorticklines(self):
-        r"""Return this Axis' major tick lines as a list of `.Line2D`\s."""
+        """
+        Return this Axis' major tick lines as a list of `.Line2D`.
+
+        .. warning::
+
+            Ticks and their constituent parts, including tick lines, are not
+            persistent. Various operations can create, delete, and modify the tick
+            instances; see :ref:`axes-tick-objects`.
+
+            You should generally use `.Axis.set_tick_params` / `.Axis.get_tick_params`
+            to define and query tick styling; see :ref:`axes-ticks-styling`.
+        """
         lines = []
         ticks = self.get_major_ticks()
         for tick in ticks:
@@ -1579,7 +1632,18 @@ def get_majorticklines(self):
         return cbook.silent_list('Line2D ticklines', lines)
 
     def get_minorticklines(self):
-        r"""Return this Axis' minor tick lines as a list of `.Line2D`\s."""
+        """
+        Return this Axis' minor tick lines as a list of `.Line2D`.
+
+        .. warning::
+
+            Ticks and their constituent parts, including tick lines, are not
+            persistent. Various operations can create, delete, and modify the tick
+            instances; see :ref:`axes-tick-objects`.
+
+            You should generally use `.Axis.set_tick_params` / `.Axis.get_tick_params`
+            to define and query tick styling; see :ref:`axes-ticks-styling`.
+        """
         lines = []
         ticks = self.get_minor_ticks()
         for tick in ticks:
@@ -1588,7 +1652,18 @@ def get_minorticklines(self):
         return cbook.silent_list('Line2D ticklines', lines)
 
     def get_ticklines(self, minor=False):
-        r"""Return this Axis' tick lines as a list of `.Line2D`\s."""
+        """
+        Return this Axis' tick lines as a list of `.Line2D`.
+
+        .. warning::
+
+            Ticks and their constituent parts, including tick lines, are not
+            persistent. Various operations can create, delete, and modify the tick
+            instances; see :ref:`axes-tick-objects`.
+
+            You should generally use `.Axis.set_tick_params` / `.Axis.get_tick_params`
+            to define and query tick styling; see :ref:`axes-ticks-styling`.
+        """
         if minor:
             return self.get_minorticklines()
         return self.get_majorticklines()