bootstack 0.1.0__py3-none-any.whl

bootstack/scheduling/_schedule.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import time
+import tkinter as tk
+from datetime import datetime
+from typing import Any, Callable, Optional
+
+
+class Job:
+    """Handle for a scheduled task.
+
+    Returned by every `Schedule` method. Call `.cancel()` to stop a pending
+    job before it fires. Truthy while active, falsy once cancelled or complete.
+    """
+
+    __slots__ = ("_owner", "_after_id", "_active", "_discard")
+
+    def __init__(self, owner: tk.Misc, discard: Callable[[], None]) -> None:
+        self._owner = owner
+        self._after_id: Optional[str] = None
+        self._active: bool = True
+        self._discard = discard
+
+    def cancel(self) -> None:
+        """Cancel the job if it has not already fired or been cancelled."""
+        if not self._active:
+            return
+        try:
+            if self._after_id is not None:
+                self._owner.after_cancel(self._after_id)
+        except Exception:
+            pass
+        finally:
+            self._after_id = None
+            self._active = False
+            self._discard()
+
+    def __bool__(self) -> bool:
+        return self._active
+
+    def __repr__(self) -> str:
+        state = "active" if self._active else "cancelled"
+        return f"<Job {state}>"
+
+
+class Schedule:
+    """Timed task scheduler tied to a widget's lifetime.
+
+    Runs callbacks after a delay, at idle, at an absolute time, or on a repeat,
+    with automatic cleanup: all pending jobs are cancelled when the owner widget
+    is destroyed.
+
+    Usage::
+
+        sched = widget.schedule          # property on every public widget
+        sched = Schedule(widget)      # or construct directly
+
+        job = sched.delay(500, callback)   # one-shot after delay
+        sched.idle(callback)               # one-shot at next idle
+        sched.at(datetime(...), callback)  # one-shot at absolute time
+        job = sched.every(1000, tick)      # repeating every 1 second
+
+        job.cancel()        # cancel one job
+        sched.cancel_all()  # cancel everything
+
+    All jobs are automatically cancelled when `owner` is destroyed.
+
+    Args:
+        owner: Widget that owns this scheduler. Its lifetime bounds all created
+            jobs.
+    """
+
+    __slots__ = ("_owner", "_jobs")
+
+    def __init__(self, owner: Any) -> None:
+        # Accept both public wrapper widgets and the underlying widget object.
+        if hasattr(owner, "_internal"):
+            owner = owner._internal
+        self._owner: tk.Misc = owner
+        self._jobs: set[Job] = set()
+        try:
+            owner.bind("<Destroy>", self._on_destroy, add=True)
+        except Exception:
+            pass
+
+    # ----- public API --------------------------------------------------------
+
+    def delay(self, ms: int, fn: Callable, *args: Any, **kwargs: Any) -> Job:
+        """Schedule `fn` to run once after `ms` milliseconds.
+
+        Args:
+            ms: Delay in milliseconds (clamped to 0).
+            fn: Callable to invoke.
+            *args: Positional arguments forwarded to `fn`.
+            **kwargs: Keyword arguments forwarded to `fn`.
+
+        Returns:
+            Job handle — call `.cancel()` to prevent execution.
+        """
+        ms = max(0, int(ms))
+        job = Job(self._owner, lambda: self._jobs.discard(job))
+
+        def _run():
+            job._after_id = None
+            if job._active:
+                job._active = False
+                self._jobs.discard(job)
+                fn(*args, **kwargs)
+
+        job._after_id = self._owner.after(ms, _run)
+        self._jobs.add(job)
+        return job
+
+    def idle(self, fn: Callable, *args: Any, **kwargs: Any) -> Job:
+        """Schedule `fn` to run once when the event loop is next idle.
+
+        Args:
+            fn: Callable to invoke.
+            *args: Positional arguments forwarded to `fn`.
+            **kwargs: Keyword arguments forwarded to `fn`.
+
+        Returns:
+            Job handle — call `.cancel()` to prevent execution.
+        """
+        job = Job(self._owner, lambda: self._jobs.discard(job))
+
+        def _run():
+            job._after_id = None
+            if job._active:
+                job._active = False
+                self._jobs.discard(job)
+                fn(*args, **kwargs)
+
+        job._after_id = self._owner.after_idle(_run)
+        self._jobs.add(job)
+        return job
+
+    def at(self, when: datetime, fn: Callable, *args: Any, **kwargs: Any) -> Job:
+        """Schedule `fn` to run at an absolute `datetime`.
+
+        If `when` is in the past the job runs as soon as possible.
+
+        Args:
+            when: Target `datetime` (local time).
+            fn: Callable to invoke.
+            *args: Positional arguments forwarded to `fn`.
+            **kwargs: Keyword arguments forwarded to `fn`.
+
+        Returns:
+            Job handle.
+        """
+        delay_ms = max(0, int((when - datetime.now()).total_seconds() * 1000))
+        return self.delay(delay_ms, fn, *args, **kwargs)
+
+    def every(self, ms: int, fn: Callable, *args: Any, **kwargs: Any) -> Job:
+        """Schedule `fn` to run repeatedly every `ms` milliseconds.
+
+        Compensates for callback execution time to reduce drift. If the
+        callback raises an exception the interval is stopped and the exception
+        is re-raised into the application's error handler.
+
+        Args:
+            ms: Period in milliseconds (minimum 1).
+            fn: Callable to invoke on each tick.
+            *args: Positional arguments forwarded to `fn`.
+            **kwargs: Keyword arguments forwarded to `fn`.
+
+        Returns:
+            Job handle — call `.cancel()` to stop the repeating task.
+        """
+        period = max(1, int(ms))
+        job = Job(self._owner, lambda: self._jobs.discard(job))
+
+        def _tick():
+            if not job._active:
+                return
+            start = time.perf_counter()
+            try:
+                fn(*args, **kwargs)
+            except Exception:
+                # Stop the interval cleanly before re-raising.
+                job._active = False
+                job._after_id = None
+                self._jobs.discard(job)
+                raise
+            if job._active:
+                elapsed = int((time.perf_counter() - start) * 1000)
+                next_ms = max(0, period - elapsed)
+                try:
+                    job._after_id = self._owner.after(next_ms, _tick)
+                except Exception:
+                    job._active = False
+                    job._after_id = None
+                    self._jobs.discard(job)
+
+        job._after_id = self._owner.after(period, _tick)
+        self._jobs.add(job)
+        return job
+
+    def cancel_all(self) -> None:
+        """Cancel all pending jobs created by this `Schedule`."""
+        for j in list(self._jobs):
+            try:
+                j.cancel()
+            except Exception:
+                pass
+        self._jobs.clear()
+
+    # ----- internal ----------------------------------------------------------
+
+    def _on_destroy(self, event: Any = None) -> None:
+        # `<Destroy>` propagates up from descendants, so this handler fires
+        # whenever any child of the owner is destroyed. Only cancel the owner's
+        # jobs when the owner itself is going away — otherwise destroying a child
+        # widget would wipe out unrelated scheduled work on its ancestors.
+        if event is not None and getattr(event, "widget", None) is not self._owner:
+            return
+        self.cancel_all()

bootstack/shortcuts.py

@@ -0,0 +1,21 @@
+"""Cross-platform keyboard shortcuts — the public home for the shortcut service.
+
+Register named shortcuts with platform-agnostic patterns (`Mod+S` becomes
+`Ctrl+S` on Windows/Linux and `⌘S` on macOS), bind them to an app, and let
+menus display the resolved shortcut text automatically.
+
+Usage::
+
+    from bootstack.shortcuts import get_shortcuts
+
+    shortcuts = get_shortcuts()
+    shortcuts.register("save", "Mod+S", save_file)
+    shortcuts.bind_to(app)
+"""
+from bootstack._runtime.shortcuts import Shortcut, Shortcuts, get_shortcuts
+
+__all__ = [
+    "Shortcuts",
+    "Shortcut",
+    "get_shortcuts",
+]

bootstack/signals/README.md

@@ -0,0 +1,98 @@
+Signals for bootstack
+=====================
+
+Lightweight reactive state. A ``Signal[T]`` holds a value, notifies subscribers
+when it changes, and can be bound two-way to widgets. It is backed by a Tk
+variable, but that variable is created lazily, so the Tk surface never leaks
+into the public API.
+
+> The user-facing guide is ``docs/reference/signals.rst`` (teaching) and the
+> API Reference page for ``bootstack.signals`` (lookup). This README covers the
+> package internals; keep it in sync with ``signal.py``.
+
+Architecture
+- ``Signal[T]`` (public): the reactive cell — ``signal()`` to read, ``set()`` to
+  write, ``subscribe()`` to observe, ``map()`` to derive.
+- Lazy Tk-var realization: ``Signal(...)`` creates **no** Tk variable at
+  construction, so a signal can be created at module level (before any ``App``).
+  The backing variable is realized on first bind/escape-hatch access against the
+  running interpreter, and re-realized cleanly across ``App`` lifecycles.
+- Object mode: values that are not Tk-native (anything other than
+  ``bool``/``int``/``float``/``str``/``set`` — e.g. a ``date`` or a dataclass)
+  are held as the authoritative Python object; the Tk variable is used only as a
+  change-notification bus. Native values are stored in the Tk variable directly.
+- ``_SignalTrace`` (internal): manages the Tcl variable trace
+  (``trace_add``/``trace_remove``).
+
+Key behaviors
+- Read / write: ``signal()`` returns the current value; ``signal.set(v)`` updates
+  it. A ``set()`` to an equal value is a no-op (no notification).
+- Subscriptions: ``subscribe(callback, *, immediate=False)`` returns a
+  ``streams.Handle``; call ``handle.cancel()`` to unsubscribe. ``immediate=True``
+  fires the callback once with the current value at subscribe time.
+- Derived signals: ``map(transform)`` returns a new signal that follows this one.
+  A weak reference keeps the parent from holding the derived signal alive.
+- Robustness: the last value is cached and returned even if the backing variable
+  has been dropped (e.g. between ``App`` lifecycles).
+- Escape hatch: ``Signal.from_variable(tk_var)`` wraps an existing Tk variable,
+  and ``signal.var`` exposes the backing variable. These are the only Tk-aware
+  paths; everything else stays Tk-free.
+
+Usage
+1) Quick start (works at module level — no ``App`` required)
+```python
+from bootstack.signals import Signal
+
+count = Signal(0)
+print(count())        # -> 0
+count.set(1)
+print(count())        # -> 1
+```
+
+2) Two-way binding to a widget
+```python
+import bootstack as bs
+
+with bs.App() as app:
+    name = bs.Signal("")
+    bs.TextField(textsignal=name)          # edits flow into the signal
+    bs.Label(textsignal=name.map(lambda v: f"Hello, {v}!"))  # derived display
+app.run()
+```
+
+3) Subscribing and unsubscribing
+```python
+import bootstack as bs
+
+with bs.App() as app:
+    flag = bs.Signal(False)
+
+    def on_flag(value):
+        print("flag:", value)
+
+    handle = flag.subscribe(on_flag, immediate=True)  # prints: flag: False
+    flag.set(True)                                     # prints: flag: True
+    handle.cancel()                                    # stop observing
+app.run()
+```
+
+4) Typed (object-mode) values
+```python
+from datetime import date
+import bootstack as bs
+
+with bs.App():
+    due = bs.Signal(date.today())
+    bs.DateField(signal=due)        # binds the typed value
+    print(type(due()))              # -> <class 'datetime.date'> (not str)
+```
+
+Import path
+- ``import bootstack as bs; bs.Signal``
+- ``from bootstack.signals import Signal``
+
+Notes
+- The UI toolkit is not thread-safe. Marshal cross-thread updates onto the UI
+  via the framework's scheduling, not by touching the signal from a worker
+  thread.
+- Keep subscriber callbacks fast; offload long-running work.

bootstack/signals/__init__.py

@@ -0,0 +1,10 @@
+"""Reactive signal primitives for bootstack widgets."""
+from .signal import Signal
+
+__all__ = [
+    "Signal",
+]
+
+# TraceOperation is an internal low-level type for variable-trace callbacks
+# (no public Signal method exposes it). Import it from `bootstack.signals.types`
+# if internal code needs it.

bootstack/signals/integration.py

@@ -0,0 +1,100 @@
+"""Integration helpers for using Signal with tkinter/ttk widgets.
+
+Call `enable_widget_integration()` once early (after creating your Tk/Window)
+to allow passing `Signal` objects directly to widget constructors and
+`configure(...)` for options like `textvariable` and `variable`.
+
+Without this, some environments/widgets may not coerce custom objects to the
+required Tcl variable name automatically.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Tuple
+
+import tkinter as tk
+import tkinter.ttk as ttk
+
+
+def _is_signal(obj: Any) -> bool:
+    try:
+        # Cheap duck-typing to avoid hard import dependency
+        m = type(obj).__module__
+        return (
+            (m.startswith("bootstack.signals") or m.startswith("bootstack.signals"))
+            and hasattr(obj, "name")
+            and hasattr(obj, "var")
+        )
+    except Exception:
+        return False
+
+
+def _coerce_kwargs(kwargs: dict[str, Any]) -> None:
+    for key in ("textvariable", "variable"):
+        if key in kwargs:
+            val = kwargs[key]
+            if _is_signal(val):
+                kwargs[key] = str(val)
+
+
+def _wrap_init(cls: type) -> None:
+    orig_init = cls.__init__  # type: ignore[attr-defined]
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # type: ignore[override]
+        _coerce_kwargs(kwargs)
+        orig_init(self, *args, **kwargs)  # type: ignore[misc]
+
+    cls.__init__ = __init__  # type: ignore[assignment]
+
+
+def _wrap_configure(cls: type) -> None:
+    orig_config = cls.configure  # type: ignore[attr-defined]
+
+    def configure(self, cnf: Any = None, **kwargs: Any):  # type: ignore[override]
+        if isinstance(cnf, dict):
+            _coerce_kwargs(cnf)
+        _coerce_kwargs(kwargs)
+        return orig_config(self, cnf, **kwargs)  # type: ignore[misc]
+
+    cls.configure = configure  # type: ignore[assignment]
+    cls.config = configure  # type: ignore[assignment]
+
+
+def _patch(classes: Iterable[type]) -> None:
+    for cls in classes:
+        _wrap_init(cls)
+        _wrap_configure(cls)
+
+
+def enable_widget_integration() -> None:
+    """Enable passing `Signal` directly to widget options.
+
+    Patches common tk/ttk widget classes so that when you pass a `Signal`
+    instance to `textvariable` or `variable` in the constructor or in
+    `configure(...)`, it is automatically converted to its Tcl name.
+    """
+
+    ttk_classes: Tuple[type, ...] = (
+        ttk.Entry,
+        ttk.Label,
+        ttk.Button,
+        ttk.Checkbutton,
+        ttk.Radiobutton,
+        ttk.Combobox,
+        ttk.Spinbox,
+        ttk.Progressbar,
+        ttk.Scale,
+        ttk.OptionMenu,
+    )
+
+    tk_classes: Tuple[type, ...] = (
+        tk.Entry,
+        tk.Label,
+        tk.Button,
+        tk.Checkbutton,
+        tk.Radiobutton,
+    )
+
+    _patch(ttk_classes)
+    _patch(tk_classes)
+