polytope-theme 0.1.4__py3-none-any.whl

polytope_theme/__init__.py

@@ -0,0 +1,107 @@
+"""Polytope for Python: palette data and chart/app themes.
+
+The palette data is generated from tokens/tokens.json by scripts/build.mjs and
+lives in ``_tokens.py``. This module re-exports it and adds small accessors.
+Library integrations live in submodules so that importing this package never
+imports matplotlib, plotly, gradio or streamlit:
+
+- ``polytope_theme.mpl``             matplotlib style, colormaps, direct labels
+- ``polytope_theme.plotly_theme``    plotly template
+- ``polytope_theme.gradio_theme``    gradio theme
+- ``polytope_theme.streamlit_theme`` streamlit config.toml
+
+Chart rules encoded here:
+
+- Categorical colors are assigned in fixed order and never cycled. At most 8
+  series; fold the rest into "Other" or split into small multiples.
+- Scatter plots and small multiples use only the first 3 slots.
+- Sequential data uses the cobalt ramp (SEQUENTIAL).
+- Diverging data runs cobalt -> gray midpoint -> tomato (DIVERGING).
+- STATUS colors are reserved for good/warning/serious/critical and must be
+  paired with a label or marker, never used as the only signal.
+"""
+
+from __future__ import annotations
+
+from ._tokens import CATEGORICAL, COLORS, DIVERGING, FONTS, SEQUENTIAL, STATUS, SURFACE
+
+__version__ = "0.1.4"
+
+__all__ = [
+    "CATEGORICAL",
+    "COLORS",
+    "DIVERGING",
+    "FONTS",
+    "MAX_SERIES",
+    "MODES",
+    "SCATTER_SLOTS",
+    "SEQUENTIAL",
+    "STATUS",
+    "SURFACE",
+    "__version__",
+    "categorical",
+    "colors",
+    "use",
+]
+
+MODES = ("light", "dark")
+
+# Number of categorical slots. Charts with more series must be restructured.
+MAX_SERIES = len(CATEGORICAL["names"])
+
+# Scatter plots and small multiples use only the first SCATTER_SLOTS colors.
+SCATTER_SLOTS = 3
+
+
+def _check_mode(mode: str) -> str:
+    if mode not in MODES:
+        raise ValueError(f"mode must be one of {MODES!r}, got {mode!r}")
+    return mode
+
+
+def colors(mode: str = "light") -> dict[str, str]:
+    """Return the semantic UI colors for ``mode`` as a new dict.
+
+    Keys match the token names, for example ``bg``, ``text``, ``text_muted``,
+    ``rule``, ``accent``, ``link`` and ``note``. Chart backgrounds use
+    ``SURFACE[mode]``, which differs from ``bg`` in dark mode.
+    """
+    return dict(COLORS[_check_mode(mode)])
+
+
+def categorical(mode: str = "light", n: int | None = None) -> list[str]:
+    """Return the first ``n`` categorical colors in their fixed order.
+
+    With ``n=None`` all 8 colors are returned. Colors are never cycled, so
+    asking for more than 8 raises ValueError.
+    """
+    palette = CATEGORICAL[_check_mode(mode)]
+    if n is None:
+        return list(palette)
+    if not isinstance(n, int) or isinstance(n, bool) or n < 0:
+        raise ValueError(f"n must be a non-negative integer or None, got {n!r}")
+    if n > MAX_SERIES:
+        raise ValueError(
+            f"categorical() supports at most {MAX_SERIES} series, got {n}. "
+            "Colors are not cycled. Fold the extra series into an \"Other\" "
+            "group, or split the chart into small multiples."
+        )
+    return list(palette[:n])
+
+
+def use(mode: str = "light") -> None:
+    """Apply the matplotlib style for ``mode`` and register the colormaps.
+
+    matplotlib is imported only when this function is called.
+    """
+    _check_mode(mode)
+    try:
+        import matplotlib  # noqa: F401
+    except ImportError as exc:
+        raise ImportError(
+            "polytope_theme.use() needs matplotlib. Install it with "
+            "pip install \"polytope-theme[matplotlib]\"."
+        ) from exc
+    from . import mpl
+
+    mpl.use(mode)

polytope_theme/_tokens.py

@@ -0,0 +1,127 @@
+"""Generated from tokens/tokens.json by scripts/build.mjs. Do not edit by hand."""
+
+COLORS = {
+    "light": {
+        "bg": "#FFFFFF",
+        "surface_sunken": "#EEF0EF",
+        "panel": "#141414",
+        "panel_text": "#F6F7F6",
+        "panel_muted": "#B9BAB4",
+        "panel_rule": "#4A4A47",
+        "text": "#141414",
+        "text_muted": "#4A4A47",
+        "text_subtle": "#6B6B66",
+        "rule_strong": "#141414",
+        "rule": "#D9DAD6",
+        "accent": "#D9412B",
+        "accent_text": "#B8321F",
+        "link": "#0F6E73",
+        "link_hover": "#141414",
+        "note": "#E9A81C",
+        "note_soft": "#FBEFD2",
+        "focus": "#0F6E73",
+        "focus_on_panel": "#F2B83A",
+        "selection": "#E9A81C",
+        "code_comment": "#F2B83A",
+        "code_keyword": "#F0654F",
+        "code_string": "#5CC2C7",
+        "code_number": "#95AEE3"
+    },
+    "dark": {
+        "bg": "#161615",
+        "surface_sunken": "#1C1C1A",
+        "panel": "#262624",
+        "panel_text": "#F6F7F6",
+        "panel_muted": "#B9BAB4",
+        "panel_rule": "#4A4A47",
+        "text": "#F2F2EE",
+        "text_muted": "#B9BAB4",
+        "text_subtle": "#8F8F89",
+        "rule_strong": "#F2F2EE",
+        "rule": "#3A3A37",
+        "accent": "#F0654F",
+        "accent_text": "#F0654F",
+        "link": "#5CC2C7",
+        "link_hover": "#F2F2EE",
+        "note": "#E9A81C",
+        "note_soft": "#3A2F14",
+        "focus": "#F2B83A",
+        "focus_on_panel": "#F2B83A",
+        "selection": "#E9A81C",
+        "code_comment": "#F2B83A",
+        "code_keyword": "#F0654F",
+        "code_string": "#5CC2C7",
+        "code_number": "#95AEE3"
+    }
+}
+
+CATEGORICAL = {
+    "light": [
+        "#D9412B",
+        "#009B93",
+        "#3A62C4",
+        "#4C8C2B",
+        "#2E8FD0",
+        "#C28A0A",
+        "#9A3E96",
+        "#E06C91"
+    ],
+    "dark": [
+        "#E04B34",
+        "#00A39A",
+        "#5A7FDB",
+        "#5A9A35",
+        "#2E8FD0",
+        "#B98200",
+        "#9A52C8",
+        "#D9658B"
+    ],
+    "names": [
+        "tomato",
+        "teal",
+        "cobalt",
+        "grass",
+        "sky",
+        "mustard",
+        "plum",
+        "pink"
+    ]
+}
+
+SEQUENTIAL = [
+    "#E3EAF8",
+    "#C2D1F0",
+    "#95AEE3",
+    "#6A8BD4",
+    "#3A62C4",
+    "#2B4A99",
+    "#1D336B"
+]
+
+DIVERGING = [
+    "#2B4A99",
+    "#6A8BD4",
+    "#C2D1F0",
+    "#D9DAD6",
+    "#F6C3B9",
+    "#E8765F",
+    "#B8321F"
+]
+
+STATUS = {
+    "good": "#1E7A3C",
+    "warning": "#F2B71F",
+    "serious": "#E8743B",
+    "critical": "#B3261E"
+}
+
+SURFACE = {
+    "light": "#FFFFFF",
+    "dark": "#1C1C1A"
+}
+
+FONTS = {
+    "display": "Ultra",
+    "text": "Libre Franklin",
+    "mono": "JetBrains Mono"
+}

polytope_theme/gradio_theme.py

@@ -0,0 +1,181 @@
+"""gradio integration: a theme with square corners and exhibit-black buttons.
+
+Usage (gradio 6 passes the theme to ``launch``; gradio 4 and 5 take it in
+``gr.Blocks(theme=...)``)::
+
+    import gradio as gr
+    from polytope_theme.gradio_theme import theme
+
+    with gr.Blocks() as demo:
+        ...
+    demo.launch(theme=theme())
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from ._tokens import CATEGORICAL, COLORS, FONTS
+
+__all__ = ["theme"]
+
+_MODES = ("light", "dark", "auto")
+_INK = "#141414"
+_WHITE = "#FFFFFF"
+
+
+def _require():
+    try:
+        import gradio as gr
+    except ImportError as exc:
+        raise ImportError(
+            "polytope_theme.gradio_theme needs gradio. Install it with "
+            "pip install \"polytope-theme[gradio]\"."
+        ) from exc
+    return gr
+
+
+def _mix(a: str, b: str, t: float) -> str:
+    """Blend hex color ``a`` toward ``b`` by fraction ``t``."""
+    ca = [int(a[i : i + 2], 16) for i in (1, 3, 5)]
+    cb = [int(b[i : i + 2], 16) for i in (1, 3, 5)]
+    return "#" + "".join(f"{round(x + (y - x) * t):02X}" for x, y in zip(ca, cb))
+
+
+def _ramp(base: str) -> list[str]:
+    """11-step c50..c950 scale around ``base`` (c500), tinted toward white and ink."""
+    lighter = [_mix(base, _WHITE, t) for t in (0.92, 0.84, 0.66, 0.46, 0.24)]
+    darker = [_mix(base, _INK, t) for t in (0.16, 0.32, 0.48, 0.62, 0.74)]
+    return lighter + [base] + darker
+
+
+# Warm gray scale taken straight from the token values.
+_NEUTRAL = [
+    COLORS["light"]["panel_text"],  # c50  #F6F7F6
+    COLORS["light"]["surface_sunken"],  # c100 #EEF0EF
+    COLORS["light"]["rule"],  # c200 #D9DAD6
+    COLORS["light"]["panel_muted"],  # c300 #B9BAB4
+    COLORS["dark"]["text_subtle"],  # c400 #8F8F89
+    COLORS["light"]["text_subtle"],  # c500 #6B6B66
+    COLORS["light"]["text_muted"],  # c600 #4A4A47
+    COLORS["dark"]["rule"],  # c700 #3A3A37
+    COLORS["dark"]["panel"],  # c800 #262624
+    COLORS["dark"]["surface_sunken"],  # c900 #1C1C1A
+    COLORS["light"]["text"],  # c950 #141414
+]
+
+
+def _variables(c: dict[str, str]) -> dict[str, str]:
+    """Theme variables for one mode, mirroring css/src/components/button.css and form.css."""
+    return {
+        "body_background_fill": c["bg"],
+        "body_text_color": c["text"],
+        "body_text_color_subdued": c["text_muted"],
+        "background_fill_primary": c["bg"],
+        "background_fill_secondary": c["surface_sunken"],
+        "border_color_primary": c["rule"],
+        "border_color_accent": c["accent"],
+        "border_color_accent_subdued": c["rule"],
+        "color_accent": c["accent"],
+        "color_accent_soft": c["note_soft"],
+        "link_text_color": c["link"],
+        "link_text_color_active": c["link"],
+        "link_text_color_hover": c["link_hover"],
+        "link_text_color_visited": c["link"],
+        "code_background_fill": c["surface_sunken"],
+        "panel_background_fill": c["surface_sunken"],
+        "block_background_fill": c["bg"],
+        "block_border_color": c["rule"],
+        "block_label_background_fill": c["bg"],
+        "block_label_text_color": c["text_muted"],
+        "block_title_text_color": c["text"],
+        "input_background_fill": c["bg"],
+        "input_background_fill_focus": c["bg"],
+        "input_border_color": c["rule_strong"],
+        "input_border_color_focus": c["focus"],
+        "checkbox_background_color_selected": c["text"],
+        "checkbox_border_color_selected": c["text"],
+        "slider_color": c["text"],
+        "loader_color": c["accent"],
+        "table_even_background_fill": c["bg"],
+        "table_odd_background_fill": c["surface_sunken"],
+        # Primary: exhibit black, tomato on hover, white label on hover.
+        "button_primary_background_fill": c["text"],
+        "button_primary_background_fill_hover": c["accent"],
+        "button_primary_border_color": c["text"],
+        "button_primary_border_color_hover": c["accent"],
+        "button_primary_text_color": c["bg"],
+        "button_primary_text_color_hover": _WHITE,
+        # Secondary: outlined, fills with ink on hover.
+        "button_secondary_background_fill": "transparent",
+        "button_secondary_background_fill_hover": c["text"],
+        "button_secondary_border_color": c["text"],
+        "button_secondary_border_color_hover": c["text"],
+        "button_secondary_text_color": c["text"],
+        "button_secondary_text_color_hover": c["bg"],
+    }
+
+
+# Mode-independent variables: no shadows, square corners, semibold labels.
+_FLAT = {
+    "shadow_drop": "none",
+    "shadow_drop_lg": "none",
+    "shadow_spread": "0px",
+    "block_shadow": "none",
+    "block_label_shadow": "none",
+    "input_shadow": "none",
+    "input_shadow_focus": "none",
+    "checkbox_shadow": "none",
+    "button_primary_shadow": "none",
+    "button_primary_shadow_hover": "none",
+    "button_primary_shadow_active": "none",
+    "button_secondary_shadow": "none",
+    "button_secondary_shadow_hover": "none",
+    "button_secondary_shadow_active": "none",
+    "block_title_text_weight": "600",
+    "button_large_text_weight": "600",
+    "button_medium_text_weight": "600",
+    "button_small_text_weight": "600",
+}
+
+
+def theme(mode: str = "light") -> Any:
+    """Return a ``gr.themes.Base`` configured for the design system.
+
+    ``mode`` picks which token set fills gradio's light and dark variables:
+
+    - "light": light tokens for both, so the app stays light.
+    - "dark":  dark tokens for both, so the app stays dark.
+    - "auto":  light tokens for light mode and dark tokens for dark mode,
+      following the browser or the ``?__theme=dark`` URL parameter.
+
+    Fonts load from Google Fonts. Ultra is reserved for display titles and is
+    not applied by the theme.
+    """
+    if mode not in _MODES:
+        raise ValueError(f"mode must be one of {_MODES!r}, got {mode!r}")
+    gr = _require()
+    themes = gr.themes
+
+    light = COLORS["dark" if mode == "dark" else "light"]
+    dark = COLORS["light" if mode == "light" else "dark"]
+
+    base = themes.Base(
+        primary_hue=themes.Color(*_ramp(CATEGORICAL["light"][0]), name="dl_tomato"),
+        secondary_hue=themes.Color(*_ramp(CATEGORICAL["light"][1]), name="dl_teal"),
+        neutral_hue=themes.Color(*_NEUTRAL, name="dl_gray"),
+        radius_size=themes.sizes.radius_none,
+        font=[themes.GoogleFont(FONTS["text"], weights=(400, 600, 700)), "Franklin Gothic Medium", "Helvetica Neue", "Arial", "sans-serif"],
+        font_mono=[themes.GoogleFont(FONTS["mono"], weights=(400, 700)), "ui-monospace", "Menlo", "monospace"],
+    )
+
+    values: dict[str, str] = dict(_FLAT)
+    for key, value in _variables(light).items():
+        values[key] = value
+    for key, value in _variables(dark).items():
+        values[f"{key}_dark"] = value
+
+    # Variable names shift between gradio releases; drop any this version lacks.
+    accepted = inspect.signature(base.set).parameters
+    return base.set(**{k: v for k, v in values.items() if k in accepted})

polytope_theme/mpl.py

@@ -0,0 +1,275 @@
+"""matplotlib integration: style files, colormaps and direct line labels.
+
+The module is named ``mpl`` so that it does not shadow ``matplotlib`` itself.
+Importing it registers the colormaps ``ply-sequential`` and ``ply-diverging``
+(plus their ``_r`` reversals) when matplotlib is installed. ``style_path()``
+works without matplotlib.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterable, Sequence
+
+from ._tokens import DIVERGING, SEQUENTIAL
+
+try:
+    import matplotlib as _matplotlib
+    from matplotlib.colors import LinearSegmentedColormap
+except ImportError:  # matplotlib is an optional extra
+    _matplotlib = None
+    LinearSegmentedColormap = None
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.text import Annotation
+
+__all__ = [
+    "DIVERGING_NAME",
+    "SEQUENTIAL_NAME",
+    "diverging_cmap",
+    "label_lines",
+    "rc_params",
+    "register_cmaps",
+    "sequential_cmap",
+    "style_path",
+    "use",
+]
+
+SEQUENTIAL_NAME = "ply-sequential"
+DIVERGING_NAME = "ply-diverging"
+
+_STYLE_DIR = Path(__file__).resolve().parent / "styles"
+_MODES = ("light", "dark")
+_HEX_VALUE = re.compile(r"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?(\s|$)")
+
+
+def _require() -> None:
+    if _matplotlib is None:
+        raise ImportError(
+            "This function needs matplotlib. Install it with "
+            "pip install \"polytope-theme[matplotlib]\"."
+        )
+
+
+def style_path(mode: str = "light") -> Path:
+    """Return the path of the generated .mplstyle file for ``mode``.
+
+    Prefer ``use(mode)`` or ``rc_params(mode)``: they read "#RRGGBB" colors
+    that ``plt.style.use(path)`` skips when the file writes them unquoted.
+    """
+    if mode not in _MODES:
+        raise ValueError(f"mode must be one of {_MODES!r}, got {mode!r}")
+    return _STYLE_DIR / f"polytope-{mode}.mplstyle"
+
+
+def sequential_cmap(name: str = SEQUENTIAL_NAME, n: int = 256) -> "LinearSegmentedColormap":
+    """Cobalt ramp from light to dark, built from the SEQUENTIAL tokens."""
+    _require()
+    return LinearSegmentedColormap.from_list(name, SEQUENTIAL, N=n)
+
+
+def diverging_cmap(name: str = DIVERGING_NAME, n: int = 256) -> "LinearSegmentedColormap":
+    """Cobalt -> gray midpoint -> tomato, built from the DIVERGING tokens.
+
+    Center the data on the midpoint, for example with
+    ``matplotlib.colors.TwoSlopeNorm(vcenter=0)`` or symmetric vmin/vmax.
+    """
+    _require()
+    return LinearSegmentedColormap.from_list(name, DIVERGING, N=n)
+
+
+def register_cmaps(force: bool = False) -> None:
+    """Register ply-sequential, ply-diverging and their _r reversals.
+
+    Names already present are left alone unless ``force`` is true.
+    """
+    _require()
+    for cmap in (sequential_cmap(), diverging_cmap()):
+        for item in (cmap, cmap.reversed()):
+            if force or item.name not in _matplotlib.colormaps:
+                _matplotlib.colormaps.register(item, name=item.name, force=force)
+
+
+def rc_params(mode: str = "light") -> dict[str, str]:
+    """Return the style for ``mode`` as a dict of rcParams values (strings).
+
+    The generated .mplstyle file stores colors as bare hex (``FFFFFF``) because
+    matplotlib's rc parser treats an unquoted "#" as a comment. This returns them
+    as ``#RRGGBB``. The dict works with ``matplotlib.style.use`` and
+    ``matplotlib.rc_context``.
+    """
+    params: dict[str, str] = {}
+    for raw in style_path(mode).read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or ":" not in line:
+            continue
+        key, value = (part.strip() for part in line.split(":", 1))
+        if _HEX_VALUE.match(value):
+            value = value.split()[0]
+        else:
+            value = value.split(" #", 1)[0].strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        if re.fullmatch(r"[0-9A-Fa-f]{6}", value):
+            value = "#" + value
+        params[key] = value
+    return params
+
+
+def use(mode: str = "light") -> None:
+    """Apply the style for ``mode`` and make ply-sequential the default image cmap."""
+    _require()
+    import matplotlib.style
+
+    matplotlib.style.use(rc_params(mode))
+    register_cmaps()
+    _matplotlib.rcParams["image.cmap"] = SEQUENTIAL_NAME
+
+
+def _line_end(line: Any) -> tuple[float, float] | None:
+    """Return the finite data point with the largest x, or None."""
+    xs = line.get_xdata(orig=False)
+    ys = line.get_ydata(orig=False)
+    best = None
+    for x, y in zip(xs, ys):
+        try:
+            fx, fy = float(x), float(y)
+        except (TypeError, ValueError):
+            continue
+        if not (math.isfinite(fx) and math.isfinite(fy)):
+            continue
+        if best is None or fx >= best[0]:
+            best = (fx, fy)
+    return best
+
+
+def _spread(positions: Sequence[float], gap: float) -> list[float]:
+    """Move 1-D positions apart so neighbours are at least ``gap`` apart.
+
+    Colliding labels are grouped and each group is centred on the mean of its
+    members, so a label only moves when it overlaps another one.
+    """
+    order = sorted(range(len(positions)), key=lambda i: positions[i])
+    groups: list[tuple[list[int], float]] = []  # (members, first position)
+    for idx in order:
+        groups.append(([idx], positions[idx]))
+        while len(groups) > 1:
+            (prev, prev_start), (cur, cur_start) = groups[-2], groups[-1]
+            if cur_start - (prev_start + gap * (len(prev) - 1)) >= gap:
+                break
+            members = prev + cur
+            mean = sum(positions[i] for i in members) / len(members)
+            groups[-2:] = [(members, mean - gap * (len(members) - 1) / 2)]
+    out = [0.0] * len(positions)
+    for members, first in groups:
+        for k, idx in enumerate(members):
+            out[idx] = first + k * gap
+    return out
+
+
+def label_lines(
+    ax: "Axes",
+    labels: Iterable[str] | None = None,
+    *,
+    offset: float = 6.0,
+    color: str | None = None,
+    fontsize: float | str | None = None,
+    min_gap: float | None = None,
+    leader: bool = True,
+    remove_legend: bool = False,
+) -> list["Annotation"]:
+    """Direct-label each line at its right end, in the text color.
+
+    Labels use ``rcParams["text.color"]`` (or ``color``) and never the series
+    color, so the line itself carries the hue and the label stays readable.
+    Call it after plotting and after setting axis limits. Overlapping labels
+    are spread vertically, and a label moved away from its line gets a thin
+    leader line back to the line end.
+
+    Parameters
+    ----------
+    ax:
+        Axes holding the lines.
+    labels:
+        Optional labels in line order. Defaults to each line's own label;
+        lines whose label starts with "_" are skipped.
+    offset:
+        Horizontal distance from the line end, in points.
+    color:
+        Label color. Defaults to the style's text color.
+    fontsize:
+        Label size. Defaults to ``rcParams["legend.fontsize"]``.
+    min_gap:
+        Minimum vertical distance between labels, in points. Defaults to
+        1.2 times the font size.
+    leader:
+        Draw a leader line for labels moved more than a third of the font size.
+    remove_legend:
+        Remove an existing legend. Off by default: with two or more series a
+        legend stays as the primary key and the labels supplement it.
+    """
+    _require()
+    from matplotlib.font_manager import FontProperties
+
+    rc = _matplotlib.rcParams
+    color = color or rc["text.color"]
+    fontsize = fontsize if fontsize is not None else rc["legend.fontsize"]
+    size_pt = FontProperties(size=fontsize).get_size_in_points()
+    gap_pt = min_gap if min_gap is not None else 1.2 * size_pt
+
+    lines = ax.get_lines()
+    if labels is None:
+        items = [(ln, ln.get_label()) for ln in lines if not str(ln.get_label()).startswith("_")]
+    else:
+        items = list(zip(lines, labels))
+
+    ends = []
+    for line, text in items:
+        end = _line_end(line)
+        if end is not None:
+            ends.append((line, str(text), end))
+    if not ends:
+        return []
+
+    fig = ax.figure
+    points_per_px = 72.0 / fig.dpi
+    to_px = ax.transData.transform
+    y_pt = [to_px(end)[1] * points_per_px for _, _, end in ends]
+    new_y_pt = _spread(y_pt, gap_pt)
+
+    out = []
+    for (line, text, end), y0, y1 in zip(ends, y_pt, new_y_pt):
+        moved = abs(y1 - y0) > size_pt / 3
+        arrowprops = None
+        if leader and moved:
+            arrowprops = dict(
+                arrowstyle="-",
+                color=rc["axes.edgecolor"],
+                linewidth=0.8,
+                shrinkA=1,
+                shrinkB=2,
+            )
+        ann = ax.annotate(
+            text,
+            xy=end,
+            xytext=(offset * (2 if arrowprops else 1), y1 - y0),
+            textcoords="offset points",
+            ha="left",
+            va="center",
+            color=color,
+            fontsize=fontsize,
+            annotation_clip=False,
+            arrowprops=arrowprops,
+        )
+        out.append(ann)
+
+    if remove_legend and ax.get_legend() is not None:
+        ax.get_legend().remove()
+    return out
+
+
+if _matplotlib is not None:
+    register_cmaps()