Move transform type checks and improve docs

ZachDaChampion · ZachDaChampion · commit e33abe5e845c · 2023-04-12T12:41:13.000-04:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -597,12 +597,9 @@ def invert(x):
         if not (location in ['top', 'bottom'] or isinstance(location, Real)):
             raise ValueError('secondary_xaxis location must be either '
                              'a float or "top"/"bottom"')
-        if not (isinstance(transform, mtransforms.Transform) or transform is None):
-            raise ValueError('transform must be either an mtransforms.Transform '
-                             'or None')
 
         secondary_ax = SecondaryAxis(self, 'x', location, functions,
-                                        transform, **kwargs)
+                                     transform, **kwargs)
         self.add_child_axes(secondary_ax)
         return secondary_ax
 
@@ -628,15 +625,25 @@ def secondary_yaxis(self, location, *, functions=None, transform=None, **kwargs)
             secax = ax.secondary_yaxis('right', functions=(np.deg2rad,
                                                            np.rad2deg))
             secax.set_ylabel('radians')
+
+        To add a secondary axis relative to your data, you can pass a transform
+        to the new axis.
+
+        .. plot::
+
+            fig, ax = plt.subplots()
+            ax.plot(range(0, 5), range(-1, 4))
+
+            # Pass 'ax.transData' as a transform to place the axis
+            # relative to your data at x=0
+            secax = ax.secondary_yaxis(3, transform=ax.transData)
         """
         if not (location in ['left', 'right'] or isinstance(location, Real)):
             raise ValueError('secondary_xaxis location must be either '
                              'a float or "left"/"right"')
-        if not (isinstance(transform, mtransforms.Transform) or transform is None):
-            raise ValueError('transform must be either an mtransforms.Transform '
-                             'or None')
+
         secondary_ax = SecondaryAxis(self, 'y', location, functions,
-                                        transform, **kwargs)
+                                     transform, **kwargs)
         self.add_child_axes(secondary_ax)
         return secondary_ax
 
diff --git a/lib/matplotlib/axes/_secondary_axes.py b/lib/matplotlib/axes/_secondary_axes.py
@@ -90,10 +90,15 @@ def set_location(self, location, transform=None):
 
         transform : `.Transform`, optional
             Transform for the location to use. Defaults to
-            self._parent.transAxes, so locations are normally relative to
+            the parent's ``transAxes``, so locations are normally relative to
             the parent axes.
+
+            .. versionadded:: 3.8
         """
 
+        # Make sure transform is a Transform or None.
+        _api.check_isinstance((transforms.Transform, None), transform=transform)
+
         # This puts the rectangle into figure-relative coordinates.
         if isinstance(location, str):
             _api.check_in_list(self._locstrings, location=location)
@@ -132,8 +137,7 @@ def set_location(self, location, transform=None):
         # so it never needs to know where the parent is explicitly in
         # figure coordinates.
         # it gets called in ax.apply_aspect() (of all places)
-        self.set_axes_locator(
-            _TransformedBoundsLocator(bounds, transform))
+        self.set_axes_locator(_TransformedBoundsLocator(bounds, transform))
 
     def apply_aspect(self, position=None):
         # docstring inherited.
@@ -281,12 +285,6 @@ def set_color(self, color):
     parent axes to put the new axes, 0.0 being the bottom (or left)
     and 1.0 being the top (or right).
 
-transform : `.Transform`, optional
-    An optional transform that can be passed. *location* will be
-    placed relative to this transform (in the direction of the axis)
-    rather than the parent's axis. i.e. a secondary x-axis will
-    use the provided y transform and the x transform of the parent.
-
 functions : 2-tuple of func, or Transform with an inverse
 
     If a 2-tuple of functions, the user specifies the transform
@@ -301,6 +299,14 @@ def set_color(self, color):
     See :doc:`/gallery/subplots_axes_and_figures/secondary_axis`
     for examples of making these conversions.
 
+transform : `.Transform`, optional
+    An optional transform that can be passed. *location* will be
+    placed relative to this transform (in the direction of the axis)
+    rather than the parent's axis. i.e. a secondary x-axis will
+    use the provided y transform and the x transform of the parent.
+
+    .. versionadded:: 3.8
+
 Returns
 -------
 ax : axes._secondary_axes.SecondaryAxis
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -7241,7 +7241,7 @@ def test_secondary_fail():
         ax.secondary_xaxis('right')
     with pytest.raises(ValueError):
         ax.secondary_yaxis('bottom')
-    with pytest.raises(ValueError):
+    with pytest.raises(TypeError):
         ax.secondary_xaxis(0.2, transform='error')
 
 
