Make _apply_theta_transforms public

Author: dstansby

doc/api/next_api_changes/deprecations/24834-DS.rst

@@ -2,6 +2,15 @@ Applying theta transforms in ``PolarTransform``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Applying theta transforms in `~matplotlib.projections.polar.PolarTransform`
 and `~matplotlib.projections.polar.InvertedPolarTransform`
-is deprecated. This is currently the default behaviour, so to prevent
-a warning, manually pass ``_apply_theta_transforms=False``, and
-apply any theta shift before passing points to this transform.
+is deprecated, and will be removed in a future version of Matplotlib. This
+is currently the default behaviour when these transforms are used externally,
+but only takes affect when:
+
+- An axis is associated with the transform.
+- The axis has a non-zero theta offset or has theta values increasing in
+  a clockwise direction.
+
+To silence this warning and adopt future behaviour,
+set ``apply_theta_transforms=False``. If you need to retain the behaviour
+where theta values are transformed, chain the ``PolarTransform`` with
+another transform that performs the theta shift and/or sign shift.

galleries/examples/axisartist/demo_curvelinear_grid.py

@@ -55,7 +55,7 @@ def curvelinear_test2(fig):
     # PolarAxes.PolarTransform takes radian. However, we want our coordinate
     # system in degree
     tr = Affine2D().scale(np.pi/180, 1) + PolarAxes.PolarTransform(
-        _apply_theta_transforms=False)
+        apply_theta_transforms=False)
     # Polar projection, which involves cycle, and also has limits in
     # its coordinates, needs a special method to find the extremes
     # (min, max of the coordinate within the view).

galleries/examples/axisartist/demo_floating_axes.py

@@ -54,7 +54,7 @@ def setup_axes2(fig, rect):
     With custom locator and formatter.
     Note that the extreme values are swapped.
     """
-    tr = PolarAxes.PolarTransform(_apply_theta_transforms=False)
+    tr = PolarAxes.PolarTransform(apply_theta_transforms=False)
 
     pi = np.pi
     angle_ticks = [(0, r"$0$"),
@@ -100,7 +100,7 @@ def setup_axes3(fig, rect):
     tr_scale = Affine2D().scale(np.pi/180., 1.)
 
     tr = tr_rotate + tr_scale + PolarAxes.PolarTransform(
-        _apply_theta_transforms=False)
+        apply_theta_transforms=False)
 
     grid_locator1 = angle_helper.LocatorHMS(4)
     tick_formatter1 = angle_helper.FormatterHMS()

galleries/examples/axisartist/demo_floating_axis.py

@@ -23,7 +23,7 @@ def curvelinear_test2(fig):
     """Polar projection, but in a rectangular box."""
     # see demo_curvelinear_grid.py for details
     tr = Affine2D().scale(np.pi / 180., 1.) + PolarAxes.PolarTransform(
-        _apply_theta_transforms=False)
+        apply_theta_transforms=False)
 
     extreme_finder = angle_helper.ExtremeFinderCycle(20,
                                                      20,

galleries/examples/axisartist/simple_axis_pad.py

@@ -22,7 +22,7 @@ def setup_axes(fig, rect):
 
     # see demo_curvelinear_grid.py for details
     tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform(
-        _apply_theta_transforms=False)
+        apply_theta_transforms=False)
 
     extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
                                                      lon_cycle=360,

lib/matplotlib/projections/polar.py

@@ -19,10 +19,10 @@ def _apply_theta_transforms_warn():
     _api.warn_deprecated(
                 "3.7",
                 message=(
-                    "Passing `_apply_theta_transforms=True` (the default) "
+                    "Passing `apply_theta_transforms=True` (the default) "
                     "is deprecated. Support for this will be removed in "
                     "Matplotlib %(removal)s. To prevent this warning, "
-                    "set `_apply_theta_transforms=False`, and make sure to "
+                    "set `apply_theta_transforms=False`, and make sure to "
                     "shift theta values before being passed to this transform."
                 )
             )
@@ -47,8 +47,8 @@ class PolarTransform(mtransforms.Transform):
 
     input_dims = output_dims = 2
 
-    def __init__(self, axis=None, use_rmin=True,
-                 _apply_theta_transforms=True, *, scale_transform=None):
+    def __init__(self, axis=None, use_rmin=True, *,
+                 apply_theta_transforms=True, scale_transform=None):
         """
         Parameters
         ----------
@@ -63,15 +63,15 @@ def __init__(self, axis=None, use_rmin=True,
         super().__init__()
         self._axis = axis
         self._use_rmin = use_rmin
-        self._apply_theta_transforms = _apply_theta_transforms
+        self._apply_theta_transforms = apply_theta_transforms
         self._scale_transform = scale_transform
-        if _apply_theta_transforms:
+        if apply_theta_transforms:
             _apply_theta_transforms_warn()
 
     __str__ = mtransforms._make_str_method(
         "_axis",
         use_rmin="_use_rmin",
-        _apply_theta_transforms="_apply_theta_transforms")
+        apply_theta_transforms="_apply_theta_transforms")
 
     def _get_rorigin(self):
         # Get lower r limit after being scaled by the radial scale transform
@@ -148,8 +148,10 @@ def transform_path_non_affine(self, path):
 
     def inverted(self):
         # docstring inherited
-        return PolarAxes.InvertedPolarTransform(self._axis, self._use_rmin,
-                                                self._apply_theta_transforms)
+        return PolarAxes.InvertedPolarTransform(
+            self._axis, self._use_rmin,
+            apply_theta_transforms=self._apply_theta_transforms
+        )
 
 
 class PolarAffine(mtransforms.Affine2DBase):
@@ -208,7 +210,7 @@ class InvertedPolarTransform(mtransforms.Transform):
     input_dims = output_dims = 2
 
     def __init__(self, axis=None, use_rmin=True,
-                 _apply_theta_transforms=True):
+                 *, apply_theta_transforms=True):
         """
         Parameters
         ----------
@@ -223,14 +225,14 @@ def __init__(self, axis=None, use_rmin=True,
         super().__init__()
         self._axis = axis
         self._use_rmin = use_rmin
-        self._apply_theta_transforms = _apply_theta_transforms
-        if _apply_theta_transforms:
+        self._apply_theta_transforms = apply_theta_transforms
+        if apply_theta_transforms:
             _apply_theta_transforms_warn()
 
     __str__ = mtransforms._make_str_method(
         "_axis",
         use_rmin="_use_rmin",
-        _apply_theta_transforms="_apply_theta_transforms")
+        apply_theta_transforms="_apply_theta_transforms")
 
     @_api.rename_parameter("3.8", "xy", "values")
     def transform_non_affine(self, values):
@@ -251,8 +253,10 @@ def transform_non_affine(self, values):
 
     def inverted(self):
         # docstring inherited
-        return PolarAxes.PolarTransform(self._axis, self._use_rmin,
-                                        self._apply_theta_transforms)
+        return PolarAxes.PolarTransform(
+            self._axis, self._use_rmin,
+            apply_theta_transforms=self._apply_theta_transforms
+        )
 
 
 class ThetaFormatter(mticker.Formatter):
@@ -896,7 +900,7 @@ def _set_lim_and_transforms(self):
         # data.  This one is aware of rmin
         self.transProjection = self.PolarTransform(
             self,
-            _apply_theta_transforms=False,
+            apply_theta_transforms=False,
             scale_transform=self.transScale
         )
         # Add dependency on rorigin.

lib/matplotlib/tests/test_transforms.py

@@ -859,7 +859,7 @@ def test_str_transform():
         PolarTransform(
             PolarAxes(0.125,0.1;0.775x0.8),
             use_rmin=True,
-            _apply_theta_transforms=False)),
+            apply_theta_transforms=False)),
     CompositeGenericTransform(
         CompositeGenericTransform(
             PolarAffine(

lib/matplotlib/text.py

@@ -1497,7 +1497,7 @@ def _get_xy_transform(self, renderer, coords):
             return self.axes.transData
         elif coords == 'polar':
             from matplotlib.projections import PolarAxes
-            tr = PolarAxes.PolarTransform(_apply_theta_transforms=False)
+            tr = PolarAxes.PolarTransform(apply_theta_transforms=False)
             trans = tr + self.axes.transData
             return trans
 

lib/mpl_toolkits/axisartist/tests/test_floating_axes.py

@@ -24,7 +24,7 @@ def test_curvelinear3():
     fig = plt.figure(figsize=(5, 5))
 
     tr = (mtransforms.Affine2D().scale(np.pi / 180, 1) +
-          mprojections.PolarAxes.PolarTransform(_apply_theta_transforms=False))
+          mprojections.PolarAxes.PolarTransform(apply_theta_transforms=False))
     grid_helper = GridHelperCurveLinear(
         tr,
         extremes=(0, 360, 10, 3),
@@ -73,7 +73,7 @@ def test_curvelinear4():
     fig = plt.figure(figsize=(5, 5))
 
     tr = (mtransforms.Affine2D().scale(np.pi / 180, 1) +
-          mprojections.PolarAxes.PolarTransform(_apply_theta_transforms=False))
+          mprojections.PolarAxes.PolarTransform(apply_theta_transforms=False))
     grid_helper = GridHelperCurveLinear(
         tr,
         extremes=(120, 30, 10, 0),

lib/mpl_toolkits/axisartist/tests/test_grid_helper_curvelinear.py

@@ -83,7 +83,7 @@ def test_polar_box():
     # PolarAxes.PolarTransform takes radian. However, we want our coordinate
     # system in degree
     tr = (Affine2D().scale(np.pi / 180., 1.) +
-          PolarAxes.PolarTransform(_apply_theta_transforms=False))
+          PolarAxes.PolarTransform(apply_theta_transforms=False))
 
     # polar projection, which involves cycle, and also has limits in
     # its coordinates, needs a special method to find the extremes
@@ -146,7 +146,7 @@ def test_axis_direction():
     # PolarAxes.PolarTransform takes radian. However, we want our coordinate
     # system in degree
     tr = (Affine2D().scale(np.pi / 180., 1.) +
-          PolarAxes.PolarTransform(_apply_theta_transforms=False))
+          PolarAxes.PolarTransform(apply_theta_transforms=False))
 
     # polar projection, which involves cycle, and also has limits in
     # its coordinates, needs a special method to find the extremes