bootstack 0.1.0__py3-none-any.whl

bootstack/dev/_capture.py

@@ -0,0 +1,141 @@
+"""Capture a ``with bs.App()`` block's body from source for hot reload.
+
+PROVISIONAL — part of the carved-out ``bootstack.dev`` surface.
+
+The body of a ``with`` block runs in the caller's frame and is never handed to
+the context manager, so a flag alone cannot re-run it. In dev mode the App
+captures *where* its body lives (file + the ``as`` target name) and, on each
+reload, re-reads the file and re-extracts the matching block's statements — so a
+save is picked up. Matching is by the ``as`` target name, which is stable across
+edits that shift line numbers.
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from types import FrameType
+from typing import Any
+
+
+@dataclass
+class BodyCapture:
+    """Where a reloadable ``with`` block lives, plus its compiled body cache."""
+
+    filename: str
+    """Absolute path of the source file holding the ``with`` block."""
+    target_names: tuple[str, ...]
+    """The ``as <name>`` targets of the block (e.g. ``("app",)``)."""
+    module_globals: dict
+    """The module namespace the body executes in (frame globals)."""
+    with_lineno: int
+    """Line of the ``with`` statement at capture time (a matching hint only)."""
+
+    @property
+    def is_capturable(self) -> bool:
+        """Whether this capture can drive an in-process reload."""
+        return bool(self.filename) and bool(self.target_names)
+
+
+def capture_from_frame(frame: FrameType) -> BodyCapture | None:
+    """Capture the enclosing ``with`` block from a caller frame.
+
+    Returns None when the block is not reloadable in-process — notably when it
+    is authored inside a function (frame locals differ from globals), so the
+    body's names cannot be safely re-bound by re-exec.
+    """
+    # A module-level `with` runs with locals IS globals. Inside a function the
+    # two differ; re-execing the body into globals would mis-scope its names.
+    if frame.f_locals is not frame.f_globals:
+        return None
+
+    filename = frame.f_code.co_filename
+    lineno = frame.f_lineno
+    try:
+        source = _read(filename)
+    except OSError:
+        return None
+
+    node = _find_with_node(source, lineno)
+    if node is None:
+        return None
+    targets = _with_target_names(node)
+    if not targets:
+        return None
+
+    return BodyCapture(
+        filename=filename,
+        target_names=targets,
+        module_globals=frame.f_globals,
+        with_lineno=node.lineno,
+    )
+
+
+def find_current_body(capture: BodyCapture) -> list[ast.stmt]:
+    """Re-read the source and return the matching block's current statements.
+
+    Raises ``SyntaxError`` if the file no longer parses (the caller renders a
+    banner and keeps the process alive), or ``RuntimeError`` if the block can no
+    longer be located.
+    """
+    source = _read(capture.filename)
+    tree = ast.parse(source, capture.filename)  # SyntaxError propagates
+    node = _match_with_node(tree, capture)
+    if node is None:
+        raise RuntimeError(
+            "hot reload: could not locate the `with` block to reload "
+            f"(looking for `as {', '.join(capture.target_names)}` in "
+            f"{capture.filename})"
+        )
+    return list(node.body)
+
+
+def compile_body(filename: str, body: list[ast.stmt]) -> Any:
+    """Compile a block body (list of statements) into an executable code object."""
+    module = ast.Module(body=list(body), type_ignores=[])
+    ast.fix_missing_locations(module)
+    return compile(module, filename, "exec")
+
+
+# --- internals ---------------------------------------------------------------
+
+
+def _read(filename: str) -> str:
+    with open(filename, "r", encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _find_with_node(source: str, lineno: int) -> ast.With | None:
+    """Find the top-level ``with`` node at (or nearest to) a line."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    candidates = [n for n in tree.body if isinstance(n, ast.With)]
+    if not candidates:
+        return None
+    for node in candidates:
+        if node.lineno == lineno:
+            return node
+    return min(candidates, key=lambda n: abs(n.lineno - lineno))
+
+
+def _match_with_node(tree: ast.Module, capture: BodyCapture) -> ast.With | None:
+    """Locate the block to reload, preferring a target-name match."""
+    candidates = [n for n in tree.body if isinstance(n, ast.With)]
+    if not candidates:
+        return None
+    want = set(capture.target_names)
+    by_name = [n for n in candidates if want & set(_with_target_names(n))]
+    if by_name:
+        # Prefer the one nearest the original line if several share the name.
+        return min(by_name, key=lambda n: abs(n.lineno - capture.with_lineno))
+    return min(candidates, key=lambda n: abs(n.lineno - capture.with_lineno))
+
+
+def _with_target_names(node: ast.With) -> tuple[str, ...]:
+    names = []
+    for item in node.items:
+        var = item.optional_vars
+        if isinstance(var, ast.Name):
+            names.append(var.id)
+    return tuple(names)

bootstack/dev/_env.py

@@ -0,0 +1,43 @@
+"""Dev-mode environment detection for bootstack hot reload.
+
+PROVISIONAL — the `bootstack.dev` surface ships in 0.1.0 but is carved out of
+the API freeze: it may change in a minor release while it settles.
+
+`bootstack dev <file>` launches an app with these variables set so that
+`App.run()` installs the hot-reload loop instead of a plain mainloop.
+"""
+from __future__ import annotations
+
+import os
+
+#: Set to ``"1"`` by ``bootstack dev`` to enable hot reload in the child process.
+DEV_ENV_VAR = "BOOTSTACK_DEV"
+
+#: Selects the reload strategy: ``"inprocess"`` (default — re-exec the with-body
+#: in place, preserving state) or ``"restart"`` (re-exec the whole process on
+#: save). ``bootstack dev --restart`` sets this to ``"restart"``.
+DEV_MODE_VAR = "BOOTSTACK_DEV_MODE"
+
+#: Reasonable minimum window size applied under ``bootstack dev`` when the app
+#: did not set its own ``min_size`` — so the reload window starts usable and a
+#: reload that shrinks content never collapses it below this floor. Dev-only;
+#: production launches are unaffected.
+DEV_MIN_SIZE = (640, 480)
+
+#: Exit code the dev child uses to ask the ``bootstack dev`` supervisor to
+#: relaunch it — the cross-platform restart signal. The app exits with this code
+#: instead of calling ``os.execv``, which on Windows spawns a new process (new
+#: PID) and terminates the caller rather than replacing it in place. The CLI
+#: supervisor re-launches on this code; any other exit code ends the session.
+DEV_RESTART_EXIT_CODE = 42
+
+
+def is_dev_mode() -> bool:
+    """Return True when running under ``bootstack dev`` (hot reload enabled)."""
+    return os.environ.get(DEV_ENV_VAR) == "1"
+
+
+def dev_mode() -> str:
+    """Return the configured reload strategy: ``"inprocess"`` or ``"restart"``."""
+    mode = os.environ.get(DEV_MODE_VAR, "inprocess")
+    return mode if mode in ("inprocess", "restart") else "inprocess"

bootstack/dev/_registry.py

@@ -0,0 +1,140 @@
+"""Registry behind ``@reloadable`` for deterministic multi-file hot reload.
+
+PROVISIONAL — part of the carved-out ``bootstack.dev`` surface.
+
+A page builder in another file calls bootstack widgets into whatever container
+is active when it runs (the thread-local container stack). ``@reloadable`` marks
+such a builder so the reloader can, when only that file changes, re-invoke the
+*current* version of the builder into the exact region it last painted —
+bypassing the entry module's possibly-stale ``from x import f`` binding and
+giving per-page reload granularity.
+
+In production (no dev mode) the decorator is a transparent no-op.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from bootstack.dev._env import is_dev_mode
+
+# qualified-name -> the most recently defined builder function. Reloading a page
+# module re-runs its top level, which re-registers the builder under the same
+# qualname, so this always points at the live version.
+_builders: dict[str, Callable] = {}
+
+# qualified-name -> list of mount records describing where the builder painted,
+# so a per-page reload can clear and rebuild just those regions.
+_mounts: dict[str, list["MountRecord"]] = {}
+
+
+class MountRecord:
+    """Where a ``@reloadable`` builder painted, for targeted re-invocation."""
+
+    __slots__ = ("container", "args", "kwargs")
+
+    def __init__(self, container: Any, args: tuple, kwargs: dict) -> None:
+        self.container = container
+        self.args = args
+        self.kwargs = kwargs
+
+
+def reloadable(func: Callable) -> Callable:
+    """Mark a builder function as a hot-reload unit (no-op in production).
+
+    Apply to a function that *builds* part of the UI by calling widgets into the
+    active container::
+
+        @reloadable
+        def build_dashboard(db):
+            bs.Label("Dashboard", font="heading-lg")
+            bs.DataTable(data_source=db)
+
+    In dev mode the framework records where the builder mounted; when its file is
+    saved, only that region is torn down and rebuilt with the new code. Outside
+    dev mode the function is returned unchanged.
+    """
+    if not is_dev_mode():
+        return func
+
+    qualname = f"{func.__module__}.{func.__qualname__}"
+    # Register at DECORATION time so importlib.reload (which re-runs the module
+    # top level, re-decorating) refreshes the builder to the new version. The
+    # wrapper then always invokes the current registration.
+    _builders[qualname] = func
+
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        from bootstack.widgets._core.context import current_container
+
+        container = current_container()
+        if container is not None:
+            _mounts.setdefault(qualname, []).append(
+                MountRecord(container, args, kwargs)
+            )
+        return _builders.get(qualname, func)(*args, **kwargs)
+
+    wrapper.__wrapped__ = func  # type: ignore[attr-defined]
+    wrapper.__name__ = getattr(func, "__name__", "reloadable")
+    wrapper.__qualname__ = getattr(func, "__qualname__", "reloadable")
+    wrapper.__doc__ = func.__doc__
+    wrapper._bs_reloadable_qualname = qualname  # type: ignore[attr-defined]
+    return wrapper
+
+
+def builders_in_module(module_name: str) -> list[str]:
+    """Return the qualnames of registered builders defined in a module."""
+    prefix = module_name + "."
+    return [q for q in _builders if q.startswith(prefix)]
+
+
+def reinvoke(qualname: str) -> bool:
+    """Clear and rebuild every region a builder painted. Returns True if any ran.
+
+    Used for per-page reload: when only a page file changed, its builder(s) are
+    re-invoked into their recorded regions instead of re-running the entry body.
+    """
+    from bootstack.dev._reset import clear_container
+    from bootstack.widgets._core.context import push_container, pop_container
+
+    func = _builders.get(qualname)
+    records = _mounts.get(qualname)
+    if func is None or not records:
+        return False
+
+    ran = False
+    for record in list(records):
+        container = record.container
+        if not _container_alive(container):
+            records.remove(record)
+            continue
+        clear_container(container)
+        push_container(container)
+        try:
+            func(*record.args, **record.kwargs)
+            ran = True
+        finally:
+            pop_container(container)
+    return ran
+
+
+def reset_mounts() -> None:
+    """Forget mount records (used before a full rebuild re-records them).
+
+    Builders are kept — they are keyed by qualname and overwritten when their
+    module reloads, so there is nothing stale to clear, and dropping them would
+    discard registrations from modules that did not reload this pass.
+    """
+    _mounts.clear()
+
+
+def reset() -> None:
+    """Forget all registered builders and mount records (used on teardown)."""
+    _builders.clear()
+    _mounts.clear()
+
+
+def _container_alive(container: Any) -> bool:
+    internal = getattr(container, "_internal", container)
+    try:
+        return bool(internal.winfo_exists())
+    except Exception:
+        return False

bootstack/dev/_reloader.py

@@ -0,0 +1,351 @@
+"""The hot-reload engine: watch, re-exec, recover.
+
+PROVISIONAL — part of the carved-out ``bootstack.dev`` surface.
+
+Two strategies, chosen in :func:`install_reloader`:
+
+* **in-process** (default) — on save, re-read the entry file, reset the region
+  the ``with`` body built, and re-exec the body in place. Module-level state
+  (signals, datasources, stores) lives outside the body and survives. Multi-file
+  edits reload the changed page modules first; ``@reloadable`` builders rebuild
+  just their own region.
+* **restart** — on save, exit with a sentinel code so the ``bootstack dev``
+  supervisor relaunches the process. The floor for apps that aren't a
+  module-level ``with bs.App()``; window geometry is persisted so it re-opens
+  where it was. (We avoid ``os.execv``: on Windows it does not replace the
+  process in place.)
+
+The watcher only enqueues; all Tk work happens on a main-thread ``after`` pump,
+so the one tkinter threading rule is never broken.
+"""
+from __future__ import annotations
+
+import os
+import queue
+import sys
+import traceback
+from typing import Any
+
+from bootstack.dev._capture import BodyCapture, compile_body, find_current_body
+from bootstack.dev._env import dev_mode, is_dev_mode
+from bootstack.dev._watcher import PollWatcher
+
+_PREFIX = "[bootstack dev]"
+
+
+def _project_watch_root(start: str) -> str:
+    """Widen the watch root from a starting file to the project tree.
+
+    Walks up from `start` looking for a `bootstack.toml`; when found, watches its
+    `src/` subtree if present (the conventional layout) else the project dir — so
+    edits to any module in the project, not just the entry file's directory, are
+    picked up. Falls back to the starting file's directory when no project marker
+    is found.
+    """
+    start = os.path.abspath(start)
+    cur = start if os.path.isdir(start) else os.path.dirname(start)
+    base = cur
+    for _ in range(40):  # bounded walk-up
+        if os.path.isfile(os.path.join(cur, "bootstack.toml")):
+            src = os.path.join(cur, "src")
+            return src if os.path.isdir(src) else cur
+        parent = os.path.dirname(cur)
+        if parent == cur:
+            break
+        cur = parent
+    return base
+
+
+def install_reloader(app: Any) -> None:
+    """Install the appropriate reloader for the running app, if in dev mode."""
+    if not is_dev_mode():
+        return
+    mode = dev_mode()
+    supports = getattr(app, "_dev_supports_inprocess", False)
+    capture: BodyCapture | None = getattr(app, "_dev_body", None)
+    in_process_ok = supports and capture is not None and capture.is_capturable
+
+    if mode == "restart" or not in_process_ok:
+        if mode != "restart":
+            if not supports:
+                _log(
+                    "in-process reload isn't supported for this app type yet - "
+                    "using process restart on save"
+                )
+            elif capture is None or not capture.is_capturable:
+                _log(
+                    "in-process reload needs a module-level `with bs.App()` - "
+                    "using process restart on save"
+                )
+        _RestartReloader(app).install()
+        return
+
+    _InProcessReloader(app, capture).install()
+
+
+def _log(message: str) -> None:
+    print(f"{_PREFIX} {message}", flush=True)
+
+
+class _BaseReloader:
+    """Shared watcher + main-thread pump plumbing."""
+
+    def __init__(self, app: Any) -> None:
+        self.app = app
+        self.root = app._internal
+        self._queue: "queue.Queue[set[str]]" = queue.Queue()
+        self._watcher: PollWatcher | None = None
+        self._pump_id: Any = None
+
+    def _watch_root(self) -> str:
+        raise NotImplementedError
+
+    def install(self) -> None:
+        self._watcher = PollWatcher(self._watch_root(), self._queue.put)
+        self._watcher.start()
+        self._schedule_pump()
+
+    def _schedule_pump(self) -> None:
+        try:
+            self._pump_id = self.root.after(120, self._pump)
+        except Exception:
+            self._pump_id = None
+
+    def _pump(self) -> None:
+        changed: set[str] = set()
+        try:
+            while True:
+                changed |= self._queue.get_nowait()
+        except queue.Empty:
+            pass
+        if changed:
+            try:
+                self._handle(changed)
+            except Exception:
+                traceback.print_exc()
+        try:
+            if self.root.winfo_exists():
+                self._schedule_pump()
+        except Exception:
+            pass
+
+    def _handle(self, changed: set[str]) -> None:
+        raise NotImplementedError
+
+
+class _RestartReloader(_BaseReloader):
+    """Re-exec the whole process on save (the robust floor)."""
+
+    def install(self) -> None:
+        super().install()
+        _log(f"watching for changes - process restart on save (mode={dev_mode()})")
+
+    def _watch_root(self) -> str:
+        entry = sys.argv[0] if sys.argv and sys.argv[0] else os.getcwd()
+        return _project_watch_root(entry) or os.getcwd()
+
+    def _handle(self, changed: set[str]) -> None:
+        _log("change detected - restarting")
+        if self._watcher is not None:
+            self._watcher.stop()
+        # Persist geometry (and, for a shell, the selected page) so the
+        # relaunched process re-opens in place. We exit immediately, skipping
+        # destroy, so save now.
+        for attr in ("_save_window_state", "_save_nav_state"):
+            save = getattr(self.app._internal, attr, None)
+            if callable(save):
+                try:
+                    save()
+                except Exception:
+                    pass
+        sys.stdout.flush()
+        sys.stderr.flush()
+        # Ask the `bootstack dev` supervisor to relaunch us by exiting with the
+        # sentinel code. We do NOT os.execv: on Windows it spawns a new process
+        # and terminates this one, orphaning the app and dropping the supervisor
+        # after the first reload. os._exit skips interpreter cleanup/atexit — the
+        # supervisor owns the new process's lifecycle.
+        from bootstack.dev._env import DEV_RESTART_EXIT_CODE
+
+        os._exit(DEV_RESTART_EXIT_CODE)
+
+
+class _InProcessReloader(_BaseReloader):
+    """Reset and re-exec the ``with`` body in place, preserving module state."""
+
+    def __init__(self, app: Any, capture: BodyCapture) -> None:
+        super().__init__(app)
+        self.capture = capture
+        self._error_banner: Any = None
+
+    def install(self) -> None:
+        super().install()
+        rel = os.path.relpath(self.capture.filename)
+        _log(f"hot reload active - editing {rel} updates the running app on save")
+
+    def _watch_root(self) -> str:
+        return _project_watch_root(self.capture.filename)
+
+    def _handle(self, changed: set[str]) -> None:
+        entry = os.path.abspath(self.capture.filename)
+        changed_abs = {os.path.abspath(p) for p in changed}
+        entry_changed = entry in changed_abs
+        page_files = changed_abs - {entry}
+
+        try:
+            # Per-page fast path: the entry is unchanged AND every changed file is a
+            # module that holds registered @reloadable builders — rebuild just those
+            # regions, skip the entry body. A changed module WITHOUT a builder
+            # (constants/models with module-level state) must take the full path:
+            # importlib.reload would otherwise split object identity (fresh objects
+            # while live widgets still hold the old ones) without rebinding. (#326)
+            builder_files = set(self._builder_module_files())
+            if not entry_changed and page_files and page_files <= builder_files:
+                reloaded = self._reload_modules(page_files)
+                if reloaded and self._reinvoke_pages(reloaded):
+                    self._clear_error()
+                    self.app._dev_after_rebuild()
+                    _log("reloaded " + ", ".join(sorted(reloaded)))
+                    return
+
+            # Full reload: reload any changed project modules first (so the re-exec'd
+            # entry body rebinds to the fresh objects), then re-run the body.
+            self._reload_modules(page_files)
+            self._full_reload()
+            self._clear_error()
+            _log("reloaded")
+        except SyntaxError as exc:
+            self._show_error(_format_syntax_error(exc))
+            _log("syntax error - fix and save again")
+        except Exception:
+            self._show_error(traceback.format_exc())
+            _log("reload failed - see the banner; fix and save again")
+
+    def _full_reload(self) -> None:
+        # Compile BEFORE tearing down, so a syntax error never blanks the UI.
+        body = find_current_body(self.capture)
+        code = compile_body(self.capture.filename, body)
+
+        route = _safe(self.app._dev_capture_route)
+        self.app._dev_reset_region()
+
+        from bootstack.widgets._core.context import push_container, pop_container
+
+        push_container(self.app)
+        try:
+            exec(code, self.capture.module_globals)
+        finally:
+            pop_container(self.app)
+
+        self.app._dev_after_rebuild()
+        if route is not None:
+            try:
+                self.app._dev_restore_route(route)
+            except Exception:
+                pass
+
+    def _reinvoke_pages(self, modules: set[str]) -> bool:
+        from bootstack.dev import _registry
+
+        ran = False
+        for module in modules:
+            for qualname in _registry.builders_in_module(module):
+                if _registry.reinvoke(qualname):
+                    ran = True
+        return ran
+
+    def _builder_module_files(self) -> dict[str, str]:
+        """Map abspath -> module name for loaded modules holding registered builders."""
+        from bootstack.dev import _registry
+
+        out: dict[str, str] = {}
+        for name, module in list(sys.modules.items()):
+            path = getattr(module, "__file__", None)
+            if path and _registry.builders_in_module(name):
+                out[os.path.abspath(path)] = name
+        return out
+
+    def _reload_modules(self, files: set[str]) -> set[str]:
+        """importlib.reload any loaded project module whose file changed."""
+        if not files:
+            return set()
+        import importlib
+
+        reloaded: set[str] = set()
+        for name, module in list(sys.modules.items()):
+            path = getattr(module, "__file__", None)
+            if not path:
+                continue
+            if os.path.abspath(path) in files:
+                importlib.reload(module)  # exceptions surface as a banner
+                reloaded.add(name)
+        return reloaded
+
+    # --- error banner --------------------------------------------------------
+
+    def _show_error(self, text: str) -> None:
+        import tkinter as tk
+
+        self._clear_error()
+        # `_content_frame` is an attribute on App but a method on AppShell/
+        # Workbench — resolve both to the content widget that hosts the banner.
+        frame = getattr(self.app, "_content_frame", None)
+        if callable(frame):
+            frame = frame()
+        if frame is None:
+            sys.stderr.write(text + "\n")
+            return
+        try:
+            banner = tk.Frame(frame, background="#2b0f10")
+            banner.place(relx=0, rely=0, relwidth=1, relheight=1)
+            tk.Label(
+                banner,
+                text="Hot reload failed - fix the error and save again",
+                background="#2b0f10",
+                foreground="#ff7b72",
+                font=("TkDefaultFont", 11, "bold"),
+                anchor="w",
+            ).pack(fill="x", padx=14, pady=(12, 4))
+            body = tk.Text(
+                banner,
+                background="#2b0f10",
+                foreground="#ffd7d5",
+                relief="flat",
+                borderwidth=0,
+                wrap="word",
+                padx=14,
+                pady=4,
+                highlightthickness=0,
+            )
+            body.insert("1.0", text)
+            body.configure(state="disabled")
+            body.pack(fill="both", expand=True)
+            self._error_banner = banner
+        except Exception:
+            sys.stderr.write(text + "\n")
+
+    def _clear_error(self) -> None:
+        banner = self._error_banner
+        self._error_banner = None
+        if banner is not None:
+            try:
+                banner.destroy()
+            except Exception:
+                pass
+
+
+def _safe(fn: Any) -> Any:
+    try:
+        return fn()
+    except Exception:
+        return None
+
+
+def _format_syntax_error(exc: SyntaxError) -> str:
+    where = f"{exc.filename}:{exc.lineno}"
+    parts = [f"SyntaxError: {exc.msg}", f"  at {where}"]
+    if exc.text:
+        parts.append("  " + exc.text.rstrip())
+        if exc.offset:
+            parts.append("  " + " " * (exc.offset - 1) + "^")
+    return "\n".join(parts)