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

pythonnative/__init__.py

@@ -60,7 +60,7 @@ Example:
     ```
 """
 
-__version__ = "0.24.0"
+__version__ = "0.25.0"
 
 from . import appearance, diagnostics, gestures, images, runtime, sdk
 from .alerts import Alert
@@ -92,6 +92,7 @@ from .components import (
     Slider,
     Spacer,
     StatusBar,
+    Suspense,
     Switch,
     Text,
     TextInput,
@@ -111,11 +112,11 @@ from .hooks import (
     component,
     create_context,
     memo,
-    use_async_effect,
     use_back_handler,
     use_callback,
     use_color_scheme,
     use_context,
+    use_deferred_value,
     use_effect,
     use_imperative_handle,
     use_keyboard_height,
@@ -126,8 +127,10 @@ from .hooks import (
     use_query,
     use_reducer,
     use_ref,
+    use_resource,
     use_safe_area_insets,
     use_state,
+    use_transition,
     use_window_dimensions,
 )
 from .native_modules import (
@@ -160,7 +163,7 @@ from .navigation import (
 )
 from .net import HTTPError, Response, fetch
 from .platform import Platform
-from .runtime import run_async
+from .runtime import run_async, run_blocking
 from .screen import create_screen
 from .sdk import (
     Props,
@@ -204,6 +207,7 @@ from .style import (
     style,
     use_theme,
 )
+from .suspense import Resource, lazy, start_resource
 
 __all__ = [
     # Components
@@ -233,6 +237,7 @@ __all__ = [
     "Slider",
     "Spacer",
     "StatusBar",
+    "Suspense",
     "Switch",
     "Text",
     "TextInput",
@@ -251,11 +256,11 @@ __all__ = [
     "MutationState",
     "QueryResult",
     "Ref",
-    "use_async_effect",
     "use_back_handler",
     "use_callback",
     "use_color_scheme",
     "use_context",
+    "use_deferred_value",
     "use_effect",
     "use_focus_effect",
     "use_imperative_handle",
@@ -268,11 +273,17 @@ __all__ = [
     "use_query",
     "use_reducer",
     "use_ref",
+    "use_resource",
     "use_route",
     "use_safe_area_insets",
     "use_state",
+    "use_transition",
     "use_window_dimensions",
     "Provider",
+    # Suspense and async rendering
+    "Resource",
+    "lazy",
+    "start_resource",
     # Navigation
     "NavigationContainer",
     "ScreenOptions",
@@ -349,6 +360,7 @@ __all__ = [
     "Response",
     # Runtime
     "run_async",
+    "run_blocking",
     "runtime",
     # Diagnostics
     "HookOrderError",

pythonnative/animated.py

@@ -47,7 +47,7 @@ Example:
             await pn.Animated.timing(opacity, to=1.0, duration=400)
             await pn.Animated.timing(opacity, to=0.5, duration=200)
 
-        pn.use_async_effect(fade_in, [])
+        pn.use_effect(fade_in, [])
 
         return pn.Animated.View(
             pn.Text("Hello!"),
@@ -1014,7 +1014,7 @@ def use_animated_value(initial: float = 0.0) -> AnimatedValue:
             async def fade_in():
                 await pn.Animated.timing(opacity, to=1.0, duration=300)
 
-            pn.use_async_effect(fade_in, [])
+            pn.use_effect(fade_in, [])
             return pn.Animated.View(
                 pn.Text("Hello"),
                 style=pn.style(opacity=opacity),

pythonnative/components.py

@@ -1732,6 +1732,65 @@ def ErrorBoundary(
     return Element("__ErrorBoundary__", props, list(children), key=key)
 
 
+def Suspense(
+    *children: Element,
+    fallback: Optional[Any] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Show ``fallback`` while descendants wait on async work, then swap in the content.
+
+    A Suspense boundary catches **suspensions** from the subtree it
+    wraps: an ``async def`` component body blocking on a pending
+    await, or a regular component calling
+    [`Resource.read`][pythonnative.suspense.Resource.read] on data that hasn't
+    arrived (see [`use_resource`][pythonnative.use_resource] and
+    [`lazy`][pythonnative.lazy]). While anything is pending the
+    boundary renders ``fallback``; when the awaited work completes it
+    retries the content and swaps it in. Suspended components keep
+    their hook state across retries, so cached resources aren't
+    refetched.
+
+    Two timing behaviors, matching React:
+
+    - **Initial mount**: the fallback shows until the content is ready.
+    - **Updates**: a component that's already on screen and suspends
+      again (its dependencies changed) keeps its previous content
+      visible and re-renders when ready; there's no fallback flash.
+
+    Args:
+        *children: Subtree to wrap (the async content).
+        fallback: Content shown while suspended: an
+            [`Element`][pythonnative.Element] or a zero-arg callable
+            returning one. Without it, suspensions propagate to the
+            next Suspense boundary up.
+        key: Stable identity for keyed reconciliation.
+
+    Returns:
+        An [`Element`][pythonnative.Element] of type ``"__Suspense__"``.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        async def Profile(user_id: str):
+            user = await api.fetch_user(user_id)
+            return pn.Text(user.name)
+
+        @pn.component
+        def Screen():
+            return pn.Suspense(
+                Profile(user_id="42"),
+                fallback=pn.ActivityIndicator(),
+            )
+        ```
+    """
+    props: Dict[str, Any] = {}
+    if fallback is not None:
+        props["__fallback__"] = fallback
+    return Element("__Suspense__", props, list(children), key=key)
+
+
 # ======================================================================
 # Lists (native virtualization with a Python-windowed fallback)
 # ======================================================================