pythonnative 0.36.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

pythonnative/gestures.py

@@ -34,10 +34,13 @@ configuration into plain dicts for the native handler (so prop diffing
 never compares closures) and routes the callbacks through the
 tag-based event channel. Recognition itself is native:
 
-- **iOS** attaches real ``UIGestureRecognizer`` instances.
-- **Android** feeds raw ``MotionEvent`` streams into the pure-Python
-  [`GestureArbiter`][pythonnative.gestures.GestureArbiter] below.
-- **Desktop** feeds Tk pointer events into the same arbiter.
+- **iOS** attaches real ``UIGestureRecognizer`` instances
+  (``PythonNativeKit``).
+- **Android** runs an equivalent recognizer set in Kotlin (the
+  ``pythonnative`` Gradle module) on top of ``MotionEvent`` streams.
+- **Desktop** feeds Tk pointer events into the pure-Python
+  [`GestureArbiter`][pythonnative.gestures.GestureArbiter] below, which
+  doubles as the executable specification for the native ports.
 
 Composition
 -----------
@@ -518,14 +521,14 @@ def serialize_gestures(
 
 
 # ======================================================================
-# Pure-Python recognition engine (Android + desktop backends)
+# Pure-Python recognition engine (desktop backend + reference semantics)
 # ======================================================================
 #
-# iOS uses real UIGestureRecognizers. Android and the desktop preview
-# receive raw pointer streams instead, which this arbiter turns into
-# the same GestureEvent payloads. Keeping it in pure Python makes the
-# state machines unit-testable with scripted event sequences and
-# guarantees identical semantics on both backends.
+# iOS and Android recognize natively. The desktop preview receives raw
+# Tk pointer streams instead, which this arbiter turns into the same
+# GestureEvent payloads. Keeping it in pure Python makes the state
+# machines unit-testable with scripted event sequences; the Kotlin
+# arbiter mirrors this file so the two stay in lockstep.
 
 EmitFn = Callable[[int, Dict[str, Any]], None]
 """``emit(gesture_index, payload)``: the arbiter's output channel."""

pythonnative/hooks.py

@@ -67,6 +67,7 @@ from typing import (
 
 from . import diagnostics
 from .element import Element, Node
+from .platform_metrics import SafeAreaInsets, WindowDimensions
 from .scheduler import TransitionQueue, in_transition, run_in_transition, schedule_trigger
 from .suspense import CoroDriver, Resource
 
@@ -1235,27 +1236,39 @@ def use_mutation(
     from .runtime import run_async
 
     state, set_state = use_state(lambda: MutationState[T]())
+    # The trigger is identity-stable across renders (like ``set_state``)
+    # so it can sit in effect deps or be passed to memoized children;
+    # it always calls the latest ``mutator``.
+    latest = use_ref(mutator)
+    latest.current = mutator
+
+    def _make_mutate() -> Callable[..., MutationCall[T]]:
+        def mutate(*args: Any, **kwargs: Any) -> MutationCall[T]:
+            set_state(lambda s: replace(s, loading=True, error=None))
+            fn = latest.current
 
-    def mutate(*args: Any, **kwargs: Any) -> MutationCall[T]:
-        set_state(lambda s: replace(s, loading=True, error=None))
+            async def _runner() -> T:
+                try:
+                    data = await fn(*args, **kwargs)
+                    set_state(lambda s: replace(s, data=data, loading=False, error=None))
+                    return data
+                except asyncio.CancelledError:
+                    set_state(lambda s: replace(s, loading=False))
+                    raise
+                except BaseException as exc:
+                    failure = exc
+                    set_state(lambda s: replace(s, loading=False, error=failure))
+                    raise
 
-        async def _runner() -> T:
-            try:
-                data = await mutator(*args, **kwargs)
-                set_state(lambda s: replace(s, data=data, loading=False, error=None))
-                return data
-            except asyncio.CancelledError:
-                set_state(lambda s: replace(s, loading=False))
-                raise
-            except BaseException as exc:
-                failure = exc
-                set_state(lambda s: replace(s, loading=False, error=failure))
-                raise
+            future = run_async(_runner())
+            return MutationCall[T](future)
 
-        future = run_async(_runner())
-        return MutationCall[T](future)
+        return mutate
 
-    return state, mutate
+    mutate_ref: Ref[Optional[Callable[..., MutationCall[T]]]] = use_ref(None)
+    if mutate_ref.current is None:
+        mutate_ref.current = _make_mutate()
+    return state, mutate_ref.current
 
 
 # ======================================================================
@@ -1294,7 +1307,7 @@ def use_subscription(subscribe: Callable[[Callable[[], None]], Callable[[], None
     return get_snapshot()
 
 
-def use_window_dimensions() -> Dict[str, float]:
+def use_window_dimensions() -> WindowDimensions:
     """Return the current viewport size and re-render when it changes.
 
     Equivalent to React Native's ``useWindowDimensions``. The values
@@ -1302,26 +1315,29 @@ def use_window_dimensions() -> Dict[str, float]:
     size (initial layout, rotation, multitasking split-view).
 
     Returns:
-        A dict with ``"width"`` and ``"height"`` floats in layout
+        A [`WindowDimensions`][pythonnative.platform_metrics.WindowDimensions]
+        named tuple with ``width`` and ``height`` floats in layout
         units (pt on iOS, dp on Android). Both are ``0.0`` until the
-        screen host has run its first layout pass.
+        screen host has run its first layout pass. Being a tuple, it
+        unpacks (``width, height = pn.use_window_dimensions()``) and
+        compares by value.
 
     Raises:
         RuntimeError: If called outside a ``@component`` function.
     """
     from . import platform_metrics
 
-    dims = use_subscription(platform_metrics.subscribe, platform_metrics.get_window_dimensions)
-    return {"width": dims.width, "height": dims.height}
+    return use_subscription(platform_metrics.subscribe, platform_metrics.get_window_dimensions)
 
 
-def use_safe_area_insets() -> Dict[str, float]:
+def use_safe_area_insets() -> SafeAreaInsets:
     """Return the current safe-area insets and re-render on change.
 
     Mirrors ``react-native-safe-area-context``'s ``useSafeAreaInsets``.
 
     Returns:
-        A dict with ``"top"``, ``"bottom"``, ``"left"``, and ``"right"``
+        A [`SafeAreaInsets`][pythonnative.platform_metrics.SafeAreaInsets]
+        named tuple with ``top``, ``left``, ``bottom``, and ``right``
         floats in layout units (pt on iOS, dp on Android).
 
     Raises:
@@ -1329,8 +1345,7 @@ def use_safe_area_insets() -> Dict[str, float]:
     """
     from . import platform_metrics
 
-    insets = use_subscription(platform_metrics.subscribe, platform_metrics.get_safe_area_insets)
-    return {"top": insets.top, "bottom": insets.bottom, "left": insets.left, "right": insets.right}
+    return use_subscription(platform_metrics.subscribe, platform_metrics.get_safe_area_insets)
 
 
 def use_keyboard_height() -> float:

pythonnative/hosts/__init__.py

@@ -1,18 +1,13 @@
 """Screen hosts: the bridge between a native screen and the reconciler.
 
-Native templates create one host per screen:
-
-```python
-host = pythonnative.hosts.create_screen("app.main", native_instance, args_json)
-host.on_create()
-```
-
-and forward lifecycle events to it. The concrete class depends on the
-runtime ([`AndroidScreenHost`][pythonnative.hosts.android.AndroidScreenHost],
-[`IOSScreenHost`][pythonnative.hosts.ios.IOSScreenHost],
-[`DesktopScreenHost`][pythonnative.hosts.desktop.DesktopScreenHost]);
-the headless base [`ScreenHost`][pythonnative.hosts.ScreenHost] is used
-in unit tests with a fake backend.
+On device the native runtime creates screens through the bridge
+(``callback("host", screen_id, "create", {...})``), which lands in
+[`NativeScreenHost`][pythonnative.hosts.native.NativeScreenHost]. Off device,
+``pn preview`` creates a
+[`DesktopScreenHost`][pythonnative.hosts.desktop.DesktopScreenHost]
+through [`create_screen`][pythonnative.hosts.create_screen], and unit
+tests use the headless base [`ScreenHost`][pythonnative.hosts.ScreenHost]
+with a fake backend.
 """
 
 from __future__ import annotations
@@ -27,18 +22,14 @@ __all__ = ["ScreenHost", "create_screen", "host_class", "import_component"]
 
 def host_class() -> Type[ScreenHost]:
     """The host class for the current runtime."""
-    if IS_ANDROID:
-        from .android import AndroidScreenHost
+    if IS_ANDROID or IS_IOS:
+        from .native import NativeScreenHost
 
-        return AndroidScreenHost
+        return NativeScreenHost
     if IS_DESKTOP:
         from .desktop import DesktopScreenHost
 
         return DesktopScreenHost
-    if IS_IOS:
-        from .ios import IOSScreenHost
-
-        return IOSScreenHost
     return ScreenHost
 
 
@@ -49,8 +40,8 @@ def create_screen(component_path: str, native_instance: Any = None, args_json: O
         component_path: ``"app.main"`` (the module's ``App`` is used) or a
             dotted path like ``"app.main.RootScreen"``. Imported lazily
             so the dev server can reload it.
-        native_instance: The platform object owning the screen
-            (``Activity``, ``UIViewController`` pointer, ``DesktopApp``).
+        native_instance: The platform object owning the screen (the
+            integer screen id on device, ``DesktopApp`` in the preview).
         args_json: Optional JSON launch arguments (pushed screens
             receive their navigation history here).
 
@@ -64,20 +55,6 @@ def create_screen(component_path: str, native_instance: Any = None, args_json: O
     return host
 
 
-def drain_ios_scheduled_renders() -> None:
-    """Drain deferred iOS renders (called by the Swift template on the main thread)."""
-    from .ios import drain_ios_scheduled_renders as drain
-
-    drain()
-
-
-def forward_lifecycle(native_addr: int, event: str) -> None:
-    """Forward a Swift view-controller lifecycle event to its host."""
-    from .ios import forward_lifecycle as forward
-
-    forward(native_addr, event)
-
-
 def drain_desktop_scheduled_renders() -> None:
     """Drain deferred desktop renders (called by the preview's Tk loop)."""
     from .desktop import drain_desktop_scheduled_renders as drain

pythonnative/hosts/native.py

@@ -0,0 +1,348 @@
+"""On-device screen host, shared by iOS and Android.
+
+One [`NativeScreenHost`][pythonnative.hosts.native.NativeScreenHost]
+exists per native screen (``UIViewController`` / ``Fragment``). The
+native side never holds Python objects: screens are addressed by an
+integer id it assigns, lifecycle arrives through
+``callback("host", screen_id, event, payload)`` (routed here by
+[`dispatch_host_event`][pythonnative.hosts.native.dispatch_host_event]),
+and everything the host needs from the platform goes out through the
+``Host`` native module (``attach_root``, ``push``, ``pop``, ...). See
+``docs/concepts/bridge.md`` for the payloads.
+
+Because native reports viewport size, safe-area insets, keyboard
+height, and color scheme *with* each lifecycle event, this module
+never queries the platform; it only publishes what it is told.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+from .. import appearance, diagnostics, platform_metrics
+from ..bridge import codec
+from ..native_modules.registry import native_module
+from .base import ScreenHost, flush_hosts, log_pn
+
+__all__ = ["NativeScreenHost", "dispatch_host_event", "host_for_screen", "live_hosts"]
+
+_HOSTS: Dict[int, "NativeScreenHost"] = {}
+_SCHEDULED: Dict[int, ScreenHost] = {}
+_flush_pending = False
+
+
+def host_for_screen(screen_id: int) -> Optional["NativeScreenHost"]:
+    """Return the host registered for ``screen_id`` (``None`` if unknown)."""
+    return _HOSTS.get(int(screen_id))
+
+
+def live_hosts() -> Sequence["NativeScreenHost"]:
+    """Every host currently registered, in creation order."""
+    return list(_HOSTS.values())
+
+
+def _host_module() -> Any:
+    return native_module("Host")
+
+
+# ======================================================================
+# Deferred renders
+# ======================================================================
+
+
+def _flush_scheduled() -> None:
+    global _flush_pending
+    _flush_pending = False
+    hosts = list(_SCHEDULED.values())
+    _SCHEDULED.clear()
+    if hosts:
+        log_pn(f"render_scheduler: flushing {len(hosts)} host(s)")
+    flush_hosts(hosts)
+
+
+def _request_flush() -> None:
+    """Queue one main-thread flush of every scheduled host."""
+    global _flush_pending
+    if _flush_pending:
+        return
+    _flush_pending = True
+    from ..bridge import post_to_main
+
+    post_to_main(_flush_scheduled)
+
+
+# ======================================================================
+# Payload helpers
+# ======================================================================
+
+
+def _publish_metrics(payload: Any) -> Tuple[float, float]:
+    """Publish viewport, insets, keyboard, and color scheme from a host payload.
+
+    Returns the ``(width, height)`` it found (``0, 0`` when absent).
+    """
+    if not isinstance(payload, dict):
+        return (0.0, 0.0)
+    width = float(payload.get("width") or 0.0)
+    height = float(payload.get("height") or 0.0)
+    insets = payload.get("insets")
+    if isinstance(insets, dict):
+        platform_metrics.set_safe_area_insets(
+            float(insets.get("top") or 0.0),
+            float(insets.get("left") or 0.0),
+            float(insets.get("bottom") or 0.0),
+            float(insets.get("right") or 0.0),
+        )
+    if "keyboard_height" in payload:
+        platform_metrics.set_keyboard_height(float(payload.get("keyboard_height") or 0.0))
+    scheme = payload.get("color_scheme")
+    if scheme in ("light", "dark"):
+        appearance.set_system_color_scheme(str(scheme))
+    if width > 0 and height > 0:
+        platform_metrics.set_window_dimensions(width, height)
+    return (width, height)
+
+
+# ======================================================================
+# Host
+# ======================================================================
+
+
+class NativeScreenHost(ScreenHost):
+    """Screen host addressed by an integer ``screen_id`` on the bridge."""
+
+    def __init__(self, screen_id: int, component_path: str, component: Any) -> None:
+        super().__init__(int(screen_id), component_path, component)
+        self.screen_id = int(screen_id)
+        self._pending_viewport: Optional[Tuple[float, float]] = None
+        _HOSTS[self.screen_id] = self
+
+    # -- lifecycle ------------------------------------------------------
+
+    def on_destroy(self) -> None:
+        """Forget the screen id, then tear down the tree."""
+        _HOSTS.pop(self.screen_id, None)
+        _SCHEDULED.pop(id(self), None)
+        super().on_destroy()
+
+    def apply_metrics(self, payload: Any) -> None:
+        """Publish the metrics carried by a host event and resize the viewport."""
+        width, height = _publish_metrics(payload)
+        if width > 0 and height > 0:
+            self._pending_viewport = (width, height)
+            self.set_viewport_size(width, height)
+
+    # -- platform primitives -------------------------------------------
+
+    def _initial_viewport_size(self) -> Optional[Tuple[float, float]]:
+        if self._pending_viewport is not None:
+            return self._pending_viewport
+        dims = platform_metrics.get_window_dimensions()
+        if dims.width > 0 and dims.height > 0:
+            return (dims.width, dims.height)
+        return None
+
+    def _schedule_render_async(self) -> bool:
+        if self._render_scheduled:
+            return True
+        self._render_scheduled = True
+        _SCHEDULED[id(self)] = self
+        try:
+            _request_flush()
+        except Exception as exc:
+            self._render_scheduled = False
+            _SCHEDULED.pop(id(self), None)
+            log_pn(f"request_render: bridge defer failed ({exc!r}); rendering synchronously")
+            return False
+        return True
+
+    def _attach_root(self, native_view: Any) -> None:
+        tag = getattr(native_view, "tag", None)
+        if tag is None:
+            return
+        # Native answers with the viewport the root now occupies, which
+        # is the earliest exact size available on iOS.
+        result = _host_module().call("attach_root", screen=self.screen_id, tag=int(tag))
+        if isinstance(result, dict):
+            self.apply_metrics(result)
+
+    def _detach_root(self, native_view: Any) -> None:
+        tag = getattr(native_view, "tag", None)
+        if tag is None:
+            return
+        try:
+            _host_module().call("detach_root", screen=self.screen_id, tag=int(tag))
+        except Exception:
+            diagnostics.swallowed("hosts.native.detach_root")
+
+    def _native_push(self, component_path: str, args: Dict[str, Any], options: Dict[str, Any]) -> None:
+        _host_module().call(
+            "push",
+            screen=self.screen_id,
+            path=component_path,
+            args=json.dumps(args) if args else None,
+            options=codec.to_jsonable(options or {}),
+        )
+
+    def _native_pop(self, count: int) -> None:
+        _host_module().call("pop", screen=self.screen_id, count=int(count))
+
+    def _native_pop_to_root(self) -> None:
+        _host_module().call("pop_to_root", screen=self.screen_id)
+
+    def _native_replace(self, component_path: str, args: Dict[str, Any], options: Dict[str, Any]) -> None:
+        _host_module().call(
+            "replace",
+            screen=self.screen_id,
+            path=component_path,
+            args=json.dumps(args) if args else None,
+            options=codec.to_jsonable(options or {}),
+        )
+
+    def _native_reset(self, component_path: str, screens: Sequence[Tuple[Dict[str, Any], Dict[str, Any]]]) -> None:
+        _host_module().call(
+            "reset",
+            screen=self.screen_id,
+            path=component_path,
+            screens=[
+                {
+                    "path": component_path,
+                    "args": json.dumps(args) if args else None,
+                    "options": codec.to_jsonable(options or {}),
+                }
+                for args, options in screens
+            ],
+        )
+
+    def _native_set_options(self, options: Dict[str, Any]) -> None:
+        _host_module().call("set_options", screen=self.screen_id, options=codec.to_jsonable(options or {}))
+
+
+# ======================================================================
+# Inbound host events
+# ======================================================================
+
+_create_lock = threading.Lock()
+
+
+def dispatch_host_event(screen_id: int, event: str, payload: Any) -> Optional[str]:
+    """Route ``callback("host", screen_id, event, payload)`` to a host.
+
+    Events (payloads are what ``PNViewController`` and
+    ``PNScreenFragment`` send):
+
+    - ``create`` ``{"path", "args", "dev_root", "restored_state",
+      ...metrics}``: import the component, create the host, and mount.
+      ``path`` is the dotted component path (``None`` means the app
+      entry module), ``args`` a JSON string, ``dev_root`` the hot-reload
+      overlay directory for debug builds. Returns ``{"root": tag}``.
+    - ``start`` / ``resume`` / ``pause`` / ``stop`` / ``destroy``:
+      lifecycle. ``resume`` and ``layout`` carry metrics.
+    - ``layout`` ``{width, height, insets, keyboard_height, color_scheme}``.
+    - ``appearance`` ``{"color_scheme"}``.
+    - ``back_pressed``: returns ``"true"`` when a handler consumed it.
+    - ``hot_reload_tick``: poll the reload manifest; returns ``"true"``
+      when a reload ran.
+    - ``save_state`` / ``restore_state``: instance-state hooks.
+    - ``flush``: run deferred renders now.
+
+    Returns a JSON string for request-style events, else ``None``.
+    """
+    screen_id = int(screen_id)
+    if event == "create":
+        return _create(screen_id, payload if isinstance(payload, dict) else {})
+    if event == "flush":
+        _flush_scheduled()
+        return None
+    if event == "appearance":
+        _publish_metrics(payload)
+        return None
+    host = _HOSTS.get(screen_id)
+    if host is None:
+        log_pn(f"dispatch_host_event: no host for screen={screen_id} event={event!r}")
+        return None
+    if event == "layout":
+        host.apply_metrics(payload)
+        host.on_layout()
+        return None
+    if event == "resume":
+        host.apply_metrics(payload)
+        host.on_resume()
+        return None
+    if event == "back_pressed":
+        return "true" if host.on_back_pressed() else "false"
+    if event in ("hot_reload_tick", "tick"):
+        return "true" if host.hot_reload_tick() else "false"
+    if event == "save_state":
+        host.on_save_instance_state()
+        return None
+    if event == "restore_state":
+        host.on_restore_instance_state()
+        return None
+    if event == "destroy":
+        host.on_destroy()
+        return None
+    handler = getattr(host, f"on_{event}", None)
+    if handler is None:
+        log_pn(f"dispatch_host_event: unknown event {event!r}")
+        return None
+    handler()
+    return None
+
+
+def _create(screen_id: int, payload: Dict[str, Any]) -> Optional[str]:
+    from . import import_component
+
+    component_path = str(payload.get("path") or payload.get("component") or _entry_module())
+    with _create_lock:
+        existing = _HOSTS.get(screen_id)
+        if existing is not None:
+            existing.apply_metrics(payload)
+            existing.on_create()
+            return _root_json(existing)
+        component = import_component(component_path)
+        host = NativeScreenHost(screen_id, component_path, component)
+    args = payload.get("args")
+    if args:
+        host.set_args(args)
+    dev_root = payload.get("dev_root")
+    if dev_root:
+        from .. import hot_reload
+
+        host.enable_hot_reload(hot_reload.manifest_path_for(str(dev_root)), str(dev_root))
+    if not (payload.get("width") and payload.get("height")):
+        # ``create`` is sent before the first layout pass; ask native for
+        # its best guess so the first commit lays out at the right size.
+        try:
+            viewport = _host_module().call("viewport", screen=screen_id)
+        except Exception:
+            viewport = None
+        if isinstance(viewport, dict):
+            payload = {**viewport, **payload}
+    _publish_metrics(payload)
+    width = float(payload.get("width") or 0.0)
+    height = float(payload.get("height") or 0.0)
+    if width > 0 and height > 0:
+        host._pending_viewport = (width, height)
+    host.on_create()
+    return _root_json(host)
+
+
+def _entry_module() -> str:
+    import os
+
+    return os.environ.get("PN_ENTRY_MODULE") or "app.main"
+
+
+def _root_json(host: ScreenHost) -> str:
+    tag = getattr(host.root_native_view, "tag", None)
+    return codec.dumps({"root": None if tag is None else int(tag)})
+
+
+def _reset_for_tests() -> None:
+    global _flush_pending
+    _HOSTS.clear()
+    _SCHEDULED.clear()
+    _flush_pending = False

pythonnative/images.py

@@ -38,13 +38,14 @@ def _default_cache_dir() -> str:
     backups). Desktop: a per-user directory under the system temp dir.
     """
     try:
-        from .utils import IS_ANDROID
+        from .utils import IS_ANDROID, IS_IOS
 
-        if IS_ANDROID:
-            from .utils import get_android_context
+        if IS_ANDROID or IS_IOS:
+            from .native_modules.registry import native_module
 
-            base = str(get_android_context().getCacheDir().getAbsolutePath())
-            return os.path.join(base, "pn_images")
+            info = native_module("Device").call("info")
+            if isinstance(info, dict) and info.get("cache_dir"):
+                return os.path.join(str(info["cache_dir"]), "pn_images")
     except Exception:
         pass
     home = os.path.expanduser("~")