pythonnative 0.22.1__py3-none-any.whl → 0.24.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:
@@ -678,6 +917,65 @@ if IS_ANDROID:
                 bottom_px / density,
                 right_px / density,
             )
+            # IME (soft keyboard) insets: API 30+ exposes them through
+            # the typed getInsets API. The keyboard overlaps the system
+            # navigation bar, so the visible keyboard height is the IME
+            # inset minus the permanent bottom bar inset. Older API
+            # levels don't report IME insets here; those devices rely
+            # on ``adjustResize`` shrinking the window (the viewport
+            # push handles the layout) and the height stays 0.
+            try:
+                ime = insets_obj.getInsets(Type.ime())
+                ime_px = max(0, int(ime.bottom) - bottom_px)
+                platform_metrics.set_keyboard_height(ime_px / density)
+            except Exception:
+                pass
+        except Exception:
+            pass
+
+    def _android_publish_color_scheme(activity: Any) -> None:
+        """Read the system night mode from the activity and publish it.
+
+        Android delivers appearance changes as a configuration change,
+        which recreates the activity by default, so publishing on
+        ``on_create`` / ``on_resume`` covers both the initial value and
+        subsequent flips.
+        """
+        try:
+            from . import appearance
+
+            Configuration = jclass("android.content.res.Configuration")
+            ui_mode = int(activity.getResources().getConfiguration().uiMode)
+            night = ui_mode & int(Configuration.UI_MODE_NIGHT_MASK)
+            is_dark = night == int(Configuration.UI_MODE_NIGHT_YES)
+            appearance.set_system_color_scheme("dark" if is_dark else "light")
+        except Exception:
+            pass
+
+    def _android_register_insets_listener(host: Any, view: Any) -> None:
+        """Re-publish insets whenever the window's insets change.
+
+        The ``OnLayoutChangeListener`` in ``_android_register_layout_listener``
+        only fires when the container is re-measured, which covers
+        ``adjustResize`` keyboards but not inset-only changes (e.g. an
+        edge-to-edge window where the IME floats over the content).
+        ``setOnApplyWindowInsetsListener`` fires on every insets pass,
+        so keyboard show/hide reaches ``platform_metrics`` immediately.
+        """
+        try:
+            View = jclass("android.view.View")
+
+            class _PNInsetsListener(dynamic_proxy(View.OnApplyWindowInsetsListener)):  # type: ignore[misc]
+                def onApplyWindowInsets(self, v: Any, insets: Any) -> Any:
+                    try:
+                        _android_publish_window_insets(v)
+                    except Exception:
+                        pass
+                    return insets
+
+            listener = _PNInsetsListener()
+            view.setOnApplyWindowInsetsListener(listener)
+            host._insets_listener = listener  # retain to prevent GC
         except Exception:
             pass
 
@@ -760,13 +1058,24 @@ 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)
 
         def on_start(self) -> None:
             pass
 
         def on_resume(self) -> None:
+            _android_publish_color_scheme(self.native_instance)
             _set_host_focused(self, True)
 
         def on_layout(self) -> None:
@@ -783,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)
@@ -873,14 +1185,22 @@ if IS_ANDROID:
 
             if container is not None:
                 _android_register_layout_listener(self, container)
+                _android_register_insets_listener(self, container)
                 _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
 
@@ -943,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)
 
@@ -962,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)
@@ -1128,6 +1462,24 @@ else:
         except Exception:
             pass
 
+    def _ios_publish_color_scheme() -> None:
+        """Read the current UIKit interface style and publish it.
+
+        ``UITraitCollection.currentTraitCollection`` reflects the
+        active appearance; ``userInterfaceStyle`` is 1 for light and
+        2 for dark (0 = unspecified, treated as light). Called from
+        the lifecycle callbacks that fire on appearance flips
+        (``viewDidLayoutSubviews`` / ``viewDidAppear``).
+        """
+        try:
+            from . import appearance
+
+            UITraitCollection = ObjCClass("UITraitCollection")
+            style_value = int(UITraitCollection.currentTraitCollection.userInterfaceStyle)
+            appearance.set_system_color_scheme("dark" if style_value == 2 else "light")
+        except Exception:
+            pass
+
     def _ios_register_screen(vc_instance: Any, host_obj: Any) -> None:
         ptr = _objc_addr(vc_instance)
         if ptr is None:
@@ -1272,7 +1624,26 @@ 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)
 
             def on_start(self) -> None:
@@ -1287,6 +1658,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)
@@ -1483,6 +1858,9 @@ else:
                 # insets are now valid (initial layout, rotation,
                 # multitasking, …). Re-sync the root frame and push the
                 # viewport so the layout engine matches the visible area.
+                # Appearance flips also trigger a layout pass, so the
+                # color scheme is re-published here too.
+                _ios_publish_color_scheme()
                 if self._root_native_view is None:
                     _log_pn("on_layout: no root_native_view yet, skipping")
                     return
@@ -1494,6 +1872,7 @@ else:
                 # ``viewDidAppear`` always follows ``viewDidLayoutSubviews``,
                 # but trigger one extra sync here for safety in case a
                 # template overrides the layout call without forwarding.
+                _ios_publish_color_scheme()
                 _set_host_focused(self, True)
                 if self._root_native_view is None:
                     _log_pn("on_resume: no root_native_view yet, skipping")
@@ -1546,7 +1925,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,7 +375,7 @@ 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"),
             )
         ```
     """
@@ -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])
 
     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