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

pythonnative/components/layout.py

@@ -113,7 +113,16 @@ def View(
 def Column(
     *children: Element,
     style: StyleProp = None,
+    gestures: Optional[List[Any]] = None,
+    hit_slop: Optional[Union[float, Dict[str, float]]] = None,
     on_layout: Optional[Callable[[Dict[str, float]], None]] = None,
+    accessibility_label: Optional[str] = None,
+    accessibility_hint: Optional[str] = None,
+    accessibility_role: Optional[str] = None,
+    accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -123,12 +132,25 @@ def Column(
     ``flex_direction`` locked to ``"column"``. Use ``View`` directly if
     you need to switch between row and column at runtime.
 
+    Accepts every [`View`][pythonnative.View] prop (gestures, hit slop,
+    accessibility, ``test_id``); only ``flex_direction`` is fixed.
+
     Args:
         *children: Child elements stacked top to bottom.
         style: Style dict (or list of dicts).
+        gestures: Gesture descriptors recognized natively on this view.
+        hit_slop: Extra touch target beyond the bounds (see ``View``).
         on_layout: Callback invoked with
             ``{"x", "y", "width", "height"}`` after layout and on
             frame changes.
+        accessibility_label: Spoken description for screen readers.
+        accessibility_hint: Spoken extra detail (iOS only).
+        accessibility_role: Semantic role for assistive tech.
+        accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech.
+        accessibility_live_region: How AT announces dynamic changes
+            (Android only).
+        test_id: Stable identifier for UI tests.
         ref: Optional [`Ref`][pythonnative.Ref] for native-view access.
         key: Stable identity for keyed reconciliation.
 
@@ -139,9 +161,18 @@ def Column(
         "Column",
         *children,
         style=style,
-        on_layout=on_layout,
         ref=ref,
         key=key,
+        gestures=gestures,
+        hit_slop=hit_slop,
+        on_layout=on_layout,
+        accessibility_label=accessibility_label,
+        accessibility_hint=accessibility_hint,
+        accessibility_role=accessibility_role,
+        accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _forced={"flex_direction": "column"},
     )
 
@@ -149,7 +180,16 @@ def Column(
 def Row(
     *children: Element,
     style: StyleProp = None,
+    gestures: Optional[List[Any]] = None,
+    hit_slop: Optional[Union[float, Dict[str, float]]] = None,
     on_layout: Optional[Callable[[Dict[str, float]], None]] = None,
+    accessibility_label: Optional[str] = None,
+    accessibility_hint: Optional[str] = None,
+    accessibility_role: Optional[str] = None,
+    accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -159,12 +199,25 @@ def Row(
     ``flex_direction`` locked to ``"row"``. Use ``View`` directly if you
     need to switch between row and column at runtime.
 
+    Accepts every [`View`][pythonnative.View] prop (gestures, hit slop,
+    accessibility, ``test_id``); only ``flex_direction`` is fixed.
+
     Args:
         *children: Child elements arranged left to right.
         style: Style dict (or list of dicts).
+        gestures: Gesture descriptors recognized natively on this view.
+        hit_slop: Extra touch target beyond the bounds (see ``View``).
         on_layout: Callback invoked with
             ``{"x", "y", "width", "height"}`` after layout and on
             frame changes.
+        accessibility_label: Spoken description for screen readers.
+        accessibility_hint: Spoken extra detail (iOS only).
+        accessibility_role: Semantic role for assistive tech.
+        accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech.
+        accessibility_live_region: How AT announces dynamic changes
+            (Android only).
+        test_id: Stable identifier for UI tests.
         ref: Optional [`Ref`][pythonnative.Ref] for native-view access.
         key: Stable identity for keyed reconciliation.
 
@@ -175,9 +228,18 @@ def Row(
         "Row",
         *children,
         style=style,
-        on_layout=on_layout,
         ref=ref,
         key=key,
+        gestures=gestures,
+        hit_slop=hit_slop,
+        on_layout=on_layout,
+        accessibility_label=accessibility_label,
+        accessibility_hint=accessibility_hint,
+        accessibility_role=accessibility_role,
+        accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _forced={"flex_direction": "row"},
     )
 
@@ -326,7 +388,7 @@ def _SafeAreaContainer(
     for edge in _SAFE_AREA_EDGES:
         if edge not in selected:
             continue
-        inset = float(insets.get(edge, 0.0) or 0.0)
+        inset = float(getattr(insets, edge, 0.0) or 0.0)
         if inset > 0:
             resolved[f"padding_{edge}"] = _numeric_edge_padding(resolved, edge) + inset
     return Element("SafeAreaView", resolved, list(children))

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