flextool 4.0.0__py3-none-any.whl

flextool/gui/output_log_window.py

@@ -0,0 +1,159 @@
+"""Non-modal log window for output action subprocesses."""
+
+from __future__ import annotations
+
+import subprocess
+import tkinter as tk
+import tkinter.font as tkfont
+from tkinter import ttk
+from typing import Callable
+
+
+class OutputLogWindow(tk.Toplevel):
+    """Non-modal window that displays the command and live stdout of a subprocess.
+
+    The window stays open after the process finishes so the user can
+    review the output.  Two buttons are provided:
+
+    * **Close** -- closes the window without stopping the process.
+    * **Stop and close** -- kills the process and closes the window.
+    """
+
+    def __init__(
+        self, parent: tk.Misc, title: str, on_abort: Callable[[], None] | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self.title(title)
+        self.transient(parent)
+
+        self._process: subprocess.Popen | None = None
+        self._on_abort = on_abort
+        self._aborted = False
+
+        # ── Font metrics ─────────────────────────────────────────
+        mono_font = tkfont.nametofont("TkFixedFont")
+        default_font = tkfont.nametofont("TkDefaultFont")
+        cw = default_font.measure("0")
+        lh = default_font.metrics("linespace")
+
+        # ── Window sizing ────────────────────────────────────────
+        screen_w = self.winfo_screenwidth()
+        screen_h = self.winfo_screenheight()
+        taskbar_margin = lh * 4
+        win_h = screen_h - taskbar_margin
+        win_w = 1800
+        x = max(0, screen_w - win_w)
+        self.geometry(f"{win_w}x{win_h}+{x}+0")
+        self.minsize(cw * 50, lh * 10)
+
+        self.columnconfigure(0, weight=1)
+        self.rowconfigure(0, weight=1)
+
+        # ── Text widget ─────────────────────────────────────────
+        text_frame = ttk.Frame(self)
+        text_frame.grid(row=0, column=0, sticky="nsew", padx=8, pady=(8, 4))
+        text_frame.columnconfigure(0, weight=1)
+        text_frame.rowconfigure(0, weight=1)
+
+        self._text = tk.Text(text_frame, wrap="word", font=mono_font)
+        self._text.grid(row=0, column=0, sticky="nsew")
+        self._text.bind("<Key>", self._on_key_press)
+
+        vscroll = ttk.Scrollbar(text_frame, orient="vertical", command=self._text.yview)
+        self._text.configure(yscrollcommand=vscroll.set)
+        vscroll.grid(row=0, column=1, sticky="ns")
+
+        # ── Buttons ──────────────────────────────────────────────
+        btn_frame = ttk.Frame(self, padding=(8, 4, 8, 8))
+        btn_frame.grid(row=1, column=0, sticky="ew")
+
+        if on_abort is not None:
+            self._stop_close_btn = ttk.Button(
+                btn_frame, text="Abort", command=self._on_abort_clicked,
+            )
+        else:
+            self._stop_close_btn = ttk.Button(
+                btn_frame, text="Stop and close", command=self._on_stop_and_close,
+            )
+        self._stop_close_btn.pack(side="left", padx=(0, 10))
+
+        self._close_btn = ttk.Button(
+            btn_frame, text="Close", command=self._on_close,
+        )
+        self._close_btn.pack(side="right")
+
+        if on_abort is not None:
+            self.protocol("WM_DELETE_WINDOW", self._on_abort_clicked)
+        else:
+            self.protocol("WM_DELETE_WINDOW", self._on_close)
+
+    # ── Public API ───────────────────────────────────────────────
+
+    def set_process(self, proc: subprocess.Popen) -> None:
+        """Register the subprocess so Stop can kill it."""
+        self._process = proc
+
+    def append_line(self, line: str) -> None:
+        """Append a line of text. Must be called from the main thread."""
+        if not self.winfo_exists():
+            return
+        at_bottom = self._text.yview()[1] >= 0.99
+        self._text.insert("end", line + "\n")
+        if at_bottom:
+            self._text.see("end")
+
+    def mark_finished(self, success: bool) -> None:
+        """Mark the process as finished — update button states."""
+        if not self.winfo_exists():
+            return
+        self._process = None
+        self._stop_close_btn.configure(state="disabled")
+
+    @property
+    def is_aborted(self) -> bool:
+        """Whether the user clicked Abort."""
+        return self._aborted
+
+    def minimize(self) -> None:
+        """Minimize the window to the taskbar.
+
+        Transient windows cannot be iconified, so we first remove the
+        transient binding, then iconify normally.
+        """
+        self.transient('')  # remove transient parent → gets own taskbar entry
+        self.iconify()
+
+    # ── Event handlers ───────────────────────────────────────────
+
+    def _on_key_press(self, event: tk.Event) -> str | None:  # type: ignore[type-arg]
+        """Allow Ctrl+C/A but block other input."""
+        if event.state & 0x4 and event.keysym in ("c", "C", "a", "A"):
+            return None
+        return "break"
+
+    def _on_close(self) -> None:
+        """Close the window without stopping the process."""
+        self.destroy()
+
+    def _on_abort_clicked(self) -> None:
+        """Kill the process, signal abort, and close the window."""
+        if self._process is not None:
+            try:
+                self._process.kill()
+            except OSError:
+                pass
+            self._process = None
+        self._aborted = True
+        if self._on_abort is not None:
+            self._on_abort()
+        self.destroy()
+
+    def _on_stop_and_close(self) -> None:
+        """Kill the process and close the window."""
+        if self._process is not None:
+            try:
+                self._process.kill()
+            except OSError:
+                pass
+            self._process = None
+        self.destroy()

flextool/gui/platform_utils.py

@@ -0,0 +1,421 @@
+"""Cross-platform helper functions for opening files and launching external tools."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import tkinter as tk
+
+logger = logging.getLogger(__name__)
+
+
+def _clean_env() -> dict[str, str]:
+    """Return a copy of os.environ without Python virtualenv variables.
+
+    LibreOffice and other desktop apps bundle their own Python and crash
+    (std::bad_alloc) if they inherit PYTHONPATH/VIRTUAL_ENV from the
+    parent process.  This only affects the child process — the current
+    Python process keeps its full environment.
+    """
+    env = {
+        k: v for k, v in os.environ.items()
+        if k not in ("PYTHONPATH", "VIRTUAL_ENV", "VIRTUAL_ENV_DISABLE_PROMPT",
+                     "PYTHONHOME", "CONDA_PREFIX", "CONDA_DEFAULT_ENV")
+    }
+    if "VIRTUAL_ENV" in os.environ:
+        venv_bin = os.path.join(os.environ["VIRTUAL_ENV"], "bin")
+        env["PATH"] = os.pathsep.join(
+            p for p in os.environ.get("PATH", "").split(os.pathsep)
+            if p != venv_bin
+        )
+    return env
+
+
+def open_file_in_default_app(filepath: Path) -> None:
+    """Open a file using the OS default application.
+
+    Windows: os.startfile
+    macOS: subprocess.Popen(['open', str(filepath)])
+    Linux: subprocess.Popen(['xdg-open', str(filepath)])
+
+    Raises:
+        OSError: If the file does not exist or the platform command fails.
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise OSError(f"File does not exist: {filepath}")
+
+    if sys.platform == "win32":
+        os.startfile(str(filepath))  # type: ignore[attr-defined]
+    elif sys.platform == "darwin":
+        subprocess.Popen(["open", str(filepath)])
+    else:
+        subprocess.Popen(
+            ["xdg-open", str(filepath)],
+            start_new_session=True,
+            env=_clean_env(),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+
+def open_folder(dirpath: Path) -> None:
+    """Open a folder in the OS file manager.
+
+    Windows: os.startfile
+    macOS: subprocess.Popen(['open', str(dirpath)])
+    Linux: subprocess.Popen(['xdg-open', str(dirpath)])
+
+    Raises:
+        OSError: If the directory does not exist.
+    """
+    dirpath = Path(dirpath)
+    if not dirpath.is_dir():
+        raise OSError(f"Directory does not exist: {dirpath}")
+
+    if sys.platform == "win32":
+        os.startfile(str(dirpath))  # type: ignore[attr-defined]
+    elif sys.platform == "darwin":
+        subprocess.Popen(["open", str(dirpath)])
+    else:
+        subprocess.Popen(
+            ["xdg-open", str(dirpath)],
+            start_new_session=True,
+            env=_clean_env(),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+
+def open_spine_db_editor(db_url: str) -> subprocess.Popen | None:
+    """Launch spine-db-editor as a subprocess.
+
+    Command: ``spine-db-editor <db_url>``
+
+    Returns:
+        The :class:`subprocess.Popen` object, or ``None`` if
+        ``spine-db-editor`` is not found on the system PATH.
+    """
+    exe = shutil.which("spine-db-editor")
+    if exe is None:
+        logger.warning("spine-db-editor not found on PATH")
+        return None
+
+    try:
+        proc = subprocess.Popen([exe, db_url])
+        return proc
+    except OSError:
+        logger.warning("Failed to launch spine-db-editor", exc_info=True)
+        return None
+
+
+def set_process_dpi_awareness() -> None:
+    """Mark the process DPI-aware on Windows, before the first Tk window.
+
+    MUST be called **before** the Tk root (HWND) exists — Windows only
+    honours ``SetProcessDpiAwareness`` while the process owns no windows.
+    Called afterwards it is a silent no-op, leaving the process DPI-
+    *unaware*: the OS then hands Tk a virtualized, bitmap-upscaled (blurry)
+    screen and lies about its size. Setting awareness here makes Tk render
+    at native pixels and report the true DPI, which ``apply_dpi_scaling``
+    then converts into the matching ``tk scaling``. No-op off Windows
+    (macOS handles Retina internally; Linux scales via ``tk scaling``).
+    """
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+        # 1 = PROCESS_SYSTEM_DPI_AWARE.
+        ctypes.windll.shcore.SetProcessDpiAwareness(1)  # type: ignore[attr-defined]
+    except Exception:
+        pass
+
+
+def apply_dpi_scaling(root: tk.Tk) -> float:
+    """Detect the OS display scale factor and apply it to tkinter.
+
+    Must be called **before** any widgets or themes are created so that
+    default fonts (and everything derived from them) pick up the correct
+    size.
+
+    Resolution order:
+
+    1. ``FLEXTOOL_DPI`` environment variable — explicit user override
+       (e.g. ``FLEXTOOL_DPI=144``) for setups where auto-detection fails.
+    2. On Windows, ``ctypes`` queries the system DPI directly (the process
+       must already be DPI-aware via :func:`set_process_dpi_awareness`,
+       called before the Tk root existed) and sets ``tk scaling`` to
+       ``dpi / 72`` so fonts match the OS scale.
+    3. On Linux/X11, ``Xft.dpi`` (set by GNOME/KDE/Xfce) is the most
+       reliable hint, followed by ``GDK_SCALE`` and finally an
+       ``xrandr``-derived DPI.  The xrandr fallback uses the monitor
+       under the cursor at startup (which is where the WM will open
+       the window on every desktop I've tested), and falls back to
+       the primary monitor when the cursor's monitor reports a clearly
+       bogus physical size (e.g. virtual / mirrored displays often
+       report 0mm or copy a real monitor's dimensions verbatim).
+    4. On macOS, Tk handles Retina internally — nothing to do.
+
+    Once-at-startup is intentional.  ``tk scaling`` doesn't re-flow
+    widgets that are already laid out, so changing it mid-session
+    would only partially update the UI.
+
+    A best-effort per-monitor handler in :class:`MainWindow` reapplies
+    ``setup_fonts`` when ``winfo_fpixels('1i')`` swings by more than 10 %,
+    so text rescales on monitor changes; widget positions still need a
+    restart to fully re-flow.
+
+    Returns:
+        The ratio by which tk scaling was increased (1.0 means no change).
+        Use this to rescale theme fonts that use hardcoded pixel sizes.
+    """
+    if sys.platform == "darwin":
+        return 1.0
+
+    dpi: float | None = None
+
+    # Explicit override always wins.
+    flextool_dpi = os.environ.get("FLEXTOOL_DPI")
+    if flextool_dpi:
+        try:
+            dpi = float(flextool_dpi)
+        except ValueError:
+            pass
+
+    if dpi is None and sys.platform == "win32":
+        # Awareness is set earlier (set_process_dpi_awareness, before the Tk
+        # root existed); here we only read the now-truthful system DPI.
+        try:
+            import ctypes
+            dpi = ctypes.windll.user32.GetDpiForSystem()  # type: ignore[attr-defined]
+        except Exception:
+            pass
+    elif dpi is None:
+        # Linux / X11: try xrdb for Xft.dpi (set by GNOME, KDE, Xfce)
+        try:
+            out = subprocess.check_output(
+                ["xrdb", "-query"], text=True, timeout=2, stderr=subprocess.DEVNULL,
+            )
+            for line in out.splitlines():
+                if line.startswith("Xft.dpi:"):
+                    dpi = float(line.split(":", 1)[1].strip())
+                    break
+        except Exception:
+            pass
+        # Fallback: GDK_SCALE environment variable (integer scale factor)
+        if dpi is None:
+            gdk_scale = os.environ.get("GDK_SCALE")
+            if gdk_scale:
+                try:
+                    dpi = 96.0 * float(gdk_scale)
+                except ValueError:
+                    pass
+        # Last resort: ask xrandr which monitor the cursor is on and
+        # use that monitor's DPI.  Falls through to primary if the
+        # cursor's monitor is suspect (mirrored / virtual / headless).
+        if dpi is None:
+            try:
+                cursor_x, cursor_y = root.winfo_pointerxy()
+            except Exception:
+                cursor_x, cursor_y = (None, None)
+            dpi = _xrandr_dpi_for_window(cursor_x, cursor_y)
+
+    if dpi is not None and dpi > 0:
+        current_scaling = float(root.tk.call("tk", "scaling"))
+        if sys.platform == "win32":
+            # Pin ``tk scaling`` to the documented pixels-per-point for the
+            # real DPI. When the process is DPI-aware Tk usually pre-sets
+            # this to the same value already (so the call is a harmless
+            # no-op); when it doesn't (or ``FLEXTOOL_DPI`` overrides), this
+            # is what makes point-sized fonts track the OS scale instead of
+            # rendering tiny. Either way the result is deterministic, not
+            # dependent on Tk's startup guess.
+            #
+            # The factor we RETURN is NOT ``new/current``: on a DPI-aware
+            # box ``current`` already equals ``new`` (Tk read the true DPI),
+            # so that ratio collapses to ~1.0 and ``scale_theme_fonts`` would
+            # never touch sv_ttk's pixel-sized fonts — they'd stay frozen at
+            # their 96-DPI baseline while every point font doubled (tiny body
+            # text + huge headings on hi-DPI). Return the *absolute* factor
+            # that lifts those 96-DPI-baseline pixel fonts to the current DPI
+            # (``dpi/96``), so the pixel and point worlds scale together.
+            new_scaling = dpi / 72.0
+            root.tk.call("tk", "scaling", new_scaling)
+            return new_scaling / (96.0 / 72.0)
+        # Linux/X11: desktop apps treat 96 DPI as "scale = 1.0", and a
+        # 0.85 fudge keeps sv_ttk's heavier metrics in line with
+        # surrounding Qt/GTK content. Only raise scaling, never shrink it
+        # below tk's default on systems that already got it right.
+        new_scaling = (dpi / 96.0) * 0.85
+        if new_scaling > current_scaling:
+            root.tk.call("tk", "scaling", new_scaling)
+            return new_scaling / current_scaling
+    return 1.0
+
+
+def log_dpi_diagnostics(root: tk.Tk) -> None:
+    """Log ground-truth DPI / font-scaling values for support diagnosis.
+
+    Call this once at startup AFTER the theme and fonts are configured (so
+    the theme's own fonts exist). Emitted at WARNING so the single line lands
+    in ``flextool_gui.log`` regardless of the configured level.
+
+    The point is to stop guessing: it reveals the real display DPI, whether
+    the process is genuinely DPI-aware, the effective ``tk scaling``, and —
+    crucially — that the sv_ttk theme paints widgets with PIXEL-sized fonts
+    (negative ``size``) that ``tk scaling`` cannot affect. That distinguishes
+    a 100%-scale no-op from a silent DPI-awareness failure in one run.
+    """
+    import tkinter.font as tkfont
+    parts: list[str] = []
+
+    if sys.platform == "win32":
+        try:
+            import ctypes
+            try:
+                aw = ctypes.c_int(-1)
+                ctypes.windll.shcore.GetProcessDpiAwareness(  # type: ignore[attr-defined]
+                    None, ctypes.byref(aw),
+                )
+                awareness = aw.value  # 0=unaware 1=system 2=per-monitor
+            except Exception:
+                awareness = -1
+            try:
+                sysdpi: object = ctypes.windll.user32.GetDpiForSystem()  # type: ignore[attr-defined]
+            except Exception:
+                sysdpi = "err"
+            parts.append(f"awareness={awareness}(0=unaware,1=system,2=permon)")
+            parts.append(f"GetDpiForSystem={sysdpi}")
+        except Exception:
+            parts.append("win_dpi=err")
+
+    for label, getter in (
+        ("tk_scaling", lambda: f"{float(root.tk.call('tk', 'scaling')):.4f}"),
+        ("fpixels_1i", lambda: f"{float(root.winfo_fpixels('1i')):.1f}"),
+        ("screen", lambda: f"{root.winfo_screenwidth()}x{root.winfo_screenheight()}"),
+    ):
+        try:
+            parts.append(f"{label}={getter()}")
+        except Exception:
+            pass
+
+    for name in ("TkDefaultFont", "TkHeadingFont", "TkFixedFont"):
+        try:
+            sz = tkfont.nametofont(name).cget("size")
+            parts.append(f"{name}={sz}{'pt' if sz > 0 else 'px'}")
+        except Exception:
+            pass
+    try:
+        sv = tkfont.Font(root=root, name="SunValleyBodyFont", exists=True)
+        parts.append(f"SunValleyBodyFont={sv.cget('size')}px(scaling-immune)")
+    except Exception:
+        parts.append("SunValleyBodyFont=absent")
+
+    parts.append(f"FLEXTOOL_DPI={os.environ.get('FLEXTOOL_DPI', '<auto>')}")
+    logger.warning("DPI-DIAG: %s", " ".join(parts))
+
+
+def _xrandr_monitors() -> list[dict]:
+    """Parse all connected monitors from xrandr.
+
+    Returns a list of dicts with keys: name, primary, x, y, w, h,
+    mm_w, mm_h, dpi.  Empty list if xrandr is unavailable.
+    """
+    import re
+    try:
+        out = subprocess.check_output(
+            ["xrandr"], text=True, timeout=2, stderr=subprocess.DEVNULL,
+        )
+    except Exception:
+        return []
+    monitors: list[dict] = []
+    # Match e.g. "DP-0 connected primary 3840x2160+1920+0 ... 700mm x 390mm"
+    pattern = re.compile(
+        r"^(\S+)\s+connected\s+(primary\s+)?(\d+)x(\d+)\+(\d+)\+(\d+)"
+        r".*?(\d+)mm\s+x\s+(\d+)mm",
+    )
+    for line in out.splitlines():
+        m = pattern.match(line)
+        if not m:
+            continue
+        name = m.group(1)
+        primary = bool(m.group(2))
+        w, h, x, y = int(m.group(3)), int(m.group(4)), int(m.group(5)), int(m.group(6))
+        mm_w, mm_h = int(m.group(7)), int(m.group(8))
+        dpi = (w / mm_w) * 25.4 if mm_w > 0 else 0.0
+        monitors.append({
+            "name": name, "primary": primary,
+            "x": x, "y": y, "w": w, "h": h,
+            "mm_w": mm_w, "mm_h": mm_h, "dpi": dpi,
+        })
+    return monitors
+
+
+def _xrandr_dpi_for_window(x: int | None, y: int | None) -> float | None:
+    """DPI for the monitor at (x, y); falls back to primary when sensible.
+
+    A monitor is "suspect" when its physical-size readings are 0
+    (virtual / mirrored / headless) or when its derived DPI is < 80
+    (impossibly low — typically a virtual buffer claiming a real
+    monitor's mm dimensions but at a fraction of the resolution).
+    Suspect monitors are skipped in favour of the primary or the
+    highest-DPI real monitor.
+    """
+    monitors = _xrandr_monitors()
+    if not monitors:
+        return None
+
+    def is_real(m: dict) -> bool:
+        return m["mm_w"] > 0 and m["dpi"] >= 80.0
+
+    chosen = None
+    if x is not None and y is not None:
+        for m in monitors:
+            if (m["x"] <= x < m["x"] + m["w"]
+                    and m["y"] <= y < m["y"] + m["h"]):
+                chosen = m
+                break
+    if chosen is not None and is_real(chosen):
+        return chosen["dpi"]
+
+    primary = next((m for m in monitors if m["primary"]), None)
+    if primary is not None and is_real(primary):
+        return primary["dpi"]
+
+    real = [m for m in monitors if is_real(m)]
+    if real:
+        # Pick the highest-DPI real monitor as the safest default —
+        # users on hi-DPI displays would rather have slightly oversized
+        # widgets than unreadable ones.
+        return max(real, key=lambda m: m["dpi"])["dpi"]
+
+    return None
+
+
+def scale_theme_fonts(root: tk.Tk, factor: float) -> None:
+    """Rescale hardcoded theme fonts (e.g. sv_ttk's SunValley* fonts).
+
+    sv_ttk defines its own fonts with absolute pixel sizes that do not
+    respond to ``tk scaling``.  This function finds all ``SunValley*``
+    fonts and multiplies their size by *factor*.
+
+    Must be called **after** ``sv_ttk.set_theme()`` (which creates the
+    fonts).
+    """
+    if factor <= 1.0:
+        return
+    import tkinter.font as tkfont
+
+    for name in tkfont.names(root):
+        if name.startswith("SunValley"):
+            font = tkfont.Font(root=root, name=name, exists=True)
+            current_size = font.cget("size")
+            # Negative size = pixels, positive = points; scale either way
+            font.configure(size=round(current_size * factor))

flextool/gui/plot_cache.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+
+
+def _figure_size_bytes(fig: Figure) -> int:
+    """Estimate memory usage of a matplotlib Figure in bytes."""
+    try:
+        renderer = fig.canvas.get_renderer()
+        # Rendered bitmap size: width * height * 4 (RGBA)
+        w, h = int(renderer.width), int(renderer.height)
+        return w * h * 4
+    except Exception:
+        pass
+    # Fallback: estimate from figure size in inches * dpi
+    dpi = fig.get_dpi() or 100
+    w_in, h_in = fig.get_size_inches()
+    return int(w_in * dpi) * int(h_in * dpi) * 4
+
+
+class PlotCache:
+    """Memory-bounded LRU cache for matplotlib Figure objects.
+
+    *max_bytes* sets the memory limit (default 0.5 GB).  Figures are
+    evicted oldest-first when the total estimated memory exceeds the
+    limit.
+    """
+
+    def __init__(self, max_bytes: int = 512 * 1024 * 1024):
+        self._max_bytes = max_bytes
+        self._cache: OrderedDict[tuple, Figure] = OrderedDict()
+        self._sizes: dict[tuple, int] = {}
+        self._total_bytes: int = 0
+
+    @property
+    def max_gb(self) -> float:
+        """Current limit in GB."""
+        return self._max_bytes / (1024 ** 3)
+
+    @max_gb.setter
+    def max_gb(self, value: float) -> None:
+        """Set limit in GB and evict if necessary."""
+        self._max_bytes = int(value * 1024 ** 3)
+        self._evict_to_limit()
+
+    def get(self, key: tuple) -> Figure | None:
+        if key in self._cache:
+            self._cache.move_to_end(key)
+            return self._cache[key]
+        return None
+
+    def put(self, key: tuple, fig: Figure) -> None:
+        fig_bytes = _figure_size_bytes(fig)
+
+        if key in self._cache:
+            # Update existing entry
+            old_bytes = self._sizes.get(key, 0)
+            self._total_bytes -= old_bytes
+            self._cache.move_to_end(key)
+            self._cache[key] = fig
+            self._sizes[key] = fig_bytes
+            self._total_bytes += fig_bytes
+        else:
+            self._cache[key] = fig
+            self._sizes[key] = fig_bytes
+            self._total_bytes += fig_bytes
+
+        self._evict_to_limit()
+
+    def _evict_to_limit(self) -> None:
+        """Evict oldest entries until total size is within the limit."""
+        while self._total_bytes > self._max_bytes and self._cache:
+            evicted_key, evicted_fig = self._cache.popitem(last=False)
+            evicted_bytes = self._sizes.pop(evicted_key, 0)
+            self._total_bytes -= evicted_bytes
+            evicted_fig.clf()
+            plt.close(evicted_fig)
+
+    def clear(self) -> None:
+        for fig in self._cache.values():
+            fig.clf()
+            plt.close(fig)
+        self._cache.clear()
+        self._sizes.clear()
+        self._total_bytes = 0