pythonnative 0.24.0__py3-none-any.whl → 0.26.0__py3-none-any.whl

pythonnative/screen.py

@@ -1587,6 +1587,19 @@ else:
                     return True
                 _log_pn("_request_render: native iOS scheduler unavailable; render remains queued")
                 return True
+            # Defer via the main dispatch queue rather than an NSTimer.
+            # GCD main-queue blocks are serviced in the common run-loop
+            # modes, so they still run while UIKit is in tracking mode
+            # (scrolls, synthesized test touches). A default-mode NSTimer
+            # is starved for the whole gesture, which delayed renders
+            # long enough on slow CI simulators for Maestro asserts to
+            # time out, and let stale flushes land mid-touch.
+            from .runtime import _ensure_libdispatch_loaded, _ios_dispatch_async
+
+            if _ensure_libdispatch_loaded():
+                _ios_dispatch_async(_flush_ios_scheduled_renders)
+                _log_pn("_request_render: deferred iOS render to next main-queue turn")
+                return True
             try:
                 NSTimer = ObjCClass("NSTimer")
                 target = _ensure_ios_render_scheduler_target()
@@ -1719,22 +1732,55 @@ else:
                     raise RuntimeError(
                         "No UINavigationController available; ensure template embeds root in navigation controller"
                     )
-                nav.pushViewController_animated_(next_vc, True)
+                self._run_nav_op(lambda n: n.pushViewController_animated_(next_vc, True))
 
             def _pop(self) -> None:
-                nav = getattr(self.native_instance, "navigationController", None)
-                if nav is not None:
-                    nav.popViewControllerAnimated_(True)
+                self._run_nav_op(lambda n: n.popViewControllerAnimated_(True))
 
             def _reset_to_root(self) -> None:
                 """Pop everything above the root view-controller."""
-                nav = getattr(self.native_instance, "navigationController", None)
-                if nav is not None:
+
+                def op(n: Any) -> None:
                     try:
-                        nav.popToRootViewControllerAnimated_(True)
+                        n.popToRootViewControllerAnimated_(True)
                     except Exception:
                         pass
 
+                self._run_nav_op(op)
+
+            def _run_nav_op(self, op: Any) -> None:
+                """Run ``op(nav)`` unless a stack transition is mid-flight.
+
+                UIKit does not queue navigation calls: a
+                ``pushViewController`` / ``popViewController`` issued
+                while the previous transition is still animating is
+                silently ignored or, worse, misapplies and pops past
+                the intended screen. A fast tap right after a push
+                (easy for a user, common for a UI test on a slow
+                machine) lands exactly in that window. Dropping the
+                operation keeps the stack consistent: the tap simply
+                does nothing, and a retry lands on a settled stack.
+                (Deferring the operation instead was tried and is
+                worse: the user retries, then the deferred operation
+                also fires, popping one screen too many.)
+                """
+                nav = getattr(self.native_instance, "navigationController", None)
+                if nav is None:
+                    return
+                try:
+                    # rubicon resolves ``transitionCoordinator`` as a bound
+                    # method rather than a property on some classes; call
+                    # it to get the actual (possibly nil -> None) value.
+                    coord = nav.transitionCoordinator
+                    if callable(coord):
+                        coord = coord()
+                    if coord is not None:
+                        _log_pn("_run_nav_op: transition in flight; dropping nav op")
+                        return
+                except Exception:
+                    pass
+                op(nav)
+
             def _set_screen_options(self, options: Dict[str, Any]) -> None:
                 """Bind screen options (e.g. title) to the native nav bar.
 

pythonnative/storage.py

@@ -379,7 +379,7 @@ def use_persisted_state(
             )
         ```
     """
-    from .hooks import use_async_effect, use_callback, use_ref, use_state
+    from .hooks import use_callback, use_effect, use_ref, use_state
     from .runtime import run_async
 
     state, set_state = use_state(initial)
@@ -391,7 +391,7 @@ def use_persisted_state(
             set_state(stored)
         loaded.current = True
 
-    use_async_effect(_load, [key])
+    use_effect(_load, [key])
 
     def setter(value_or_updater: Any) -> None:
         def _reducer(current: Any) -> Any:

pythonnative/suspense.py

@@ -0,0 +1,417 @@
+"""Suspense primitives: suspension signals, resources, and lazy loading.
+
+This module implements the machinery behind PythonNative's async
+rendering model:
+
+- ``async def`` components: a component body may be a coroutine. The
+  reconciler drives it synchronously as far as possible (awaits on
+  already-resolved futures complete inline); if it blocks on pending
+  work, the render **suspends** and the nearest
+  [`Suspense`][pythonnative.Suspense] boundary shows its fallback
+  until the coroutine finishes.
+- [`use_resource`][pythonnative.use_resource]: a hook that starts an
+  async fetch and caches it across renders. Reading an unresolved
+  [`Resource`][pythonnative.Resource] suspends the render; awaiting it
+  inside an ``async def`` component does the same thing without the
+  boundary having to re-run anything by hand.
+- [`lazy`][pythonnative.lazy]: code-splitting for components. The
+  loader runs once, and renders suspend until it resolves.
+
+The core building block is [`CoroDriver`][pythonnative.suspense.CoroDriver],
+a miniature task that steps a coroutine **synchronously** until it
+either finishes or blocks on a pending :class:`asyncio.Future`. This is
+what lets an ``async def`` component whose awaits are all cached
+(resolved resources, completed tasks) render in a single synchronous
+pass with zero event-loop round trips, while genuinely pending awaits
+suspend cleanly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import inspect
+from typing import Any, Callable, Generic, List, Optional, Tuple, TypeVar
+
+T = TypeVar("T")
+
+_UNSET = object()
+
+
+class Suspend(BaseException):
+    """Signal that a render is blocked on pending async work.
+
+    Raised while a component renders, either by
+    [`Resource.read`][pythonnative.suspense.Resource.read] or by an
+    ``async def`` component body blocking on a pending await. The
+    reconciler catches it: the nearest
+    [`Suspense`][pythonnative.Suspense] boundary shows its fallback
+    (initial mounts), or the component keeps its previous content and
+    re-renders when the work finishes (updates).
+
+    Derives from :class:`BaseException` so
+    [`ErrorBoundary`][pythonnative.ErrorBoundary] (which catches
+    :class:`Exception`) never mistakes a suspension for a crash.
+
+    Attributes:
+        waitable: The pending work; exposes ``done()`` and
+            ``add_done_callback(cb)``.
+        hook_state: The suspended component's hook state, carried so
+            a Suspense boundary can preserve it across retries (its
+            cached resources survive, so the retry doesn't refetch).
+        key: ``(component identity, element key)`` used to re-match
+            ``hook_state`` on retry.
+        label: Component name for diagnostics.
+    """
+
+    def __init__(self, waitable: Any, hook_state: Any = None, label: str = "") -> None:
+        super().__init__(label or "render suspended")
+        self.waitable = waitable
+        self.hook_state = hook_state
+        self.key: Optional[Tuple[int, Any]] = None
+        self.label = label
+
+
+class CoroDriver:
+    """Drive a coroutine synchronously until it blocks on pending work.
+
+    A miniature :class:`asyncio.Task`: it steps the coroutine with
+    ``send()``, resolving awaits on already-done futures inline. When
+    the coroutine blocks on a *pending* future, the driver parks and
+    resumes from that future's done callback (on the framework loop's
+    thread). Each step runs inside the :mod:`contextvars` context
+    captured at creation, so hooks called after an ``await`` still see
+    the owning component's hook state.
+
+    Attributes:
+        done: Whether the coroutine finished (returned, raised, or was
+            cancelled).
+    """
+
+    __slots__ = (
+        "_coro",
+        "_context",
+        "done",
+        "_cancelled",
+        "_result",
+        "_error",
+        "_callbacks",
+        "_waiting_on",
+        "_stepping",
+    )
+
+    def __init__(self, coro: Any, context: Optional[contextvars.Context] = None) -> None:
+        self._coro = coro
+        self._context = context if context is not None else contextvars.copy_context()
+        self.done = False
+        self._cancelled = False
+        self._result: Any = _UNSET
+        self._error: Optional[BaseException] = None
+        self._callbacks: List[Callable[["CoroDriver"], None]] = []
+        self._waiting_on: Optional[Any] = None
+        self._stepping = False
+
+    # -- inspection ------------------------------------------------------
+
+    def cancelled(self) -> bool:
+        """Whether the driver was cancelled before finishing normally."""
+        return self._cancelled
+
+    def result(self) -> Any:
+        """Return the coroutine's return value (raises if not done or failed)."""
+        if not self.done:
+            raise RuntimeError("CoroDriver is not done")
+        if self._error is not None:
+            raise self._error
+        return self._result
+
+    def exception(self) -> Optional[BaseException]:
+        """Return the coroutine's exception, or ``None``."""
+        if not self.done:
+            raise RuntimeError("CoroDriver is not done")
+        return self._error
+
+    def add_done_callback(self, callback: Callable[["CoroDriver"], None]) -> None:
+        """Invoke ``callback(self)`` when the coroutine finishes.
+
+        Fires immediately when already done. Callbacks run on whatever
+        thread finished the coroutine (the framework loop's thread for
+        suspended coroutines).
+        """
+        if self.done:
+            callback(self)
+            return
+        self._callbacks.append(callback)
+
+    # -- driving ---------------------------------------------------------
+
+    def start(self) -> None:
+        """Run the coroutine as far as it can go without blocking."""
+        self._step(("send", None))
+
+    def cancel(self) -> bool:
+        """Throw :class:`asyncio.CancelledError` into the coroutine.
+
+        Returns:
+            ``False`` when the coroutine had already finished,
+            ``True`` otherwise.
+        """
+        if self.done:
+            return False
+        waiting = self._waiting_on
+        self._waiting_on = None
+        if waiting is not None:
+            try:
+                waiting.remove_done_callback(self._resume)
+            except Exception:
+                pass
+        self._cancelled = True
+        self._step(("throw", asyncio.CancelledError()))
+        return True
+
+    def _resume(self, _fut: Any) -> None:
+        self._waiting_on = None
+        self._step(("send", None))
+
+    def _step(self, action: Tuple[str, Any]) -> None:
+        if self.done or self._stepping:
+            return
+        self._stepping = True
+        # When a step runs outside a loop iteration (a synchronous
+        # render), mark the framework loop as the running loop for the
+        # duration, exactly as asyncio.Task steps do. Without this,
+        # anything the coroutine calls that uses
+        # ``asyncio.get_running_loop()`` internally (``asyncio.sleep``,
+        # ``asyncio.create_task``, ...) raises "no running event loop".
+        from . import runtime
+
+        events = asyncio.events
+        installed_loop = None
+        if events._get_running_loop() is None:
+            installed_loop = runtime.get_loop()
+            events._set_running_loop(installed_loop)
+        try:
+            self._context.run(self._advance, action)
+        finally:
+            if installed_loop is not None:
+                events._set_running_loop(None)
+            self._stepping = False
+
+    def _advance(self, action: Tuple[str, Any]) -> None:
+        kind, value = action
+        while True:
+            try:
+                if kind == "throw":
+                    yielded = self._coro.throw(value)
+                else:
+                    yielded = self._coro.send(value)
+            except StopIteration as stop:
+                self._finish(stop.value, None)
+                return
+            except asyncio.CancelledError as exc:
+                self._cancelled = True
+                self._finish(None, exc)
+                return
+            except BaseException as exc:
+                self._finish(None, exc)
+                return
+
+            kind, value = "send", None
+            if yielded is None:
+                # ``await asyncio.sleep(0)`` and bare yields: resume on
+                # the next loop tick to preserve cooperative yielding.
+                from . import runtime
+
+                runtime.get_loop().call_soon(self._resume, None)
+                return
+            if isinstance(yielded, asyncio.Future):
+                # Mirror asyncio.Task's handshake with Future.__await__.
+                try:
+                    yielded._asyncio_future_blocking = False
+                except AttributeError:
+                    pass
+                if yielded.done():
+                    continue
+                self._waiting_on = yielded
+                yielded.add_done_callback(self._resume)
+                return
+            self._finish(
+                None,
+                RuntimeError(
+                    f"async component awaited an unsupported object: {yielded!r}. "
+                    "Await asyncio futures, tasks, or PythonNative awaitables."
+                ),
+            )
+            return
+
+    def _finish(self, result: Any, error: Optional[BaseException]) -> None:
+        self.done = True
+        self._result = result
+        self._error = error
+        self._waiting_on = None
+        callbacks = self._callbacks
+        self._callbacks = []
+        for callback in callbacks:
+            try:
+                callback(self)
+            except Exception as exc:
+                print(f"[pn.suspense] done callback raised: {exc!r}")
+
+
+class Resource(Generic[T]):
+    """A cached async value with Suspense integration.
+
+    Returned by [`use_resource`][pythonnative.use_resource]. A resource
+    starts fetching as soon as the hook runs and remembers its result
+    across renders (until its dependencies change), so re-renders never
+    refetch.
+
+    Two ways to consume it:
+
+    - ``resource.read()`` in a regular component: returns the value
+      when ready, re-raises the fetcher's error if it failed, and
+      **suspends the render** while pending.
+    - ``await resource`` in an ``async def`` component: same
+      semantics, expressed as a plain await.
+    """
+
+    __slots__ = ("_driver",)
+
+    def __init__(self, driver: CoroDriver) -> None:
+        self._driver = driver
+
+    @property
+    def ready(self) -> bool:
+        """Whether the fetch has finished (successfully or not)."""
+        return self._driver.done
+
+    def read(self) -> T:
+        """Return the fetched value, or suspend the render while pending.
+
+        Raises:
+            Suspend: While the fetch is still in flight (caught by the
+                reconciler, never by user code).
+            BaseException: Whatever the fetcher raised, re-raised so an
+                enclosing [`ErrorBoundary`][pythonnative.ErrorBoundary]
+                can catch it.
+        """
+        driver = self._driver
+        if driver.done:
+            return driver.result()
+        raise Suspend(driver, label="Resource.read")
+
+    def __await__(self) -> Any:
+        driver = self._driver
+        if driver.done:
+
+            def _done() -> Any:
+                return driver.result()
+                yield  # pragma: no cover - marks this as a generator
+
+            return _done()
+        from . import runtime
+
+        future = runtime.create_future()
+
+        def _transfer(d: CoroDriver) -> None:
+            error = d.exception() if not d.cancelled() else asyncio.CancelledError()
+            if error is not None:
+                runtime.reject_future(future, error)
+            else:
+                runtime.resolve_future(future, d.result())
+
+        driver.add_done_callback(_transfer)
+        return future.__await__()
+
+    def cancel(self) -> None:
+        """Cancel the in-flight fetch (no-op when already done)."""
+        self._driver.cancel()
+
+
+def start_resource(fetcher: Callable[[], Any]) -> Resource[Any]:
+    """Start ``fetcher`` immediately and wrap it in a [`Resource`][pythonnative.Resource].
+
+    The fetcher may be an ``async def`` (typical) or a plain function;
+    synchronous results resolve the resource immediately, so reading
+    it never suspends.
+
+    This is the non-hook constructor used for module-level resources
+    (preloading data before a screen mounts) and by
+    [`lazy`][pythonnative.lazy]. Inside components, prefer
+    [`use_resource`][pythonnative.use_resource], which caches per
+    component instance and re-fetches when dependencies change.
+    """
+
+    async def _run() -> Any:
+        value = fetcher()
+        if inspect.isawaitable(value):
+            return await value
+        return value
+
+    driver = CoroDriver(_run())
+    driver.start()
+    return Resource(driver)
+
+
+def lazy(loader: Callable[[], Any]) -> Callable[..., Any]:
+    """Define a component that loads its implementation on first render.
+
+    ``loader`` runs once, the first time the returned component
+    renders; until it resolves, renders suspend (so wrap usages in a
+    [`Suspense`][pythonnative.Suspense] boundary to show a loading
+    state). The loaded value must be a component (a ``@component``
+    function or any element factory).
+
+    Args:
+        loader: A zero-arg callable returning the component, or an
+            ``async def`` resolving to it. Synchronous loaders (a
+            deferred ``import``) resolve immediately and never
+            suspend.
+
+    Returns:
+        A component. Props (and children) pass through to the loaded
+        component unchanged.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        Chart = pn.lazy(lambda: __import__("app.chart", fromlist=["Chart"]).Chart)
+
+        @pn.component
+        def Dashboard():
+            return pn.Suspense(
+                Chart(points=[1, 2, 3]),
+                fallback=pn.ActivityIndicator(),
+            )
+        ```
+    """
+    from .hooks import component
+
+    state: dict = {}
+
+    @component
+    def Lazy(**props: Any) -> Any:
+        resource = state.get("resource")
+        if resource is None:
+            resource = start_resource(loader)
+            state["resource"] = resource
+        loaded = resource.read()
+        children = props.pop("children", None)
+        if children:
+            return loaded(*children, **props)
+        return loaded(**props)
+
+    Lazy.__name__ = getattr(loader, "__name__", "Lazy")
+    if Lazy.__name__ == "<lambda>":
+        Lazy.__name__ = "Lazy"
+    return Lazy
+
+
+__all__ = [
+    "CoroDriver",
+    "Resource",
+    "Suspend",
+    "lazy",
+    "start_resource",
+]

pythonnative/templates/android_template/app/build.gradle

@@ -27,6 +27,11 @@ android {
         }
     }
 
+    buildFeatures {
+        // MainActivity gates dev-only behavior (hot reload) on BuildConfig.DEBUG.
+        buildConfig true
+    }
+
     buildTypes {
         release {
             minifyEnabled false

pythonnative/templates/android_template/app/src/main/AndroidManifest.xml

@@ -15,6 +15,7 @@
         <activity
             android:name=".MainActivity"
             android:exported="true"
+            android:launchMode="singleTask"
             android:windowSoftInputMode="adjustResize">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />

pythonnative/templates/android_template/app/src/main/java/com/pythonnative/android_template/MainActivity.kt

@@ -1,39 +1,115 @@
 package com.pythonnative.android_template
 
-import androidx.appcompat.app.AppCompatActivity
+import android.content.Intent
+import android.graphics.Color
+import android.graphics.Typeface
 import android.os.Bundle
 import android.util.Log
+import android.util.TypedValue
+import android.widget.ScrollView
 import android.widget.TextView
+import androidx.appcompat.app.AppCompatActivity
 import com.chaquo.python.Python
 import com.chaquo.python.android.AndroidPlatform
 
 class MainActivity : AppCompatActivity() {
     private val TAG = javaClass.simpleName
+    private var pythonReady = false
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         Log.d(TAG, "onCreate() called")
 
-        // Initialize Chaquopy
         if (!Python.isStarted()) {
             Python.start(AndroidPlatform(this))
         }
         try {
-            // Set content view to the NavHost layout; the initial screen loads via nav_graph startDestination
+            // Set content view to the NavHost layout; the initial screen
+            // loads via nav_graph startDestination.
             setContentView(R.layout.activity_main)
-            // Optionally, bootstrap Python so first fragment can create the initial screen onCreate
             val py = Python.getInstance()
-            py.getModule("pythonnative.hot_reload").callAttr(
-                "configure_dev_environment",
-                filesDir.absolutePath
-            )
-            // Touch module to ensure bundled Python code is available; actual instantiation happens in ScreenFragment
+            if (BuildConfig.DEBUG) {
+                // Dev-only writable source overlay for hot reload.
+                py.getModule("pythonnative.hot_reload").callAttr(
+                    "configure_dev_environment",
+                    filesDir.absolutePath
+                )
+            }
+            // Import the entry module now so a broken app fails here,
+            // with a full traceback, instead of inside the first fragment.
             py.getModule("app.main")
+            pythonReady = true
         } catch (e: Exception) {
             Log.e("PythonNative", "Bootstrap failed", e)
-            val tv = TextView(this)
-            tv.text = "Hello from PythonNative (Android template)"
-            setContentView(tv)
+            showBootstrapError(e)
+            return
+        }
+
+        // A cold start from a deep link carries the URL on the launch intent.
+        intent?.dataString?.let { dispatchUrl(it) }
+    }
+
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        setIntent(intent)
+        intent.dataString?.let { dispatchUrl(it) }
+    }
+
+    // MARK: - AppState forwarding
+
+    override fun onResume() {
+        super.onResume()
+        dispatchAppState("active")
+    }
+
+    override fun onPause() {
+        super.onPause()
+        dispatchAppState("inactive")
+    }
+
+    override fun onStop() {
+        super.onStop()
+        dispatchAppState("background")
+    }
+
+    private fun dispatchAppState(state: String) {
+        if (!pythonReady) return
+        try {
+            Python.getInstance()
+                .getModule("pythonnative.native_modules.app_state")
+                .callAttr("dispatch_app_state", state)
+        } catch (e: Exception) {
+            Log.e("PythonNative", "dispatch_app_state($state) failed", e)
         }
     }
+
+    // MARK: - Deep links
+
+    private fun dispatchUrl(url: String) {
+        if (!pythonReady) return
+        try {
+            Python.getInstance()
+                .getModule("pythonnative.native_modules.linking")
+                .callAttr("dispatch_url", url)
+        } catch (e: Exception) {
+            Log.e("PythonNative", "dispatch_url failed", e)
+        }
+    }
+
+    // MARK: - Bootstrap error UI
+
+    private fun showBootstrapError(error: Exception) {
+        val text = TextView(this)
+        text.text = "PythonNative could not start\n\n" + Log.getStackTraceString(error)
+        text.setTextColor(Color.WHITE)
+        text.setBackgroundColor(Color.rgb(191, 26, 26))
+        text.typeface = Typeface.MONOSPACE
+        text.setTextSize(TypedValue.COMPLEX_UNIT_SP, 12f)
+        val pad = (16 * resources.displayMetrics.density).toInt()
+        text.setPadding(pad, pad * 3, pad, pad * 2)
+        val scroll = ScrollView(this)
+        scroll.setBackgroundColor(Color.rgb(191, 26, 26))
+        scroll.addView(text)
+        setContentView(scroll)
+    }
 }