ultraplot 0.99.3__py3-none-any.whl

ultraplot/internals/docstring.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+Utilities for modifying ultraplot docstrings.
+"""
+# WARNING: To check every docstring in the package for
+# unfilled snippets simply use the following code:
+# >>> import ultraplot as pplt
+# ... seen = set()
+# ... def _iter_doc(objs):
+# ...     if objs in seen:
+# ...         return
+# ...     seen.add(objs)
+# ...     for attr in dir(objs):
+# ...         obj = getattr(objs, attr, None)
+# ...         if callable(obj) and hasattr(obj, '__doc__'):
+# ...             if obj in seen:
+# ...                 continue
+# ...             seen.add(obj)
+# ...             if obj.__doc__ and '%(' in obj.__doc__:
+# ...                 yield obj.__name__
+# ...             yield from _iter_doc(obj)
+# ... print(*_iter_doc(pplt))
+import inspect
+import re
+
+import matplotlib.axes as maxes
+import matplotlib.figure as mfigure
+from matplotlib import rcParams as rc_matplotlib
+
+from . import ic  # noqa: F401
+
+
+def _obfuscate_kwargs(func):
+    """
+    Obfuscate keyword args.
+    """
+    return _obfuscate_signature(func, lambda **kwargs: None)
+
+
+def _obfuscate_params(func):
+    """
+    Obfuscate all parameters.
+    """
+    return _obfuscate_signature(func, lambda *args, **kwargs: None)
+
+
+def _obfuscate_signature(func, dummy):
+    """
+    Obfuscate a misleading or incomplete call signature.
+    Instead users should inspect the parameter table.
+    """
+    # Obfuscate signature by converting to *args **kwargs. Note this does
+    # not change behavior of function! Copy parameters from a dummy function
+    # because I'm too lazy to figure out inspect.Parameters API
+    # See: https://stackoverflow.com/a/33112180/4970632
+    sig = inspect.signature(func)
+    sig_repl = inspect.signature(dummy)
+    func.__signature__ = sig.replace(parameters=tuple(sig_repl.parameters.values()))
+    return func
+
+
+def _concatenate_inherited(func, prepend_summary=False):
+    """
+    Concatenate docstrings from a matplotlib axes method with a ultraplot
+    axes method and obfuscate the call signature.
+    """
+    # Get matplotlib axes func
+    # NOTE: Do not bother inheriting from cartopy GeoAxes. Cartopy completely
+    # truncates the matplotlib docstrings (which is kind of not great).
+    qual = func.__qualname__
+    if "Axes" in qual:
+        cls = maxes.Axes
+    elif "Figure" in qual:
+        cls = mfigure.Figure
+    else:
+        raise ValueError(f"Unexpected method {qual!r}. Must be Axes or Figure method.")
+    doc = inspect.getdoc(func) or ""  # also dedents
+    func_orig = getattr(cls, func.__name__, None)
+    doc_orig = inspect.getdoc(func_orig)
+    if not doc_orig:  # should never happen
+        return func
+
+    # Optionally prepend the function summary
+    # Concatenate docstrings only if this is not generated for website
+    regex = re.search(r"\.( | *\n|\Z)", doc_orig)
+    if regex and prepend_summary:
+        doc = doc_orig[: regex.start() + 1] + "\n\n" + doc
+    if not rc_matplotlib["docstring.hardcopy"]:
+        doc = f"""
+=====================
+ultraplot documentation
+=====================
+
+{doc}
+
+========================
+Matplotlib documentation
+========================
+
+{doc_orig}
+"""
+
+    # Return docstring
+    # NOTE: Also obfuscate parameters to avoid partial coverage of call signatures
+    func.__doc__ = inspect.cleandoc(doc)
+    func = _obfuscate_params(func)
+    return func
+
+
+class _SnippetManager(dict):
+    """
+    A simple database for handling documentation snippets.
+    """
+
+    def __call__(self, obj):
+        """
+        Add snippets to the string or object using ``%(name)s`` substitution. Here
+        ``%(name)s`` is used rather than ``.format`` to support invalid identifiers.
+        """
+        if isinstance(obj, str):
+            obj %= self  # add snippets to a string
+        else:
+            obj.__doc__ = inspect.getdoc(obj)  # also dedents the docstring
+            if obj.__doc__:
+                obj.__doc__ %= self  # insert snippets after dedent
+        return obj
+
+    def __setitem__(self, key, value):
+        """
+        Populate input strings with other snippets and strip newlines. Developers
+        should take care to import modules in the correct order.
+        """
+        value = self(value)
+        value = value.strip("\n")
+        super().__setitem__(key, value)
+
+
+# Initiate snippets database
+_snippet_manager = _SnippetManager()

ultraplot/internals/fonts.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""
+Overrides related to math fonts.
+"""
+import matplotlib as mpl
+from matplotlib.font_manager import findfont, ttfFontProperty
+from matplotlib.mathtext import MathTextParser
+
+from . import warnings
+
+try:  # newer versions
+    from matplotlib._mathtext import UnicodeFonts
+except ImportError:  # older versions
+    from matplotlib.mathtext import UnicodeFonts
+
+# Global constant
+WARN_MATHPARSER = True
+
+
+class _UnicodeFonts(UnicodeFonts):
+    """
+    A simple `~matplotlib._mathtext.UnicodeFonts` subclass that
+    interprets ``rc['mathtext.default'] != 'regular'`` in the presence of
+    ``rc['mathtext.fontset'] == 'custom'`` as possibly modifying the active font.
+
+    Works by permitting the ``rc['mathtext.rm']``, ``rc['mathtext.it']``,
+    etc. settings to have the dummy value ``'regular'`` instead of a valid family
+    name, e.g. ``rc['mathtext.it'] == 'regular:italic'`` (permitted through an
+    override of the `~matplotlib.rcsetup.validate_font_properties` validator).
+    When this dummy value is detected then the font properties passed to
+    `~matplotlib._mathtext.TrueTypeFont` are taken by replacing ``'regular'``
+    in the "math" fontset with the active font name.
+    """
+
+    def __init__(self, *args, **kwargs):
+        # Initialize font
+        # NOTE: Could also capture the 'default_font_prop' passed as positional
+        # argument but want to guard against keyword changes. This entire API is
+        # private and it is easier to do graceful fallback with _fonts dictionary.
+        ctx = {}  # rc context
+        regular = {}  # styles
+        for texfont in ("cal", "rm", "tt", "it", "bf", "sf"):
+            key = "mathtext." + texfont
+            prop = mpl.rcParams[key]
+            if prop.startswith("regular"):
+                ctx[key] = prop.replace("regular", "sans", 1)
+                regular[texfont] = prop
+        with mpl.rc_context(ctx):
+            super().__init__(*args, **kwargs)
+        # Apply current font replacements
+        global WARN_MATHPARSER
+        if (
+            hasattr(self, "fontmap")
+            and hasattr(self, "_fonts")
+            and "regular" in self._fonts
+        ):
+            font = self._fonts["regular"]  # an ft2font.FT2Font instance
+            font = ttfFontProperty(font)
+            for texfont, prop in regular.items():
+                prop = prop.replace("regular", font.name)
+                self.fontmap[texfont] = findfont(prop, fallback_to_default=False)
+        elif WARN_MATHPARSER:
+            # Suppress duplicate warnings in case API changes
+            warnings._warn_ultraplot("Failed to update the math text parser.")
+            WARN_MATHPARSER = False
+
+
+# Replace the parser
+try:
+    mapping = MathTextParser._font_type_mapping
+    if mapping["custom"] is UnicodeFonts:
+        mapping["custom"] = _UnicodeFonts
+except (KeyError, AttributeError):
+    warnings._warn_ultraplot("Failed to update math text parser.")
+    WARN_MATHPARSER = False

ultraplot/internals/guides.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Utilties related to legends and colorbars.
+"""
+import matplotlib.artist as martist
+import matplotlib.colorbar as mcolorbar
+import matplotlib.legend as mlegend  # noqa: F401
+import matplotlib.ticker as mticker
+import numpy as np
+
+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):
+    """
+    Add to the `colorbar_kw` or `legend_kw` dict if there are no conflicts.
+    """
+    # NOTE: Here we *do not* want to overwrite properties in dictionary. Indicates
+    # e.g. default locator inferred from levels or default title inferred from metadata.
+    attr = f"{name}_kw"
+    if not opts:
+        return
+    if not kwargs.get(attr, None):
+        kwargs[attr] = {}  # permit e.g. colorbar_kw=None
+    guide_kw = kwargs[attr]
+    _update_kw(guide_kw, overwrite=False, **opts)
+
+
+def _cache_guide_kw(obj, name, kwargs):
+    """
+    Cache settings on the object from the input keyword arguments.
+    """
+    # NOTE: Here we overwrite the hidden dictionary if it already exists.
+    # This is only called once in _update_guide() so its fine.
+    try:
+        setattr(obj, f"_{name}_kw", kwargs)
+    except AttributeError:
+        pass
+    if isinstance(obj, (tuple, list, np.ndarray)):
+        for member in obj:
+            _cache_guide_kw(member, name, kwargs)
+
+
+def _flush_guide_kw(obj, name, kwargs):
+    """
+    Flux settings cached on the object into the keyword arguments.
+    """
+    # NOTE: Here we *do not* overwrite properties in the dictionary by default.
+    # Indicates e.g. calling colorbar(extend='both') after pcolor(extend='neither').
+    # NOTE: Previously had problems reusing same keyword arguments for more than one
+    # colorbar() because locator or formatter axis would get reset. Old solution was
+    # to delete the _guide_kw but that destroyed default behavior. New solution is
+    # to keep _guide_kw but have constructor functions return shallow copies.
+    guide_kw = getattr(obj, f"_{name}_kw", None)
+    if guide_kw:
+        _update_kw(kwargs, overwrite=False, **guide_kw)
+        for key in REMOVE_AFTER_FLUSH:
+            guide_kw.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)
+    return kwargs
+
+
+def _update_kw(kwargs, overwrite=False, **opts):
+    """
+    Add the keyword arguments to the dictionary if not already present.
+    """
+    for key, value in opts.items():
+        if value is None:
+            continue
+        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:
+            kwargs[key] = value
+        elif overwrite:  # overwrite existing key
+            kwargs[keys_found[0]] = value
+
+
+def _iter_children(*args):
+    """
+    Iterate through `_children` of `HPacker`, `VPacker`, and `DrawingArea`.
+    This is used to update legend handle properties.
+    """
+    for arg in args:
+        if hasattr(arg, "_children"):
+            yield from _iter_children(*arg._children)
+        elif arg is not None:
+            yield arg
+
+
+def _iter_iterables(*args):
+    """
+    Iterate over arbitrary nested lists of iterables. Used for deciphering legend input.
+    Things can get complicated with e.g. bar colunns plus negative-positive colors.
+    """
+    for arg in args:
+        if np.iterable(arg):
+            yield from _iter_iterables(*arg)
+        elif arg is not None:
+            yield arg
+
+
+def _update_ticks(self, manual_only=False):
+    """
+    Refined colorbar tick updater without subclassing.
+    """
+    # TODO: Add this to generalized colorbar subclass?
+    # NOTE: Matplotlib 3.5+ does not define _use_auto_colorbar_locator since
+    # ticks are always automatically adjusted by its colorbar subclass. This
+    # override is thus backwards and forwards compatible.
+    attr = "_use_auto_colorbar_locator"
+    if not hasattr(self, attr) or getattr(self, attr)():
+        if manual_only:
+            pass
+        else:
+            mcolorbar.Colorbar.update_ticks(self)  # AutoMinorLocator auto updates
+    else:
+        mcolorbar.Colorbar.update_ticks(self)  # update necessary
+        minorlocator = getattr(self, "minorlocator", None)
+        if minorlocator is None:
+            pass
+        elif hasattr(self, "_ticker"):
+            ticks, *_ = self._ticker(self.minorlocator, mticker.NullFormatter())
+            axis = self.ax.yaxis if self.orientation == "vertical" else self.ax.xaxis
+            axis.set_ticks(ticks, minor=True)
+            axis.set_ticklabels([], minor=True)
+        else:
+            warnings._warn_ultraplot(
+                f"Cannot use user-input colorbar minor locator {minorlocator!r} (older matplotlib version). Turning on minor ticks instead."
+            )  # noqa: E501
+            self.minorlocator = None
+            self.minorticks_on()  # at least turn them on
+
+
+class _InsetColorbar(martist.Artist):
+    """
+    Legend-like class for managing inset colorbars.
+    """
+
+    # TODO: Write this!
+
+
+class _CenteredLegend(martist.Artist):
+    """
+    Legend-like class for managing centered-row legends.
+    """
+
+    # TODO: Write this!