pythonnative 0.23.0__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:
@@ -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)
@@ -1352,6 +1624,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 +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)
@@ -1631,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
 

pythonnative/style.py

@@ -34,8 +34,10 @@ Example:
     ```
 """
 
+import difflib
 from typing import Any, Dict, List, Literal, Optional, Tuple, TypedDict, Union
 
+from . import diagnostics
 from .hooks import Context, create_context, use_color_scheme, use_context
 
 # ======================================================================
@@ -74,6 +76,30 @@ EdgeValue = Union[Dimension, EdgeInsets]
 [`EdgeInsets`][pythonnative.EdgeInsets] dict."""
 
 
+class AccessibilityState(TypedDict, total=False):
+    """Current widget state exposed to assistive technology.
+
+    Passed via the ``accessibility_state=`` prop on interactive
+    components. All keys are optional; omitted keys are treated as
+    unset (not ``False``).
+
+    Attributes:
+        disabled: The widget is visible but not interactive.
+        selected: The widget is currently selected (e.g. the active
+            tab).
+        checked: Toggle/checkbox state. ``"mixed"`` represents a
+            tri-state checkbox.
+        busy: The widget is loading or otherwise temporarily busy.
+        expanded: A disclosure/accordion is currently expanded.
+    """
+
+    disabled: bool
+    selected: bool
+    checked: Union[bool, Literal["mixed"]]
+    busy: bool
+    expanded: bool
+
+
 class ShadowOffset(TypedDict):
     """Shadow displacement in points."""
 
@@ -136,6 +162,17 @@ TransformSpec = Union[TransformEntry, List[TransformEntry]]
 # ----------------------------------------------------------------------
 
 FlexDirection = Literal["row", "column", "row_reverse", "column_reverse"]
+FlexWrap = Literal["nowrap", "wrap", "wrap_reverse"]
+AlignContent = Literal[
+    "flex_start",
+    "center",
+    "flex_end",
+    "stretch",
+    "space_between",
+    "space_around",
+    "space_evenly",
+]
+LayoutDirection = Literal["ltr", "rtl"]
 JustifyContent = Literal[
     "flex_start",
     "center",
@@ -241,9 +278,12 @@ class Style(TypedDict, total=False):
     flex_shrink: float
     flex_basis: Dimension
     flex_direction: FlexDirection
+    flex_wrap: FlexWrap
     justify_content: JustifyContent
     align_items: AlignItems
     align_self: AlignSelf
+    align_content: AlignContent
+    direction: LayoutDirection
 
     # --- Layout: position ---
     position: Position
@@ -251,6 +291,8 @@ class Style(TypedDict, total=False):
     right: Dimension
     bottom: Dimension
     left: Dimension
+    start: Dimension
+    end: Dimension
 
     # --- Layout: spacing ---
     padding: EdgeValue
@@ -258,6 +300,8 @@ class Style(TypedDict, total=False):
     padding_bottom: Dimension
     padding_left: Dimension
     padding_right: Dimension
+    padding_start: Dimension
+    padding_end: Dimension
     padding_horizontal: Dimension
     padding_vertical: Dimension
     margin: EdgeValue
@@ -265,10 +309,14 @@ class Style(TypedDict, total=False):
     margin_bottom: Dimension
     margin_left: Dimension
     margin_right: Dimension
+    margin_start: Dimension
+    margin_end: Dimension
     margin_horizontal: Dimension
     margin_vertical: Dimension
     spacing: float
     gap: float
+    row_gap: float
+    column_gap: float
 
     # --- Visual: clipping & overflow ---
     overflow: Overflow
@@ -378,6 +426,40 @@ def resolve_style(value: StyleProp) -> Dict[str, Any]:
     return result
 
 
+_KNOWN_STYLE_KEYS = frozenset(Style.__annotations__)
+"""Every key declared on the [`Style`][pythonnative.Style] TypedDict."""
+
+
+def validate_style_keys(style_dict: Dict[str, Any], owner: str = "") -> None:
+    """Warn (once per key) about style keys no built-in handler reads.
+
+    Dev-mode only; production skips the scan entirely. Typos get a
+    "did you mean" suggestion via fuzzy matching against the declared
+    [`Style`][pythonnative.Style] keys. Unknown keys still flow through
+    to handlers untouched, so custom components that read extra keys
+    keep working (at the cost of one dev warning).
+
+    Args:
+        style_dict: The flattened style dict about to be merged into an
+            element's props.
+        owner: Element type name for the warning message (e.g.
+            ``"Text"``).
+    """
+    if not diagnostics.is_dev() or not style_dict:
+        return
+    for key in style_dict:
+        if key in _KNOWN_STYLE_KEYS:
+            continue
+        matches = difflib.get_close_matches(str(key), _KNOWN_STYLE_KEYS, n=1)
+        hint = f" Did you mean {matches[0]!r}?" if matches else ""
+        diagnostics.warn_once(
+            f"Unknown style key {key!r}"
+            + (f" on {owner}" if owner else "")
+            + f".{hint} Built-in components ignore keys they don't recognize.",
+            key=f"style:{owner}:{key}",
+        )
+
+
 # ======================================================================
 # StyleSheet
 # ======================================================================
@@ -604,4 +686,5 @@ __all__ = [
     "resolve_style",
     "style",
     "use_theme",
+    "validate_style_keys",
 ]