Merge ParasiteAxesAuxTransBase into ParasiteAxesBase.

anntzer · anntzer · commit 1f79f5beed2b · 2020-10-07T02:06:47.000+02:00
It doesn't warrant being a separate mixin class (cf. merging of Subplot
into Axes -- flat is better than nested).

Also, currently mpl_toolkits axes mixins create non-picklable Axes
subclasses because they lack the same pickling machinery as the
standard SubplotBase mixin.  It's not too hard to also set up the
same machinery for mpl_toolkits mixins (planned for a later PR), but
also supporting the double-mixin case (both ParasiteAxesBase and
ParasiteAxesAuxTransBase) adds unnecessary complications.
diff --git a/doc/api/next_api_changes/deprecations/YYYYY-AL.rst b/doc/api/next_api_changes/deprecations/YYYYY-AL.rst
@@ -0,0 +1,11 @@
+ParasiteAxesAuxTransBase
+~~~~~~~~~~~~~~~~~~~~~~~~
+The functionality of that mixin class has been moved to the base
+``ParasiteAxesBase`` class.  Thus, ``ParasiteAxesAuxTransBase``,
+``ParasiteAxesAuxTrans``, and ``parasite_axes_auxtrans_class_factory`` are
+deprecated.
+
+In general, it is suggested to use ``HostAxes.get_aux_axes`` to create
+parasite axes, as this saves the need of manually appending the parasite
+to ``host.parasites`` and makes sure that their ``remove()`` method works
+properly.
diff --git a/examples/axisartist/demo_curvelinear_grid.py b/examples/axisartist/demo_curvelinear_grid.py
@@ -17,8 +17,7 @@
 from matplotlib.projections import PolarAxes
 from matplotlib.transforms import Affine2D
 
-from mpl_toolkits.axisartist import (
-    angle_helper, Axes, HostAxes, ParasiteAxesAuxTrans)
+from mpl_toolkits.axisartist import angle_helper, Axes, HostAxes
 from mpl_toolkits.axisartist.grid_helper_curvelinear import (
     GridHelperCurveLinear)
 
@@ -100,7 +99,7 @@ def curvelinear_test2(fig):
     ax1.grid(True, zorder=0)
 
     # A parasite axes with given transform
-    ax2 = ParasiteAxesAuxTrans(ax1, tr, "equal")
+    ax2 = ax1.get_aux_axes(tr, "equal")
     # note that ax2.transData == tr + ax1.transData
     # Anything you draw in ax2 will match the ticks and grids of ax1.
     ax1.parasites.append(ax2)
diff --git a/lib/mpl_toolkits/axes_grid/parasite_axes.py b/lib/mpl_toolkits/axes_grid/parasite_axes.py
@@ -1,10 +1,12 @@
+from matplotlib import cbook
 from mpl_toolkits.axes_grid1.parasite_axes import (
     host_axes_class_factory, parasite_axes_class_factory,
     parasite_axes_auxtrans_class_factory, subplot_class_factory)
 from mpl_toolkits.axisartist.axislines import Axes
 
 
 ParasiteAxes = parasite_axes_class_factory(Axes)
-ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
 HostAxes = host_axes_class_factory(Axes)
 SubplotHost = subplot_class_factory(HostAxes)
+with cbook._suppress_matplotlib_deprecation_warning():
+    ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
diff --git a/lib/mpl_toolkits/axes_grid1/parasite_axes.py b/lib/mpl_toolkits/axes_grid1/parasite_axes.py
@@ -10,13 +10,12 @@
 
 class ParasiteAxesBase:
 
-    def get_images_artists(self):
-        artists = {a for a in self.get_children() if a.get_visible()}
-        images = {a for a in self.images if a.get_visible()}
-        return list(images), list(artists - images)
-
-    def __init__(self, parent_axes, **kwargs):
+    def __init__(self, parent_axes,
+                 aux_transform=None, viewlim_mode=None,
+                 **kwargs):
         self._parent_axes = parent_axes
+        self.transAux = aux_transform
+        self.set_viewlim_mode(viewlim_mode)
         kwargs["frameon"] = False
         super().__init__(parent_axes.figure, parent_axes._position, **kwargs)
 
@@ -25,6 +24,11 @@ def cla(self):
         martist.setp(self.get_children(), visible=False)
         self._get_lines = self._parent_axes._get_lines
 
+    def get_images_artists(self):
+        artists = {a for a in self.get_children() if a.get_visible()}
+        images = {a for a in self.images if a.get_visible()}
+        return list(images), list(artists - images)
+
     def pick(self, mouseevent):
         # This most likely goes to Artist.pick (depending on axes_class given
         # to the factory), which only handles pick events registered on the
@@ -37,6 +41,49 @@ def pick(self, mouseevent):
                     and self in mouseevent.inaxes.parasites):
                 a.pick(mouseevent)
 
+    # aux_transform support
+
+    def _set_lim_and_transforms(self):
+        if self.transAux is not None:
+            self.transAxes = self._parent_axes.transAxes
+            self.transData = self.transAux + self._parent_axes.transData
+            self._xaxis_transform = mtransforms.blended_transform_factory(
+                self.transData, self.transAxes)
+            self._yaxis_transform = mtransforms.blended_transform_factory(
+                self.transAxes, self.transData)
+        else:
+            super()._set_lim_and_transforms()
+
+    def set_viewlim_mode(self, mode):
+        _api.check_in_list([None, "equal", "transform"], mode=mode)
+        self._viewlim_mode = mode
+
+    def get_viewlim_mode(self):
+        return self._viewlim_mode
+
+    @cbook.deprecated("3.4", alternative="apply_aspect")
+    def update_viewlim(self):
+        return self._update_viewlim
+
+    def _update_viewlim(self):  # Inline after deprecation elapses.
+        viewlim = self._parent_axes.viewLim.frozen()
+        mode = self.get_viewlim_mode()
+        if mode is None:
+            pass
+        elif mode == "equal":
+            self.axes.viewLim.set(viewlim)
+        elif mode == "transform":
+            self.axes.viewLim.set(
+                viewlim.transformed(self.transAux.inverted()))
+        else:
+            _api.check_in_list([None, "equal", "transform"], mode=mode)
+
+    def apply_aspect(self, position=None):
+        self._update_viewlim()
+        super().apply_aspect()
+
+    # end of aux_transform support
+
 
 @functools.lru_cache(None)
 def parasite_axes_class_factory(axes_class=None):
@@ -55,11 +102,10 @@ def parasite_axes_class_factory(axes_class=None):
 ParasiteAxes = parasite_axes_class_factory(Axes)
 
 
+@cbook.deprecated("3.4", alternative="ParasiteAxesBase")
 class ParasiteAxesAuxTransBase:
     def __init__(self, parent_axes, aux_transform, viewlim_mode=None,
                  **kwargs):
-        self.transAux = aux_transform
-        self.set_viewlim_mode(viewlim_mode)
         super().__init__(parent_axes, **kwargs)
 
     def _set_lim_and_transforms(self):
@@ -99,6 +145,7 @@ def apply_aspect(self, position=None):
         super().apply_aspect()
 
 
+@cbook.deprecated("3.4", alternative="parasite_axes_class_factory")
 @functools.lru_cache(None)
 def parasite_axes_auxtrans_class_factory(axes_class=None):
     if axes_class is None:
@@ -117,16 +164,29 @@ def parasite_axes_auxtrans_class_factory(axes_class=None):
                 {'name': 'parasite_axes'})
 
 
-ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
+# Also deprecated.
+with cbook._suppress_matplotlib_deprecation_warning():
+    ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
 
 
 class HostAxesBase:
     def __init__(self, *args, **kwargs):
         self.parasites = []
         super().__init__(*args, **kwargs)
 
-    def get_aux_axes(self, tr, viewlim_mode="equal", axes_class=ParasiteAxes):
-        parasite_axes_class = parasite_axes_auxtrans_class_factory(axes_class)
+    def get_aux_axes(self, tr=None, viewlim_mode="equal", axes_class=Axes):
+        """
+        Add a parasite axes to this host.
+
+        Despite this method's name, this should actually be thought of as an
+        ``add_parasite_axes`` method.
+
+        *tr* may be `.Transform`, in which case the following relation will
+        hold: ``parasite.transData = tr + host.transData``.  Alternatively, it
+        may be None (the default), no special relationship will hold between
+        the parasite's and the host's ``transData``.
+        """
+        parasite_axes_class = parasite_axes_class_factory(axes_class)
         ax2 = parasite_axes_class(self, tr, viewlim_mode)
         # note that ax2.transData == tr + ax1.transData
         # Anything you draw in ax2 will match the ticks and grids of ax1.
@@ -236,13 +296,11 @@ def twin(self, aux_trans=None, axes_class=None):
         if axes_class is None:
             axes_class = self._get_base_axes()
 
-        parasite_axes_auxtrans_class = \
-            parasite_axes_auxtrans_class_factory(axes_class)
+        parasite_axes_class = parasite_axes_class_factory(axes_class)
 
         if aux_trans is None:
             aux_trans = mtransforms.IdentityTransform()
-        ax2 = parasite_axes_auxtrans_class(
-            self, aux_trans, viewlim_mode="transform")
+        ax2 = parasite_axes_class(self, aux_trans, viewlim_mode="transform")
         self.parasites.append(ax2)
         ax2._remove_method = self._remove_any_twin
 
diff --git a/lib/mpl_toolkits/axisartist/__init__.py b/lib/mpl_toolkits/axisartist/__init__.py
@@ -1,3 +1,4 @@
+from matplotlib import cbook
 from .axislines import (
     Axes, AxesZero, AxisArtistHelper, AxisArtistHelperRectlinear,
     GridHelperBase, GridHelperRectlinear, Subplot, SubplotZero)
@@ -10,6 +11,7 @@
 
 
 ParasiteAxes = parasite_axes_class_factory(Axes)
-ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
 HostAxes = host_axes_class_factory(Axes)
 SubplotHost = subplot_class_factory(HostAxes)
+with cbook._suppress_matplotlib_deprecation_warning():
+    ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
diff --git a/lib/mpl_toolkits/axisartist/parasite_axes.py b/lib/mpl_toolkits/axisartist/parasite_axes.py
@@ -1,10 +1,12 @@
+from matplotlib import cbook
 from mpl_toolkits.axes_grid1.parasite_axes import (
     host_axes_class_factory, parasite_axes_class_factory,
     parasite_axes_auxtrans_class_factory, subplot_class_factory)
 from .axislines import Axes
 
 
 ParasiteAxes = parasite_axes_class_factory(Axes)
-ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
 HostAxes = host_axes_class_factory(Axes)
 SubplotHost = subplot_class_factory(HostAxes)
+with cbook._suppress_matplotlib_deprecation_warning():
+    ParasiteAxesAuxTrans = parasite_axes_auxtrans_class_factory(ParasiteAxes)
diff --git a/lib/mpl_toolkits/tests/test_axisartist_axislines.py b/lib/mpl_toolkits/tests/test_axisartist_axislines.py
@@ -4,7 +4,7 @@
 from matplotlib.transforms import IdentityTransform
 
 from mpl_toolkits.axisartist.axislines import SubplotZero, Subplot
-from mpl_toolkits.axisartist import SubplotHost, ParasiteAxesAuxTrans
+from mpl_toolkits.axisartist import SubplotHost, ParasiteAxes
 
 from mpl_toolkits.axisartist import Axes
 
@@ -83,7 +83,7 @@ def test_ParasiteAxesAuxTrans():
         ax1 = SubplotHost(fig, 1, 3, i+1)
         fig.add_subplot(ax1)
 
-        ax2 = ParasiteAxesAuxTrans(ax1, IdentityTransform())
+        ax2 = ParasiteAxes(ax1, IdentityTransform())
         ax1.parasites.append(ax2)
         if name.startswith('pcolor'):
             getattr(ax2, name)(xx, yy, data[:-1, :-1])
diff --git a/lib/mpl_toolkits/tests/test_axisartist_grid_helper_curvelinear.py b/lib/mpl_toolkits/tests/test_axisartist_grid_helper_curvelinear.py
@@ -7,7 +7,7 @@
 from matplotlib.transforms import Affine2D, Transform
 from matplotlib.testing.decorators import image_comparison
 
-from mpl_toolkits.axes_grid1.parasite_axes import ParasiteAxesAuxTrans
+from mpl_toolkits.axes_grid1.parasite_axes import ParasiteAxes
 from mpl_toolkits.axisartist import SubplotHost
 from mpl_toolkits.axes_grid1.parasite_axes import host_subplot_class_factory
 from mpl_toolkits.axisartist import angle_helper
@@ -68,7 +68,7 @@ def inverted(self):
     ax1 = SubplotHost(fig, 1, 1, 1, grid_helper=grid_helper)
     fig.add_subplot(ax1)
 
-    ax2 = ParasiteAxesAuxTrans(ax1, tr, "equal")
+    ax2 = ParasiteAxes(ax1, tr, "equal")
     ax1.parasites.append(ax2)
     ax2.plot([3, 6], [5.0, 10.])
 
@@ -130,7 +130,7 @@ def test_polar_box():
     axis.get_helper()._extremes = -180, 90
 
     # A parasite axes with given transform
-    ax2 = ParasiteAxesAuxTrans(ax1, tr, "equal")
+    ax2 = ParasiteAxes(ax1, tr, "equal")
     assert ax2.transData == tr + ax1.transData
     # Anything you draw in ax2 will match the ticks and grids of ax1.
     ax1.parasites.append(ax2)
