bootstack 0.1.0a1__py3-none-any.whl

bootstack/core/signals/signal.py

@@ -0,0 +1,317 @@
+import tkinter as tk
+import weakref
+from itertools import count
+from typing import Any, Callable, Generic, Type, TypeVar
+
+from bootstack.core.signals.types import TraceOperation
+from bootstack.core.variables import SetVar
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+class _SignalTrace:
+    """
+    Internal helper to manage Tcl variable traces using tkinter's Variable API.
+    This class encapsulates low-level `trace_add` and `trace_remove` logic.
+    """
+
+    def __init__(self, tk_var: tk.Variable):
+        """
+        Initialize a trace manager for a tkinter variable.
+
+        Args:
+            tk_var: A tkinter.Variable instance (e.g., StringVar, IntVar).
+        """
+        self._var = tk_var
+        # Map trace id -> (operation, callback)
+        self._traces: dict[str, tuple[TraceOperation, Callable[..., Any]]] = {}
+
+    def callbacks(self) -> tuple[str, ...]:
+        """
+        Return all currently active trace IDs.
+
+        Returns:
+            A tuple of trace ID strings.
+        """
+        return tuple(self._traces.keys())
+
+    def add(
+            self,
+            operation: TraceOperation,
+            callback: Callable[[T], Any],
+            get_value: Callable[[], T],
+    ) -> str:
+        """
+        Add a new trace that calls a callback when the variable is written.
+        """
+
+        def traced_callback(name: str, index: str, mode: str) -> None:
+            callback(get_value())
+
+        try:
+            fid = self._var.trace_add(operation, traced_callback)
+        except tk.TclError as e:
+            raise RuntimeError(f"failed to add trace: {e}") from e
+        self._traces[fid] = (operation, traced_callback)
+        return fid
+
+    def remove(self, fid: str) -> None:
+        """
+        Remove a trace by ID. Safe if already removed or variable destroyed.
+        """
+        op_cb = self._traces.pop(fid, None)
+        if op_cb is None:
+            return
+        operation, _ = op_cb
+        try:
+            self._var.trace_remove(operation, fid)
+        except tk.TclError:
+            # Variable may be unset/destroyed; ignore
+            pass
+
+
+class Signal(Generic[T]):
+    """
+    A reactive signal backed by a tkinter Variable.
+
+    Supports value access, transformation via `.map()`, and subscription
+    to change events via `.subscribe()`.
+
+    Can be passed to Tkinter widgets using `str(signal)` or `signal.name`.
+    """
+
+    _cnt = count(1)
+
+    def __init__(self, value: T, name: str | None = None, master: tk.Misc | None = None):
+        self._name = name or f"SIG{next(self._cnt)}"
+        self._type: Type[T] = type(value)
+        self._master: tk.Misc | None = master
+        self._var = self._create_variable(value)
+        self._trace = _SignalTrace(self._var)
+        # Map fid -> callback to allow multiple subscriptions of same function
+        self._subscribers: dict[str, Callable[[T], Any]] = {}
+        # Reverse index: callback -> set of fids
+        self._callback_index: dict[Callable[[T], Any], set[str]] = {}
+        # Cache last known value for robustness when Tcl variable is torn down
+        self._last: T = value
+
+    def _create_variable(self, value: T) -> tk.Variable:
+        if isinstance(value, bool):
+            return tk.BooleanVar(master=self._master, name=self._name, value=value)
+        elif isinstance(value, int):
+            return tk.IntVar(master=self._master, name=self._name, value=value)
+        elif isinstance(value, float):
+            return tk.DoubleVar(master=self._master, name=self._name, value=value)
+        elif isinstance(value, set):
+            return SetVar(master=self._master, name=self._name, value=value)
+        else:
+            return tk.StringVar(master=self._master, name=self._name, value=value)
+
+    def __call__(self) -> T:
+        """
+        Get the current value of the signal.
+
+        Returns:
+            The current typed value.
+        """
+        try:
+            value = self._var.get()
+            self._last = value  # cache last good value
+            return value
+        except tk.TclError:
+            # Return last known value when underlying var is destroyed/unset
+            return self._last
+
+    def get(self) -> T:
+        """Return the current value of the signal.
+
+        Alias for calling the instance directly (`signal()`). Mirrors
+        tkinter's `Variable.get` naming for consistency.
+        """
+        return self()
+
+    @classmethod
+    def from_variable(
+            cls,
+            tk_var: tk.Variable,
+            *,
+            name: str | None = None,
+            coerce: Type[T] | None = None,
+    ) -> "Signal[T]":
+        """
+        Wrap an existing tkinter Variable as a Signal.
+
+        Args:
+            tk_var: An existing tkinter.Variable instance (StringVar, IntVar, etc.).
+            name: Optional override of the Tcl variable name. Defaults to tk_var's name.
+            coerce: Optional Python type to treat the signal as (e.g., int/float/bool/str).
+                    If omitted, the type is inferred from the tk_var subclass.
+
+        Returns:
+            A Signal bound to the provided tk_var.
+        """
+        # Infer Python type from the tk variable if not explicitly provided
+        if coerce is None:
+            if isinstance(tk_var, tk.BooleanVar):
+                py_type: Type[Any] = bool
+            elif isinstance(tk_var, tk.IntVar):
+                py_type = int
+            elif isinstance(tk_var, tk.DoubleVar):
+                py_type = float
+            elif isinstance(tk_var, SetVar):
+                py_type = set
+            else:
+                py_type = str
+        else:
+            py_type = coerce
+
+        # Construct without creating a new tk.Variable
+        self = cls.__new__(cls)  # bypass __init__
+        self._name = name or getattr(tk_var, "_name", str(tk_var))
+        self._type = py_type  # type: ignore[assignment]
+        self._var = tk_var
+        self._trace = _SignalTrace(self._var)
+        self._subscribers = {}
+        self._callback_index = {}
+        # Best-effort capture of master/interpreter for reference
+        self._master = getattr(tk_var, "_master", None)
+        try:
+            current = tk_var.get()  # type: ignore[assignment]
+        except tk.TclError:
+            # Fallback default per inferred type
+            if py_type is float:  # type: ignore[comparison-overlap]
+                current = 0.0
+            elif py_type is int:  # type: ignore[comparison-overlap]
+                current = 0
+            elif py_type is bool:  # type: ignore[comparison-overlap]
+                current = False
+            elif py_type is set:
+                current = set()
+            else:
+                current = ""
+        self._last = current  # type: ignore[assignment]
+        return self
+
+    def set(self, value: T) -> None:
+        """
+        Set the signal to a new value and notify subscribers.
+
+        Args:
+            value: The new value. Must match the original type.
+
+        Raises:
+            TypeError: If the value type does not match the original.
+        """
+        # Enforce exact type to avoid bool being accepted for int, etc.
+        if type(value) is not self._type:
+            raise TypeError(f"Expected {self._type.__name__}, got {type(value).__name__}")
+        # Reduce redundant updates if value unchanged
+        try:
+            current = self._var.get()
+            if current == value:
+                return
+        except tk.TclError:
+            # If var is gone, proceed to set and let Tcl recreate path if possible
+            pass
+        self._var.set(value)
+        self._last = value
+
+    def map(self, transform: Callable[[T], U]) -> 'Signal[U]':
+        """
+        Create a derived signal that transforms this signal's value.
+
+        Args:
+            transform: A function applied to the current and future values.
+
+        Returns:
+            A new Signal[U] that stays updated with the transformed value.
+        """
+        derived = Signal(transform(self()))
+
+        # Use weakref to avoid keeping derived alive solely via subscription
+        weak_derived = weakref.ref(derived)
+
+        def update(value: T) -> None:
+            d = weak_derived()
+            if d is None:
+                # Auto-detach if derived is GC'd
+                return
+            d.set(transform(value))
+
+        self.subscribe(update)
+        return derived
+
+    def subscribe(self, callback: Callable[[T], Any], *, immediate: bool = False) -> str:
+        """
+        Subscribe to value changes of this signal.
+
+        Args:
+            callback: A function that receives the current value (T) when updated.
+
+        Returns:
+            A trace ID that can be used for removal.
+        """
+        fid = self._trace.add("write", callback, self)
+        self._subscribers[fid] = callback
+        self._callback_index.setdefault(callback, set()).add(fid)
+        if immediate:
+            try:
+                callback(self())
+            except Exception:
+                # Do not fail subscription due to callback error
+                pass
+        return fid
+
+    def unsubscribe(self, funcid: str) -> None:
+        """
+        Remove a previously registered subscriber.
+
+        Args:
+            funcid: The function id returned from `subscribe()`.
+        """
+        self._subscribers.pop(funcid, None)
+        self._trace.remove(funcid)
+
+    def unsubscribe_all(self) -> None:
+        """
+        Remove all currently subscribed callbacks.
+        """
+        # Copy keys to avoid mutation during iteration
+        for fid in list(self._subscribers.keys()):
+            self._trace.remove(fid)
+        self._subscribers.clear()
+        self._callback_index.clear()
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Proxy access to the underlying tk.Variable instance.
+        """
+        return getattr(self._var, name)
+
+    @property
+    def name(self) -> str:
+        """
+        Return the Tcl name of the variable (for use in widget `textvariable`).
+        """
+        return self._name
+
+    @property
+    def type(self) -> Type[T]:
+        """
+        The original type of the signal value.
+
+        Returns:
+            A Python type (e.g., int, str).
+        """
+        return self._type
+
+    @property
+    def var(self) -> tk.Variable:
+        return self._var
+
+    def __str__(self) -> str:
+        return self._name
+
+    def __repr__(self) -> str:
+        return self._name

bootstack/core/signals/types.py

@@ -0,0 +1,4 @@
+"""Type aliases for the signal and variable tracing system."""
+from typing import Literal
+
+TraceOperation = Literal["array", "read", "write", "unset"]

bootstack/core/validation/__init__.py

@@ -0,0 +1,5 @@
+"""Validation rules and results for Field-based input widgets."""
+from .validation_rules import ValidationRule
+from .validation_result import ValidationResult
+
+__all__ = ['ValidationRule', 'ValidationResult']

bootstack/core/validation/types.py

@@ -0,0 +1,13 @@
+from typing import Callable, Literal, Optional, TypedDict
+
+RuleType = Literal["required", "email", "pattern", "stringLength", "custom", "compare"]
+RuleTriggerType = Literal['key', 'blur', 'always', 'manual']
+
+
+class ValidationOptions(TypedDict, total=False):
+    pattern: str
+    message: str
+    min: int
+    max: int
+    trigger: Optional[Literal["key", "blur", "always", "manual"]]
+    func: Callable[[str], bool]

bootstack/core/validation/validation_result.py

@@ -0,0 +1,17 @@
+class ValidationResult:
+    """The outcome of a single validation check.
+
+    Attributes:
+        is_valid (bool): True if validation passed, False otherwise.
+        message (str): Error message when `is_valid` is False; empty string otherwise.
+    """
+
+    def __init__(self, is_valid: bool, message: str = ""):
+        """Create a validation result.
+
+        Args:
+            is_valid: True if validation passed.
+            message: Error message. Defaults to an empty string.
+        """
+        self.is_valid = is_valid
+        self.message = message

bootstack/core/validation/validation_rules.py

@@ -0,0 +1,112 @@
+import re
+from typing import Callable
+
+from bootstack.core.validation.types import RuleTriggerType, RuleType
+from bootstack.core.validation.validation_result import ValidationResult
+
+
+class ValidationRule:
+    """A single validation rule that can be applied to a string value.
+
+    Supports the built-in rule types `'required'`, `'email'`,
+    `'stringLength'`, `'pattern'`, and `'custom'`, and carries a trigger
+    policy that controls when the rule is evaluated.
+
+    Attributes:
+        type (RuleType): The validation rule type.
+        message (str): Custom error message; if empty a default is generated.
+        trigger (RuleTriggerType): When the rule fires — `'always'`, `'blur'`, or `'manual'`.
+        params (dict): Additional parameters specific to the rule type
+            (e.g., `min`/`max` for `'stringLength'`, `pattern` for `'pattern'`,
+            `func` for `'custom'`).
+    """
+
+    def __init__(
+            self,
+            rule_type: RuleType,
+            message: str = "",
+            **kwargs
+    ):
+        """Create a validation rule.
+
+        Args:
+            rule_type: The type of validation to apply.
+            message: Custom error message. If empty, a sensible default is used.
+            **kwargs: Rule-specific parameters.  Pass `trigger` to override the
+                default trigger policy; all other keys are stored in `params`
+                (e.g., `min=3, max=20` for `'stringLength'`, `pattern=r'\\d+'`
+                for `'pattern'`, `func=callable` for `'custom'`).
+        """
+        self.type = rule_type
+        self.message = message
+        self.trigger = kwargs.pop('trigger', self._default_trigger())
+        self.params = kwargs
+
+    def validate(self, value: str) -> ValidationResult:
+        """Apply this rule to a value and return the result.
+
+        Args:
+            value: The string value to validate.
+
+        Returns:
+            A ValidationResult with `is_valid=True` on success or `is_valid=False`
+            with an error message on failure.
+        """
+        msg = self.message or self._default_message()
+
+        if self.type == "required":
+            if value is None:
+                return ValidationResult(False, msg)
+            if isinstance(value, str) and not value.strip():
+                return ValidationResult(False, msg)
+            # Everything else is valid (non-empty string, number, date, etc.)
+            return ValidationResult(True, "")
+
+        elif self.type == "email":
+            if not re.match(r"[^@]+@[^@]+\.[^@]+", value):
+                return ValidationResult(False, msg)
+        elif self.type == "stringLength":
+            min_len = self.params.get("min", 0)
+            max_len = self.params.get("max", float("inf"))
+            if not (min_len <= len(value) <= max_len):
+                return ValidationResult(False, msg)
+        elif self.type == "pattern":
+            pattern = self.params.get("pattern", "")
+            if not re.match(pattern, value):
+                return ValidationResult(False, msg)
+        elif self.type == "custom":
+            func: Callable[[str], bool] = self.params.get("func")
+            if func and not func(value):
+                return ValidationResult(False, msg)
+
+        return ValidationResult(True)
+
+    def _default_message(self) -> str:
+        """Return a sensible default error message for this rule type."""
+        if self.type == "required":
+            return "This field is required."
+        elif self.type == "email":
+            return "Enter a valid email address."
+        elif self.type == "stringLength":
+            min_len = self.params.get("min", 0)
+            max_len = self.params.get("max", None)
+            if max_len is None or max_len == float("inf"):
+                return f"Enter at least {min_len} characters."
+            return f"Enter between {min_len} and {max_len} characters."
+        elif self.type == "pattern":
+            return "Value does not match the required pattern."
+        elif self.type == "custom":
+            return "Invalid value."
+        return "Invalid input."
+
+    def _default_trigger(self) -> RuleTriggerType:
+        """Return the default trigger policy for this rule type."""
+        if self.type == "required":
+            return "always"
+        elif self.type in {"stringLength"}:
+            return "blur"
+        elif self.type in {"email", "pattern"}:
+            return "always"
+        elif self.type in {"custom"}:
+            return "manual"
+        return "blur"

bootstack/core/variables.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import ast
+import tkinter
+
+
+class SetVar(tkinter.Variable):
+    """
+    A tkinter variable that holds a set of values.
+
+    This variable serializes a Python set into its string representation
+    for storage and deserializes it back into a set on retrieval.
+    """
+
+    def __init__(self, master=None, value: set | None = None, name: str | None = None):
+        """
+        Initialize the SetVar.
+
+        Args:
+            master (Widget, optional): The parent widget. Defaults to None.
+            value (set, optional): The initial value. Defaults to an empty set.
+            name (str, optional): The name of the variable. Defaults to None.
+        """
+        if value is None:
+            value = set()
+        super().__init__(master, value, name)
+
+    def set(self, value: set | frozenset):
+        """
+        Set the variable to a new value.
+
+        The value is converted to its string representation for storage.
+
+        Args:
+            value (set | frozenset): The new value. Should be a set or frozenset.
+        """
+        if not isinstance(value, (set, frozenset)):
+            raise TypeError(f"Expected set or frozenset, got {type(value).__name__}")
+        super().set(repr(value))
+
+    def get(self) -> set:
+        """
+        Return the value of the variable as a Python set.
+
+        The string representation is deserialized back into a set.
+
+        Returns:
+            set: The current value of the variable.
+        """
+        value_str = super().get()
+        if not value_str:
+            return set()
+
+        try:
+            # Use literal_eval for safe evaluation of the string representation
+            deserialized_value = ast.literal_eval(value_str)
+            if isinstance(deserialized_value, (set, frozenset)):
+                return set(deserialized_value)
+            else:
+                return set()
+        except (ValueError, SyntaxError):
+            return set()