pythonnative 0.16.0__py3-none-any.whl → 0.17.0__py3-none-any.whl

pythonnative/__init__.py

@@ -51,9 +51,9 @@ Example:
     ```
 """
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"
 
-from . import sdk
+from . import runtime, sdk
 from .alerts import Alert
 from .animated import Animated, AnimatedValue, use_animated_value
 from .components import (
@@ -103,17 +103,23 @@ from .components import (
 )
 from .element import Element
 from .hooks import (
+    MutationCall,
+    MutationState,
     Provider,
+    QueryResult,
     batch_updates,
     component,
     create_context,
     memo,
+    use_async_effect,
     use_callback,
     use_context,
     use_effect,
     use_keyboard_height,
     use_memo,
+    use_mutation,
     use_navigation,
+    use_query,
     use_reducer,
     use_ref,
     use_safe_area_insets,
@@ -129,7 +135,9 @@ from .navigation import (
     use_focus_effect,
     use_route,
 )
+from .net import HTTPError, Response, fetch
 from .platform import Platform
+from .runtime import run_async
 from .screen import create_screen
 from .sdk import (
     Props,
@@ -138,6 +146,7 @@ from .sdk import (
     native_component,
     register_component,
 )
+from .storage import AsyncStorage, use_persisted_state
 from .style import (
     AlignItems,
     AlignSelf,
@@ -219,13 +228,20 @@ __all__ = [
     "component",
     "create_context",
     "memo",
+    "MutationCall",
+    "MutationState",
+    "QueryResult",
+    "use_async_effect",
     "use_callback",
     "use_context",
     "use_effect",
     "use_focus_effect",
     "use_keyboard_height",
     "use_memo",
+    "use_mutation",
     "use_navigation",
+    "use_persisted_state",
+    "use_query",
     "use_reducer",
     "use_ref",
     "use_route",
@@ -274,6 +290,14 @@ __all__ = [
     "FileSystem",
     "Location",
     "Notifications",
+    # Networking + persistence
+    "AsyncStorage",
+    "fetch",
+    "HTTPError",
+    "Response",
+    # Runtime
+    "run_async",
+    "runtime",
     # Platform
     "Platform",
     # Custom-component SDK

pythonnative/alerts.py

@@ -1,112 +1,298 @@
-"""Imperative system alerts.
+"""Imperative, awaitable system alerts.
 
-Modeled on React Native's `Alert.alert()`. Alerts are not part of
-the element tree — they're imperative, fire-and-forget calls that
-trigger a native dialog.
+Inspired by React Native's ``Alert.alert()`` but designed around
+``async`` / ``await`` instead of per-button callbacks. There are three
+entry points:
+
+- [`Alert.show`][pythonnative.alerts.Alert.show]: fire-and-forget
+  one-button notice (no return value).
+- [`Alert.confirm`][pythonnative.alerts.Alert.confirm]: awaitable
+  two-button yes/no, resolves to a ``bool``.
+- [`Alert.choose`][pythonnative.alerts.Alert.choose]: awaitable
+  multi-button picker / action sheet, resolves to the selected
+  label (or ``None`` if dismissed).
 
 Example:
     ```python
     import pythonnative as pn
 
-    def confirm_delete():
-        pn.Alert.show(
+
+    async def maybe_delete():
+        if await pn.Alert.confirm(
             title="Delete item?",
             message="This action cannot be undone.",
-            buttons=[
-                {"label": "Cancel", "style": "cancel"},
-                {
-                    "label": "Delete",
-                    "style": "destructive",
-                    "on_press": delete_item,
-                },
-            ],
-        )
+            confirm_label="Delete",
+            cancel_label="Keep",
+        ):
+            await delete_item()
     ```
 """
 
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, List, Optional
+import asyncio
+from typing import Any, Dict, List, Optional, Sequence
 
 from .platform import Platform
+from .runtime import resolve_future
+
+# ======================================================================
+# Internal dispatch helpers
+# ======================================================================
+
+
+def _dispatch_alert(
+    *,
+    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.
+
+    ``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.
+    """
+    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)
+
+
+# ======================================================================
+# Public Alert API
+# ======================================================================
 
 
 class Alert:
     """Imperative alert / action-sheet helper.
 
-    All methods are static. Use `Alert.show()` for an alert dialog
-    and pass ``style="action_sheet"`` for an iOS-style action sheet.
+    All methods are static. Use [`show`][pythonnative.alerts.Alert.show]
+    for a fire-and-forget single-button notice,
+    [`confirm`][pythonnative.alerts.Alert.confirm] for an awaitable
+    yes/no dialog, and
+    [`choose`][pythonnative.alerts.Alert.choose] for a multi-option
+    picker.
     """
 
+    #: Records every alert call when running off-device. Tests reset
+    #: this between cases via ``Alert._test_log.clear()``. Each entry
+    #: contains ``title``, ``message``, ``buttons``, and ``style``.
+    _test_log: List[Dict[str, Any]] = []
+
+    #: Queue of indices to deliver to upcoming alerts in tests. Set via
+    #: [`Alert.set_test_response`][pythonnative.alerts.Alert.set_test_response].
+    #: A negative value (or empty queue) simulates a dismiss.
+    _test_responses: List[int] = []
+
+    @staticmethod
+    def set_test_response(*indices: int) -> None:
+        """Queue indices to return from upcoming test alerts.
+
+        Use in async tests to script the user's choices: each pending
+        call to [`confirm`][pythonnative.alerts.Alert.confirm] or
+        [`choose`][pythonnative.alerts.Alert.choose] pops the next
+        queued index. Pass ``-1`` to simulate a dismiss.
+
+        Args:
+            *indices: Sequence of button indices to deliver, oldest
+                first. Calls beyond the queue length resolve to ``-1``.
+        """
+        Alert._test_responses[:] = list(indices)
+
+    @staticmethod
+    def _next_test_response() -> int:
+        if Alert._test_responses:
+            return Alert._test_responses.pop(0)
+        return -1
+
     @staticmethod
     def show(
-        *,
         title: str,
         message: Optional[str] = None,
-        buttons: Optional[List[Dict[str, Any]]] = None,
-        style: str = "alert",
+        *,
+        button: str = "OK",
     ) -> None:
-        """Present a native alert dialog or action sheet.
+        """Display a simple, one-button alert and return immediately.
 
         Args:
-            title: Dialog title (required).
+            title: Dialog title.
             message: Optional body text.
-            buttons: Each button is ``{"label": str, "style":
-                "default"|"cancel"|"destructive", "on_press": callable}``.
-                Defaults to a single "OK" button.
-            style: ``"alert"`` (default) or ``"action_sheet"``.
-
-        On iOS this uses ``UIAlertController``; on Android it uses
-        ``AlertDialog.Builder``. On the test backend the call is a
-        no-op so unit tests don't need to mock UIKit/AndroidX.
-        """
-        if Platform.is_ios:
-            try:
-                from .native_views.ios import _present_alert as _ios_present_alert
+            button: Label for the single dismiss button (default
+                ``"OK"``).
 
-                _ios_present_alert(title=title, message=message, buttons=buttons or [], style=style)
-            except Exception:
-                pass
-            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 or [], style=style)
-            except Exception:
-                pass
-            return
-        # Test environment: record the call so unit tests can assert on it.
-        Alert._test_log.append(
-            {
-                "title": title,
-                "message": message,
-                "buttons": list(buttons or []),
-                "style": style,
-            }
+        This is fire-and-forget. To know what the user did, use
+        [`confirm`][pythonnative.alerts.Alert.confirm] or
+        [`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,
         )
 
     @staticmethod
-    def confirm(
-        *,
+    async def confirm(
         title: str,
         message: Optional[str] = None,
+        *,
         confirm_label: str = "OK",
         cancel_label: str = "Cancel",
-        on_confirm: Optional[Callable[[], None]] = None,
-        on_cancel: Optional[Callable[[], None]] = None,
-    ) -> None:
-        """Convenience wrapper for two-button confirm/cancel dialogs."""
-        Alert.show(
+    ) -> bool:
+        """Present a two-button yes/no dialog and wait for the choice.
+
+        Args:
+            title: Dialog title.
+            message: Optional body text.
+            confirm_label: Label for the "yes" button (default
+                ``"OK"``).
+            cancel_label: Label for the "no" button (default
+                ``"Cancel"``).
+
+        Returns:
+            ``True`` if the user pressed the confirm button, ``False``
+            for the cancel button or a dismiss.
+
+        Example:
+            ```python
+            if await pn.Alert.confirm("Save changes?"):
+                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(
             title=title,
             message=message,
             buttons=[
-                {"label": cancel_label, "style": "cancel", "on_press": on_cancel},
-                {"label": confirm_label, "style": "default", "on_press": on_confirm},
+                {"label": cancel_label, "style": "cancel"},
+                {"label": confirm_label, "style": "default"},
             ],
+            style="alert",
+            on_result=_on_result,
         )
+        return await future
 
-    #: Records every Alert.show call when running off-device. Tests
-    #: should reset this list between cases via
-    #: ``Alert._test_log.clear()``.
-    _test_log: List[Dict[str, Any]] = []
+    @staticmethod
+    async def choose(
+        title: str,
+        options: Sequence[str],
+        *,
+        message: Optional[str] = None,
+        cancel_label: Optional[str] = None,
+        style: str = "action_sheet",
+        destructive_labels: Sequence[str] = (),
+    ) -> Optional[str]:
+        """Present a multi-option picker and wait for the user's choice.
+
+        Args:
+            title: Dialog title.
+            options: Sequence of option labels (in display order).
+            message: Optional body text.
+            cancel_label: If provided, adds a "cancel" button with
+                this label. Selecting it resolves to ``None``.
+            style: ``"action_sheet"`` (default) for an iOS-style
+                sheet, or ``"alert"`` for a stacked alert dialog.
+            destructive_labels: Labels in ``options`` that should be
+                styled destructively (red on iOS).
+
+        Returns:
+            The selected label, or ``None`` if the user dismissed or
+            tapped the cancel button.
+
+        Example:
+            ```python
+            choice = await pn.Alert.choose(
+                "Photo source",
+                options=["Camera", "Gallery"],
+                cancel_label="Cancel",
+            )
+            if choice == "Camera":
+                ...
+            ```
+        """
+        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]] = [
+            {
+                "label": opt,
+                "style": "destructive" if opt in destructive else "default",
+            }
+            for opt in options
+        ]
+        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
+
+
+__all__ = ["Alert"]