From 98e92bea66b917dd8e76d4787a4817cf708faa6d Mon Sep 17 00:00:00 2001
From: Greg Lucas <greg.m.lucas@gmail.com>
Date: Tue, 4 Jan 2022 17:36:35 -0700
Subject: [PATCH] MNT: Change map_projection to projection for Axes creation

The GeoAxes class now requires the projection keyword argument rather
than map_projection to be more consistent with how a normal Axes/Subplot
is created.
---
 examples/miscellanea/axes_grid_basic.py |  2 +-
 lib/cartopy/crs.py                      |  2 +-
 lib/cartopy/mpl/geoaxes.py              | 26 ++++++++++++++-----------
 lib/cartopy/tests/mpl/test_axes.py      |  2 +-
 4 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/examples/miscellanea/axes_grid_basic.py b/examples/miscellanea/axes_grid_basic.py
index a5b1d5012a..926a962b06 100644
--- a/examples/miscellanea/axes_grid_basic.py
+++ b/examples/miscellanea/axes_grid_basic.py
@@ -41,7 +41,7 @@ def sample_data_3d(shape):
 def main():
     projection = ccrs.PlateCarree()
     axes_class = (GeoAxes,
-                  dict(map_projection=projection))
+                  dict(projection=projection))
 
     lons, lats, times, data = sample_data_3d((6, 73, 145))
 
diff --git a/lib/cartopy/crs.py b/lib/cartopy/crs.py
index f1ae00cbeb..42a874b0fe 100644
--- a/lib/cartopy/crs.py
+++ b/lib/cartopy/crs.py
@@ -771,7 +771,7 @@ def _repr_html_(self):
 
     def _as_mpl_axes(self):
         import cartopy.mpl.geoaxes as geoaxes
-        return geoaxes.GeoAxes, {'map_projection': self}
+        return geoaxes.GeoAxes, {'projection': self}
 
     def project_geometry(self, geometry, src_crs=None):
         """
diff --git a/lib/cartopy/mpl/geoaxes.py b/lib/cartopy/mpl/geoaxes.py
index f0b2cfd660..144ea5bf96 100644
--- a/lib/cartopy/mpl/geoaxes.py
+++ b/lib/cartopy/mpl/geoaxes.py
@@ -392,23 +392,27 @@ class GeoAxes(matplotlib.axes.Axes):
     """
     name = 'cartopy.geoaxes'
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, projection=None, **kwargs):
         """
         Create a GeoAxes object using standard matplotlib
         :class:`~matplotlib.axes.Axes` args and kwargs.
 
         Parameters
         ----------
-        map_projection: optional
-            The target :class:`~cartopy.crs.Projection` of this Axes object.
-
-
-        All other args and keywords are passed through to
-        :class:`matplotlib.axes.Axes`.
-
-        """
-        self.projection = kwargs.pop('map_projection')
-        """The :class:`cartopy.crs.Projection` of this GeoAxes."""
+        projection : cartopy.crs.Projection, required
+            The target projection of this Axes.
+        """
+        if "map_projection" in kwargs:
+            warnings.warn("The `map_projection` keyword argument is "
+                          "deprecated, use `projection` to instantiate a "
+                          "GeoAxes instead.")
+            projection = kwargs.pop("map_projection")
+
+        # The :class:`cartopy.crs.Projection` of this GeoAxes.
+        if not isinstance(projection, ccrs.Projection):
+            raise ValueError("A GeoAxes can only be created with a "
+                             "projection of type cartopy.crs.Projection")
+        self.projection = projection
 
         super().__init__(*args, **kwargs)
         self._gridliners = []
diff --git a/lib/cartopy/tests/mpl/test_axes.py b/lib/cartopy/tests/mpl/test_axes.py
index a431ce9893..5d487d71aa 100644
--- a/lib/cartopy/tests/mpl/test_axes.py
+++ b/lib/cartopy/tests/mpl/test_axes.py
@@ -98,7 +98,7 @@ class Test_Axes_add_geometries:
     @mock.patch('cartopy.feature.ShapelyFeature')
     def test_styler_kwarg(self, ShapelyFeature, add_feature_method):
         ax = GeoAxes(plt.figure(), [0, 0, 1, 1],
-                     map_projection=ccrs.Robinson())
+                     projection=ccrs.Robinson())
         ax.add_geometries(mock.sentinel.geometries, mock.sentinel.crs,
                           styler=mock.sentinel.styler, wibble='wobble')