bootstack 0.1.0a1__py3-none-any.whl

bootstack/core/colorutils.py

@@ -0,0 +1,234 @@
+"""Color utility functions for bootstack.
+
+This module provides utilities for converting between different color models
+and manipulating colors (adjusting hue, saturation, luminance).
+
+Supported color models:
+    - RGB: Red, Green, Blue tuple (0-255)
+    - HSL: Hue (0-360), Saturation (0-100), Luminance (0-100)
+    - HEX: Hexadecimal color string (#RRGGBB)
+    - NAME: Named colors (e.g., 'red', 'blue')
+
+Functions:
+    color_to_rgb: Convert any color model to RGB
+    color_to_hex: Convert any color model to HEX
+    color_to_hsl: Convert any color model to HSL
+    update_color: Modify HSL values of a color
+    contrast_color: Get contrasting foreground color for readability
+
+Example:
+    ```python
+    from bootstack.colorutils import *
+
+    # Convert hex to RGB
+    rgb = color_to_rgb('#FF5733', model=HEX)  # (255, 87, 51)
+
+    # Adjust color lightness
+    lighter = update_color('#FF5733', lum=80, inmodel=HEX, outmodel=HEX)
+
+    # Get contrasting text color
+    fg_color = contrast_color('#FF5733')  # Returns 'white' or 'black'
+    ```
+"""
+from PIL import ImageColor
+from colorsys import rgb_to_hls
+
+RGB = 'rgb'
+HSL = 'hsl'
+HEX = 'hex'
+NAME = 'name'
+
+HUE = 360
+SAT = 100
+LUM = 100
+
+
+def color_to_rgb(color, model=HEX):
+    """Convert color value to rgb.
+
+    The color and model parameters represent the color to be converted.
+    The value is expected to be a string for "name" and "hex" models and
+    a Tuple or List for "rgb" and "hsl" models.
+    
+    Parameters:
+        
+        color (Any):
+            The color values for the model being converted.
+            
+        model (str):
+            The color model being converted.
+    
+    Returns:
+
+        tuple[int, int, int]:
+            The rgb color values.
+    """
+    color_ = conform_color_model(color, model)
+    return ImageColor.getrgb(color_)
+
+
+def color_to_hex(color, model=RGB):
+    """Convert color value to hex.
+
+    The color and model parameters represent the color to be converted.
+    The value is expected to be a string for "name" and "hex" models and
+    a Tuple or List for "rgb" and "hsl" models.
+    
+    Parameters:
+        
+        color (Any):
+            The color values for the model being converted.
+            
+        model (str):
+            The color model being converted.
+    
+    Returns:
+    
+        str:
+            The hexadecimal color value.
+    """
+    r, g, b = color_to_rgb(color, model)
+    return f'#{r:02x}{g:02x}{b:02x}'
+
+def color_to_hsl(color, model=HEX):
+    """Convert color value to hsl.
+
+    The color and model parameters represent the color to be converted.
+    The value is expected to be a string for "name" and "hex" models and
+    a Tuple or List for "rgb" and "hsl" models.
+    
+    Parameters:
+        
+        color (Any):
+            The color values for the model being converted.
+            
+        model (str):
+            The color model being converted.
+    
+    Returns:
+
+        tuple[int, int, int]:
+            The hsl color values.
+    """
+    r, g, b = color_to_rgb(color, model)
+    hls = rgb_to_hls(r/255, g/255, b/255)
+    h = int(hls[0]*HUE)
+    l = int(hls[1]*LUM)
+    s = int(hls[2]*SAT)
+    return h, s, l
+
+def update_hsl_value(color, hue=None, sat=None, lum=None, inmodel=HSL, outmodel=HSL):
+    """Change hue, saturation, or lumenosity of the color based on the
+    hue, sat, lum parameters provided.
+    
+    Parameters:
+
+        color (Any):
+            The color
+
+        hue (int):
+            A number between 0 and 360.
+
+        sat (int):
+            A number between 0 and 100.
+
+        lum (int):
+            A number between 0 and 100.
+
+        inmodel (str):
+            The color model used by the color to be changed. One of
+            hsl, rgb, hex, name.
+
+        outmodel (str):
+            The color value model to be returned when the color is
+            changed. One of hsl, rgb, hex.
+
+    Returns:
+
+        Union[tuple[int, int, int], str]:
+            The color value based on the selected color model.
+    """
+    h, s, l = color_to_hsl(color, inmodel)
+    if hue is not None:
+        h = hue
+    if sat is not None:
+        s = sat
+    if lum is not None:
+        l = lum
+    if outmodel == RGB:
+        return color_to_rgb([h, s, l], HSL)
+    elif outmodel == HEX:
+        return color_to_hex([h, s, l], HSL)
+    else:
+        return h, s, l
+
+
+"""
+https://stackoverflow.com/questions/1855884/determine-font-color-based-on-background-color
+
+"""
+
+def contrast_color(color, model=RGB, darkcolor='#000', lightcolor='#fff'):
+    """Returns the best matching contrasting light or dark color for
+    the given color.
+    
+    Parameters:
+
+        color (Any):
+            The color value to evaluate.
+
+        model (str):
+            The model of the color value to be evaluated. 'rgb' by 
+            default.
+
+        darkcolor (Any):
+            The color value to be returned when the constrasting color 
+            should be dark.
+
+        lightcolor (Any):
+            The color value to be returned when the constrasting color
+            should be light.
+
+    Returns:
+
+        str:
+            The matching color value.
+    """
+    if model != RGB:
+        r, g, b = color_to_rgb(color, model)
+    else:
+        r, g, b = color
+
+    luminance = ((0.299 * r) + (0.587 * g) + (0.114 * b))/255
+    if luminance > 0.5:
+        return darkcolor
+    else:
+        return lightcolor
+
+
+def conform_color_model(color, model):
+    """Conform the color values to a string that can be interpreted
+    by the `PIL.ImageColor.getrgb method`.
+
+    Parameters:
+
+        color (Union[tuple[int, int, int], str]):
+            The color value to conform.
+
+        model (str):
+            One of 'HSL', 'RGB', or 'HEX'
+
+    Returns:
+
+        str:
+            A color value string that can be used as a parameter in the
+            PIL.ImageColor.getrgb method.
+    """    
+    if model == HSL:
+        h, s, l = color
+        return f'hsl({h},{s}%,{l}%)'
+    elif model == RGB:
+        r, g, b = color
+        return f'rgb({r},{g},{b})'
+    else:
+        return color

bootstack/core/exceptions.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class TTKBootstrapError(Exception):
+    """Base for all bootstack errors."""
+    __slots__ = ("hint", "code", "widget_id")
+
+    def __init__(
+            self, message: str, *, hint: Optional[str] = None,
+            code: Optional[str] = None, widget_id: Optional[str] = None):
+        """Create a bootstack error.
+
+        Args:
+            message: Human-readable description of what went wrong.
+            hint: Optional suggestion for how to resolve the error.
+            code: Optional machine-readable error code for programmatic handling.
+            widget_id: Optional Tk widget path string identifying the source widget.
+        """
+        super().__init__(message)
+        self.hint = hint
+        self.code = code
+        self.widget_id = widget_id
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.hint:
+            return f"{base} — Hint: {self.hint}"
+        return base
+
+
+class LayoutError(TTKBootstrapError):
+    """Raised when a widget layout operation fails.
+
+    Examples: invalid geometry manager usage, pane configuration errors,
+    or attempting to pack/grid/place a widget into an incompatible container.
+    """
+
+
+class ThemeError(TTKBootstrapError):
+    """Raised when a theme-related operation fails.
+
+    Examples: requesting an unknown theme name, loading a malformed theme
+    definition, or applying a theme before the style system is initialised.
+    """
+
+
+class ConfigError(TTKBootstrapError):
+    """Raised when a widget or application configuration is invalid.
+
+    Examples: passing mutually exclusive options, supplying an unsupported
+    value for a configuration key, or configuring a widget after it has
+    been destroyed.
+    """
+
+
+class StateError(TTKBootstrapError):
+    """Raised when an operation is attempted while the widget is in an invalid state.
+
+    Examples: calling `start()` on an already-running animation, or
+    modifying a widget that has been destroyed.
+    """
+
+
+class NavigationError(TTKBootstrapError):
+    """Raised when a navigation operation fails.
+
+    Examples: referencing a tab key that does not exist, supplying an index
+    that is out of range, or navigating in a container that has no items.
+    """
+
+
+class BootstyleBuilderError(TTKBootstrapError):
+    """Raised when a style builder encounters an error during style construction.
+
+    Examples: a builder receiving an unsupported option, a required theme
+    color token being missing, or an internal style-engine failure.
+    """
+
+
+class BootstyleParsingError(TTKBootstrapError):
+    """Raised when a bootstyle string cannot be parsed into valid tokens.
+
+    Examples: an unrecognised accent name, an invalid variant, or a
+    combination of tokens that the parser cannot resolve.
+    """
+
+
+class ConfigurationWarning(Warning):
+    """Issued when a widget receives a deprecated or questionable configuration option.
+
+    Examples: passing the legacy `bootstyle` keyword instead of the
+    recommended `accent`/`variant` pair.
+    """

bootstack/core/images.py

@@ -0,0 +1,283 @@
+"""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 `Image` 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.
+
+Examples:
+    Basic usage with file paths:
+
+    ```python
+    from bootstack import Image
+
+    # Load an image from disk (cached automatically)
+    photo = Image.open("icons/save.png")
+    button = Button(app, image=photo)
+    ```
+
+    Loading from bytes (e.g., embedded resources):
+
+    ```python
+    photo = Image.from_bytes(icon_data)
+    ```
+
+    Creating transparent spacer images:
+
+    ```python
+    spacer = Image.transparent(16, 16)
+    ```
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Hashable
+
+from PIL import Image as PILImage
+from PIL.ImageTk import PhotoImage as PILPhotoImage
+
+
+@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 Image:
+    """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 = Image.open("path/to/icon.png")
+
+            # From raw bytes
+            icon = Image.from_bytes(embedded_data)
+
+            # From a PIL Image object
+            pil_img = PILImage.open("photo.jpg").resize((100, 100))
+            icon = Image.from_pil(pil_img)
+
+            # Create a transparent spacer
+            spacer = Image.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] = {}
+
+    # =========================================================================
+    # 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 = Image.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 = Image.open("assets/logo.png")
+            >>> label = Label(app, image=photo)
+
+            >>> # With custom cache key for versioning
+            >>> photo = Image.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, the object id
+                of the PIL Image is used (note: this means the same PIL Image
+                object will be cached, but copies won't hit the cache).
+
+        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 = Image.from_pil(pil_img)
+        """
+        cache_key = key if key is not None else ("pil", id(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 = Image.from_bytes(icon_data)
+
+            >>> # With custom cache key
+            >>> photo = Image.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 = Image.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)

bootstack/core/localization/README.md

@@ -0,0 +1,90 @@
+# Localization (Message Catalog + Babel/gettext)
+
+ttkbootstrap uses a unified message catalog that bridges Python gettext (compiled with Babel) and Tcl/Tk msgcat. Catalogs are distributed with the package under `ttkbootstrap/assets/locales`.
+
+Highlights
+- Use `_ = MessageCatalog.translate` in code to mark strings.
+- Style auto-initializes the catalog and auto-discovers shipped catalogs.
+- Switch language at runtime with `MessageCatalog.locale('de')`.
+- A virtual event `<<LocaleChanged>>` is emitted on language changes so UIs can refresh.
+- Runtime overrides (`set`, `set_many`) let you add translations that aren't in the catalogs yet.
+
+Directory structure
+- `src/ttkbootstrap/assets/locales/<lang>/LC_MESSAGES/ttkbootstrap.po`
+- `src/ttkbootstrap/assets/locales/<lang>/LC_MESSAGES/ttkbootstrap.mo`
+
+Marking strings for translation
+- In modules that render UI:
+  - `from ttkbootstrap.core.localization import MessageCatalog`
+  - `_ = MessageCatalog.translate`
+  - Example: `ttk.Label(root, text=_('Cancel'))`
+- Formatting:
+  - `_("File: %s", name)` uses Python `%` formatting.
+  - Legacy Tcl printf like `%1$s` are supported via a formatting fallback.
+
+Language switching
+- Change language at runtime:
+  - `MessageCatalog.locale('fr')`
+  - Bind a refresh: `root.bind('<<LocaleChanged>>', lambda e: refresh())`
+
+Runtime overrides (non-compiled messages)
+- Add translations for a locale during runtime:
+  - Single: `MessageCatalog.set('fr', 'Hello', 'Bonjour')`
+  - Many: `MessageCatalog.set_many('de', 'Open','Oeffnen', 'Cancel','Abbrechen')`
+  - Emit refresh if you're already in that locale: `root.event_generate('<<LocaleChanged>>')`
+
+Developer workflow (Babel)
+- Config lives at project root: `babel.cfg` (extracts from `src/**/*.py` and `_()`/gettext keywords).
+- Use the helper to manage catalogs (defaults to `src/ttkbootstrap/assets/locales` and domain `ttkbootstrap`):
+  - Extract template: `python tools/make_i18n.py extract`
+  - Init locales: `python tools/make_i18n.py init -l de fr`
+  - Update catalogs: `python tools/make_i18n.py update`
+  - Compile catalogs: `python tools/make_i18n.py compile`
+- The compiled `.mo` files are shipped in the wheel from `assets/locales`.
+
+Tools
+- `tools/make_i18n.py` — primary helper for extract/init/update/compile (targets `assets/locales`).
+- `tools/audit_messages.py` — optional QA to spot duplicates and accelerator issues.
+  - Scans `src/ttkbootstrap/assets/locales` by default.
+  
+Note: Legacy migration helpers (e.g., `convert_msgs_to_po.py`, `sync_locales_to_package.py`) have been removed. The workflow compiles directly to `assets/locales`.
+
+Contribution notes
+- Prefer base locales (`de`, `fr`, `nl`) unless region-specific differences are required (for example `pt_BR`).
+- Avoid embedding mnemonics `&` in messages; MessageCatalog strips them when rendering.
+- Keep message ids consistent (case and punctuation) to avoid duplicates.
+- Optional: audit keys with `python tools/audit_messages.py`.
+
+Demos
+- `examples/localization_widgets_demo.py` - shows `_()` usage and `<<LocaleChanged>>` auto-refresh.
+- `examples/runtime_overrides_demo.py` - shows `set`/`set_many` for messages not in catalogs yet.
+
+Contributors
+- Where to place translations:
+  - Add or edit `.po` files under `src/ttkbootstrap/assets/locales/<lang>/LC_MESSAGES/ttkbootstrap.po`.
+  - Compile to `.mo` with `python tools/make_i18n.py compile`.
+- Workflow for a new language:
+  1) Extract: `python tools/make_i18n.py extract`
+  2) Init: `python tools/make_i18n.py init -l <lang>`
+  3) Translate the new `.po` file
+  4) Compile: `python tools/make_i18n.py compile`
+- Minimum keys to translate for a new language (baseline UI):
+  - OK, Ok, Retry, Delete, Next, Prev, Previous
+  - Yes, No, Open, Close, Add, Remove, Submit, Cancel
+  - Family, Weight, Slant, Effects, Preview, Size
+  - Should be of data type, Invalid data type
+  - Number cannot be greater than, Number cannot be less than, Out of range
+  - The quick brown fox jumps over the lazy dog.
+  - Font Selector, Color Chooser, Advanced, Themed, Standard
+  - Current, New, Hue, Sat, Lum, Hex, Red, Green, Blue
+  - color dropper, Search, Page, of
+  - Reset table, Columns, Move, Align
+  - Hide column, Delete column, Show All
+  - Move to left, Move to right, Move to first, Move to last
+  - Align left, Align center, Align right
+  - Sort, Filter, Export, Delete selected rows
+  - Sort Ascending, Sort Descending, Clear filters
+  - Filter by cell's value, Hide select rows, Show only select rows
+  - Export all records, Export current page, Export current selection, Export records in filter
+  - Move up, Move down, Move to top, Move to bottom
+  - Mo, Tu, We, Th, Fr, Sa, Su