Add 'basemap' and 'cartopy.circular' rc settings

Author: lukelbd

docs/projections.py

@@ -150,17 +150,16 @@
 #
 # .. note::
 #
-#    * ProPlot ensures that polar cartopy projections like
-#      `~cartopy.crs.NorthPolarStereo` have circular boundaries (see `this example\
+#    * By default, ProPlot gives circular boundaries to polar cartopy projections like
+#      `~cartopy.crs.NorthPolarStereo` (see `this example\
 #      <https://scitools.org.uk/cartopy/docs/latest/gallery/lines_and_polygons/always_circular_stereo.html>`__
-#      from the cartopy website).
-#    * By default, non-polar cartopy projections are forced to have global extent
-#      with `~cartopy.mpl.geoaxes.GeoAxes.set_global` and polar cartopy projections
-#      are bounded at the equator. This stands in contrast to the default cartopy
-#      behavior, where map boundaries are determined automatically based on the
-#      coordinates of the plotted content. To revert to cartopy's default behavior,
-#      set :rcraw:`cartopy.autoextent` to ``True`` or pass ``autoextent=True``
-#      to `~proplot.axes.CartopyAxes`.
+#      from the cartopy website). This is consistent with basemap's default behavior.
+#      To disable this feature, set :rcraw:`cartopy.circular` to ``False``.
+#    * By default, ProPlot uses `~cartopy.mpl.geoaxes.GeoAxes.set_global` to give
+#      non-polar cartopy projections global extent and bounds polar cartopy projections
+#      at the equator. This is a deviation from cartopy, which determines map boundaries
+#      automatically based on the coordinates of the plotted content. To revert to
+#      cartopy's default behavior, set :rcraw:`cartopy.autoextent` to ``True``.
 #    * To make things more consistent between cartopy and basemap, the
 #      `~proplot.constructor.Proj` constructor function lets you supply native
 #      `PROJ <https://proj.org>`__ keyword names for the cartopy

proplot/axes/geo.py

@@ -48,7 +48,7 @@
 __all__ = ['GeoAxes', 'BasemapAxes', 'CartopyAxes']
 
 
-def _circle_boundary(N=100):
+def _circular_boundary(N=100):
     """
     Return a circle `~matplotlib.path.Path` used as the outline for polar
     stereographic, azimuthal equidistant, Lambert conformal, and gnomonic
@@ -718,13 +718,18 @@ class CartopyAxes(GeoAxes, GeoAxesBase):
     )
     _proj_polar = _proj_north + _proj_south
 
-    def __init__(self, *args, autoextent=None, map_projection=None, **kwargs):
+    def __init__(
+        self, *args, autoextent=None, circular=None, map_projection=None, **kwargs
+    ):
         """
         Parameters
         ----------
         autoextent : bool, optional
             Whether to automatically adjust map bounds based on plotted content
             or enforce *global* map extent. Default is :rc:`cartopy.autoextent`.
+        circular : bool, optional
+            Whether to bound polar projections with circles rather than squares.
+            Default is :rc:`cartopy.circular`.
         map_projection : `~cartopy.crs.Projection`
             The `~cartopy.crs.Projection` instance.
 
@@ -770,9 +775,10 @@ def __init__(self, *args, autoextent=None, map_projection=None, **kwargs):
         # can do their things. This also updates _LatAxis and _LonAxis.
         # NOTE: Use set_global rather than _update_extent() manually in case projection
         # extent cannot be global.
-        if polar and hasattr(self, 'set_boundary'):
-            self.set_boundary(_circle_boundary(), transform=self.transAxes)
         auto = _not_none(autoextent, rc['cartopy.autoextent'])
+        circular = _not_none(circular, rc['cartopy.circular'])
+        if polar and circular and hasattr(self, 'set_boundary'):
+            self.set_boundary(_circular_boundary(), transform=self.transAxes)
         if auto:
             self._set_view_intervals(self._get_global_extent())
         elif polar:

proplot/constructor.py

@@ -1261,7 +1261,7 @@ def Proj(name, basemap=None, **kwargs):
 
     basemap : bool, optional
         Whether to use the basemap package as opposed to the cartopy package.
-        Default is ``False``.
+        Default is :rc:`basemap`.
     lonlim : 2-tuple of float, optional
         Alternative way to specify `llcrnrlon` and `urcrnrlon` for basemap
         projections.
@@ -1351,7 +1351,7 @@ def Proj(name, basemap=None, **kwargs):
         )
 
     # Basemap
-    elif basemap:
+    elif basemap or basemap is None and rc['basemap']:
         # NOTE: Known issue that basemap sometimes produces backwards maps:
         # https://stackoverflow.com/q/56299971/4970632
         # NOTE: We set rsphere to fix non-conda installed basemap issue:

proplot/internals/rcsetup.py

@@ -363,6 +363,12 @@
         'Alias for :rcraw:`axes.formatter.offset_threshold`.'
     ),
 
+    # Special basemap settings
+    'basemap': (
+        False,
+        'Boolean, toggles whether basemap is the default backend.'
+    ),
+
     # Country borders
     'borders': (
         False,
@@ -398,9 +404,13 @@
     # Special cartopy settings
     'cartopy.autoextent': (
         False,
-        'If ``False`` (the default), the projection extent is no longer automatically '
-        'adjusted based on plotted content. See the :ref:`user guide <ug_geo>` for '
-        'details.'
+        'If ``False`` (the default), cartopy projection extents are global by '
+        'default and no longer automatically adjusted based on plotted content.'
+    ),
+    'cartopy.circular': (
+        True,
+        "If ``True`` (the default), polar cartopy projections like ``'npstere'`` and "
+        "``'spstere'`` are bounded with circles rather than squares."
     ),
 
     # Coastlines

proplot/ui.py

@@ -309,7 +309,7 @@ def subplots(
     basemap : bool, list of bool, or dict of bool, optional
         Passed to `~proplot.constructor.Proj`, determines whether projection
         string names like ``'pcarree'`` are used to create `~proplot.axes.BasemapAxes`
-        or `~proplot.axes.CartopyAxes`. Default is ``False``. If boolean, applies
+        or `~proplot.axes.CartopyAxes`. Default is :rc:`basemap`. If boolean, applies
         to all subplots. If list or dict, applies to specific subplots, as with `proj`.
     journal : str, optional
         String name corresponding to an academic journal standard that is used
@@ -562,8 +562,7 @@ def subplots(
         subplotspec = gridspec[y0:y1 + 1, x0:x1 + 1]
         with fig._context_authorize_add_subplot():
             axs[idx] = fig.add_subplot(
-                subplotspec, number=num, main=True,
-                **axes_kw[num]
+                subplotspec, number=num, main=True, **axes_kw[num]
             )
 
     # Shared axes setup