Permit passing mixed projection keywords to fig/grid.format

Author: lukelbd

WHATSNEW.rst

@@ -36,6 +36,8 @@ Features
 
 * Permit passing arbitrary ``format`` arguments to multi-axes creation commands
   like `~proplot.ui.subplots` (:commit:`0b801442`).
+* Permit passing ``format`` arguments for different projections to the same
+  `proplot.gridspec.SubplotGrid.format`
 * Add `[xy]labelsize`, `[xy]labelweight`, `[xy]ticklabelsize`, `[xy]ticklabelweight`
   keywords to `proplot.axes.CartesianAxes.format` (:commit:`975025df`).
 * Add `labelsize` and `labelweight` keywords to `proplot.axes.PolarAxes.format`,

proplot/axes/base.py

@@ -391,23 +391,26 @@
     with the "¤" dummy character. For details see this `mathtext tutorial \
 <https://matplotlib.org/stable/tutorials/text/mathtext.html#custom-fonts>`__.
 """
+_rc_init_docstring = """
+    Remaining keyword arguments are passed to `matplotlib.axes.Axes`.
+"""
 _rc_format_docstring = """
 rc_mode : int, optional
     The context mode passed to `~proplot.config.Configurator.context`.
 rc_kw : dict-like, optional
     An alternative to passing extra keyword arguments. See below.
 **kwargs
-    Unknown keyword arguments are passed to `matplotlib.axes.Axes`. Other keyword
-    arguments that match the name of an `~proplot.config.rc` setting are passed to
-    `proplot.config.Configurator.context` and used to update the axes. If the setting
-    name has "dots" you can simply omit the dots. For example, ``abc='A.'`` modifies
-    the :rcraw:`abc` setting, ``titleloc='left'`` modifies the :rcraw:`title.loc`
-    setting, ``gridminor=True`` modifies the :rcraw:`gridminor` setting, and
-    ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many of the keyword
-    arguments documented above are internally applied by retrieving settings passed
-    to `~proplot.config.Configurator.context`.
+    {}Keyword arguments that match the name of an `~proplot.config.rc` setting are
+    passed to `proplot.config.Configurator.context` and used to update the axes.
+    If the setting name has "dots" you can simply omit the dots. For example,
+    ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the
+    :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor`
+    setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many
+    of the keyword arguments documented above are internally applied by retrieving
+    settings passed to `~proplot.config.Configurator.context`.
 """
-docstring._snippet_manager['axes.rc'] = _rc_format_docstring
+docstring._snippet_manager['rc.init'] = _rc_format_docstring.format(_rc_init_docstring.strip())  # noqa: E501
+docstring._snippet_manager['rc.format'] = _rc_format_docstring.format('')
 docstring._snippet_manager['axes.format'] = _axes_format_docstring
 docstring._snippet_manager['figure.format'] = _figure_format_docstring
 
@@ -678,7 +681,7 @@ def __init__(self, *args, **kwargs):
 
         Other parameters
         ----------------
-        %(axes.rc)s
+        %(rc.init)s
 
         See also
         --------
@@ -691,18 +694,20 @@ def __init__(self, *args, **kwargs):
         proplot.figure.Figure.subplot
         proplot.figure.Figure.add_subplot
         """
-        # Initialize parent after removing args
-        # NOTE: These are really "subplot" features so documented on add_subplot().
+        # Remove subplot-related args
+        # NOTE: These are documented on add_subplot()
         ss = kwargs.pop('_subplot_spec', None)  # see below
         number = kwargs.pop('number', None)
         autoshare = kwargs.pop('autoshare', None)
         autoshare = _not_none(autoshare, True)
+
+        # Remove format-related args and initialize
         rc_kw, rc_mode = _pop_rc(kwargs)
         kw_format = _pop_props(kwargs, 'patch')  # background properties
-        if 'zorder' in kw_format:  # special case: refers to entire axes
+        if 'zorder' in kw_format:  # special case: refers to the entire axes
             kwargs['zorder'] = kw_format.pop('zorder')
-        kw_format.update(_pop_params(kwargs, self._format_signature_proj))
-        kw_format.update(_pop_params(kwargs, self._format_signature_base))
+        for name in {None, self._name}:  # base method and class method (if it exists)
+            kw_format.update(_pop_params(kwargs, self._format_signatures.get(name)))
         super().__init__(*args, **kwargs)
 
         # Varous scalar properties
@@ -760,20 +765,18 @@ def __init__(self, *args, **kwargs):
         # set_subplotspec. Tried to defer to setter but really messes up both format()
         # and _auto_share(). Instead use workaround: Have Figure.add_subplot pass
         # subplotspec as a hidden keyword arg. Non-subplots don't need this arg.
-        # See https://github.com/matplotlib/matplotlib/pull/18564
+        # See: https://github.com/matplotlib/matplotlib/pull/18564
         self._number = None
         if number:  # not None or False
-            self.number = number  # documented in add_subplot
-        if ss is not None:
+            self.number = number
+        if ss is not None:  # always passed from add_subplot
             self.set_subplotspec(ss)
         if autoshare:
             self._auto_share()
 
         # Default formatting
         # NOTE: This ignores user-input rc_mode. Mode '1' applies proplot
         # features which is necessary on first run. Default otherwise is mode '2'
-        if 'color' in rc_kw:
-            kw_format['color'] = rc_kw.pop('color')  # special case (argument clash)
         self.format(rc_kw=rc_kw, rc_mode=1, skip_figure=True, **kw_format)
 
     @staticmethod
@@ -1431,11 +1434,6 @@ def format(
         ----------
         %(axes.format)s
 
-        Other parameters
-        ----------------
-        %(figure.format)s
-        %(axes.rc)s
-
         Important
         ---------
         `abc`, `abcloc`, `titleloc`, `titleabove`, `titlepad`, and
@@ -1444,6 +1442,11 @@ def format(
         change them for specific axes. But many :ref:`other configuration
         settings <ug_format>` can be passed to ``format`` too.
 
+        Other parameters
+        ----------------
+        %(figure.format)s
+        %(rc.format)s
+
         See also
         --------
         proplot.axes.CartesianAxes.format
@@ -3042,8 +3045,8 @@ def number(self, num):
         else:
             raise ValueError(f'Invalid number {num!r}. Must be integer >=1.')
 
-    # Apply signature obfuscation after getting keys
-    # NOTE: This is needed for __init__
-    _format_signature_proj = None
-    _format_signature_base = inspect.signature(format)
-    format = docstring._obfuscate_kwargs(format)
+
+# Apply signature obfuscation after storing previous signature
+# NOTE: This is needed for __init__
+Axes._format_signatures = {None: inspect.signature(Axes.format)}
+Axes.format = docstring._obfuscate_kwargs(Axes.format)

proplot/axes/cartesian.py

@@ -320,7 +320,7 @@ def __init__(self, *args, **kwargs):
         Other parameters
         ----------------
         %(axes.format)s
-        %(axes.rc)s
+        %(rc.init)s
 
         See also
         --------
@@ -945,7 +945,7 @@ def format(
         ----------------
         %(axes.format)s
         %(figure.format)s
-        %(axes.rc)s
+        %(rc.format)s
 
         See also
         --------
@@ -1347,7 +1347,8 @@ def get_tightbbox(self, renderer, *args, **kwargs):
         self._update_rotation('x')
         return super().get_tightbbox(renderer, *args, **kwargs)
 
-    # Apply signature obfuscation after getting keys
-    # NOTE: This is needed for __init__, altx, and alty
-    _format_signature_proj = inspect.signature(format)
-    format = docstring._obfuscate_kwargs(format)
+
+# Apply signature obfuscation after storing previous signature
+# NOTE: This is needed for __init__, altx, and alty
+CartesianAxes._format_signatures[CartesianAxes._name] = inspect.signature(CartesianAxes.format)  # noqa: E501
+CartesianAxes.format = docstring._obfuscate_kwargs(CartesianAxes.format)

proplot/axes/geo.py

@@ -425,7 +425,7 @@ def __init__(self, *args, **kwargs):
         Other parameters
         ----------------
         %(axes.format)s
-        %(axes.rc)s
+        %(rc.init)s
 
         Note
         ----
@@ -555,7 +555,7 @@ def format(
         ----------------
         %(axes.format)s
         %(figure.format)s
-        %(axes.rc)s
+        %(rc.format)s
 
         See also
         --------
@@ -690,11 +690,6 @@ def projection(self, map_projection):
             raise ValueError(f'Projection must be a {cls} instance.')
         self._map_projection = map_projection
 
-    # Apply signature obfuscation after getting keys
-    # NOTE: This is needed for __init__
-    _format_signature_proj = inspect.signature(format)
-    format = docstring._obfuscate_kwargs(format)
-
 
 class _CartopyAxes(GeoAxes, _GeoAxes):
     """
@@ -1416,3 +1411,9 @@ def _update_minor_gridlines(self, longrid=None, latgrid=None, nsteps=None):
             axis.isDefault_majfmt = True
             axis.isDefault_majloc = True
             axis.isDefault_minloc = True
+
+
+# Apply signature obfuscation after storing previous signature
+GeoAxes._format_signatures[_CartopyAxes._name] = inspect.signature(GeoAxes.format)
+GeoAxes._format_signatures[_BasemapAxes._name] = inspect.signature(GeoAxes.format)
+GeoAxes.format = docstring._obfuscate_kwargs(GeoAxes.format)

proplot/axes/polar.py

@@ -119,7 +119,7 @@ def __init__(self, *args, **kwargs):
         Other parameters
         ----------------
         %(axes.format)s
-        %(axes.rc)s
+        %(rc.init)s
 
         See also
         --------
@@ -232,7 +232,7 @@ def format(
         ----------------
         %(axes.format)s
         %(figure.format)s
-        %(axes.rc)s
+        %(rc.format)s
 
         See also
         --------
@@ -332,7 +332,8 @@ def format(
         # Parent format method
         super().format(rc_kw=rc_kw, rc_mode=rc_mode, **kwargs)
 
-    # Apply signature obfuscation after getting keys
-    # NOTE: This is needed for __init__
-    _format_signature_proj = inspect.signature(format)
-    format = docstring._obfuscate_kwargs(format)
+
+# Apply signature obfuscation after storing previous signature
+# NOTE: This is needed for __init__
+PolarAxes._format_signatures[PolarAxes._name] = inspect.signature(PolarAxes.format)
+PolarAxes.format = docstring._obfuscate_kwargs(PolarAxes.format)

proplot/figure.py

@@ -1435,7 +1435,7 @@ def _align_content():  # noqa: E306
 
     @docstring._snippet_manager
     def format(
-        self, axs=None,
+        self, axs=None, *,
         figtitle=None, suptitle=None, suptitle_kw=None,
         llabels=None, leftlabels=None, leftlabels_kw=None,
         rlabels=None, rightlabels=None, rightlabels_kw=None,
@@ -1451,15 +1451,8 @@ def format(
         Parameters
         ----------
         axs : sequence of `~proplot.axes.Axes`, optional
-            The axes to format.
+            The axes to format. Default is the numbered subplots.
         %(figure.format)s
-        **kwargs
-            Passed to the projection-specific ``format`` command for each axes.
-
-        Other parameters
-        ----------------
-        %(axes.format)s
-        %(axes.rc)s
 
         Important
         ---------
@@ -1469,6 +1462,14 @@ def format(
         change them for specific figures. But many :ref:`other configuration
         settings <ug_format>` can be passed to ``format`` too.
 
+        Other parameters
+        ----------------
+        %(axes.format)s
+        %(cartesian.format)s
+        %(polar.format)s
+        %(geo.format)s
+        %(rc.format)s
+
         See also
         --------
         proplot.axes.Axes.format
@@ -1479,6 +1480,7 @@ def format(
         proplot.config.Configurator.context
         """
         # Initiate context block
+        axs = axs or self._subplot_dict.values()
         skip_axes = kwargs.pop('skip_axes', False)  # internal keyword arg
         rc_kw, rc_mode = _pop_rc(kwargs)
         with rc.context(rc_kw, mode=rc_mode):
@@ -1539,9 +1541,30 @@ def format(
         # Update the main axes
         if skip_axes:  # avoid recursion
             return
-        axs = axs or self._subplot_dict.values()
+        names = set()  # track used dictionaries
+        dicts = {
+            name: _pop_params(kwargs, signature)
+            for name, signature in paxes.Axes._format_signatures.items()
+        }
         for ax in axs:
-            ax.format(rc_kw=rc_kw, rc_mode=rc_mode, skip_figure=True, **kwargs)
+            dict_ = {}
+            for name in {None, ax._name}:
+                names.add(name)
+                dict_.update(dicts.get(name, {}))
+            ax.format(rc_kw=rc_kw, rc_mode=rc_mode, skip_figure=True, **dict_)
+
+        # Warn unused keyword argument(s)
+        kwargs.update(
+            {
+                key: value
+                for name in dicts.keys() - names
+                for key, value in dicts[name].items()
+            }
+        )
+        if kwargs:
+            warnings._warn_proplot(
+                f'Ignoring unrecognized format keyword argument(s): {kwargs}'
+            )
 
     @docstring._concatenate_inherited
     @docstring._snippet_manager

proplot/gridspec.py

@@ -1109,7 +1109,7 @@ def update(self, **kwargs):
     @property
     def figure(self):
         """
-        The `proplot.figure.Figure` instance uniquely associated with this `GridSpec`.
+        The `proplot.figure.Figure` uniquely associated with this `GridSpec`.
         On assignment the gridspec parameters and figure size are updated.
         """
         return self._figure
@@ -1383,7 +1383,7 @@ def _validate_item(self, items, scalar=False):
         return items
 
     @docstring._snippet_manager
-    def format(self, *args, **kwargs):
+    def format(self, **kwargs):
         """
         Call the ``format`` command for every axes in the grid.
 
@@ -1397,7 +1397,10 @@ def format(self, *args, **kwargs):
         Other parameters
         ----------------
         %(figure.format)s
-        %(axes.rc)s
+        %(cartesian.format)s
+        %(polar.format)s
+        %(geo.format)s
+        %(rc.format)s
 
         See also
         --------
@@ -1408,14 +1411,21 @@ def format(self, *args, **kwargs):
         proplot.figure.Figure.format
         proplot.config.Configurator.context
         """
-        for ax in self:
-            ax.format(*args, **kwargs)
+        self.figure.format(axs=self, **kwargs)
+
+    @property
+    def figure(self):
+        """
+        The `proplot.figure.Figure` uniquely associated with this `SubplotGrid`.
+        This is used for the `SubplotGrid.format` command.
+        """
+        return self.gridspec.figure
 
     @property
     def gridspec(self):
         """
-        The `~proplot.gridspec.GridSpec` associated with the grid. This is used
-        to resolve 2D indexing. See `~SubplotGrid.__getitem__` for details.
+        The `~proplot.gridspec.GridSpec` uniquely associated with this `SubplotGrid`.
+        This is used to resolve 2D indexing. See `~SubplotGrid.__getitem__` for details.
         """
         # Return the gridspec associatd with the grid
         if not self:

proplot/ui.py

@@ -185,9 +185,8 @@ def subplots(*args, **kwargs):
     # Format keywords
     rc_kw, rc_mode = _pop_rc(kwargs)
     kwformat = _pop_params(kwargs, pfigure.Figure._format_signature)
-    kwformat.update(_pop_params(kwargs, paxes.Axes._format_signature_base))
-    for cls in (paxes.CartesianAxes, paxes.PolarAxes, paxes.GeoAxes):
-        kwformat.update(_pop_params(kwargs, cls._format_signature_proj))
+    for name, signature in paxes.Axes._format_signatures.items():
+        kwformat.update(_pop_params(kwargs, signature))
     # Initialize
     fig = figure(rc_kw=rc_kw, **kwargs)
     axs = fig.add_subplots(*args, **kwsubs)