Convert docstring snippets dict to _SnippetsManager class

Author: lukelbd

proplot/axes/base.py

@@ -35,6 +35,7 @@
     _pop_kwargs,
     _pop_params,
     _pop_props,
+    _snippet_manager,
     _version_mpl,
     docstring,
     rcsetup,
@@ -64,7 +65,7 @@
     `~matplotlib.axes.Axes.transAxes`, or `~matplotlib.figure.Figure.transFigure`
     transforms. Default is ``'axes'``, i.e. `bounds` is in axes-relative coordinates.
 """
-docstring.snippets['axes.transform'] = _transform_docstring
+_snippet_manager['axes.transform'] = _transform_docstring
 
 
 # Projection docstring
@@ -89,9 +90,9 @@
     Whether to use `~mpl_toolkits.basemap.Basemap` or `~cartopy.crs.Projection`
     for map projections. Default is :rc:`basemap`.
 """
-docstring.snippets['axes.proj'] = _proj_docstring
-docstring.snippets['axes.proj_kw'] = _proj_kw_docstring
-docstring.snippets['axes.basemap'] = _basemap_docstring
+_snippet_manager['axes.proj'] = _proj_docstring
+_snippet_manager['axes.proj_kw'] = _proj_kw_docstring
+_snippet_manager['axes.basemap'] = _basemap_docstring
 
 
 # Inset docstring
@@ -125,7 +126,7 @@
 **kwargs
     Passed to `CartesianAxes`.
 """
-docstring.snippets['axes.inset'] = docstring.add_snippets(_inset_docstring)
+_snippet_manager['axes.inset'] = _inset_docstring
 
 
 # Panel docstring
@@ -168,7 +169,7 @@
 `~proplot.axes.CartesianAxes`
     The panel axes.
 """
-docstring.snippets['axes.panel'] = docstring.add_snippets(_panel_docstring)
+_snippet_manager['axes.panel'] = _panel_docstring
 
 
 # Colorbar and legend space
@@ -191,11 +192,11 @@
     *inset* {name}, the old {name} is removed. If ``False`` and `loc` is an
     *outer* {name}, the {name}s are stacked.
 """
-docstring.snippets['axes.legend_space'] = docstring.add_snippets(
-    _space_docstring.format(name='legend', default='legend.borderaxespad')
+_snippet_manager['axes.legend_space'] = _space_docstring.format(
+    name='legend', default='legend.borderaxespad'
 )
-docstring.snippets['axes.colorbar_space'] = docstring.add_snippets(
-    _space_docstring.format(name='colorbar', default='colorbar.insetpad')
+_snippet_manager['axes.colorbar_space'] = _space_docstring.format(
+    name='colorbar', default='colorbar.insetpad'
 )
 
 
@@ -302,9 +303,9 @@
     Many of the keyword arguments documented above are actually applied by updating
     the `~proplot.config.rc` settings then retrieving the updated settings.
 """
-docstring.snippets['axes.rc'] = _rc_format_docstring
-docstring.snippets['axes.format'] = _axes_format_docstring
-docstring.snippets['figure.format'] = _figure_format_docstring
+_snippet_manager['axes.rc'] = _rc_format_docstring
+_snippet_manager['axes.format'] = _axes_format_docstring
+_snippet_manager['figure.format'] = _figure_format_docstring
 
 
 # Colorbar docstrings
@@ -344,8 +345,8 @@
     mappable object. If the attribute is unavailable, we use ``'neither'``.
 extendsize : float or str, optional
     The length of the colorbar "extensions" in physical units. Default is
-    :rc:`colorbar.insetextend` for inset colorbars and :rc:`colorbar.extend`
-    for outer colorbars. %(units.em)s
+    :rc:`colorbar.insetextend` for inset colorbars and :rc:`colorbar.extend` for
+    outer colorbars. %(units.em)s
 frame, frameon : bool, optional
     For inset colorbars only. Indicates whether to draw a "frame", just
     like `~matplotlib.axes.Axes.legend`. Default is :rc:`colorbar.frameon`.
@@ -411,8 +412,8 @@
 **kwargs
     Passed to `~matplotlib.figure.Figure.colorbar`.
 """
-docstring.snippets['axes.colorbar_args'] = _colorbar_args_docstring
-docstring.snippets['axes.colorbar_kwargs'] = _colorbar_kwargs_docstring
+_snippet_manager['axes.colorbar_args'] = _colorbar_args_docstring
+_snippet_manager['axes.colorbar_kwargs'] = _colorbar_kwargs_docstring
 
 
 # Legend docstrings
@@ -476,8 +477,8 @@
 **kwargs
     Passed to `~matplotlib.axes.Axes.legend`.
 """
-docstring.snippets['axes.legend_args'] = _legend_args_docstring
-docstring.snippets['axes.legend_kwargs'] = _legend_kwargs_docstring
+_snippet_manager['axes.legend_args'] = _legend_args_docstring
+_snippet_manager['axes.legend_kwargs'] = _legend_kwargs_docstring
 
 
 class Axes(maxes.Axes):
@@ -1234,8 +1235,8 @@ def _update_super_labels(self, side, labels=None, **kwargs):
         if labels or kw:
             fig._update_super_labels(side, labels, **kw)
 
-    @docstring.obfuscate_signature
-    @docstring.add_snippets
+    @docstring._obfuscate_signature
+    @_snippet_manager
     def format(
         self, *, title=None, title_kw=None, abc_kw=None,
         ltitle=None, lefttitle=None,
@@ -1378,14 +1379,14 @@ def get_tightbbox(self, renderer, *args, **kwargs):
         self._tight_bbox = bbox
         return bbox
 
-    @docstring.add_snippets
+    @_snippet_manager
     def inset(self, *args, **kwargs):
         """
         %(axes.inset)s
         """
         return self.inset_axes(*args, **kwargs)
 
-    @docstring.add_snippets
+    @_snippet_manager
     def inset_axes(
         self, bounds, transform=None, *, proj=None, projection=None,
         zoom=None, zoom_kw=None, zorder=4, **kwargs
@@ -1486,14 +1487,14 @@ def indicate_inset_zoom(self, **kwargs):
         self._inset_zoom_data = (rectpatch, connects)
         return rectpatch, connects
 
-    @docstring.add_snippets
+    @_snippet_manager
     def panel(self, *args, **kwargs):
         """
         %(axes.panel)s
         """
         return self.panel_axes(*args, **kwargs)
 
-    @docstring.add_snippets
+    @_snippet_manager
     def panel_axes(self, *args, **kwargs):
         """
         %(axes.panel)s
@@ -2187,8 +2188,8 @@ def _draw_colorbar(
         self._add_guide('colorbar', obj, loc)  # possibly replace another
         return obj
 
-    @docstring.obfuscate_signature
-    @docstring.add_snippets
+    @docstring._obfuscate_signature
+    @_snippet_manager
     def colorbar(
         self, mappable, values=None, *, loc=None, location=None, queue=False,
         **kwargs
@@ -2701,8 +2702,8 @@ def _draw_legend(
         self._add_guide('legend', obj, loc)  # possibly replace another
         return obj
 
-    @docstring.concatenate_original
-    @docstring.add_snippets
+    @docstring._concatenate_original
+    @_snippet_manager
     def legend(
         self, handles=None, labels=None, *, loc=None, location=None, queue=False,
         **kwargs
@@ -2838,7 +2839,8 @@ def _update_text(text, props=None, **kwargs):
 
         return mtext.Text.update(text, props)
 
-    @docstring.concatenate_original
+    @docstring._concatenate_original
+    @_snippet_manager
     def text(
         self, *args,
         border=False, bordercolor='w', borderwidth=2, borderinvert=False,
@@ -2883,15 +2885,17 @@ def text(
             The alpha for the bounding box. Default is ``'0.5'``.
         bboxpad : float, optional
             The padding for the bounding box. Default is :rc:`title.bboxpad`.
-        family, fontfamily, name, fontname : str, optional
-            The font name (e.g., ``'Fira Math'``) or font family name (e.g.,
+        name, fontname
+            Aliases for `family`, `fontfamily`.
+        family, fontfamily : str, optional
+            The font typeface name (e.g., ``'Fira Math'``) or font family name (e.g.,
             ``'serif'``). Matplotlib falls back to the system default if not found.
         size, fontsize : float or str, optional
             The font size. %(units.pt)s
             This can also be a string indicating some scaling relative to
-            :rcraw:`font.size`. The sizes and scalings are shown below.
-            ``'med-small'`` and ``'med-large'`` are added by ProPlot
-            while the rest are native matplotlib sizes.
+            :rcraw:`font.size`. The sizes and scalings are shown below. The
+            scalings ``'med'``, ``'med-small'``, and ``'med-large'`` are
+            added by ProPlot while the rest are native matplotlib sizes.
 
             .. _font_table:
 

proplot/axes/cartesian.py

@@ -11,7 +11,7 @@
 from .. import ticker as pticker
 from ..config import _parse_format, rc
 from ..internals import ic  # noqa: F401
-from ..internals import _not_none, docstring, rcsetup, warnings
+from ..internals import _not_none, _snippet_manager, docstring, rcsetup, warnings
 from . import plot, shared
 
 __all__ = ['CartesianAxes']
@@ -51,7 +51,7 @@
 {args} : optional
     Prepended with ``'{x}'`` and passed to `Axes.format`.
 """
-docstring.snippets['axes.altx'] = _alt_doc.format(
+_snippet_manager['axes.altx'] = _alt_doc.format(
     x='x',
     x1='bottom',
     x2='top',
@@ -61,7 +61,7 @@
     args=', '.join(_alt_kwargs),
     xargs=', '.join('x' + key for key in _alt_kwargs),
 )
-docstring.snippets['axes.alty'] = _alt_doc.format(
+_snippet_manager['axes.alty'] = _alt_doc.format(
     x='y',
     x1='left',
     x2='right',
@@ -88,12 +88,12 @@
 {args} : optional
     Prepended with ``'{x}'`` and passed to `Axes.format`.
 """
-docstring.snippets['axes.dualx'] = _dual_doc.format(
+_snippet_manager['axes.dualx'] = _dual_doc.format(
     x='x',
     args=', '.join(_alt_kwargs),
     xargs=', '.join('x' + key for key in _alt_kwargs),
 )
-docstring.snippets['axes.dualy'] = _dual_doc.format(
+_snippet_manager['axes.dualy'] = _dual_doc.format(
     x='y',
     args=', '.join(_alt_kwargs),
     xargs=', '.join('y' + key for key in _alt_kwargs),
@@ -120,13 +120,13 @@
 {args} : optional
     Prepended with ``'{x}'`` and passed to `Axes.format`.
 """
-docstring.snippets['axes.twinx'] = _twin_doc.format(
+_snippet_manager['axes.twinx'] = _twin_doc.format(
     x='y', x1='left', x2='right',
     y='x', y1='bottom', y2='top',
     args=', '.join(_alt_kwargs),
     xargs=', '.join('y' + key for key in _alt_kwargs),
 )
-docstring.snippets['axes.twiny'] = _twin_doc.format(
+_snippet_manager['axes.twiny'] = _twin_doc.format(
     x='x', x1='bottom', x2='top',
     y='y', y1='left', y2='right',
     args=', '.join(_alt_kwargs),
@@ -651,8 +651,8 @@ def _update_locs(self, x, *, tickloc=None, ticklabelloc=None, labelloc=None):
         if labelloc is not None:
             getattr(self, x + 'axis').set_label_position(labelloc)
 
-    @docstring.obfuscate_signature
-    @docstring.add_snippets
+    @docstring._obfuscate_signature
+    @_snippet_manager
     def format(
         self, *,
         aspect=None,
@@ -1006,7 +1006,7 @@ def format(
             self.set_aspect(aspect)
         super().format(rc_kw=rc_kw, rc_mode=rc_mode, **kwargs)
 
-    @docstring.add_snippets
+    @_snippet_manager
     def altx(self, **kwargs):
         """
         %(axes.altx)s
@@ -1058,7 +1058,7 @@ def altx(self, **kwargs):
 
         return ax
 
-    @docstring.add_snippets
+    @_snippet_manager
     def alty(self, **kwargs):
         """
         %(axes.alty)s
@@ -1096,7 +1096,7 @@ def alty(self, **kwargs):
 
         return ax
 
-    @docstring.add_snippets
+    @_snippet_manager
     def dualx(self, funcscale, **kwargs):
         """
         %(axes.dualx)s
@@ -1109,7 +1109,7 @@ def dualx(self, funcscale, **kwargs):
         ax._dualx_scale()
         return ax
 
-    @docstring.add_snippets
+    @_snippet_manager
     def dualy(self, funcscale, **kwargs):
         """
         %(axes.dualy)s
@@ -1120,14 +1120,14 @@ def dualy(self, funcscale, **kwargs):
         ax._dualy_scale()
         return ax
 
-    @docstring.add_snippets
+    @_snippet_manager
     def twinx(self):
         """
         %(axes.twinx)s
         """
         return self.alty()
 
-    @docstring.add_snippets
+    @_snippet_manager
     def twiny(self):
         """
         %(axes.twiny)s

proplot/axes/geo.py

@@ -14,7 +14,13 @@
 from .. import crs as pcrs
 from ..config import _parse_format, rc
 from ..internals import ic  # noqa: F401
-from ..internals import _not_none, _version_cartopy, docstring, warnings
+from ..internals import (
+    _not_none,
+    _snippet_manager,
+    _version_cartopy,
+    docstring,
+    warnings,
+)
 from . import plot
 
 try:
@@ -365,8 +371,8 @@ def _to_label_array(labels, lon=True):
 
         return array
 
-    @docstring.obfuscate_signature
-    @docstring.add_snippets
+    @docstring._obfuscate_signature
+    @_snippet_manager
     def format(
         self, *,
         lonlim=None, latlim=None, boundinglat=None,