bootstack 0.1.0a16__tar.gz → 0.1.2__tar.gz

{bootstack-0.1.0a16/src/bootstack.egg-info → bootstack-0.1.2}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.1.0a16
+Version: 0.1.2
 Summary: From idea to a shipped desktop app, fast — a declarative, reactive, batteries-included Python UI framework with 60+ widgets, semantic theming, and built-in packaging.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/israel-dryer/bootstack
 Project-URL: Documentation, https://bootstack.org/
 Keywords: tkinter,ttk,gui,desktop,python3,ui,widgets,theming,cross-platform,modern,framework,application-framework,desktop-ui,python-gui
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Win32 (MS Windows)
-Classifier: Environment :: X11 Applications :: GTK
+Classifier: Environment :: MacOS X
+Classifier: Environment :: X11 Applications
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -22,6 +23,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: pillow<=12,>=10
+Requires-Dist: pygments>=2.15
 Requires-Dist: typing-extensions>=4.10
 Requires-Dist: Babel>=2.12
 Requires-Dist: python-dateutil>=2.9
@@ -46,6 +48,7 @@ Requires-Dist: pydata-sphinx-theme; extra == "docs"
 Requires-Dist: sphinx-design; extra == "docs"
 Requires-Dist: sphinx-copybutton; extra == "docs"
 Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
 Dynamic: license-file
 
 ![bootstack](https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/banner-readme.png)
@@ -59,8 +62,7 @@ Dynamic: license-file
 ![](https://img.shields.io/github/stars/israel-dryer/bootstack.svg)
 ![](https://img.shields.io/github/forks/israel-dryer/bootstack.svg)
 
-> **Pre-release.** The API may still change before 1.0. Full documentation is at
-> **[bootstack.org](https://bootstack.org)**.
+> Full documentation is at **[bootstack.org](https://bootstack.org)**.
 
 ### From idea to a shipped desktop app — fast.
 
@@ -94,15 +96,26 @@ Most Python desktop frameworks make you fight the framework. bootstack gets out
 - **DataSource abstraction** — one interface over SQLite, in-memory, and file backends with filtering, sorting, pagination, and CRUD
 - **Data visualization** — embed `matplotlib` (and `seaborn`) figures with `Chart`; they recolor with the theme and live-update from a `Signal` or `DataSource` (optional `viz` extra)
 - **A real CLI** — scaffold, run, add pages/views/dialogs/themes, and package for distribution
+- **Hot reload** — `bootstack dev app.py` updates the running app on save and keeps your place; module-level state and the active page survive the reload
 - **PyInstaller packaging built in** — `bootstack build` produces a standalone executable; no separate toolchain required
 
+## Hot reload
+
+Edit and save — the running window updates in place. `bootstack dev app.py`
+reloads the UI on every save while keeping your window position, module-level
+state, and active page, so you never lose your spot.
+
+<p align="center">
+<video src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/docs/_static/examples/live-reload.mp4" controls muted loop playsinline></video>
+</p>
+
 ## Installation
 
 Requires Python 3.12+ and Tk/Tcl (bundled with most Python distributions).
-bootstack is in pre-release, so opt in with `--pre`:
+Install with pip:
 
 ```bash
-python -m pip install --pre bootstack
+python -m pip install bootstack
 ```
 
 See the [installation guide](https://bootstack.org/getting-started/installation/)
@@ -264,6 +277,7 @@ bootstack appicon                           # Design an app icon and export it
 bootstack start MyApp                       # Create a new project (basic template)
 bootstack start MyApp --template appshell   # ...or with sidebar navigation
 bootstack run                               # Run the app defined in the project config
+bootstack dev app.py                        # Run with hot reload (live edit-and-save)
 bootstack add page Dashboard                # Add a new page (appshell)
 bootstack add view Settings                 # Add a new view (basic)
 bootstack add dialog Preferences            # Add a new dialog

{bootstack-0.1.0a16 → bootstack-0.1.2}/README.md

@@ -9,8 +9,7 @@
 ![](https://img.shields.io/github/stars/israel-dryer/bootstack.svg)
 ![](https://img.shields.io/github/forks/israel-dryer/bootstack.svg)
 
-> **Pre-release.** The API may still change before 1.0. Full documentation is at
-> **[bootstack.org](https://bootstack.org)**.
+> Full documentation is at **[bootstack.org](https://bootstack.org)**.
 
 ### From idea to a shipped desktop app — fast.
 
@@ -44,15 +43,26 @@ Most Python desktop frameworks make you fight the framework. bootstack gets out
 - **DataSource abstraction** — one interface over SQLite, in-memory, and file backends with filtering, sorting, pagination, and CRUD
 - **Data visualization** — embed `matplotlib` (and `seaborn`) figures with `Chart`; they recolor with the theme and live-update from a `Signal` or `DataSource` (optional `viz` extra)
 - **A real CLI** — scaffold, run, add pages/views/dialogs/themes, and package for distribution
+- **Hot reload** — `bootstack dev app.py` updates the running app on save and keeps your place; module-level state and the active page survive the reload
 - **PyInstaller packaging built in** — `bootstack build` produces a standalone executable; no separate toolchain required
 
+## Hot reload
+
+Edit and save — the running window updates in place. `bootstack dev app.py`
+reloads the UI on every save while keeping your window position, module-level
+state, and active page, so you never lose your spot.
+
+<p align="center">
+<video src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/docs/_static/examples/live-reload.mp4" controls muted loop playsinline></video>
+</p>
+
 ## Installation
 
 Requires Python 3.12+ and Tk/Tcl (bundled with most Python distributions).
-bootstack is in pre-release, so opt in with `--pre`:
+Install with pip:
 
 ```bash
-python -m pip install --pre bootstack
+python -m pip install bootstack
 ```
 
 See the [installation guide](https://bootstack.org/getting-started/installation/)
@@ -214,6 +224,7 @@ bootstack appicon                           # Design an app icon and export it
 bootstack start MyApp                       # Create a new project (basic template)
 bootstack start MyApp --template appshell   # ...or with sidebar navigation
 bootstack run                               # Run the app defined in the project config
+bootstack dev app.py                        # Run with hot reload (live edit-and-save)
 bootstack add page Dashboard                # Add a new page (appshell)
 bootstack add view Settings                 # Add a new view (basic)
 bootstack add dialog Preferences            # Add a new dialog

{bootstack-0.1.0a16 → bootstack-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.1.0a16"
+version = "0.1.2"
 description = "From idea to a shipped desktop app, fast — a declarative, reactive, batteries-included Python UI framework with 60+ widgets, semantic theming, and built-in packaging."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -29,9 +29,10 @@ keywords = [
     "python-gui"
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Environment :: Win32 (MS Windows)",
-    "Environment :: X11 Applications :: GTK",
+    "Environment :: MacOS X",
+    "Environment :: X11 Applications",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
@@ -44,6 +45,9 @@ classifiers = [
 dependencies = [
     "pillow>=10,<=12",
 
+    # Syntax highlighting for the CodeEditor widget
+    "pygments>=2.15",
+
     # Backported typing primitives (Self, Unpack, ParamSpec, etc.)
     "typing-extensions>=4.10",
 
@@ -88,6 +92,7 @@ docs = [
     "sphinx-design",
     "sphinx-copybutton",
     "sphinx-autobuild",
+    "myst-parser",
 ]
 
 [project.urls]
@@ -109,7 +114,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.1.0a16"
+current_version = "0.1.2"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre}{pre_n}",

{bootstack-0.1.0a16 → bootstack-0.1.2}/src/bootstack/_runtime/window_utilities.py

@@ -52,6 +52,79 @@ class WindowPositioning:
         >>> # Returns adjusted coordinates within screen bounds
     """
 
+    # Per-process cache of the macOS visible frame (work area) per monitor rect,
+    # keyed by the full monitor bounds. Computed once via a clamped probe.
+    _work_area_cache: dict[Tuple[int, int, int, int], Tuple[int, int, int, int]] = {}
+
+    @staticmethod
+    def get_work_area(
+        root: Optional[tkinter.Misc],
+        monitor_rect: Tuple[int, int, int, int],
+    ) -> Tuple[int, int, int, int]:
+        """Return the usable area of a monitor, OS-reserved strips excluded.
+
+        On macOS the menu bar (top) and Dock sit *inside* the physical monitor
+        bounds, so anchoring a window to the raw monitor rect lands it under the
+        Dock. Tk exposes no `NSScreen.visibleFrame` accessor, so this clamps a
+        throwaway, fully transparent managed Toplevel to the monitor — Aqua snaps
+        a managed window to the visible frame — and reads back the realized
+        origin and size. The result is cached per monitor rect.
+
+        Off macOS the full `monitor_rect` is returned unchanged: the X11/Windows
+        transient path already clears the taskbar via a topmost overlay.
+
+        Args:
+            root: A live widget used to parent the probe. If None, the full
+                `monitor_rect` is returned unchanged.
+            monitor_rect: `(x, y, w, h)` full bounds of the target monitor.
+
+        Returns:
+            `(x, y, w, h)` of the usable work area within `monitor_rect`.
+        """
+        if root is None:
+            return monitor_rect
+        try:
+            if root.tk.call("tk", "windowingsystem") != "aqua":
+                return monitor_rect
+        except tkinter.TclError:
+            return monitor_rect
+
+        cached = WindowPositioning._work_area_cache.get(monitor_rect)
+        if cached is not None:
+            return cached
+
+        mx, my, mw, mh = monitor_rect
+        area = monitor_rect
+        probe: Optional[tkinter.Toplevel] = None
+        try:
+            probe = tkinter.Toplevel(root)
+            try:
+                probe.attributes("-alpha", 0.0)  # invisible — no flash
+            except tkinter.TclError:
+                pass
+            # Oversize and place at the monitor origin; a managed Aqua window is
+            # clamped to that monitor's visible frame, so the realized geometry
+            # is the work area (menu bar + Dock excluded).
+            probe.geometry(f"{mw * 2}x{mh * 2}+{mx}+{my}")
+            probe.update_idletasks()
+            x, y = probe.winfo_rootx(), probe.winfo_rooty()
+            w, h = probe.winfo_width(), probe.winfo_height()
+            # Guard a degenerate probe (e.g. 1x1 if it never mapped): only trust
+            # a result that fills most of the monitor.
+            if w >= mw // 2 and h >= mh // 2:
+                area = (x, y, w, h)
+        except tkinter.TclError:
+            pass
+        finally:
+            if probe is not None:
+                try:
+                    probe.destroy()
+                except tkinter.TclError:
+                    pass
+
+        WindowPositioning._work_area_cache[monitor_rect] = area
+        return area
+
     @staticmethod
     def _get_monitor_at_point(x: int, y: int) -> Optional[Tuple[int, int, int, int]]:
         """Find the monitor containing the given point.

{bootstack-0.1.0a16 → bootstack-0.1.2}/src/bootstack/cli/__init__.py

@@ -9,6 +9,7 @@ The bootstack CLI provides commands for:
 Usage:
     bootstack start <appname>        Create a new project
     bootstack run [path]             Run the application
+    bootstack dev [path]             Run with hot reload (live edit-and-save)
     bootstack promote --pyinstaller  Enable PyInstaller support
     bootstack build                  Build for distribution
     bootstack add page <ClassName>   Add a new page (AppShell)
@@ -26,7 +27,7 @@ import argparse
 import sys
 from typing import Sequence
 
-from bootstack.cli import add, appicon, build, doctor, icons, promote, run, start
+from bootstack.cli import add, appicon, build, dev, doctor, icons, promote, run, start
 from bootstack.cli.demo import run_demo
 
 
@@ -42,6 +43,7 @@ Examples:
   bootstack start MyApp --template appshell  Create an AppShell project
   bootstack start MyApp --theme superhero    Use a specific theme
   bootstack run                      Run the application
+  bootstack dev app.py               Run with hot reload
   bootstack promote --pyinstaller    Enable PyInstaller support
   bootstack build                    Build for distribution
   bootstack add view SettingsView    Add a new view
@@ -75,6 +77,7 @@ For more information on a command:
     # Register commands
     start.add_parser(subparsers)
     run.add_parser(subparsers)
+    dev.add_parser(subparsers)
     promote.add_parser(subparsers)
     build.add_parser(subparsers)
     add.add_parser(subparsers)

{bootstack-0.1.0a16 → bootstack-0.1.2}/src/bootstack/cli/add.py

@@ -6,7 +6,12 @@ import argparse
 from pathlib import Path
 
 from bootstack.cli.config import TtkbConfig, find_config
-from bootstack.cli.templates import create_dialog, create_page, create_view
+from bootstack.cli.templates import (
+    _build_func_name,
+    create_dialog,
+    create_page,
+    create_view,
+)
 
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
@@ -202,6 +207,7 @@ def run_add_page(args: argparse.Namespace) -> None:
     scrollable = args.scrollable
     file_path = create_page(class_name, target_dir, scrollable=scrollable)
 
+    func_name = _build_func_name(class_name)
     print(f"Created page: {file_path.relative_to(project_root)}")
     print()
     print("This created the file only - it is NOT yet shown in the sidebar.")
@@ -209,10 +215,11 @@ def run_add_page(args: argparse.Namespace) -> None:
     print("inside your shell.page_nav() block:")
     print()
     import_module = f"{module_name}.pages" if module_name else "<module>.pages"
-    print(f"  from {import_module}.{file_path.stem} import {class_name}")
+    print(f"  from {import_module}.{file_path.stem} import {func_name}")
     scrollable_arg = ", scrollable=True" if scrollable else ""
-    print(f'  with nav.add_page("<id>", text="<Label>", icon="<icon>"{scrollable_arg}):')
-    print(f"      {class_name}()")
+    print(f'  with nav.add_page("<id>", text="<Label>", icon="<icon>",')
+    print(f'                    padding=20, gap=12, horizontal_items="stretch"{scrollable_arg}):')
+    print(f"      {func_name}()")
 
 
 def run_add_dialog(args: argparse.Namespace) -> None:

bootstack-0.1.2/src/bootstack/cli/dev.py

@@ -0,0 +1,153 @@
+"""bootstack dev command - Run an application with hot reload.
+
+PROVISIONAL — the dev workflow ships in 0.1.0 but is carved out of the API
+freeze and may change in a minor release.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import threading
+from pathlib import Path
+
+from bootstack.cli.config import TtkbConfig, find_config
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the 'dev' subcommand parser."""
+    parser = subparsers.add_parser(
+        "dev",
+        help="Run the application with hot reload",
+        description=(
+            "Run the application with live reload. Saving a source file updates "
+            "the running app. A module-level `with bs.App()` reloads in place "
+            "(state preserved); anything else falls back to a process restart."
+        ),
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help="Path to entry point or directory with bootstack.toml (default: current directory)",
+    )
+    parser.add_argument(
+        "--restart",
+        action="store_true",
+        help="Always reload by restarting the process, even for a module-level app",
+    )
+    parser.set_defaults(func=run_dev)
+
+
+def run_dev(args: argparse.Namespace) -> None:
+    """Execute the dev command."""
+    resolved = _resolve_entry(args.path)
+    if resolved is None:
+        return
+    entry_point, project_root = resolved
+
+    if not entry_point.exists():
+        print(f"Error: Entry point '{entry_point}' does not exist.")
+        return
+
+    try:
+        display_path = entry_point.relative_to(project_root)
+    except ValueError:
+        display_path = entry_point
+    print(f"Starting {display_path} with hot reload...")
+    print("(Save a file to reload. Press Ctrl+C to stop.)")
+    print()
+
+    env = dict(os.environ)
+    env["BOOTSTACK_DEV"] = "1"
+    env["BOOTSTACK_DEV_MODE"] = "restart" if args.restart else "inprocess"
+
+    src_dir = project_root / "src"
+    if src_dir.exists():
+        python_path = env.get("PYTHONPATH", "")
+        env["PYTHONPATH"] = (
+            f"{src_dir}{os.pathsep}{python_path}" if python_path else str(src_dir)
+        )
+
+    # Supervise the app here rather than letting it os.execv itself on restart:
+    # on Windows execv does not replace the process in place — it spawns a new
+    # PID and terminates the caller, which would drop this supervisor after the
+    # first reload and orphan the app. The child re-launches by exiting with
+    # DEV_RESTART_EXIT_CODE; looping subprocess.run is portable and re-establishes
+    # cwd + env on every relaunch.
+    from bootstack.dev._env import DEV_RESTART_EXIT_CODE
+
+    try:
+        while True:
+            result = subprocess.run(
+                [sys.executable, str(entry_point.resolve())],
+                cwd=str(project_root),
+                env=env,
+            )
+            if result.returncode == DEV_RESTART_EXIT_CODE:
+                continue  # a valid edit asked for a clean restart
+            if result.returncode == 0:
+                sys.exit(0)  # the app window was closed normally
+            # The app crashed (e.g. an edit raised at import). Don't end the
+            # session — stay alive and relaunch when the file is fixed and
+            # saved. This is the restart-mode counterpart to the in-process
+            # error banner's fix-and-save recovery; the child's own watcher
+            # died with it, so the supervisor watches in the meantime.
+            print(
+                f"\n[bootstack dev] app exited with code {result.returncode} - "
+                "waiting for a change to retry (Ctrl+C to stop)...",
+                flush=True,
+            )
+            _wait_for_change(str(project_root))
+    except KeyboardInterrupt:
+        print("\nStopped.")
+        sys.exit(0)
+
+
+def _wait_for_change(root: str) -> None:
+    """Block until a watched source file under `root` changes (or Ctrl+C).
+
+    Used by the restart supervisor to stay alive after the app crashes: rather
+    than ending the dev session, it waits for the next save and lets the loop
+    relaunch.
+    """
+    from bootstack.dev._watcher import PollWatcher
+
+    changed = threading.Event()
+    watcher = PollWatcher(root, lambda _paths: changed.set())
+    watcher.start()
+    try:
+        # Short timed waits keep Ctrl+C responsive on Windows, where a bare
+        # Event.wait() with no timeout can swallow the interrupt.
+        while not changed.wait(0.3):
+            pass
+    finally:
+        watcher.stop()
+
+
+def _resolve_entry(path: str | None) -> tuple[Path, Path] | None:
+    """Resolve (entry_point, project_root) from a path or bootstack.toml."""
+    if path:
+        p = Path(path)
+        if p.is_file() and p.suffix == ".py":
+            return p, p.parent
+        if p.is_dir():
+            config_path = p / "bootstack.toml"
+            if not config_path.exists():
+                print(f"Error: No bootstack.toml found in '{p}'")
+                return None
+            config = TtkbConfig.load(config_path)
+            return p / config.app.entry, p
+        print(f"Error: '{path}' is not a valid file or directory")
+        return None
+
+    config_path = find_config()
+    if config_path is None:
+        print("Error: No bootstack.toml found in current directory or parents.")
+        print("Pass a path: bootstack dev app.py")
+        return None
+    config = TtkbConfig.load(config_path)
+    project_root = config_path.parent
+    return project_root / config.app.entry, project_root

{bootstack-0.1.0a16 → bootstack-0.1.2}/src/bootstack/cli/run.py

@@ -85,7 +85,7 @@ def run_run(args: argparse.Namespace) -> None:
 
     try:
         result = subprocess.run(
-            [sys.executable, str(entry_point)],
+            [sys.executable, str(entry_point.resolve())],
             cwd=str(project_root),
             env=env,
         )