bootstack 0.1.0__py3-none-any.whl

bootstack/_core/images.py

@@ -0,0 +1,463 @@
+"""Image loading and caching utilities for bootstack.
+
+This module provides a unified image service for loading, caching, and managing
+Tk-compatible PhotoImage objects. It uses Pillow as the backend to support a wide
+variety of image formats beyond what Tk natively supports.
+
+The primary interface is the `_ImageService` class, which provides class methods
+for loading images from various sources while automatically caching them to avoid
+repeated decoding and to prevent garbage collection issues with Tk images.
+
+This is the internal render/cache backend. The public, Tk-free image handle that
+delegates to it lives in `bootstack.images` (`Image`/`get_icon`/`AppIcon`).
+
+Examples:
+    Basic usage with file paths:
+
+    ```python
+    from bootstack._core.images import _ImageService
+
+    # Load an image from disk (cached automatically)
+    photo = _ImageService.open("icons/save.png")
+    button = Button(app, image=photo)
+    ```
+
+    Loading from bytes (e.g., embedded resources):
+
+    ```python
+    photo = _ImageService.from_bytes(icon_data)
+    ```
+
+    Creating transparent spacer images:
+
+    ```python
+    spacer = _ImageService.transparent(16, 16)
+    ```
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Hashable
+
+from PIL import Image as PILImage, ImageDraw, ImageFilter, ImageFont
+from PIL.ImageTk import PhotoImage as PILPhotoImage
+
+_ICONS_DIR = Path(__file__).parent.parent / "assets" / "icons"
+_ICON_Y_BIAS = 0.02
+_ICON_PAD_FACTOR = 0.10
+
+
+@dataclass(frozen=True)
+class ImageCacheInfo:
+    """Information about the current state of an image cache.
+
+    Attributes:
+        items: The number of images currently stored in the cache.
+    """
+
+    items: int
+
+
+class _ImageService:
+    """Platform image service for loading and caching PhotoImage objects.
+
+    This class provides a centralized service for working with images in
+    bootstack applications. It handles:
+
+    - Loading images from files, bytes, or PIL Image objects
+    - Automatic caching to avoid repeated decoding
+    - Keeping strong references to prevent Tk garbage collection issues
+    - Support for many image formats via Pillow (PNG, JPEG, GIF, BMP, etc.)
+
+    All methods are class methods, so no instantiation is required.
+
+    Examples:
+        ```python
+            # From a file path
+            icon = _ImageService.open("path/to/icon.png")
+
+            # From raw bytes
+            icon = _ImageService.from_bytes(embedded_data)
+
+            # From a PIL Image object
+            pil_img = PILImage.open("photo.jpg").resize((100, 100))
+            icon = _ImageService.from_pil(pil_img)
+
+            # Create a transparent spacer
+            spacer = _ImageService.transparent(32, 32)
+        ```
+
+    Note:
+        Images are cached by default using automatically generated keys based
+        on the source (file path, content hash, or object id). You can provide
+        a custom `key` parameter to control caching behavior.
+    """
+
+    _cache: dict[Hashable, PILPhotoImage] = {}
+    _icon_font_bytes: bytes | None = None
+    _icon_glyphmap: dict[str, str] | None = None
+    _icon_metrics: dict[str, list[float]] | None = None
+    _icon_font_cache: dict[int, Any] = {}
+
+    # =========================================================================
+    # Cache Management
+    # =========================================================================
+
+    @classmethod
+    def get_cached(cls, key: Hashable) -> PILPhotoImage | None:
+        """Retrieve a cached PhotoImage by its key.
+
+        Args:
+            key: The cache key to look up.
+
+        Returns:
+            The cached PhotoImage if found, or None if not in cache.
+        """
+        return cls._cache.get(key)
+
+    @classmethod
+    def set_cached(cls, key: Hashable, img: PILPhotoImage) -> PILPhotoImage:
+        """Store a PhotoImage in the cache.
+
+        Args:
+            key: The cache key to store the image under.
+            img: The PhotoImage to cache.
+
+        Returns:
+            The same PhotoImage that was passed in (for chaining).
+        """
+        cls._cache[key] = img
+        return img
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Clear all cached images.
+
+        This removes all images from the cache. Use with caution, as any
+        widgets still referencing these images may display incorrectly.
+        """
+        cls._cache.clear()
+
+    @classmethod
+    def cache_info(cls) -> ImageCacheInfo:
+        """Get information about the current cache state.
+
+        Returns:
+            An ImageCacheInfo object containing cache statistics.
+
+        Examples:
+            >>> info = _ImageService.cache_info()
+            >>> print(f"Cached images: {info.items}")
+        """
+        return ImageCacheInfo(items=len(cls._cache))
+
+    # =========================================================================
+    # Image Constructors
+    # =========================================================================
+
+    @classmethod
+    def open(cls, path: str | Path, *, key: Hashable | None = None) -> PILPhotoImage:
+        """Load an image from a file path.
+
+        Opens an image file using Pillow and converts it to a Tk-compatible
+        PhotoImage. The result is cached to avoid repeated disk reads and
+        decoding for the same file.
+
+        Args:
+            path: Path to the image file. Supports ~ expansion and relative paths.
+            key: Optional custom cache key. If not provided, the absolute file
+                path is used as the cache key.
+
+        Returns:
+            A Tk-compatible PhotoImage that can be used with widgets.
+
+        Examples:
+            >>> photo = _ImageService.open("assets/logo.png")
+            >>> label = Label(app, image=photo)
+
+            >>> # With custom cache key for versioning
+            >>> photo = _ImageService.open("icon.png", key=("icon", "v2"))
+        """
+        p = Path(path).expanduser().resolve()
+        cache_key = key if key is not None else ("file", str(p))
+        cached = cls.get_cached(cache_key)
+        if cached is not None:
+            return cached
+
+        pil = PILImage.open(p)
+        photo = PILPhotoImage(image=pil)
+        return cls.set_cached(cache_key, photo)
+
+    @classmethod
+    def from_pil(cls, image: PILImage.Image, *, key: Hashable | None = None) -> PILPhotoImage:
+        """Convert a PIL Image to a Tk PhotoImage.
+
+        Wraps an existing PIL Image object in a Tk-compatible PhotoImage.
+        This is useful when you need to perform image manipulation (resizing,
+        filtering, etc.) before displaying the image.
+
+        Args:
+            image: A PIL Image object to convert.
+            key: Optional custom cache key. If not provided, a key derived from
+                the image's content is used, so equal images share a photo and a
+                new image can never collide with a freed one's cached photo.
+
+        Returns:
+            A Tk-compatible PhotoImage that can be used with widgets.
+
+        Examples:
+            >>> from PIL import Image as PILImage
+            >>> pil_img = PILImage.open("photo.jpg")
+            >>> pil_img = pil_img.resize((100, 100))
+            >>> photo = _ImageService.from_pil(pil_img)
+        """
+        if key is not None:
+            cache_key: Hashable = key
+        else:
+            # Content-based key. id(image) is NOT safe: PIL images are short-lived
+            # (e.g. a freshly rendered icon), and once garbage-collected their id
+            # can be reused by a different image — which would then be served the
+            # previous image's cached photo (a stale/duplicated picture).
+            try:
+                cache_key = (
+                    "pil", image.mode, image.size,
+                    hashlib.md5(image.tobytes()).hexdigest(),
+                )
+            except Exception:
+                # Content not byte-serializable — render fresh, uncached.
+                return PILPhotoImage(image=image)
+        cached = cls.get_cached(cache_key)
+        if cached is not None:
+            return cached
+
+        photo = PILPhotoImage(image=image)
+        return cls.set_cached(cache_key, photo)
+
+    @classmethod
+    def from_bytes(cls, data: bytes, *, key: Hashable | None = None) -> PILPhotoImage:
+        """Create a PhotoImage from raw image bytes.
+
+        Decodes image data from bytes using Pillow and converts it to a
+        Tk-compatible PhotoImage. This is useful for embedded resources,
+        downloaded images, or any other source of raw image data.
+
+        Args:
+            data: Raw image bytes in any format supported by Pillow
+                (PNG, JPEG, GIF, BMP, etc.).
+            key: Optional custom cache key. If not provided, an MD5 hash
+                of the bytes is used as the cache key.
+
+        Returns:
+            A Tk-compatible PhotoImage that can be used with widgets.
+
+        Examples:
+            >>> # Load from embedded resource
+            >>> with open("icon.png", "rb") as f:
+            ...     icon_data = f.read()
+            >>> photo = _ImageService.from_bytes(icon_data)
+
+            >>> # With custom cache key
+            >>> photo = _ImageService.from_bytes(data, key="my-icon")
+        """
+        digest = hashlib.md5(data).hexdigest()
+        cache_key = key if key is not None else ("bytes", digest)
+        cached = cls.get_cached(cache_key)
+        if cached is not None:
+            return cached
+
+        pil = PILImage.open(io.BytesIO(data))
+        photo = PILPhotoImage(image=pil)
+        return cls.set_cached(cache_key, photo)
+
+    @classmethod
+    def transparent(cls, width: int, height: int, *, key: Hashable | None = None) -> PILPhotoImage:
+        """Create a transparent spacer image.
+
+        Creates a fully transparent RGBA image of the specified dimensions.
+        This is useful for creating spacing in layouts or as a placeholder
+        image.
+
+        Args:
+            width: Width of the image in pixels.
+            height: Height of the image in pixels.
+            key: Optional custom cache key. If not provided, a tuple of
+                ("transparent", width, height) is used.
+
+        Returns:
+            A transparent Tk-compatible PhotoImage.
+
+        Examples:
+            >>> # Create a 16x16 transparent spacer
+            >>> spacer = _ImageService.transparent(16, 16)
+            >>> label = Label(app, image=spacer)
+
+            >>> # Use as compound image padding
+            >>> button = Button(app, image=spacer, compound="left")
+        """
+        cache_key = key if key is not None else ("transparent", width, height)
+        cached = cls.get_cached(cache_key)
+        if cached is not None:
+            return cached
+
+        pil = PILImage.new("RGBA", (width, height), (255, 255, 255, 0))
+        photo = PILPhotoImage(image=pil)
+        return cls.set_cached(cache_key, photo)
+
+    # =========================================================================
+    # Icon Rendering
+    # =========================================================================
+
+    @classmethod
+    def _load_icon_assets(cls) -> tuple[bytes, dict[str, str]]:
+        if cls._icon_font_bytes is not None:
+            return cls._icon_font_bytes, cls._icon_glyphmap  # type: ignore[return-value]
+        cls._icon_font_bytes = (_ICONS_DIR / "bootstrap.ttf").read_bytes()
+        raw: dict[str, int] = json.loads((_ICONS_DIR / "glyphmap.json").read_text(encoding="utf-8"))
+        cls._icon_glyphmap = {name: chr(cp) for name, cp in raw.items()}
+        return cls._icon_font_bytes, cls._icon_glyphmap
+
+    @classmethod
+    def _get_icon_metrics(cls) -> dict[str, list[float]]:
+        """Lazy-load precomputed normalized ink bounds per glyph.
+
+        Maps icon name to `[left, top, width, height]` as fractions of the font
+        size (from the text draw origin), generated by
+        `tools/generate_icon_metrics.py`. Missing file degrades gracefully to an
+        empty map (the renderer then falls back to measuring at render time).
+        """
+        if cls._icon_metrics is None:
+            try:
+                cls._icon_metrics = json.loads((_ICONS_DIR / "icon_metrics.json").read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                cls._icon_metrics = {}
+        return cls._icon_metrics
+
+    @classmethod
+    def _get_icon_font(cls, size: int) -> ImageFont.FreeTypeFont:
+        font = cls._icon_font_cache.get(size)
+        if font is None:
+            font_bytes, _ = cls._load_icon_assets()
+            font = ImageFont.truetype(io.BytesIO(font_bytes), size)
+            cls._icon_font_cache[size] = font
+        return font
+
+    @classmethod
+    def get_icon(cls, name: str, size: int, color: str) -> PILPhotoImage:
+        """Render a Bootstrap icon and return a cached Tk PhotoImage.
+
+        Even-pixel snapping is applied before rendering to eliminate half-pixel
+        LANCZOS blur at non-integer DPI scale factors (e.g., 125%, 150%).
+
+        Args:
+            name: Bootstrap icon name (e.g., `"house"`, `"arrow-right-fill"`).
+            size: Requested pixel size. Snapped to the nearest even integer.
+            color: Foreground color as a hex string (e.g., `"#ffffff"`).
+
+        Returns:
+            A cached Tk-compatible PhotoImage for the icon.
+        """
+        size = size if size % 2 == 0 else size + 1
+        key = ("icon", name, size, color)
+        cached = cls.get_cached(key)
+        if cached is not None:
+            return cached
+        pil = cls._render_icon(name, size, color)
+        photo = PILPhotoImage(image=pil)
+        return cls.set_cached(key, photo)
+
+    @classmethod
+    def _render_icon(
+        cls, name: str, size: int, color: str, *, align: bool = False
+    ) -> PILImage.Image:
+        """Render a named glyph to an RGBA image of `size` x `size`.
+
+        Args:
+            name: Bootstrap Icons glyph name.
+            size: Output edge length in pixels.
+            color: Fill color (hex).
+            align: Snap the glyph's draw origin to the final pixel grid. Crisper
+                for standalone marks (e.g. app icons) where the glyph fills the
+                frame; off by default so glyphs sitting beside text keep their
+                exact optical centering.
+        """
+        _, glyphmap = cls._load_icon_assets()
+        glyph = glyphmap.get(name)
+        if glyph is None:
+            return PILImage.new("RGBA", (size, size), (0, 0, 0, 0))
+
+        if size < 32:
+            oversample = 3
+        elif size < 64:
+            oversample = 2
+        else:
+            oversample = 1
+
+        def _snap(dx: float, dy: float) -> tuple[float, float]:
+            # Round the draw origin to a multiple of `oversample` so that after
+            # the downscale the glyph lands on whole pixels — its edges stay crisp
+            # instead of being antialiased across a sub-pixel offset.
+            if not align:
+                return dx, dy
+            return round(dx / oversample) * oversample, round(dy / oversample) * oversample
+
+        canvas_size = size * oversample
+        pad = int(canvas_size * _ICON_PAD_FACTOR)
+        inner = canvas_size - 2 * pad
+
+        img = PILImage.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))
+        draw = ImageDraw.Draw(img)
+
+        metrics = cls._get_icon_metrics().get(name)
+        if metrics:
+            # Precomputed normalized ink bounds (em fractions, from the text
+            # draw origin): [left, top, width, height]. Fit the ink to the inner
+            # box (never enlarging past natural size) and center on the true ink
+            # — accurate for full-bleed glyphs and free of getbbox skew.
+            nl, nt, nw, nh = metrics
+            font_size = max(1, int(min(canvas_size, inner / max(nw, nh, 1e-6))))
+            font = cls._get_icon_font(font_size)
+            ink_w, ink_h = nw * font_size, nh * font_size
+            dx = (canvas_size - ink_w) / 2 - nl * font_size
+            dy = (canvas_size - ink_h) / 2 - nt * font_size
+            if _ICON_Y_BIAS:
+                dy += canvas_size * _ICON_Y_BIAS
+            dx, dy = _snap(dx, dy)
+            draw.text((dx, dy), glyph, font=font, fill=color)
+        else:
+            # Fallback for glyphs absent from icon_metrics.json: measure with
+            # getbbox at render time (under-reports full-bleed ink, but always
+            # works). Regenerate the metrics with tools/generate_icon_metrics.py.
+            eff_size = max(1, canvas_size)
+            font = cls._get_icon_font(eff_size)
+            ascent, descent = font.getmetrics()
+            bbox = font.getbbox(glyph)
+            glyph_w = bbox[2] - bbox[0]
+            glyph_h = bbox[3] - bbox[1]
+
+            if glyph_w > inner or glyph_h > inner:
+                scale_factor = min(inner / max(glyph_w, 1), inner / max(glyph_h, 1)) * 0.95
+                scaled_size = max(1, int(eff_size * scale_factor))
+                font = cls._get_icon_font(scaled_size)
+                ascent, descent = font.getmetrics()
+                bbox = font.getbbox(glyph)
+                glyph_w = bbox[2] - bbox[0]
+                glyph_h = bbox[3] - bbox[1]
+
+            full_height = ascent + descent
+            dx = pad + (inner - glyph_w) // 2 - bbox[0]
+            dy = pad + (inner - full_height) // 2 + (ascent - bbox[3])
+            if _ICON_Y_BIAS:
+                dy += int(canvas_size * _ICON_Y_BIAS)
+            dx, dy = _snap(dx, dy)
+            draw.text((dx, dy), glyph, font=font, fill=color)
+
+        if oversample > 1:
+            img = img.resize((size, size), PILImage.Resampling.LANCZOS)
+            img = img.filter(ImageFilter.UnsharpMask(radius=0.6, percent=60, threshold=0))
+
+        return img

bootstack/_core/mixins/__init__.py

@@ -0,0 +1 @@
+"""Widget capability and TTK state mixins for bootstack widgets."""

bootstack/_core/mixins/ttk_state.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Iterable, Any
+
+
+class TtkStateMixin:
+    """ttk-only widget helpers.
+
+    This mixin contains methods that exist on ttk widgets but not on classic Tk widgets
+    (e.g., `tk.Text`, `tk.Canvas`).
+    """
+
+    def state(self, statespec: str | Iterable[str] | None = None) -> Any:
+        """Get or modify the ttk state of the widget.
+
+        Args:
+            statespec: State specification (e.g. ("disabled",) or ("!disabled",)).
+                If None, returns the current state.
+
+        Returns:
+            The current state (getter) or an implementation-dependent result.
+        """
+        return super().state(statespec)  # type: ignore[misc]
+
+    def instate(self, statespec: str | Iterable[str], callback: Any = None) -> bool:
+        """Test the ttk state of the widget.
+
+        Args:
+            statespec: State specification to test.
+            callback: Optional callable invoked if the test succeeds.
+
+        Returns:
+            True if the widget matches the state spec; otherwise False.
+        """
+        return super().instate(statespec, callback)  # type: ignore[misc]

bootstack/_core/mixins/widget.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from typing import Mapping, Any
+
+from bootstack._core.capabilities.after import AfterMixin
+from bootstack._core.capabilities.bind import BindingsMixin
+from bootstack._core.capabilities.bindtags import BindtagsMixin
+from bootstack._core.capabilities.clipboard import ClipboardMixin
+from bootstack._core.capabilities.focus import FocusMixin
+from bootstack._core.capabilities.grab import GrabMixin
+from bootstack._core.capabilities.grid import GridMixin
+from bootstack._core.capabilities.pack import PackMixin
+from bootstack._core.capabilities.place import PlaceMixin
+from bootstack._core.capabilities.selection import SelectionMixin
+from bootstack._core.capabilities.winfo import WinfoMixin
+
+
+class WidgetCapabilitiesMixin(
+    AfterMixin,
+    BindingsMixin,
+    BindtagsMixin,
+    ClipboardMixin,
+    FocusMixin,
+    GrabMixin,
+    GridMixin,
+    PackMixin,
+    PlaceMixin,
+    SelectionMixin,
+    WinfoMixin,
+):
+    """Common widget API surface (tk + ttk).
+
+    This mixin aggregates documented capability mixins into a single interface
+    suitable for both Tk and ttk widgets, plus a small set of commonly used
+    widget operations (configure/cget/destroy, stacking order, etc.).
+    """
+
+    # -------------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------------
+
+    def destroy(self) -> None:
+        """Destroy this widget and release its Tk resources."""
+        return super().destroy()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Configuration
+    # -------------------------------------------------------------------------
+
+    def configure(self, cnf: Mapping[str, Any] | None = None, **kw: Any) -> Any:
+        """Configure widget options.
+
+        Args:
+            cnf: Optional mapping of option values.
+            **kw: Option values as keyword arguments.
+
+        Returns:
+            Tk returns configuration details when called with no args; otherwise
+            the return value is implementation-dependent.
+        """
+        if cnf is None:
+            return super().configure(**kw)  # type: ignore[misc]
+        return super().configure(cnf, **kw)  # type: ignore[misc]
+
+    config = configure
+
+    def cget(self, key: str) -> Any:
+        """Return the current value for an option.
+
+        Args:
+            key: Option name (with or without a leading dash).
+
+        Returns:
+            The option value.
+        """
+        return super().cget(key)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Stacking order
+    # -------------------------------------------------------------------------
+
+    def lift(self, aboveThis: Any | None = None) -> None:
+        """Raise this widget above its siblings.
+
+        Args:
+            aboveThis: Optional sibling widget to raise above.
+        """
+        return super().lift(aboveThis)  # type: ignore[misc]
+
+    tkraise = lift
+
+    def lower(self, belowThis: Any | None = None) -> None:
+        """Lower this widget below its siblings.
+
+        Args:
+            belowThis: Optional sibling widget to lower below.
+        """
+        return super().lower(belowThis)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Layout convenience
+    # -------------------------------------------------------------------------
+
+    def forget(self) -> None:
+        """Remove the widget from layout (best-effort).
+
+        This calls the appropriate forget method depending on the active geometry manager:
+
+            - grid  -> grid_forget()
+            - pack  -> pack_forget()
+            - place -> place_forget()
+        """
+        try:
+            mgr = self.winfo_manager()  # type: ignore[attr-defined]
+        except Exception:
+            mgr = ""
+
+        if mgr == "grid":
+            try:
+                self.grid_forget()  # type: ignore[attr-defined]
+            except Exception:
+                pass
+        elif mgr == "pack":
+            try:
+                self.pack_forget()  # type: ignore[attr-defined]
+            except Exception:
+                pass
+        elif mgr == "place":
+            try:
+                self.place_forget()  # type: ignore[attr-defined]
+            except Exception:
+                pass

bootstack/_core/paths.py

@@ -0,0 +1,49 @@
+"""Platform configuration paths for bootstack apps.
+
+A single home for the per-platform config directory convention so window-state
+persistence, `Store`, and anything else that writes user state all agree on
+where files live.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+__all__ = ["user_config_dir", "app_config_dir", "app_config_file"]
+
+
+def user_config_dir() -> Path:
+    """Return the OS user-configuration base directory.
+
+    `~/Library/Application Support` on macOS, `%APPDATA%` on Windows, and
+    `$XDG_CONFIG_HOME` (falling back to `~/.config`) elsewhere.
+    """
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support"
+    if sys.platform == "win32":
+        return Path(os.environ.get("APPDATA") or (Path.home() / "AppData" / "Roaming"))
+    return Path(os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config"))
+
+
+def app_config_dir(app_name: str | None = None) -> Path:
+    """Return the per-app config directory under `user_config_dir()`.
+
+    The leaf is `app_name` (or `'bootstack'` when not given) so multiple
+    bootstack apps on one machine do not collide.
+
+    Args:
+        app_name: The application name, used as the directory leaf.
+    """
+    return user_config_dir() / (app_name or "bootstack")
+
+
+def app_config_file(filename: str, app_name: str | None = None) -> Path:
+    """Return the path to a named file inside the per-app config directory.
+
+    Args:
+        filename: The leaf file name (for example `'settings.json'`).
+        app_name: The application name, used as the directory leaf.
+    """
+    return app_config_dir(app_name) / filename