bootstack 0.1.0__py3-none-any.whl

bootstack/signals/signal.py

@@ -0,0 +1,353 @@
+import tkinter as tk
+import weakref
+from itertools import count
+from typing import Any, Callable, Generic, Type, TypeVar
+
+from bootstack.signals.types import TraceOperation
+from bootstack._core.variables import SetVar
+from bootstack.streams import Handle
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+# Weak registry of all realized signals. Cleared on App.destroy() (when no
+# other App is live) so module-level signals can be re-realized against the
+# next App's interpreter without dangling against a dead one.
+_realized: "weakref.WeakSet[Signal]" = weakref.WeakSet()
+
+# Global subscriber ID counter — unique across all Signal instances so that
+# Handle cancellation never accidentally removes the wrong entry.
+_sub_counter = count(1)
+
+
+def reset_realized_signals() -> None:
+    """Drop the Tk var from every realized signal.
+
+    Called on App.destroy() when no other App is live. Module-level signals
+    return to pending (unrealized) state and re-realize transparently the next
+    time a widget inside a new App binds them via .var / .name / .tk.
+    """
+    for sig in list(_realized):
+        try:
+            sig._drop_var()
+        except Exception:
+            pass
+
+
+class _SignalTrace:
+    """Manages the single bridge Tk trace on a realized Signal."""
+
+    def __init__(self, tk_var: tk.Variable):
+        self._var = tk_var
+        self._traces: dict[str, tuple[TraceOperation, Callable[..., Any]]] = {}
+
+    def add(
+            self,
+            operation: TraceOperation,
+            callback: Callable[[T], Any],
+            get_value: Callable[[], T],
+    ) -> str:
+        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:
+        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:
+            pass
+
+
+class Signal(Generic[T]):
+    """
+    A reactive value that widgets can bind to.
+
+    Holds a typed value and notifies subscribers when it changes. Read it by
+    calling the signal, update it with `set()`, derive new signals with
+    `map()`, and react to changes with `subscribe()`.
+
+    Bind a signal to a widget by passing it as `textsignal=` for text-bearing
+    widgets, or `signal=` for boolean and numeric widgets.
+
+    Signals may be constructed at module level (before `bs.App()` exists). The
+    backing Tk variable is created lazily on the first widget binding and torn
+    down when the App is destroyed, so the same signal can be reused across
+    successive App lifecycles.
+    """
+
+    _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._object_mode = not self._is_tk_native(value)
+        # _last is always the authoritative Python value — before realization it
+        # is the only store; after realization it stays in sync via the bridge.
+        self._last: T = value
+        # Tk var and bridge trace — None until the first widget binding.
+        self._var: tk.Variable | None = None
+        self._trace: _SignalTrace | None = None
+        self._bridge_fid: str | None = None
+        # Python-owned subscriber list (int id → callback). The bridge trace fans
+        # these out when a widget writes the Tk var; set() notifies them directly
+        # while unrealized. Replaces the old one-Tk-trace-per-subscriber model.
+        self._subscribers: dict[int, Callable[[T], Any]] = {}
+
+    @staticmethod
+    def _is_tk_native(value: Any) -> bool:
+        """Whether a value maps to a Tk variable that round-trips it losslessly."""
+        return isinstance(value, (bool, int, float, str, set))
+
+    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 _realize(self) -> None:
+        """Create the backing Tk variable and wire the single bridge trace.
+
+        Idempotent — safe to call multiple times. Only runs inside an App
+        context (widget bindings are always inside one), so a live interpreter
+        is guaranteed.
+        """
+        if self._var is not None:
+            return
+        self._var = self._create_variable(self._last)
+        self._trace = _SignalTrace(self._var)
+
+        def _bridge(value: T) -> None:
+            if not self._object_mode:
+                self._last = value
+            for cb in list(self._subscribers.values()):
+                cb(self._last)
+
+        self._bridge_fid = self._trace.add("write", _bridge, self)
+        _realized.add(self)
+
+    def _drop_var(self) -> None:
+        """Release the Tk var and bridge trace (called by reset_realized_signals)."""
+        if self._trace is not None and self._bridge_fid is not None:
+            self._trace.remove(self._bridge_fid)
+        self._var = None
+        self._trace = None
+        self._bridge_fid = None
+
+    def __call__(self) -> T:
+        """Get the current value of the signal."""
+        if self._var is None or self._object_mode:
+            return self._last
+        try:
+            value = self._var.get()
+            self._last = value
+            return value
+        except tk.TclError:
+            return self._last
+
+    @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.
+        """
+        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
+
+        self = cls.__new__(cls)
+        self._name = name or getattr(tk_var, "_name", str(tk_var))
+        self._type = py_type  # type: ignore[assignment]
+        self._object_mode = False
+        self._master = getattr(tk_var, "_master", None)
+        self._subscribers = {}
+        try:
+            current = tk_var.get()  # type: ignore[assignment]
+        except tk.TclError:
+            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]
+
+        # from_variable is immediately realized — the var already exists.
+        self._var = tk_var
+        self._trace = _SignalTrace(self._var)
+
+        def _bridge(value: T) -> None:
+            self._last = value
+            for cb in list(self._subscribers.values()):
+                cb(self._last)
+
+        self._bridge_fid = self._trace.add("write", _bridge, self)
+        _realized.add(self)
+        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 signal's type, except that an
+                `int` may be set on a `float`-typed signal (it is widened).
+
+        Raises:
+            TypeError: If the value type does not match the signal's type (and is
+                not an `int` widened to a `float`).
+        """
+        if type(value) is not self._type:
+            if self._type is float and type(value) is int:
+                value = float(value)  # type: ignore[assignment]
+            else:
+                raise TypeError(
+                    f"Expected {self._type.__name__}, got {type(value).__name__}"
+                )
+
+        if self._var is None:
+            # Unrealized — notify Python subscribers directly.
+            if self._last == value:
+                return
+            self._last = value
+            for cb in list(self._subscribers.values()):
+                cb(self._last)
+            return
+
+        if self._object_mode:
+            if self._last == value:
+                return
+            self._last = value
+            try:
+                self._var.set(str(value))
+            except tk.TclError:
+                pass
+            # Bridge trace fires from var.set() → notifies subscribers.
+            return
+
+        # Native-type, realized — let the Tk var fire the bridge trace.
+        try:
+            if self._var.get() == value:
+                return
+        except tk.TclError:
+            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.
+
+        The derived signal recomputes whenever this signal changes. It is held
+        weakly, so keep a reference to it — for example, by binding it to a
+        widget — or it will stop updating once garbage-collected.
+
+        Args:
+            transform: A function applied to the current and future values.
+
+        Returns:
+            A new read-only signal that stays updated with the transformed value.
+        """
+        derived = Signal(transform(self()))
+        weak_derived = weakref.ref(derived)
+
+        def update(value: T) -> None:
+            d = weak_derived()
+            if d is None:
+                return
+            d.set(transform(value))
+
+        self.subscribe(update)
+        return derived
+
+    def subscribe(self, callback: Callable[[T], Any], *, immediate: bool = False) -> Handle:
+        """
+        Subscribe to value changes of this signal.
+
+        Args:
+            callback: A function called with the new value whenever it changes.
+            immediate: When True, also call `callback` once with the current
+                value at subscription time. Defaults to False.
+
+        Returns:
+            A cancellable `Handle` — call `.cancel()` to stop listening, or use
+            it as a context manager to unsubscribe on exit.
+        """
+        fid = next(_sub_counter)
+        self._subscribers[fid] = callback
+        if immediate:
+            callback(self())
+        return Handle(lambda: self._subscribers.pop(fid, None))
+
+    @property
+    def name(self) -> str:
+        """The internal Tcl variable name. Accessing this realizes the signal."""
+        self._realize()
+        return self._name
+
+    @property
+    def type(self) -> Type[T]:
+        """The original type of the signal value."""
+        return self._type
+
+    @property
+    def var(self) -> tk.Variable:
+        """The backing `tk.Variable`. Accessing this realizes the signal."""
+        self._realize()
+        return self._var  # type: ignore[return-value]
+
+    @property
+    def tk(self) -> tk.Variable:
+        """Underlying `tk.Variable`. UNSUPPORTED — escape-hatch use only."""
+        self._realize()
+        return self._var  # type: ignore[return-value]
+
+    def __str__(self) -> str:
+        return self._name
+
+    def __repr__(self) -> str:
+        return self._name

bootstack/signals/types.py

@@ -0,0 +1,6 @@
+"""Type aliases for the signal and variable tracing system."""
+from typing import Literal
+
+TraceOperation = Literal["array", "read", "write", "unset"]
+"""The kind of variable access a trace callback reports — an `array` element
+access, a `read`, a `write`, or an `unset`."""

bootstack/store.py

@@ -0,0 +1,286 @@
+"""`Store` — a small, file-backed key-value store for application preferences.
+
+`Store` is the place to keep the little pieces of state an app wants to remember
+between runs: the chosen theme, a "show tips on startup" flag, recent files, the
+last-opened tab. It behaves like a dict, persists to a JSON file under the OS
+config directory, and writes through on every change by default.
+
+It is deliberately *not* a data source — there are no rows, ids, pagination, or
+queries. Reach for `MemoryDataSource` / `SqliteDataSource` for record-oriented
+data, and `Store` for "remember this setting".
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import threading
+from pathlib import Path
+from typing import Any, Iterator
+
+from bootstack._core.paths import app_config_file
+from bootstack.errors import SerializationError
+
+__all__ = ["Store"]
+
+_MISSING = object()
+
+
+def _active_app_name() -> str | None:
+    """Return the current App's name, or None when there is no active App."""
+    try:
+        from bootstack._runtime.app import get_app_settings
+
+        return get_app_settings().app_name
+    except Exception:
+        return None
+
+
+class Store:
+    """A persistent, dict-like key-value store for app preferences.
+
+    Construct one with a logical name and it lives at `<config>/<app>/<name>.json`
+    (the per-platform config directory — `Library/Application Support` on macOS,
+    `%APPDATA%` on Windows, `$XDG_CONFIG_HOME` on Linux), or pass an explicit
+    `path`. Read with `get()` or `store[key]`, write with `set()` or
+    `store[key] = value`; by default every change is saved immediately with an
+    atomic write, so a crash cannot corrupt the file.
+
+    Values must be JSON-serializable (scalars, lists, dicts); anything else
+    raises `SerializationError`. Keys must be strings. A missing or unreadable
+    file simply starts the store empty rather than raising.
+
+    `Store` does not require a running `App` — it is plain file I/O. When no
+    `app_name` is given it uses the active App's name if there is one, otherwise
+    `'bootstack'`.
+
+    Args:
+        name: Logical store name; the file is `<name>.json` under the per-app
+            config directory. Ignored when `path` is given.
+        path: An explicit file path, overriding `name`/`app_name`.
+        app_name: Override the per-app config sub-directory. Defaults to the
+            active App's name, or `'bootstack'`.
+        autosave: When True (default), persist on every change. When False,
+            changes stay in memory until `save()` is called.
+
+    Example:
+        ```python
+        store = Store("settings")
+        app = bs.App(theme=store.get("theme", "light"))
+        # later, when the user switches theme:
+        store.set("theme", "bootstrap-dark")
+        ```
+    """
+
+    def __init__(
+        self,
+        name: str = "settings",
+        *,
+        path: str | os.PathLike[str] | None = None,
+        app_name: str | None = None,
+        autosave: bool = True,
+    ) -> None:
+        if path is not None:
+            self._path = Path(path)
+        else:
+            if not name:
+                raise ValueError("Store: provide a name or an explicit path=.")
+            leaf = str(name)
+            if not leaf.endswith(".json"):
+                leaf = f"{leaf}.json"
+            self._path = app_config_file(leaf, app_name or _active_app_name())
+        self._autosave = autosave
+        self._lock = threading.RLock()
+        self._data: dict[str, Any] = {}
+        self._load()
+
+    # ----- persistence -----
+
+    def _load(self) -> None:
+        try:
+            raw = self._path.read_text(encoding="utf-8")
+        except (FileNotFoundError, OSError):
+            self._data = {}
+            return
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            # A corrupt file starts the store empty — prefs are not worth
+            # crashing an app over.
+            self._data = {}
+            return
+        self._data = data if isinstance(data, dict) else {}
+
+    def save(self) -> None:
+        """Write the store to disk now, atomically.
+
+        Useful when `autosave=False`, or to force a flush. Writes to a temporary
+        file and renames it over the target so a partial write never replaces
+        good data.
+
+        Raises:
+            OSError: If the directory cannot be created or the file written.
+        """
+        with self._lock:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self._path.with_name(f"{self._path.name}.tmp")
+            try:
+                tmp.write_text(
+                    json.dumps(self._data, indent=2, sort_keys=True),
+                    encoding="utf-8",
+                )
+                os.replace(tmp, self._path)
+            except BaseException:
+                try:
+                    tmp.unlink()
+                except OSError:
+                    pass
+                raise
+
+    def reload(self) -> None:
+        """Discard in-memory state and re-read the store from disk."""
+        with self._lock:
+            self._load()
+
+    def _autosaved(self) -> None:
+        if self._autosave:
+            self.save()
+
+    @staticmethod
+    def _check_key(key: Any) -> None:
+        if not isinstance(key, str):
+            raise TypeError(
+                f"Store keys must be strings, got {type(key).__name__}."
+            )
+
+    @staticmethod
+    def _check_value(key: str, value: Any) -> None:
+        try:
+            json.dumps(value)
+        except (TypeError, ValueError) as exc:
+            raise SerializationError(
+                f"Store value for key {key!r} is not JSON-serializable: {exc}. "
+                f"A Store holds JSON values only (scalars, lists, dicts)."
+            ) from exc
+
+    @property
+    def path(self) -> Path:
+        """The file this store reads from and writes to."""
+        return self._path
+
+    # ----- core access -----
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return the value for `key`, or `default` if it is not present."""
+        with self._lock:
+            return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set `key` to `value` and (by default) persist immediately.
+
+        Args:
+            key: A string key.
+            value: A JSON-serializable value.
+
+        Raises:
+            TypeError: If `key` is not a string.
+            SerializationError: If `value` is not JSON-serializable.
+        """
+        self._check_key(key)
+        self._check_value(key, value)
+        with self._lock:
+            self._data[key] = value
+            self._autosaved()
+
+    def delete(self, key: str) -> None:
+        """Remove `key` if present; a no-op when it is missing."""
+        with self._lock:
+            if key in self._data:
+                del self._data[key]
+                self._autosaved()
+
+    def setdefault(self, key: str, default: Any = None) -> Any:
+        """Return `key`'s value, inserting `default` first if it is missing."""
+        self._check_key(key)
+        with self._lock:
+            if key not in self._data:
+                self._check_value(key, default)
+                self._data[key] = default
+                self._autosaved()
+            return self._data[key]
+
+    def update(self, values: "dict[str, Any] | None" = None, **kwargs: Any) -> None:
+        """Merge values in, persisting once at the end.
+
+        Accepts a mapping, keyword arguments, or both (mirroring `dict.update`),
+        so `store.update(theme="dark")` and `store.update({"theme": "dark"})`
+        are equivalent.
+        """
+        merged: dict[str, Any] = {}
+        if values:
+            merged.update(values)
+        if kwargs:
+            merged.update(kwargs)
+        for key, value in merged.items():
+            self._check_key(key)
+            self._check_value(key, value)
+        with self._lock:
+            if merged:
+                self._data.update(merged)
+                self._autosaved()
+
+    def clear(self) -> None:
+        """Remove every key, persisting the now-empty store."""
+        with self._lock:
+            if self._data:
+                self._data.clear()
+                self._autosaved()
+
+    def keys(self) -> list[str]:
+        """Return the keys, as a list snapshot."""
+        with self._lock:
+            return list(self._data.keys())
+
+    def values(self) -> list[Any]:
+        """Return the values, as a list snapshot."""
+        with self._lock:
+            return list(self._data.values())
+
+    def items(self) -> list[tuple[str, Any]]:
+        """Return the `(key, value)` pairs, as a list snapshot."""
+        with self._lock:
+            return list(self._data.items())
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a deep copy of the store's contents as a plain dict."""
+        with self._lock:
+            return copy.deepcopy(self._data)
+
+    # ----- mapping protocol -----
+
+    def __getitem__(self, key: str) -> Any:
+        with self._lock:
+            return self._data[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.set(key, value)
+
+    def __delitem__(self, key: str) -> None:
+        with self._lock:
+            del self._data[key]
+            self._autosaved()
+
+    def __contains__(self, key: object) -> bool:
+        with self._lock:
+            return key in self._data
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.keys())
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._data)
+
+    def __repr__(self) -> str:
+        return f"Store(path={str(self._path)!r}, keys={len(self)})"

bootstack/streams/__init__.py

@@ -0,0 +1,12 @@
+"""Composable event-stream pipelines for bootstack widgets.
+
+Call an `on_*()` shorthand with no handler to get a `Stream`; chain
+operators (`map`, `filter`, `debounce`, …) and finish with `listen()`,
+which returns a cancellable `Handle`.
+"""
+from bootstack.streams._stream import Handle, Stream
+
+__all__ = [
+    "Handle",
+    "Stream",
+]