pythonnative 0.23.0__py3-none-any.whl → 0.25.0__py3-none-any.whl

pythonnative/screen.py

@@ -27,7 +27,7 @@ Example:
         count, set_count = pn.use_state(0)
         return pn.Column(
             pn.Text(f"Count: {count}", style={"font_size": 24}),
-            pn.Button("Tap me", on_click=lambda: set_count(count + 1)),
+            pn.Button("Tap me", on_press=lambda: set_count(count + 1)),
             style={"spacing": 12, "padding": 16},
         )
     ```
@@ -48,8 +48,10 @@ import json
 import os
 import sys
 import threading
-from typing import Any, Dict, Optional, Sequence
+import traceback
+from typing import Any, Dict, Optional, Sequence, Tuple
 
+from . import diagnostics
 from .utils import IS_ANDROID, IS_DESKTOP, IS_IOS, set_android_context
 
 _MAX_RENDER_PASSES = 25
@@ -186,6 +188,10 @@ def _init_host_common(host: Any, component_path: str, component_func: Any) -> No
     host._hot_reload_manifest_path = None
     host._hot_reload_last_version = None
     host._layout_listener = None  # retained on Android to prevent GC
+    # RedBox state: a dedicated reconciler that mounts the dev error
+    # overlay in place of the app tree (see ``_show_redbox``).
+    host._redbox_reconciler = None
+    host._redbox_root = None
     # Focus state: drives ``use_focus_effect``. Starts focused because
     # a host is only created when the screen is being presented; the
     # platform lifecycle hooks (``on_resume`` / ``on_pause``) flip this
@@ -207,6 +213,54 @@ def _set_host_focused(host: Any, focused: bool) -> None:
             pass
 
 
+def _destroy_host(host: Any) -> None:
+    """Tear down a screen host when the native screen is destroyed for good.
+
+    Called from each platform's ``on_destroy``. Unmounting the
+    reconciler runs every pending effect cleanup, destroys the native
+    views (releasing their event registrations), and clears back
+    handlers, so a popped screen doesn't leak its whole tree. Also
+    unregisters the host's RedBox reporter so runtime errors from other
+    screens don't route to a dead overlay.
+    """
+    _clear_redbox(host, reattach=False)
+    diagnostics.set_error_reporter(host, None)
+    reconciler = host._reconciler
+    host._reconciler = None
+    if reconciler is not None:
+        try:
+            reconciler.unmount()
+        except Exception:
+            _log_pn("_destroy_host: reconciler.unmount() failed")
+    root = host._root_native_view
+    host._root_native_view = None
+    if root is not None:
+        try:
+            host._detach_root(root)
+        except Exception:
+            pass
+    host._nav_handle = None
+    host._focus_subscribers = []
+
+
+def _host_back_pressed(host: Any) -> bool:
+    """Offer the system back action to ``use_back_handler`` subscribers.
+
+    Called by the native templates before running the platform's
+    default back behavior. Returns ``True`` when a handler consumed
+    the event, in which case the platform must *not* pop the screen.
+    """
+    reconciler = host._reconciler
+    if reconciler is None:
+        return False
+    try:
+        return bool(reconciler.dispatch_back_press())
+    except Exception as exc:
+        if not diagnostics.report_error(exc, phase="back handler"):
+            traceback.print_exc()
+        return False
+
+
 def _push_viewport_size(host: Any, width: float, height: float) -> None:
     """Forward a viewport-size change to the reconciler.
 
@@ -223,6 +277,9 @@ def _push_viewport_size(host: Any, width: float, height: float) -> None:
     if width <= 0 or height <= 0:
         return
     host._reconciler.set_viewport_size(float(width), float(height))
+    redbox = getattr(host, "_redbox_reconciler", None)
+    if redbox is not None:
+        redbox.set_viewport_size(float(width), float(height))
     try:
         from . import platform_metrics
 
@@ -269,6 +326,32 @@ def _flush_scheduled_renders(hosts: Sequence[Any]) -> None:
         _re_render(host)
 
 
+def _seed_initial_viewport(host: Any) -> None:
+    """Give the reconciler a plausible viewport size *before* the first mount.
+
+    The authoritative size arrives right after attach (Android's
+    ``OnLayoutChangeListener``, iOS ``viewDidLayoutSubviews``, the
+    desktop stage size), but by then the mount commit has already run:
+    without a viewport its layout pass is skipped, so mount-time
+    [`use_layout_effect`][pythonnative.use_layout_effect] callbacks
+    would observe no committed frames. Hosts opt in by providing
+    ``_initial_viewport_size()``; the estimate only needs to be
+    plausible (screen-sized), not pixel-perfect.
+    """
+    getter = getattr(host, "_initial_viewport_size", None)
+    if not callable(getter):
+        return
+    try:
+        size = getter()
+    except Exception:
+        return
+    if not size:
+        return
+    width, height = size
+    if width > 0 and height > 0:
+        host._reconciler.set_viewport_size(float(width), float(height))
+
+
 def _on_create(host: Any) -> None:
     from .hooks import NavigationHandle, Provider, _NavigationContext
 
@@ -285,23 +368,30 @@ def _on_create(host: Any) -> None:
     # If we're already mounted, just re-attach the existing root view
     # to the (newly created) native container; ``on_resume`` will
     # fire the focus subscribers separately.
+    _register_redbox_reporter(host)
     if host._reconciler is not None and host._root_native_view is not None:
         host._attach_root(host._root_native_view)
         return
 
     host._nav_handle = NavigationHandle(host)
     host._reconciler = _new_reconciler(host)
+    _seed_initial_viewport(host)
 
-    app_element = _render_app(host)
-    provider_element = Provider(_NavigationContext, host._nav_handle, app_element)
-
-    host._is_rendering = True
     try:
-        host._root_native_view = host._reconciler.mount(provider_element)
-        host._attach_root(host._root_native_view)
-        _drain_renders(host)
-    finally:
-        host._is_rendering = False
+        app_element = _render_app(host)
+        provider_element = Provider(_NavigationContext, host._nav_handle, app_element)
+
+        host._is_rendering = True
+        try:
+            host._root_native_view = host._reconciler.mount(provider_element)
+            host._attach_root(host._root_native_view)
+            _drain_renders(host)
+        finally:
+            host._is_rendering = False
+    except Exception as exc:
+        if not diagnostics.is_dev():
+            raise
+        _show_redbox(host, exc, phase="mount")
 
 
 def _request_render(host: Any) -> None:
@@ -333,13 +423,18 @@ def _re_render(host: Any) -> None:
     hot reload.
     """
     _log_pn("_re_render: starting local render pass")
-    host._is_rendering = True
     try:
-        host._render_queued = False
-        _commit_dirty(host)
-        _drain_renders(host)
-    finally:
-        host._is_rendering = False
+        host._is_rendering = True
+        try:
+            host._render_queued = False
+            _commit_dirty(host)
+            _drain_renders(host)
+        finally:
+            host._is_rendering = False
+    except Exception as exc:
+        if not diagnostics.is_dev():
+            raise
+        _show_redbox(host, exc, phase="render")
     _log_pn("_re_render: done")
 
 
@@ -367,6 +462,130 @@ def _drain_renders(host: Any) -> None:
         _commit_dirty(host)
 
 
+# ======================================================================
+# RedBox (dev-mode error overlay)
+# ======================================================================
+#
+# In dev mode (``pn preview``, ``pn run`` with hot reload, ``PN_DEV=1``)
+# an uncaught error from a mount, render, effect, or event handler
+# replaces the screen with a full-screen traceback instead of crashing
+# the process or dying silently in the log. The overlay is a normal
+# PythonNative element tree mounted by a *dedicated* reconciler so a
+# broken app tree can't take the error display down with it. Fixing the
+# code and saving clears it via hot reload; the Dismiss button restores
+# the previous native root (which is still mounted underneath).
+
+
+def _redbox_element(exc: BaseException, phase: str, on_dismiss: Any) -> Any:
+    """Build the RedBox element tree for ``exc``."""
+    from .components import Button, Column, ScrollView, Text
+
+    trace = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+    message = str(exc) or "(no message)"
+    return Column(
+        Column(
+            Text(
+                f"{type(exc).__name__} in {phase}",
+                style={"color": "#FFD3DA", "font_size": 13, "bold": True},
+            ),
+            Text(message, style={"color": "#FFFFFF", "font_size": 17, "bold": True}),
+            style={
+                "background_color": "#C4283C",
+                "padding": 16,
+                "padding_top": 56,
+                "spacing": 6,
+            },
+        ),
+        ScrollView(
+            Text(trace, style={"color": "#FF9AA8", "font_size": 12}),
+            style={"flex": 1, "padding": 12},
+        ),
+        Column(
+            Button("Dismiss", on_press=on_dismiss, style={"color": "#FFFFFF"}),
+            Text(
+                "Fix the error and save to reload.",
+                style={"color": "#8E8E93", "font_size": 12, "text_align": "center"},
+            ),
+            style={"padding": 12, "padding_bottom": 32, "spacing": 4},
+        ),
+        style={"flex": 1, "background_color": "#1C1C1E"},
+    )
+
+
+def _show_redbox(host: Any, exc: BaseException, phase: str = "render") -> None:
+    """Mount the dev error overlay over the host's screen.
+
+    Safe to call repeatedly (a newer error replaces the current
+    overlay) and from any thread (the mount hops to the main thread).
+    Failures inside the RedBox itself fall back to printing both
+    tracebacks so the original error is never lost.
+    """
+    _log_pn(f"_show_redbox: {type(exc).__name__} during {phase}")
+    try:
+        print(f"[PN] {phase} error:", file=sys.stderr)
+        traceback.print_exception(type(exc), exc, exc.__traceback__)
+    except Exception:
+        pass
+
+    def _mount() -> None:
+        try:
+            _clear_redbox(host, reattach=False)
+            from .native_views import get_registry
+            from .reconciler import Reconciler
+
+            redbox = Reconciler(get_registry())
+            redbox._screen_re_render = redbox.flush_dirty
+            element = _redbox_element(exc, phase, lambda: _clear_redbox(host))
+            root = redbox.mount(element)
+            width, height = (0.0, 0.0)
+            if host._reconciler is not None:
+                width, height = host._reconciler._viewport_size
+            if width <= 0 or height <= 0:
+                from . import platform_metrics
+
+                dims = platform_metrics.get_window_dimensions()
+                width, height = dims.width, dims.height
+            if width > 0 and height > 0:
+                redbox.set_viewport_size(width, height)
+            host._redbox_reconciler = redbox
+            host._redbox_root = root
+            if host._root_native_view is not None:
+                host._detach_root(host._root_native_view)
+            host._attach_root(root)
+        except Exception:
+            print("[PN] RedBox failed to mount:", file=sys.stderr)
+            traceback.print_exc()
+
+    from .runtime import call_on_main_thread
+
+    call_on_main_thread(_mount)
+
+
+def _clear_redbox(host: Any, reattach: bool = True) -> None:
+    """Tear down the RedBox overlay and optionally restore the app root."""
+    redbox = getattr(host, "_redbox_reconciler", None)
+    if redbox is None:
+        return
+    host._redbox_reconciler = None
+    host._redbox_root = None
+    try:
+        redbox.unmount()
+    except Exception:
+        pass
+    if reattach and host._root_native_view is not None:
+        try:
+            host._attach_root(host._root_native_view)
+        except Exception:
+            pass
+
+
+def _register_redbox_reporter(host: Any) -> None:
+    """Route runtime errors (events, async) for this host to the RedBox."""
+    if not diagnostics.is_dev():
+        return
+    diagnostics.set_error_reporter(host, lambda exc, phase: _show_redbox(host, exc, phase))
+
+
 def _set_args(host: Any, args: Any) -> None:
     if isinstance(args, str):
         try:
@@ -380,6 +599,10 @@ def _set_args(host: Any, args: Any) -> None:
 def _enable_hot_reload(host: Any, manifest_path: str) -> None:
     host._hot_reload_manifest_path = manifest_path
     host._hot_reload_last_version = None
+    # Hot reload only runs on debug builds, so treat it as the on-device
+    # dev-mode switch (validation warnings, hook-order checks, RedBox).
+    diagnostics.set_dev_mode(True)
+    _register_redbox_reporter(host)
 
 
 def _hot_reload_tick(host: Any) -> bool:
@@ -473,8 +696,13 @@ def _reload_host(host: Any, changed_modules: Optional[Sequence[str]] = None) ->
 
     try:
         new_component = _import_component(host._component_path)
-    except Exception as e:
-        _log_pn(f"_reload_host: re-import failed: {e!r}; aborting reload")
+    except Exception as exc:
+        _log_pn(f"_reload_host: re-import failed: {exc!r}; aborting reload")
+        if diagnostics.is_dev():
+            # A syntax error (or import-time crash) in the edited file:
+            # show it in the RedBox so the developer sees it on device
+            # instead of the app silently keeping the old code.
+            _show_redbox(host, exc, phase="hot reload import")
         return
     host._component = new_component
 
@@ -482,11 +710,22 @@ def _reload_host(host: Any, changed_modules: Optional[Sequence[str]] = None) ->
         _log_pn(f"_reload_host: host=0x{id(host):x} reconciler=None; skipping refresh")
         return
 
+    # A reload always replaces whatever error state was on screen.
+    # Re-attach the current root now: Fast Refresh patches that tree in
+    # place (attach must happen regardless of whether it succeeds), and
+    # a full remount swaps in its own fresh root anyway.
+    _clear_redbox(host)
+
     if _try_fast_refresh(host, reloaded):
         print(f"[hot-reload] Fast Refresh: {', '.join(requested) or ', '.join(reloaded)}", file=sys.stderr)
         return
 
-    _full_remount(host, reloaded)
+    try:
+        _full_remount(host, reloaded)
+    except Exception as exc:
+        if not diagnostics.is_dev():
+            raise
+        _show_redbox(host, exc, phase="hot reload")
 
 
 def _try_fast_refresh(host: Any, reloaded_modules: Sequence[str]) -> bool:
@@ -819,6 +1058,15 @@ if IS_ANDROID:
             set_android_context(native_instance)
             _init_host_common(self, component_path, component_func)
 
+        def _initial_viewport_size(self) -> Optional[Tuple[float, float]]:
+            """Estimate the viewport from display metrics (pre-attach)."""
+            try:
+                metrics = self.native_instance.getResources().getDisplayMetrics()
+                density = float(metrics.density) or 1.0
+                return (metrics.widthPixels / density, metrics.heightPixels / density)
+            except Exception:
+                return None
+
         def on_create(self) -> None:
             _android_publish_color_scheme(self.native_instance)
             _on_create(self)
@@ -844,7 +1092,10 @@ if IS_ANDROID:
             pass
 
         def on_destroy(self) -> None:
-            pass
+            _destroy_host(self)
+
+        def on_back_pressed(self) -> bool:
+            return _host_back_pressed(self)
 
         def enable_hot_reload(self, manifest_path: str, source_root: Optional[str] = None) -> None:
             _enable_hot_reload(self, manifest_path)
@@ -938,11 +1189,18 @@ if IS_ANDROID:
                 _android_push_initial_viewport(self, container)
 
         def _detach_root(self, native_view: Any) -> None:
+            # Remove this host's specific root view from whatever parent
+            # holds it. Never clear the shared fragment container: when a
+            # fragment is popped, its ``onDestroy`` (and therefore this
+            # detach) runs *after* the screen below has already re-attached
+            # its own root to the container, so a ``removeAllViews()`` here
+            # would blank the restored screen.
+            if native_view is None:
+                return
             try:
-                from .utils import get_android_fragment_container
-
-                container = get_android_fragment_container()
-                container.removeAllViews()
+                parent = native_view.getParent()
+                if parent is not None:
+                    parent.removeView(native_view)
             except Exception:
                 pass
 
@@ -1005,6 +1263,17 @@ elif IS_DESKTOP:
             self.native_instance = native_instance
             _init_host_common(self, component_path, component_func)
 
+        def _initial_viewport_size(self) -> Optional[Tuple[float, float]]:
+            """Read the stage size from the DesktopApp controller (pre-attach)."""
+            app = self.native_instance
+            if app is None or not hasattr(app, "viewport_size"):
+                return None
+            try:
+                width, height = app.viewport_size()
+                return (float(width), float(height))
+            except Exception:
+                return None
+
         def on_create(self) -> None:
             _on_create(self)
 
@@ -1024,7 +1293,10 @@ elif IS_DESKTOP:
             pass
 
         def on_destroy(self) -> None:
-            pass
+            _destroy_host(self)
+
+        def on_back_pressed(self) -> bool:
+            return _host_back_pressed(self)
 
         def enable_hot_reload(self, manifest_path: str, source_root: Optional[str] = None) -> None:
             _enable_hot_reload(self, manifest_path)
@@ -1315,6 +1587,19 @@ else:
                     return True
                 _log_pn("_request_render: native iOS scheduler unavailable; render remains queued")
                 return True
+            # Defer via the main dispatch queue rather than an NSTimer.
+            # GCD main-queue blocks are serviced in the common run-loop
+            # modes, so they still run while UIKit is in tracking mode
+            # (scrolls, synthesized test touches). A default-mode NSTimer
+            # is starved for the whole gesture, which delayed renders
+            # long enough on slow CI simulators for Maestro asserts to
+            # time out, and let stale flushes land mid-touch.
+            from .runtime import _ensure_libdispatch_loaded, _ios_dispatch_async
+
+            if _ensure_libdispatch_loaded():
+                _ios_dispatch_async(_flush_ios_scheduled_renders)
+                _log_pn("_request_render: deferred iOS render to next main-queue turn")
+                return True
             try:
                 NSTimer = ObjCClass("NSTimer")
                 target = _ensure_ios_render_scheduler_target()
@@ -1352,6 +1637,24 @@ else:
                 if self.native_instance is not None:
                     _ios_register_screen(self.native_instance, self)
 
+            def _initial_viewport_size(self) -> Optional[Tuple[float, float]]:
+                """Estimate the viewport from the VC's view bounds (pre-attach)."""
+                try:
+                    if self.native_instance is not None:
+                        bounds = self.native_instance.view.bounds
+                        width = float(bounds.size.width)
+                        height = float(bounds.size.height)
+                        if width > 0 and height > 0:
+                            return (width, height)
+                except Exception:
+                    pass
+                try:
+                    UIScreen = ObjCClass("UIScreen")
+                    screen_bounds = UIScreen.mainScreen.bounds
+                    return (float(screen_bounds.size.width), float(screen_bounds.size.height))
+                except Exception:
+                    return None
+
             def on_create(self) -> None:
                 _ios_publish_color_scheme()
                 _on_create(self)
@@ -1368,6 +1671,10 @@ else:
             def on_destroy(self) -> None:
                 if self.native_instance is not None:
                     _ios_unregister_screen(self.native_instance)
+                _destroy_host(self)
+
+            def on_back_pressed(self) -> bool:
+                return _host_back_pressed(self)
 
             def enable_hot_reload(self, manifest_path: str, source_root: Optional[str] = None) -> None:
                 _enable_hot_reload(self, manifest_path)
@@ -1425,22 +1732,55 @@ else:
                     raise RuntimeError(
                         "No UINavigationController available; ensure template embeds root in navigation controller"
                     )
-                nav.pushViewController_animated_(next_vc, True)
+                self._run_nav_op(lambda n: n.pushViewController_animated_(next_vc, True))
 
             def _pop(self) -> None:
-                nav = getattr(self.native_instance, "navigationController", None)
-                if nav is not None:
-                    nav.popViewControllerAnimated_(True)
+                self._run_nav_op(lambda n: n.popViewControllerAnimated_(True))
 
             def _reset_to_root(self) -> None:
                 """Pop everything above the root view-controller."""
-                nav = getattr(self.native_instance, "navigationController", None)
-                if nav is not None:
+
+                def op(n: Any) -> None:
                     try:
-                        nav.popToRootViewControllerAnimated_(True)
+                        n.popToRootViewControllerAnimated_(True)
                     except Exception:
                         pass
 
+                self._run_nav_op(op)
+
+            def _run_nav_op(self, op: Any) -> None:
+                """Run ``op(nav)`` unless a stack transition is mid-flight.
+
+                UIKit does not queue navigation calls: a
+                ``pushViewController`` / ``popViewController`` issued
+                while the previous transition is still animating is
+                silently ignored or, worse, misapplies and pops past
+                the intended screen. A fast tap right after a push
+                (easy for a user, common for a UI test on a slow
+                machine) lands exactly in that window. Dropping the
+                operation keeps the stack consistent: the tap simply
+                does nothing, and a retry lands on a settled stack.
+                (Deferring the operation instead was tried and is
+                worse: the user retries, then the deferred operation
+                also fires, popping one screen too many.)
+                """
+                nav = getattr(self.native_instance, "navigationController", None)
+                if nav is None:
+                    return
+                try:
+                    # rubicon resolves ``transitionCoordinator`` as a bound
+                    # method rather than a property on some classes; call
+                    # it to get the actual (possibly nil -> None) value.
+                    coord = nav.transitionCoordinator
+                    if callable(coord):
+                        coord = coord()
+                    if coord is not None:
+                        _log_pn("_run_nav_op: transition in flight; dropping nav op")
+                        return
+                except Exception:
+                    pass
+                op(nav)
+
             def _set_screen_options(self, options: Dict[str, Any]) -> None:
                 """Bind screen options (e.g. title) to the native nav bar.
 
@@ -1631,7 +1971,10 @@ else:
                 pass
 
             def on_destroy(self) -> None:
-                pass
+                _destroy_host(self)
+
+            def on_back_pressed(self) -> bool:
+                return _host_back_pressed(self)
 
             def enable_hot_reload(self, manifest_path: str, source_root: Optional[str] = None) -> None:
                 _enable_hot_reload(self, manifest_path)

pythonnative/storage.py

@@ -375,11 +375,11 @@ def use_persisted_state(
             theme, set_theme = pn.use_persisted_state("settings.theme", "light")
             return pn.Button(
                 f"Theme: {theme}",
-                on_click=lambda: set_theme("dark" if theme == "light" else "light"),
+                on_press=lambda: set_theme("dark" if theme == "light" else "light"),
             )
         ```
     """
-    from .hooks import use_async_effect, use_callback, use_ref, use_state
+    from .hooks import use_callback, use_effect, use_ref, use_state
     from .runtime import run_async
 
     state, set_state = use_state(initial)
@@ -389,14 +389,14 @@ def use_persisted_state(
         stored = await AsyncStorage.get_json(key)
         if stored is not None:
             set_state(stored)
-        loaded["current"] = True
+        loaded.current = True
 
-    use_async_effect(_load, [key])
+    use_effect(_load, [key])
 
     def setter(value_or_updater: Any) -> None:
         def _reducer(current: Any) -> Any:
             new_value = value_or_updater(current) if callable(value_or_updater) else value_or_updater
-            if loaded["current"] is True:
+            if loaded.current is True:
                 run_async(AsyncStorage.set_json(key, new_value))
             return new_value