Hide 'registered' axes names from public API

lukelbd · lukelbd · commit ece1102bba1a · 2021-09-04T19:09:29.000-06:00
diff --git a/proplot/axes/__init__.py b/proplot/axes/__init__.py
@@ -4,6 +4,7 @@
 """
 import matplotlib.projections as mproj
 
+from ..internals import context
 from .base import Axes  # noqa: F401
 from .cartesian import CartesianAxes
 from .geo import GeoAxes  # noqa: F401
@@ -13,13 +14,6 @@
 from .shared import _SharedAxes  # noqa: F401
 from .three import ThreeAxes  # noqa: F401
 
-# Register projections
-mproj.register_projection(CartesianAxes)
-mproj.register_projection(PolarAxes)
-mproj.register_projection(_BasemapAxes)
-mproj.register_projection(_CartopyAxes)
-mproj.register_projection(ThreeAxes)
-
 # Prevent importing module names and set order of appearance for objects
 __all__ = [
     'Axes',
@@ -29,3 +23,11 @@
     'GeoAxes',
     'ThreeAxes',
 ]
+
+# Register projections with package prefix to avoid conflicts
+# NOTE: We integrate with cartopy and basemap rather than using matplotlib's
+# native projection system. Therefore axes names are not part of public API.
+for _cls in (CartesianAxes, PolarAxes, _BasemapAxes, _CartopyAxes, ThreeAxes):
+    for _name in (_cls._name, *_cls._name_aliases):
+        with context._state_context(_cls, name='proplot_' + _name):
+            mproj.register_projection(_cls)
diff --git a/proplot/axes/base.py b/proplot/axes/base.py
@@ -561,6 +561,9 @@ class Axes(maxes.Axes):
     The lowest-level `~matplotlib.axes.Axes` subclass used by proplot.
     Implements basic universal features.
     """
+    _name = None  # derived must override
+    _name_aliases = ()
+
     def __repr__(self):  # override matplotlib
         # Show the position in the geometry excluding panels. Panels are
         # indicated by showing their parent geometry plus a 'side' argument.
@@ -577,11 +580,9 @@ def __repr__(self):  # override matplotlib
         if self._panel_side:
             name = name.replace('Subplot', 'Panel')  # e.g. CartesianAxesPanel
             params['side'] = self._panel_side
-        for package in ('cartopy', 'basemap'):
-            head = '_' + package.title()
-            if head in name:  # e.g. _CartopyAxesSubplot to GeoAxesSubplot
-                name = name.replace(head, 'Geo')
-                params['backend'] = package
+        if self._name in ('cartopy', 'basemap'):
+            name = name.replace('_' + self._name.title(), 'Geo')
+            params['backend'] = self._name
         params = ', '.join(f'{key}={value!r}' for key, value in params.items())
         return f'{name}({params})'
 
@@ -1474,23 +1475,25 @@ def inset_axes(
         label = kwargs.pop('label', 'inset_axes')
 
         # Get projection, inherit from current axes by default
+        # NOTE: The _parse_proj method also accepts axes classes.
         proj = _not_none(proj=proj, projection=projection)
         if proj is None:
-            proj = self.name  # will have 'proplot_' prefix
-            if proj in ('proplot_cartopy', 'proplot_basemap'):
+            if self._name in ('cartopy', 'basemap'):
                 proj = copy.copy(self.projection)
+            else:
+                proj = self._name
         kwargs = self.figure._parse_proj(proj, **kwargs)
         cls = mprojections.get_projection_class(kwargs.pop('projection'))
 
         # Create axes and apply locator. The locator lets the axes adjust
-        # automatically if we used data coords. Gets called by ax.apply_aspect()
+        # automatically if we used data coords. Called by ax.apply_aspect()
         ax = cls(self.figure, bb.bounds, zorder=zorder, label=label, **kwargs)
         ax.set_axes_locator(locator)
         ax._inset_parent = self
         self.add_child_axes(ax)
 
-        # Add zoom indicator (NOTE: requires version >=3.0)
-        zoom = _not_none(zoom, self.name == ax.name)  # only zoom when same projection
+        # Add zoom indicator (NOTE: requires matplotlib >= 3.0)
+        zoom = _not_none(zoom, self._name == 'cartesian' and ax._name == 'cartesian')
         ax._inset_zoom = zoom
         if zoom:
             zoom_kw = zoom_kw or {}
@@ -2920,7 +2923,7 @@ def text(
         # Translate positional args
         # Audo-redirect to text2D for 3D axes if not enough arguments passed
         # NOTE: The transform must be passed positionally for 3D axes with 2D coords
-        keys = tuple('xyz' if self.name == 'proplot_three' else 'xy')
+        keys = tuple('xyz' if self._name == 'three' else 'xy')
         keys += (('s', 'text'),)  # interpret both 's' and 'text'
         args, kwargs = _keyword_to_positional(keys, *args, **kwargs)
         if len(args) == len(keys) + 1:
@@ -2929,13 +2932,13 @@ def text(
         elif len(args) == len(keys):
             add_text = super().text
             transform = kwargs.pop('transform', None)
-        elif len(args) == len(keys) - 1 and self.name == 'proplot_three':
+        elif len(args) == len(keys) - 1 and self._name == 'three':
             add_text = self.text2D
             transform = kwargs.pop('transform', None)
         else:
             raise TypeError(
-                f'Expected {len(keys) - 1} to {len(keys)} positional '
-                f'arguments but got {len(args)}.'
+                f'Expected {len(keys) - 1} to {len(keys)} '
+                f'positional arguments but got {len(args)}.'
             )
 
         # Translate keyword args
diff --git a/proplot/axes/cartesian.py b/proplot/axes/cartesian.py
@@ -109,8 +109,8 @@ class CartesianAxes(shared._SharedAxes, plot.PlotAxes):
     Adds the `~CartesianAxes.format` method and overrides several existing
     methods.
     """
-    # The registered projection name.
-    name = 'proplot_cartesian'
+    _name = 'cartesian'
+    _name_aliases = ('cart', 'rect', 'rectilinar')  # include matplotlib name
 
     def __init__(self, *args, **kwargs):
         """
diff --git a/proplot/axes/geo.py b/proplot/axes/geo.py
@@ -533,7 +533,7 @@ def format(
         # drawing gridlines before basemap map boundary will call set_axes_limits()
         # which initializes a boundary hidden from external access. So we must call
         # it here. Must do this between matplotlib.Axes.__init__() and Axes.format().
-        if self.name == 'proplot_basemap' and self._map_boundary is None:
+        if self._name == 'basemap' and self._map_boundary is None:
             if self.projection.projection in self._proj_non_rectangular:
                 patch = self.projection.drawmapboundary(ax=self)
                 self._map_boundary = patch
@@ -653,8 +653,8 @@ class _CartopyAxes(GeoAxes, _GeoAxes):
     """
     Axes subclass for plotting cartopy projections.
     """
-    # The registered projection name.
-    name = 'proplot_cartopy'
+    _name = 'cartopy'
+    _name_aliases = ('geo', 'geographic')  # default 'geographic' axes
     _proj_class = Projection
     _proj_north = (
         pcrs.NorthPolarStereo,
@@ -684,7 +684,9 @@ def __init__(
         # NOTE: Initial extent is configured in _update_extent
         import cartopy  # noqa: F401 verify package is available
         if not isinstance(map_projection, ccrs.Projection):
-            raise ValueError('CartopyAxes requires map_projection=cartopy.crs.Projection.')  # noqa: E501
+            raise ValueError(
+                'Cartopy axes require map_projection=cartopy.crs.Projection.'
+            )
         latmax = 90
         boundinglat = None
         polar = isinstance(map_projection, self._proj_polar)
@@ -1121,8 +1123,7 @@ class _BasemapAxes(GeoAxes):
     """
     Axes subclass for plotting basemap projections.
     """
-    # The registered projection name.
-    name = 'proplot_basemap'
+    _name = 'basemap'
     _proj_class = Basemap
     _proj_north = ('npaeqd', 'nplaea', 'npstere')
     _proj_south = ('spaeqd', 'splaea', 'spstere')
@@ -1149,7 +1150,9 @@ def __init__(self, *args, map_projection=None, **kwargs):
         # and python immmediately crashes. Do not try again.
         import mpl_toolkits.basemap  # noqa: F401 verify package is available
         if not isinstance(map_projection, mbasemap.Basemap):
-            raise ValueError('BasemapAxes requires map_projection=mpl_toolkits.basemap.Basemap.')  # noqa: E501
+            raise ValueError(
+                'Basemap axes require map_projection=mpl_toolkits.basemap.Basemap.'
+            )
         map_projection = self._map_projection = copy.copy(map_projection)
         lon0 = self._get_lon0()
         if map_projection.projection in self._proj_polar:
diff --git a/proplot/axes/plot.py b/proplot/axes/plot.py
@@ -1200,7 +1200,7 @@ def _plot_native(self, name, *args, **kwargs):
         # Now prevent internal calls from running through overrides using preprocessor
         kwargs.pop('distribution', None)  # remove stat distributions
         with context._state_context(self, _internal_call=True):
-            if getattr(self, 'name', None) == 'proplot_basemap':
+            if self._name == 'basemap':
                 obj = getattr(self.projection, name)(*args, ax=self, **kwargs)
             else:
                 obj = getattr(super(), name)(*args, **kwargs)
@@ -1605,7 +1605,7 @@ def _inbounds_vlim(self, x, y, z, *, to_centers=False):
         # keep this in a try-except clause for now. However *internally* we should
         # not reach this block unless everything is an array so raise that error.
         xmask = ymask = None
-        if self.name != 'proplot_cartesian':
+        if self._name != 'cartesian':
             return z  # TODO: support geographic projections when input is PlateCarree()
         if not all(getattr(a, 'ndim', None) in (1, 2) for a in (x, y, z)):
             raise ValueError('Invalid input coordinates. Must be 1D or 2D arrays.')
@@ -1629,7 +1629,7 @@ def _inbounds_vlim(self, x, y, z, *, to_centers=False):
             return z
         except Exception as err:
             warnings._warn_proplot(
-                'Failed to restrict automatic colormap normalization algorithm '
+                'Failed to restrict automatic colormap normalization '
                 f'to in-bounds data only. Error message: {err}'
             )
             return z
@@ -1643,11 +1643,13 @@ def _inbounds_xylim(self, extents, x, y, **kwargs):
         # WARNING: This feature is still experimental. But seems obvious. Matplotlib
         # updates data limits in ad hoc fashion differently for each plotting command
         # but since proplot standardizes inputs we can easily use them for dataLim.
-        kwargs, vert = _get_vert(**kwargs)
-        if extents is None or self.name != 'proplot_cartesian':
+        if extents is None:
+            return
+        if self._name != 'cartesian':
             return
         if not x.size or not y.size:
             return
+        kwargs, vert = _get_vert(**kwargs)
         if not vert:
             x, y = y, x
         trans = self.dataLim
@@ -1767,8 +1769,8 @@ def _parse_format1d(
                 _guide_kw_to_arg('colorbar', kwargs, label=title)
 
         # Apply the basic x and y settings
-        autox = autox and self.name == 'proplot_cartesian'
-        autoy = autoy and self.name == 'proplot_cartesian'
+        autox = autox and self._name == 'cartesian'
+        autoy = autoy and self._name == 'cartesian'
         sx, sy = 'xy' if vert else 'yx'
         kw_format = {}
         if autox and autoformat:  # 'x' axis
@@ -1828,9 +1830,9 @@ def _parse_plot1d(self, x, *ys, **kwargs):
         x, *ys, kwargs = self._parse_format1d(x, *ys, zerox=zerox, **kwargs)
 
         # Geographic corrections
-        if self.name == 'proplot_cartopy' and isinstance(kwargs.get('transform'), PlateCarree):  # noqa: E501
+        if self._name == 'cartopy' and isinstance(kwargs.get('transform'), PlateCarree):  # noqa: E501
             x, *ys = data._geo_cartopy_1d(x, *ys)
-        elif self.name == 'proplot_basemap' and kwargs.get('latlon', None):
+        elif self._name == 'basemap' and kwargs.get('latlon', None):
             xmin, xmax = self._lonaxis.get_view_interval()
             x, *ys = data._geo_basemap_1d(x, *ys, xmin=xmin, xmax=xmax)
 
@@ -1853,7 +1855,7 @@ def _parse_format2d(self, x, y, *zs, autoformat=None, autoguide=True, **kwargs):
                 y = data._meta_labels(z, axis=0)
 
         # Apply labels and XY axis settings
-        if self.name == 'proplot_cartesian':
+        if self._name == 'cartesian':
             # Apply labels
             # NOTE: Do not overwrite existing labels!
             kw_format = {}
@@ -1927,9 +1929,9 @@ def _parse_plot2d(
         # Geographic corrections
         if allow1d:
             pass
-        elif self.name == 'proplot_cartopy' and isinstance(kwargs.get('transform'), PlateCarree):  # noqa: E501
+        elif self._name == 'cartopy' and isinstance(kwargs.get('transform'), PlateCarree):  # noqa: E501
             x, y, *zs = data._geo_cartopy_2d(x, y, *zs, globe=globe)
-        elif self.name == 'proplot_basemap' and kwargs.get('latlon', None):
+        elif self._name == 'basemap' and kwargs.get('latlon', None):
             xmin, xmax = self._lonaxis.get_view_interval()
             x, y, *zs = data._geo_basemap_2d(x, y, *zs, xmin=xmin, xmax=xmax, globe=globe)  # noqa: E501
             x, y = np.meshgrid(x, y)  # WARNING: required always
@@ -3707,12 +3709,7 @@ def heatmap(self, *args, aspect=None, **kwargs):
         """
         obj = self.pcolormesh(*args, default_discrete=False, **kwargs)
         aspect = _not_none(aspect, rc['image.aspect'])
-        if self.name != 'proplot_cartesian':
-            warnings._warn_proplot(
-                'The heatmap() command is meant for CartesianAxes. '
-                'Please use pcolor() or pcolormesh() instead.'
-            )
-        else:
+        if self._name == 'cartesian':
             coords = getattr(obj, '_coordinates', None)
             xlocator = ylocator = None
             if coords is not None:
@@ -3729,6 +3726,11 @@ def heatmap(self, *args, aspect=None, **kwargs):
             if self.yaxis.isDefault_minloc:
                 kw['ytickminor'] = False
             self.format(**kw)
+        else:
+            warnings._warn_proplot(
+                'The heatmap() command is meant for CartesianAxes. '
+                'Please use pcolor() or pcolormesh() instead.'
+            )
         return obj
 
     @data._preprocess('x', 'y', 'u', 'v', ('c', 'color', 'colors'))
diff --git a/proplot/axes/polar.py b/proplot/axes/polar.py
@@ -20,8 +20,7 @@ class PolarAxes(shared._SharedAxes, plot.PlotAxes, mproj.PolarAxes):
     Axes subclass for plotting in polar coordinates. Adds the `~PolarAxes.format`
     method and overrides several existing methods.
     """
-    # The registered projection name.
-    name = 'proplot_polar'
+    _name = 'polar'
 
     def __init__(self, *args, **kwargs):
         """
diff --git a/proplot/axes/three.py b/proplot/axes/three.py
@@ -14,8 +14,8 @@ class ThreeAxes(shared._SharedAxes, plot.PlotAxes, Axes3D):
     """
     Simple mix-in of `proplot.axes.PlotAxes` with `~mpl_toolkits.mplot3d.axes3d.Axes3D`.
     """
-    # The registered projection name.
-    name = 'proplot_three'
+    _name = 'three'
+    _name_aliases = ('3d',)
 
     def __init__(self, *args, **kwargs):
         import mpl_toolkits.mplot3d  # noqa: F401 verify package is available
diff --git a/proplot/constructor.py b/proplot/constructor.py
@@ -18,7 +18,7 @@
 import cycler
 import matplotlib.colors as mcolors
 import matplotlib.dates as mdates
-import matplotlib.projections.polar as mpolar
+import matplotlib.projections as mproj
 import matplotlib.scale as mscale
 import matplotlib.ticker as mticker
 import numpy as np
@@ -108,8 +108,8 @@
     LOCATORS['dms'] = partial(pticker.DegreeLocator, dms=True)
     LOCATORS['dmslon'] = partial(pticker.LongitudeLocator, dms=True)
     LOCATORS['dmslat'] = partial(pticker.LatitudeLocator, dms=True)
-if hasattr(mpolar, 'ThetaLocator'):
-    LOCATORS['theta'] = mpolar.ThetaLocator
+if hasattr(mproj.polar, 'ThetaLocator'):
+    LOCATORS['theta'] = mproj.polar.ThetaLocator
 
 # Mapping of strings to `~matplotlib.ticker.Formatter` classes. See
 # `Formatter` for a table.
@@ -151,8 +151,8 @@
     FORMATTERS['dms'] = partial(pticker.DegreeFormatter, dms=True)
     FORMATTERS['dmslon'] = partial(pticker.LongitudeFormatter, dms=True)
     FORMATTERS['dmslat'] = partial(pticker.LatitudeFormatter, dms=True)
-if hasattr(mpolar, 'ThetaFormatter'):
-    FORMATTERS['theta'] = mpolar.ThetaFormatter
+if hasattr(mproj.polar, 'ThetaFormatter'):
+    FORMATTERS['theta'] = mproj.polar.ThetaFormatter
 if hasattr(mdates, 'ConciseDateFormatter'):
     FORMATTERS['concise'] = mdates.ConciseDateFormatter
 
@@ -1433,7 +1433,7 @@ def Proj(name, basemap=None, **kwargs):
     use_basemap = _not_none(basemap, rc['basemap'])
     is_crs = CRS is not object and isinstance(name, CRS)
     is_basemap = Basemap is not object and isinstance(name, Basemap)
-    include_axes_projections = kwargs.pop('include_axes_projections', None)
+    include_axes = kwargs.pop('include_axes', None)
     if is_crs or is_basemap:
         proj = name
         proj._proj_package = 'cartopy' if is_crs else 'basemap'
@@ -1520,9 +1520,11 @@ def Proj(name, basemap=None, **kwargs):
     # Unknown
     else:
         options = tuple(PROJS)
-        if include_axes_projections:
-            from .figure import AXES_PROJS  # avoid circular import
-            options += tuple(AXES_PROJS)
+        if include_axes:
+            options += tuple(
+                proj.split('proplot_', 1)[1] for proj in mproj.get_projection_names()
+                if 'proplot_' in proj
+            )
         raise ValueError(
             f'Unknown projection {name!r}. Options are: '
             + ', '.join(map(repr, options))
diff --git a/proplot/figure.py b/proplot/figure.py
diff --git a/proplot/internals/data.py b/proplot/internals/data.py
