projs.py docs cleanup, Proj returns just the class

Author: lukelbd

proplot/projs.py

@@ -5,18 +5,21 @@
 `~cartopy.crs.Projection` classes.
 """
 from .utils import _warn_proplot
-import numpy as np
+try:
+    from mpl_toolkits.basemap import Basemap
+except ImportError:
+    Basemap = object
 try:
     from cartopy.crs import (
-        _WarpedRectangularProjection,
-        LambertAzimuthalEqualArea, AzimuthalEquidistant, Gnomonic)
-    _cartopy_installed = True
+        CRS, _WarpedRectangularProjection,
+        LambertAzimuthalEqualArea, AzimuthalEquidistant, Gnomonic
+    )
 except ModuleNotFoundError:
+    CRS = object
     _WarpedRectangularProjection = object
     LambertAzimuthalEqualArea = object
     AzimuthalEquidistant = object
     Gnomonic = object
-    _cartopy_installed = False
 
 __all__ = [
     'Proj',
@@ -54,16 +57,18 @@ def Proj(name, basemap=False, **kwargs):
 
     Parameters
     ----------
-    name : str
-        The projection name. Like basemap, we use the
-        `PROJ <https://proj.org>`__ shorthands.
-
-        The following table lists the valid projection names, their full names
-        (with links to the relevant `PROJ documentation \
+    name : str, `~mpl_toolkits.basemap.Basemap`, or `cartopy.crs.Projection`
+        The projection name or projection class instance. If the latter, it
+        is simply returned. If the former, it must correspond to one of the
+        `PROJ <https://proj.org>`__ projection name shorthands, like in
+        basemap.
+
+        The following table lists the valid projection name shorthands, their
+        full names (with links to the relevant `PROJ documentation \
 <https://proj4.org/operations/projections/index.html>`__),
         and whether they are available in the cartopy and basemap packages.
 
-        ``(added)`` indicates a projection class that ProPlot has "added"
+        (added) indicates a projection class that ProPlot has "added"
         to cartopy using the cartopy API.
 
         =============  ============================================================================================  =========  =======
@@ -123,8 +128,8 @@ def Proj(name, basemap=False, **kwargs):
         =============  ============================================================================================  =========  =======
 
     basemap : bool, optional
-        Whether to use the basemap or cartopy package. Default is
-        ``False``.
+        Whether to use the basemap package as opposed to the cartopy package.
+        Default is ``False``.
     **kwargs
         Passed to the `~mpl_toolkits.basemap.Basemap` or
         cartopy `~cartopy.crs.Projection` class.
@@ -133,17 +138,23 @@ def Proj(name, basemap=False, **kwargs):
     -------
     proj : `~mpl_toolkits.basemap.Basemap` or `~cartopy.crs.Projection`
         The projection instance.
-    aspect : float
-        The map projection aspect ratio. This may change if user zooms
-        into a projection, but returning an initial guess helps avoid
-        unnecessarily calculations down the line.
 
     See also
     --------
     `~proplot.axes.GeoAxes`, `~proplot.axes.BasemapAxes`
     """  # noqa
+    # Class instances
+    if ((CRS is not object and isinstance(name, CRS))
+            or (Basemap is not object and isinstance(name, Basemap))):
+        proj = name
+    elif not isinstance(proj, str):
+        raise ValueError(
+            f'Unexpected Proj() argument {proj!r}. '
+            'Must be name, mpl_toolkits.basemap.Basemap instance, '
+            'or cartopy.crs.CRS instance.'
+        )
     # Basemap
-    if basemap:
+    elif basemap:
         import mpl_toolkits.basemap as mbasemap
         name = BASEMAP_TRANSLATE.get(name, name)
         kwproj = basemap_kwargs.get(name, {})
@@ -158,8 +169,6 @@ def Proj(name, basemap=False, **kwargs):
         reso = kwproj.pop('resolution', None) or kwproj.pop(
             'reso', None) or 'c'
         proj = mbasemap.Basemap(projection=name, resolution=reso, **kwproj)
-        aspect = (proj.urcrnrx - proj.llcrnrx) / \
-                 (proj.urcrnry - proj.llcrnry)
     # Cartopy
     else:
         import cartopy.crs as _  # noqa
@@ -176,18 +185,17 @@ def Proj(name, basemap=False, **kwargs):
         if crs is None:
             raise ValueError(
                 f'Unknown projection {name!r}. Options are: '
-                + ', '.join(map(repr, cartopy_names.keys()))
+                + ', '.join(map(repr, cartopy_names.keys())) + '.'
             )
         proj = crs(**kwargs)
-        aspect = (np.diff(proj.x_limits) / np.diff(proj.y_limits))[0]
-    return proj, aspect
+    return proj
 
 
-class Hammer(_WarpedRectangularProjection):
-    """The `Hammer <https://en.wikipedia.org/wiki/Hammer_projection>`__
+class Aitoff(_WarpedRectangularProjection):
+    """The `Aitoff <https://en.wikipedia.org/wiki/Aitoff_projection>`__
     projection."""
     #: Registered projection name.
-    name = 'hammer'
+    name = 'aitoff'
 
     def __init__(self, central_longitude=0, globe=None,
                  false_easting=None, false_northing=None):
@@ -204,11 +212,13 @@ def __init__(self, central_longitude=0, globe=None,
                 'elliptical globes.'
             )
 
-        proj4_params = {'proj': 'hammer', 'lon_0': central_longitude}
-        super().__init__(proj4_params, central_longitude,
-                         false_easting=false_easting,
-                         false_northing=false_northing,
-                         globe=globe)
+        proj4_params = {'proj': 'aitoff', 'lon_0': central_longitude}
+        super().__init__(
+            proj4_params, central_longitude,
+            false_easting=false_easting,
+            false_northing=false_northing,
+            globe=globe
+        )
 
     @property
     def threshold(self):  # how finely to interpolate line data, etc.
@@ -218,11 +228,11 @@ def threshold(self):  # how finely to interpolate line data, etc.
     threshold.__doc__ = _reso_doc
 
 
-class Aitoff(_WarpedRectangularProjection):
-    """The `Aitoff <https://en.wikipedia.org/wiki/Aitoff_projection>`__
+class Hammer(_WarpedRectangularProjection):
+    """The `Hammer <https://en.wikipedia.org/wiki/Hammer_projection>`__
     projection."""
     #: Registered projection name.
-    name = 'aitoff'
+    name = 'hammer'
 
     def __init__(self, central_longitude=0, globe=None,
                  false_easting=None, false_northing=None):
@@ -239,11 +249,13 @@ def __init__(self, central_longitude=0, globe=None,
                 'elliptical globes.'
             )
 
-        proj4_params = {'proj': 'aitoff', 'lon_0': central_longitude}
-        super().__init__(proj4_params, central_longitude,
-                         false_easting=false_easting,
-                         false_northing=false_northing,
-                         globe=globe)
+        proj4_params = {'proj': 'hammer', 'lon_0': central_longitude}
+        super().__init__(
+            proj4_params, central_longitude,
+            false_easting=false_easting,
+            false_northing=false_northing,
+            globe=globe
+        )
 
     @property
     def threshold(self):  # how finely to interpolate line data, etc.
@@ -326,49 +338,60 @@ def threshold(self):
 class NorthPolarAzimuthalEquidistant(AzimuthalEquidistant):
     """Analogous to `~cartopy.crs.NorthPolarStereo`."""
     def __init__(self, central_longitude=0.0, globe=None):
-        super().__init__(central_latitude=90,
-                         central_longitude=central_longitude, globe=globe)
+        super().__init__(
+            central_latitude=90,
+            central_longitude=central_longitude, globe=globe
+        )
     __init__.__doc__ = _proj_doc
 
 
 class SouthPolarAzimuthalEquidistant(AzimuthalEquidistant):
     """Analogous to `~cartopy.crs.SouthPolarStereo`."""
     def __init__(self, central_longitude=0.0, globe=None):
-        super().__init__(central_latitude=-90,
-                         central_longitude=central_longitude, globe=globe)
+        super().__init__(
+            central_latitude=-90,
+            central_longitude=central_longitude, globe=globe
+        )
     __init__.__doc__ = _proj_doc
 
 
 class NorthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea):
     """Analogous to `~cartopy.crs.NorthPolarStereo`."""
     def __init__(self, central_longitude=0.0, globe=None):
-        super().__init__(central_latitude=90,
-                         central_longitude=central_longitude, globe=globe)
-
+        super().__init__(
+            central_latitude=90,
+            central_longitude=central_longitude, globe=globe
+        )
     __init__.__doc__ = _proj_doc
 
 
 class SouthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea):
     """Analogous to `~cartopy.crs.SouthPolarStereo`."""
     def __init__(self, central_longitude=0.0, globe=None):
-        super().__init__(central_latitude=-90,
-                         central_longitude=central_longitude, globe=globe)
+        super().__init__(
+            central_latitude=-90,
+            central_longitude=central_longitude, globe=globe
+        )
     __init__.__doc__ = _proj_doc
 
 
 class NorthPolarGnomonic(Gnomonic):
     """Analogous to `~cartopy.crs.SouthPolarStereo`."""
     def __init__(self, central_longitude=0.0, globe=None):
-        super().__init__(central_latitude=90,
-                         central_longitude=central_longitude, globe=globe)
+        super().__init__(
+            central_latitude=90,
+            central_longitude=central_longitude, globe=globe
+        )
     __init__.__doc__ = _proj_doc
 
 
 class SouthPolarGnomonic(Gnomonic):
     """Analogous to `~cartopy.crs.SouthPolarStereo`."""
     def __init__(self, central_longitude=0.0, globe=None):
-        super().__init__(central_latitude=-90,
-                         central_longitude=central_longitude, globe=globe)
+        super().__init__(
+            central_latitude=-90,
+            central_longitude=central_longitude, globe=globe
+        )
     __init__.__doc__ = _proj_doc
 
 
@@ -420,7 +443,7 @@ def __init__(self, central_longitude=0.0, globe=None):
 
 #: Mapping of "projection names" to cartopy `~cartopy.crs.Projection` classes.
 cartopy_names = {}
-if _cartopy_installed:
+if CRS is not object:
     # Custom ones, these are always present
     import cartopy.crs as ccrs  # verify package is available
     cartopy_names = {  # interpret string, create cartopy projection