More robust _guide_kw management

Author: lukelbd

proplot/axes/base.py

@@ -1567,26 +1567,29 @@ def _register_guide(self, guide, obj, key, **kwargs):
             kwargs_full.update(kwargs)
 
     def _update_guide(
-        self, objs, colorbar=None, colorbar_kw=None, queue_colorbar=True,
-        legend=None, legend_kw=None,
+        self, objs, legend=None, legend_kw=None, queue_legend=True,
+        colorbar=None, colorbar_kw=None, queue_colorbar=True,
     ):
         """
         Update queues for on-the-fly legends and colorbars or track keyword arguments.
         """
+        # WARNING: Important to always cache the keyword arguments so e.g.
+        # duplicate subsequent calls still enforce user and default behavior.
         # WARNING: This should generally be last in the pipeline before calling
         # the plot function or looping over data columns. The colormap parser
         # and standardize functions both modify colorbar_kw and legend_kw.
         legend_kw = legend_kw or {}
         colorbar_kw = colorbar_kw or {}
-        if colorbar:
-            colorbar_kw.setdefault('queue', queue_colorbar)
-            self.colorbar(objs, loc=colorbar, **colorbar_kw)
-        else:  # store keyword arguments for later
-            guides._cache_guide_kw(objs, 'colorbar', colorbar_kw)
+        guides._cache_guide_kw(objs, 'legend', legend_kw)
+        guides._cache_guide_kw(objs, 'colorbar', colorbar_kw)
         if legend:
-            self.legend(objs, loc=legend, queue=True, **legend_kw)
-        else:  # store keyword arguments for later
-            guides._cache_guide_kw(objs, 'legend', legend_kw)
+            align = legend_kw.pop('align', None)
+            queue = legend_kw.pop('queue', queue_legend)
+            self.legend(objs, loc=legend, align=align, queue=queue, **legend_kw)
+        if colorbar:
+            align = colorbar_kw.pop('align', None)
+            queue = colorbar_kw.pop('queue', queue_colorbar)
+            self.colorbar(objs, loc=colorbar, align=align, queue=queue, **colorbar_kw)
 
     @staticmethod
     def _parse_frame(guide, fancybox=None, shadow=None, **kwargs):
@@ -2792,10 +2795,7 @@ def panel_axes(self, side=None, **kwargs):
 
     @docstring._obfuscate_params
     @docstring._snippet_manager
-    def colorbar(
-        self, mappable, values=None,
-        loc=None, location=None, align=None, queue=False, **kwargs
-    ):
+    def colorbar(self, mappable, values=None, loc=None, location=None, **kwargs):
         """
         Add an inset colorbar or an outer colorbar along the edge of the axes.
 
@@ -2848,30 +2848,31 @@ def colorbar(
         proplot.figure.Figure.colorbar
         matplotlib.figure.Figure.colorbar
         """
-        # Either draw right now or queue up for later
-        # The queue option lets us successively append objects (e.g. line handles)
-        # to a list later used for colorbar levels. Same as legend.
-        loc = _not_none(loc=loc, location=location)
+        # Translate location and possibly infer from orientation. Also optionally
+        # infer align setting from keywords stored on object.
         orientation = kwargs.get('orientation', None)
+        kwargs = guides._flush_guide_kw(mappable, 'colorbar', kwargs)
+        loc = _not_none(loc=loc, location=location)
         if orientation is not None:  # possibly infer loc from orientation
             if orientation not in ('vertical', 'horizontal'):
                 raise ValueError(f"Invalid colorbar orientation {orientation!r}. Must be 'vertical' or 'horizontal'.")   # noqa: E501
             if loc is None:
                 loc = {'vertical': 'right', 'horizontal': 'bottom'}[orientation]
         loc = _translate_loc(loc, 'colorbar', default=rc['colorbar.loc'])
-        align = _translate_loc(align, 'panel', default='center', c='center', center='center')  # noqa: E501
-        kwargs = guides._flush_guide_kw(mappable, 'colorbar', kwargs)
+        align = kwargs.pop('align', None)
+        align = _translate_loc(align, 'align', default='center')
+
+        # Either draw right now or queue up for later. The queue option lets us
+        # successively append objects (e.g. lines) to a colorbar artist list.
+        queue = kwargs.pop('queue', False)
         if queue:
             self._register_guide('colorbar', (mappable, values), (loc, align), **kwargs)
         else:
             return self._add_colorbar(mappable, values, loc=loc, align=align, **kwargs)
 
     @docstring._concatenate_inherited  # also obfuscates params
     @docstring._snippet_manager
-    def legend(
-        self, handles=None, labels=None,
-        loc=None, location=None, align=None, queue=False, **kwargs
-    ):
+    def legend(self, handles=None, labels=None, loc=None, location=None, **kwargs):
         """
         Add an *inset* legend or *outer* legend along the edge of the axes.
 
@@ -2919,13 +2920,17 @@ def legend(
         proplot.figure.Figure.legend
         matplotlib.axes.Axes.legend
         """
-        # Either draw right now or queue up for later
-        # Handles can be successively added to a single location this way. This
-        # is used internally for on-the-fly legends.
+        # Translate location and possibly infer from orientation. Also optionally
+        # infer align setting from keywords stored on object.
+        kwargs = guides._flush_guide_kw(handles, 'legend', kwargs)
         loc = _not_none(loc=loc, location=location)
         loc = _translate_loc(loc, 'legend', default=rc['legend.loc'])
-        align = _translate_loc(align, 'panel', default='center', c='center', center='center')  # noqa: E501
-        kwargs = guides._flush_guide_kw(handles, 'legend', kwargs)
+        align = kwargs.pop('align', None)
+        align = _translate_loc(align, 'align', default='center')
+
+        # Either draw right now or queue up for later. Handles can be successively
+        # added to a single location this way. Used for on-the-fly legends.
+        queue = kwargs.pop('queue', False)
         if queue:
             self._register_guide('legend', (handles, labels), (loc, align), **kwargs)
         else:

proplot/internals/__init__.py

@@ -391,7 +391,9 @@ def _translate_loc(loc, mode, *, default=None, **kwargs):
     # Create specific options dictionary
     # NOTE: This is not inside validators.py because it is also used to
     # validate various user-input locations.
-    if mode == 'panel':
+    if mode == 'align':
+        loc_dict = rcsetup.ALIGN_LOCS
+    elif mode == 'panel':
         loc_dict = rcsetup.PANEL_LOCS
     elif mode == 'legend':
         loc_dict = rcsetup.LEGEND_LOCS

proplot/internals/guides.py

@@ -11,6 +11,16 @@
 from . import ic  # noqa: F401
 from . import warnings
 
+# Global constants
+REMOVE_AFTER_FLUSH = (
+    'pad', 'space', 'width', 'length', 'shrink', 'align', 'queue',
+)
+GUIDE_ALIASES = (
+    ('title', 'label'),
+    ('locator', 'ticks'),
+    ('format', 'formatter', 'ticklabels')
+)
+
 
 def _add_guide_kw(name, kwargs, **opts):
     """
@@ -50,6 +60,8 @@ def _flush_guide_kw(obj, name, kwargs):
     opts = getattr(obj, f'_{name}_kw', None)
     if opts:
         _update_kw(kwargs, overwrite=False, **opts)
+        for key in REMOVE_AFTER_FLUSH:
+            opts.pop(key, None)
     if isinstance(obj, (tuple, list, np.ndarray)):
         for member in obj:  # possibly iterate over matplotlib tuple/list subclasses
             _flush_guide_kw(member, name, kwargs)
@@ -60,15 +72,10 @@ def _update_kw(kwargs, overwrite=False, **opts):
     """
     Add the keyword arguments to the dictionary if not already present.
     """
-    aliases = (
-        ('title', 'label'),
-        ('locator', 'ticks'),
-        ('format', 'formatter', 'ticklabels')
-    )
     for key, value in opts.items():
         if value is None:
             continue
-        keys = tuple(k for opts in aliases for k in opts if key in opts)
+        keys = tuple(k for opts in GUIDE_ALIASES for k in opts if key in opts)
         keys = keys or (key,)  # e.g. 'extend' or something
         keys_found = tuple(key for key in keys if kwargs.get(key) is not None)
         if not keys_found:

proplot/internals/rcsetup.py

@@ -106,24 +106,29 @@
     if _loc not in LEGEND_LOCS:
         LEGEND_LOCS[_loc] = _loc  # identity assignments
 TEXT_LOCS = {
-    key: value for key, value in LEGEND_LOCS.items() if value in (
+    key: val for key, val in LEGEND_LOCS.items() if val in (
         'left', 'center', 'right',
         'upper left', 'upper center', 'upper right',
         'lower left', 'lower center', 'lower right',
     )
 }
 COLORBAR_LOCS = {
-    key: value for key, value in LEGEND_LOCS.items() if value in (
+    key: val for key, val in LEGEND_LOCS.items() if val in (
         'fill', 'best',
         'left', 'right', 'top', 'bottom',
         'upper left', 'upper right', 'lower left', 'lower right',
     )
 }
 PANEL_LOCS = {
-    key: value for key, value in LEGEND_LOCS.items() if value in (
+    key: val for key, val in LEGEND_LOCS.items() if val in (
         'left', 'right', 'top', 'bottom'
     )
 }
+ALIGN_LOCS = {
+    key: val for key, val in LEGEND_LOCS.items() if isinstance(key, str) and val in (
+        'left', 'right', 'top', 'bottom', 'center',
+    )
+}
 
 # Matplotlib setting categories
 EM_KEYS = (  # em-width units