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

pythonnative/__init__.py

@@ -2,9 +2,11 @@
 
 PythonNative is a cross-platform toolkit that turns Python ``@component``
 functions into real, native Android and iOS views. The component model
-is React-like (function components plus hooks), but rendering happens
-through direct platform bindings: Chaquopy on Android (Java) and
-rubicon-objc on iOS (Objective-C). There is no JavaScript bridge.
+is React-like (function components plus hooks). Python owns the
+component tree, reconciliation, and layout; each commit crosses once
+into a native rendering core (Swift ``PythonNativeKit`` on iOS, the
+Kotlin ``pythonnative`` module on Android) that owns every platform
+view, gesture, animation, and device API. There is no JavaScript.
 
 Key building blocks:
 
@@ -60,7 +62,7 @@ Example:
     ```
 """
 
-__version__ = "0.35.0"
+__version__ = "0.37.0"
 
 from . import appearance, diagnostics, gestures, images, runtime, sdk
 from .alerts import Alert

pythonnative/_ios_log.py

@@ -14,7 +14,7 @@ straight to fd 2 is a small, reliable fix: fd 2 *is* visible to
 `simctl` (that is exactly how `NSLog` reaches the terminal), so
 Python output lands next to the Swift logs with correct ordering.
 
-This module is intentionally self-contained (no rubicon-objc or
+This module is intentionally self-contained (no bridge or
 platform-specific C bindings required), so it is safe to import
 early during `pythonnative` package initialization.
 """

pythonnative/alerts.py

@@ -30,77 +30,42 @@ Example:
 
 from __future__ import annotations
 
-import asyncio
 from typing import Any, Dict, List, Optional, Sequence
 
-from .platform import Platform
-from .runtime import resolve_future
+from .native_modules.registry import native_module
 
 # ======================================================================
 # Internal dispatch helpers
 # ======================================================================
 
 
-def _dispatch_alert(
+async def _present(
     *,
     title: str,
     message: Optional[str],
     buttons: List[Dict[str, Any]],
     style: str,
-    on_result: Any,
-) -> None:
-    """Route an alert request to the active platform presenter.
+) -> int:
+    """Ask the native ``Alert`` module to present and await the chosen index.
 
     ``buttons`` is a list of ``{"label": str, "style":
-    "default"|"cancel"|"destructive"}`` dicts. The presenter must
-    invoke ``on_result(index)`` exactly once when the user picks a
-    button, or ``on_result(-1)`` if the dialog is dismissed without a
-    selection. ``on_result`` may run on any thread.
+    "default"|"cancel"|"destructive"}`` dicts. The module resolves with
+    the index the user picked, or ``-1`` if the dialog was dismissed
+    without a selection. Off device the
+    [`DesktopAlert`][pythonnative.native_modules.desktop.DesktopAlert]
+    implementation records the call and answers from the queue set by
+    [`Alert.set_test_response`][pythonnative.alerts.Alert.set_test_response].
     """
-    if Platform.is_ios:
-        try:
-            from .native_views.ios import _present_alert as _ios_present_alert
-
-            _ios_present_alert(
-                title=title,
-                message=message,
-                buttons=buttons,
-                style=style,
-                on_result=on_result,
-            )
-            return
-        except Exception:
-            on_result(-1)
-            return
-
-    if Platform.is_android:
-        try:
-            from .native_views.android import _present_alert as _android_present_alert
-
-            _android_present_alert(
-                title=title,
-                message=message,
-                buttons=buttons,
-                style=style,
-                on_result=on_result,
-            )
-            return
-        except Exception:
-            on_result(-1)
-            return
-
-    # Test backend: record the call so unit tests can assert on it,
-    # then deliver the configured response.
-    Alert._test_log.append(
-        {
-            "title": title,
-            "message": message,
-            "buttons": list(buttons),
-            "style": style,
-        }
-    )
-    response = Alert._next_test_response()
-    on_result(response)
+    try:
+        result = await native_module("Alert").call_async(
+            "present", title=title, message=message, buttons=buttons, style=style
+        )
+    except Exception:
+        return -1
+    try:
+        return int(result)
+    except (TypeError, ValueError):
+        return -1
 
 
 # ======================================================================
@@ -170,13 +135,14 @@ class Alert:
         [`choose`][pythonnative.alerts.Alert.choose] and ``await``
         the result.
         """
-        _dispatch_alert(
-            title=title,
-            message=message,
-            buttons=[{"label": button, "style": "default"}],
-            style="alert",
-            on_result=lambda _idx: None,
-        )
+        try:
+            native_module("Alert").call(
+                "show", title=title, message=message, buttons=[{"label": button, "style": "default"}], style="alert"
+            )
+        except Exception:
+            from . import diagnostics
+
+            diagnostics.swallowed("alerts.Alert.show")
 
     @staticmethod
     async def confirm(
@@ -206,13 +172,7 @@ class Alert:
                 await save()
             ```
         """
-        loop = asyncio.get_running_loop()
-        future: asyncio.Future[bool] = loop.create_future()
-
-        def _on_result(index: int) -> None:
-            resolve_future(future, index == 1)
-
-        _dispatch_alert(
+        index = await _present(
             title=title,
             message=message,
             buttons=[
@@ -220,9 +180,8 @@ class Alert:
                 {"label": confirm_label, "style": "default"},
             ],
             style="alert",
-            on_result=_on_result,
         )
-        return await future
+        return index == 1
 
     @staticmethod
     async def choose(
@@ -265,9 +224,6 @@ class Alert:
         if not options:
             raise ValueError("Alert.choose requires at least one option")
 
-        loop = asyncio.get_running_loop()
-        future: asyncio.Future[Optional[str]] = loop.create_future()
-
         destructive = set(destructive_labels)
         buttons: List[Dict[str, Any]] = [
             {
@@ -279,20 +235,10 @@ class Alert:
         if cancel_label is not None:
             buttons.append({"label": cancel_label, "style": "cancel"})
 
-        def _on_result(index: int) -> None:
-            if 0 <= index < len(options):
-                resolve_future(future, options[index])
-            else:
-                resolve_future(future, None)
-
-        _dispatch_alert(
-            title=title,
-            message=message,
-            buttons=buttons,
-            style=style,
-            on_result=_on_result,
-        )
-        return await future
+        index = await _present(title=title, message=message, buttons=buttons, style=style)
+        if 0 <= index < len(options):
+            return options[index]
+        return None
 
 
 __all__ = ["Alert"]

pythonnative/bootstrap.py

@@ -0,0 +1,90 @@
+"""Entry point the native app templates run right after Python starts.
+
+Both templates execute one line of Python once the interpreter is up:
+
+```python
+import pythonnative.bootstrap; pythonnative.bootstrap.start()
+```
+
+[`start`][pythonnative.bootstrap.start] connects the two halves of the
+bridge (installing the native -> Python callback on iOS), verifies the
+protocol version, routes ``print()`` to the console on iOS, and warms
+the asyncio runtime. From then on the native runtime drives everything
+through ``callback("host", ...)``; see ``docs/concepts/bridge.md``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import traceback
+from typing import Any, Dict
+
+__all__ = ["start", "status"]
+
+_started: Dict[str, Any] = {}
+
+
+def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
+    """Connect the bridge and prepare the runtime.
+
+    Args:
+        dev: Enable dev mode (RedBox, validation warnings). Debug
+            templates pass ``True``; hot reload turns it on as well.
+        strict: Re-raise the failure after recording it. The templates
+            pass ``True`` so a broken bridge surfaces as a bootstrap
+            error screen with the full traceback.
+
+    Returns:
+        A status dict (``{"protocol": 1, "platform": "ios"}``) that the
+        template logs. Unless ``strict`` is set this never raises:
+        failures are printed and reported in the dict under
+        ``"error"``.
+    """
+    global _started
+    if _started and "error" not in _started:
+        return dict(_started)
+    status_: Dict[str, Any] = {"platform": None, "protocol": None}
+    try:
+        from .utils import IS_ANDROID, IS_IOS
+
+        status_["platform"] = "ios" if IS_IOS else "android" if IS_ANDROID else "off-device"
+        if IS_IOS:
+            try:
+                from . import _ios_log
+
+                _ios_log.install()
+            except Exception:
+                pass
+        from . import bridge
+
+        status_["protocol"] = bridge.handshake()
+        if dev or os.environ.get("PN_DEV") in ("1", "true"):
+            from . import diagnostics
+
+            diagnostics.set_dev_mode(True)
+        # Create the guest loop now so the first pump request has a
+        # loop to drive and effects can schedule work during mount.
+        from .runtime import get_loop
+
+        get_loop()
+        # Import the view backend eagerly: on a slow device the first
+        # commit shouldn't also pay for importing the reconciler.
+        from .native_views import get_registry
+
+        get_registry()
+    except Exception as exc:
+        status_["error"] = f"{type(exc).__name__}: {exc}"
+        print(f"[pn.bootstrap] start failed: {exc!r}", file=sys.stderr)
+        traceback.print_exc()
+        _started = status_
+        if strict:
+            raise
+        return dict(status_)
+    _started = status_
+    return dict(status_)
+
+
+def status() -> Dict[str, Any]:
+    """Return the result of the last [`start`][pythonnative.bootstrap.start] (empty before it ran)."""
+    return dict(_started)

pythonnative/bridge/__init__.py

@@ -0,0 +1,306 @@
+"""The native bridge: one channel between Python and Swift / Kotlin.
+
+Everything that crosses into native code goes through a
+[`Transport`][pythonnative.bridge.Transport] (``apply`` a transaction,
+``measure`` a view, run a ``command``, drive an ``animate`` request, or
+``call`` a native module), and everything native sends back arrives at
+[`native_callback`][pythonnative.bridge.native_callback]. The protocol
+is documented in ``docs/concepts/bridge.md``.
+
+Off-device (tests, ``pn preview``) there is no transport; the desktop
+registry renders with Tkinter and native modules fall back to their
+Python implementations. Tests that want to exercise the bridge itself
+install a [`FakeTransport`][pythonnative.bridge.fake.FakeTransport]
+with [`set_transport`][pythonnative.bridge.set_transport].
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from typing import Any, Callable, Deque, Dict, Optional, Protocol, Tuple
+
+from . import codec
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "Transport",
+    "get_transport",
+    "has_transport",
+    "handshake",
+    "native_callback",
+    "post_to_main",
+    "set_transport",
+]
+
+PROTOCOL_VERSION = 1
+"""Bridge protocol version this Python package speaks."""
+
+
+class Transport(Protocol):
+    """The Python -> native half of the bridge."""
+
+    name: str
+
+    def protocol_version(self) -> int:
+        """Return the protocol version compiled into the native library."""
+
+    def apply(self, transaction_json: str) -> None:
+        """Apply one serialized transaction (a JSON array of ops)."""
+
+    def measure(self, tag: int, max_width: float, max_height: float) -> Tuple[float, float]:
+        """Return the intrinsic ``(width, height)`` of the view ``tag`` under the constraints."""
+
+    def command(self, tag: int, name: str, args_json: str) -> Optional[str]:
+        """Run an imperative command on one view; returns its JSON result or ``None``."""
+
+    def animate(self, tag: int, request_json: str) -> Optional[str]:
+        """Handle an animation request (``set`` / ``start`` / ``cancel``) for one view."""
+
+    def call(self, module: str, method: str, args_json: str) -> Optional[str]:
+        """Call a native module method with a ``{"call_id", "args"}`` envelope."""
+
+    def set_callback(self, callback: Callable[[str, int, str, str], Optional[str]]) -> None:
+        """Install ``callback`` as the native -> Python entry point."""
+
+
+# ======================================================================
+# Transport selection
+# ======================================================================
+
+_transport: Optional[Transport] = None
+_transport_lock = threading.Lock()
+_explicit = False
+
+
+def _create_platform_transport() -> Optional[Transport]:
+    from ..utils import IS_ANDROID, IS_IOS
+
+    if IS_IOS:
+        from .ios import IOSTransport
+
+        transport: Transport = IOSTransport()
+        transport.set_callback(native_callback)
+        return transport
+    if IS_ANDROID:
+        from .android import AndroidTransport
+
+        return AndroidTransport()
+    return None
+
+
+def get_transport() -> Transport:
+    """Return the active transport, creating the platform one on first use.
+
+    Raises:
+        RuntimeError: Off-device, where no native runtime exists.
+    """
+    global _transport
+    if _transport is not None:
+        return _transport
+    with _transport_lock:
+        if _transport is None:
+            created = _create_platform_transport()
+            if created is None:
+                raise RuntimeError(
+                    "No native bridge is available on this platform (running off-device). "
+                    "Use `pn preview` for the desktop renderer or install a FakeTransport in tests."
+                )
+            _transport = created
+    return _transport
+
+
+def has_transport() -> bool:
+    """Whether a transport exists or can be created without raising."""
+    if _transport is not None:
+        return True
+    if _explicit:
+        return False
+    from ..utils import IS_ANDROID, IS_IOS
+
+    return bool(IS_IOS or IS_ANDROID)
+
+
+def set_transport(transport: Optional[Transport]) -> None:
+    """Install a transport explicitly (tests) or reset with ``None``."""
+    global _transport, _explicit
+    with _transport_lock:
+        _transport = transport
+        _explicit = transport is not None
+    if transport is not None:
+        transport.set_callback(native_callback)
+
+
+def handshake() -> int:
+    """Verify the native library speaks our protocol version.
+
+    Called by the native templates right after Python starts. Returns
+    the negotiated version.
+
+    Raises:
+        RuntimeError: On a version mismatch, with a hint to rebuild.
+    """
+    version = get_transport().protocol_version()
+    if version != PROTOCOL_VERSION:
+        raise RuntimeError(
+            f"Bridge protocol mismatch: the native runtime speaks v{version} but pythonnative "
+            f"expects v{PROTOCOL_VERSION}. Re-run 'pn build' so the staged template matches the "
+            "installed pythonnative package."
+        )
+    return version
+
+
+# ======================================================================
+# Main-queue posting
+# ======================================================================
+#
+# The asyncio guest loop and ``call_on_main_thread`` need a way to run
+# a callable on the platform main thread's next turn. Native provides
+# it: ``Host.post()`` schedules ``callback("pump")``, which drains this
+# queue. Keeping the queue in Python means one native crossing per
+# batch of callables rather than one per callable.
+
+_main_queue: Deque[Callable[[], None]] = deque()
+_main_queue_lock = threading.Lock()
+_pump_requested = False
+
+
+def post_to_main(fn: Callable[[], None]) -> None:
+    """Queue ``fn`` for the next main-thread turn (never runs inline)."""
+    global _pump_requested
+    with _main_queue_lock:
+        _main_queue.append(fn)
+        if _pump_requested:
+            return
+        _pump_requested = True
+    try:
+        get_transport().call("Host", "post", codec.dumps({"call_id": 0, "args": {}}))
+    except Exception as exc:
+        with _main_queue_lock:
+            _pump_requested = False
+        print(f"[pn.bridge] Host.post failed; running {len(_main_queue)} queued callable(s) inline: {exc!r}")
+        _drain_main_queue()
+
+
+def _drain_main_queue() -> None:
+    global _pump_requested
+    while True:
+        with _main_queue_lock:
+            if not _main_queue:
+                _pump_requested = False
+                return
+            fn = _main_queue.popleft()
+        try:
+            fn()
+        except Exception as exc:
+            print(f"[pn.bridge] main-thread callable raised: {exc!r}")
+
+
+# ======================================================================
+# native -> Python
+# ======================================================================
+
+
+def native_callback(kind: str, tag: int, name: str, payload: str) -> Optional[str]:
+    """Single entry point for every native -> Python message.
+
+    Args:
+        kind: ``"event"``, ``"module"``, ``"host"``, ``"animation"``,
+            or ``"pump"``.
+        tag: View tag (events), screen id (host), otherwise ``0``.
+        name: Event name, module name, or host event.
+        payload: JSON text whose shape depends on ``kind``.
+
+    Returns:
+        A JSON string for request-style messages (a handler's return
+        value, ``"true"`` / ``"false"`` for ``back_pressed``), else
+        ``None``. Never raises: failures are reported through
+        ``diagnostics`` so nothing propagates into UIKit or the
+        Android looper.
+    """
+    try:
+        if kind == "event":
+            return _on_event(int(tag), name, payload)
+        if kind == "module":
+            from ..native_modules.registry import dispatch_module_message
+
+            dispatch_module_message(name, codec.loads(payload) or {})
+            return None
+        if kind == "host":
+            from ..hosts.native import dispatch_host_event
+
+            return dispatch_host_event(int(tag), name, codec.loads(payload))
+        if kind == "animation":
+            from ..animated import native_animation_completed
+
+            data = codec.loads(payload) or {}
+            native_animation_completed(int(data.get("id", 0)), bool(data.get("finished", True)))
+            return None
+        if kind == "pump":
+            _drain_main_queue()
+            return None
+        print(f"[pn.bridge] unknown callback kind {kind!r}")
+    except Exception as exc:
+        from .. import diagnostics
+
+        if not diagnostics.report_error(exc, phase=f"bridge {kind}:{name}"):
+            import traceback
+
+            traceback.print_exc()
+    return None
+
+
+def _on_event(tag: int, name: str, payload: str) -> Optional[str]:
+    from ..events import get_event_registry
+
+    args = codec.loads(payload)
+    if args is None:
+        args = []
+    elif not isinstance(args, list):
+        args = [args]
+    callback = get_event_registry().get(tag, name)
+    if callback is None:
+        from ..native_views import get_registry
+
+        backend = get_registry()
+        internal = getattr(backend, "handle_internal_event", None)
+        if internal is not None:
+            result = internal(tag, name, args)
+            return None if result is None else codec.dumps(codec.to_jsonable(result))
+        return None
+    try:
+        result = callback(*args)
+    except Exception as exc:
+        from .. import diagnostics
+
+        if not diagnostics.report_error(exc, phase=f"event {name!r}"):
+            import traceback
+
+            traceback.print_exc()
+        return None
+    if result is None:
+        return None
+    try:
+        return codec.dumps(codec.to_jsonable(result))
+    except (TypeError, ValueError):
+        return None
+
+
+def _reset_for_tests() -> None:
+    """Drop the transport and any queued main-thread work (test isolation)."""
+    global _transport, _explicit, _pump_requested
+    with _transport_lock:
+        _transport = None
+        _explicit = False
+    with _main_queue_lock:
+        _main_queue.clear()
+        _pump_requested = False
+
+
+def transport_state() -> Dict[str, Any]:
+    """Diagnostics snapshot (used by ``pn doctor`` and tests)."""
+    return {
+        "transport": None if _transport is None else _transport.name,
+        "protocol_version": PROTOCOL_VERSION,
+        "queued_main_callables": len(_main_queue),
+    }

pythonnative/bridge/android.py

@@ -0,0 +1,78 @@
+"""Android transport: the ``com.pythonnative.runtime.PNBridge`` class via Chaquopy.
+
+``PNBridge`` is the only Java class Python touches. Its static methods
+mirror the C entry points used on iOS (see ``docs/concepts/bridge.md``).
+The reverse direction (native -> Python) is installed by the template's
+``MainActivity``, which implements ``PythonHost`` by calling
+[`pythonnative.bridge.native_callback`][pythonnative.bridge.native_callback]
+through Chaquopy; this transport therefore has nothing to register.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Tuple
+
+__all__ = ["AndroidTransport"]
+
+BRIDGE_CLASS = "com.pythonnative.runtime.PNBridge"
+
+
+class AndroidTransport:
+    """Thin wrapper over the static ``PNBridge`` methods."""
+
+    name = "android"
+
+    def __init__(self, bridge_class: Any = None) -> None:
+        if bridge_class is None:
+            from java import jclass
+
+            try:
+                bridge_class = jclass(BRIDGE_CLASS)
+            except Exception as exc:
+                raise RuntimeError(
+                    f"{BRIDGE_CLASS} is not on the classpath. Rebuild the app with 'pn run android' or "
+                    "'pn build android' so the pythonnative Gradle module is included."
+                ) from exc
+        self._bridge = bridge_class
+
+    def protocol_version(self) -> int:
+        """Return the protocol version compiled into the native library."""
+        return int(self._bridge.protocolVersion())
+
+    def apply(self, transaction_json: str) -> None:
+        """Apply one serialized transaction (a JSON array of ops)."""
+        self._bridge.apply(transaction_json)
+
+    def measure(self, tag: int, max_width: float, max_height: float) -> Tuple[float, float]:
+        """Return the intrinsic ``(width, height)`` of the view ``tag`` under the constraints."""
+        packed = self._bridge.measure(int(tag), float(max_width), float(max_height))
+        if not packed:
+            return (0.0, 0.0)
+        text = str(packed)
+        w, _, h = text.partition(",")
+        try:
+            return (float(w), float(h))
+        except ValueError:
+            return (0.0, 0.0)
+
+    def command(self, tag: int, name: str, args_json: str) -> Optional[str]:
+        """Run an imperative command on one view; returns its JSON result or ``None``."""
+        return _opt_str(self._bridge.command(int(tag), name, args_json))
+
+    def animate(self, tag: int, request_json: str) -> Optional[str]:
+        """Handle an animation request (``set`` / ``start`` / ``cancel``) for one view."""
+        return _opt_str(self._bridge.animate(int(tag), request_json))
+
+    def call(self, module: str, method: str, args_json: str) -> Optional[str]:
+        """Call a native module method with a ``{"call_id", "args"}`` envelope."""
+        return _opt_str(self._bridge.call(module, method, args_json))
+
+    def set_callback(self, callback: Callable[[str, int, str, str], Optional[str]]) -> None:
+        """No-op: the Android template installs the host through ``PNBridge.setHost``."""
+        del callback
+
+
+def _opt_str(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    return str(value)