pythonnative 0.48.0__tar.gz → 0.49.0__tar.gz

{pythonnative-0.48.0/src/pythonnative.egg-info → pythonnative-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.48.0
+Version: 0.49.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License

{pythonnative-0.48.0 → pythonnative-0.49.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.48.0"
+version = "0.49.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -99,6 +99,7 @@ pythonnative = [
   "templates/**", "native/**", "sdk/templates/**",
   "devserver/static/**",
   "icons/_lucide.json", "icons/LICENSE-lucide.txt",
+  "sdk/_builtin_contracts.json",
 ]
 
 [tool.setuptools.exclude-package-data]

{pythonnative-0.48.0 → pythonnative-0.49.0}/src/pythonnative/__init__.py

@@ -66,11 +66,13 @@ Example:
     ```
 """
 
-__version__ = "0.48.0"
+__version__ = "0.49.0"
 
-from . import appearance, diagnostics, gestures, icons, runtime, sdk, svg
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from . import appearance, diagnostics, runtime, sdk, svg
 from .alerts import Alert
-from .animated import ANIMATABLE_PROPS, Animated, AnimatedValue, AnimationResult, Easing, EasingSpec, use_animated_value
 from .assets import Asset, asset
 from .component import Component, component, memo
 from .components import (
@@ -124,7 +126,6 @@ from .components import (
 from .components.props import AccessibilityProps, ViewProps
 from .diagnostics import HookOrderError
 from .element import Element, Node
-from .gestures import GestureSpec, SwipeDirection
 from .handles import ScrollOffset, ScrollViewHandle, TextInputHandle, ViewHandle, WebViewHandle
 from .hooks import (
     ColorScheme,
@@ -157,7 +158,6 @@ from .hooks import (
     use_window_dimensions,
 )
 from .hosts import create_screen
-from .icons import Icon, IconName
 from .mutations import UNSET, UnsetType
 from .native_modules import (
     AccessibilityEvent,
@@ -194,27 +194,6 @@ from .native_modules import (
     use_reduce_motion,
     use_screen_reader_enabled,
 )
-from .navigation import (
-    DrawerNavigator,
-    Group,
-    Navigation,
-    NavigationContainer,
-    NavigationRef,
-    NavigationState,
-    Navigator,
-    Route,
-    Screen,
-    ScreenOptions,
-    StackNavigator,
-    TabBarStyle,
-    TabNavigator,
-    use_focus_effect,
-    use_is_focused,
-    use_navigation,
-    use_route,
-    use_screen_options,
-)
-from .net import HTTPError, Response, fetch
 from .platform import Platform, get_platform
 from .platform_metrics import WindowDimensions
 from .runtime import run_async, run_blocking
@@ -527,3 +506,92 @@ __all__ = [
 ]
 
 from .list_data import ListData, Section, ViewableItem
+
+# Subsystems an app may never touch load on first use (PEP 562), so
+# ``import pythonnative`` stays fast on a phone. Names, ``__all__``, and
+# documentation are unchanged, and type checkers see ordinary imports.
+_LAZY_GROUPS: dict[str, tuple[str, ...]] = {
+    "animated": (
+        "ANIMATABLE_PROPS",
+        "Animated",
+        "AnimatedValue",
+        "AnimationResult",
+        "Easing",
+        "EasingSpec",
+        "use_animated_value",
+    ),
+    "gestures": ("GestureSpec", "SwipeDirection"),
+    "icons": ("Icon", "IconName"),
+    "navigation": (
+        "DrawerNavigator",
+        "Group",
+        "Navigation",
+        "NavigationContainer",
+        "NavigationRef",
+        "NavigationState",
+        "Navigator",
+        "Route",
+        "Screen",
+        "ScreenOptions",
+        "StackNavigator",
+        "TabBarStyle",
+        "TabNavigator",
+        "use_focus_effect",
+        "use_is_focused",
+        "use_navigation",
+        "use_route",
+        "use_screen_options",
+    ),
+    "net": ("HTTPError", "Response", "fetch"),
+}
+_LAZY = {name: module for module, names in _LAZY_GROUPS.items() for name in names}
+_LAZY_MODULES = frozenset({"gestures", "icons"})
+
+if TYPE_CHECKING:
+    from . import gestures, icons
+    from .animated import (
+        ANIMATABLE_PROPS,
+        Animated,
+        AnimatedValue,
+        AnimationResult,
+        Easing,
+        EasingSpec,
+        use_animated_value,
+    )
+    from .gestures import GestureSpec, SwipeDirection
+    from .icons import Icon, IconName
+    from .navigation import (
+        DrawerNavigator,
+        Group,
+        Navigation,
+        NavigationContainer,
+        NavigationRef,
+        NavigationState,
+        Navigator,
+        Route,
+        Screen,
+        ScreenOptions,
+        StackNavigator,
+        TabBarStyle,
+        TabNavigator,
+        use_focus_effect,
+        use_is_focused,
+        use_navigation,
+        use_route,
+        use_screen_options,
+    )
+    from .net import HTTPError, Response, fetch
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None and name not in _LAZY_MODULES:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    imported = importlib.import_module(f".{module or name}", __name__)
+    value = imported if module is None else getattr(imported, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | _LAZY.keys() | _LAZY_MODULES)

{pythonnative-0.48.0 → pythonnative-0.49.0}/src/pythonnative/bootstrap.py

@@ -1,16 +1,17 @@
 """Entry point the native app templates run right after Python starts.
 
-Both templates execute one line of Python once the interpreter is up:
+Both templates call [`start`][pythonnative.bootstrap.start] once the
+interpreter is up, on a background thread at launch:
 
 ```python
-import pythonnative.bootstrap; pythonnative.bootstrap.start()
+pythonnative.bootstrap.start(dev, True, "app.main")
 ```
 
-[`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, warms the
-asyncio runtime, and, in debug builds, starts the dev client that syncs
-sources from ``pn start``. From then on the native runtime drives
+It 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, warms the asyncio runtime, in debug builds starts the dev
+client that syncs sources from ``pn start``, and imports the entry module,
+so the first screen only has to render. From then on the native runtime drives
 everything through ``callback("host", ...)``; see ``docs/concepts/bridge.md``.
 """
 
@@ -19,14 +20,14 @@ from __future__ import annotations
 import os
 import sys
 import traceback
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 __all__ = ["start", "status"]
 
 _started: Dict[str, Any] = {}
 
 
-def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
+def start(dev: bool = False, strict: bool = False, entry: Optional[str] = None) -> Dict[str, Any]:
     """Connect the bridge and prepare the runtime.
 
     Args:
@@ -35,6 +36,9 @@ def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
         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.
+        entry: The app's entry module, imported last so a broken app
+            fails here with its traceback, and so the first screen
+            doesn't pay for the import.
 
     Returns:
         A status dict (``{"protocol": 2, "platform": "ios"}``) that the
@@ -89,6 +93,10 @@ def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
             from .assets import configure_native
 
             configure_native()
+        if entry:
+            import importlib
+
+            importlib.import_module(entry)
     except Exception as exc:
         status_["error"] = f"{type(exc).__name__}: {exc}"
         print(f"[pn.bootstrap] start failed: {exc!r}", file=sys.stderr)

{pythonnative-0.48.0 → pythonnative-0.49.0}/src/pythonnative/bridge/__init__.py

@@ -1,9 +1,9 @@
 """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
+[`Transport`][pythonnative.bridge.Transport] (``apply`` a transaction, 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``.
 
@@ -19,7 +19,7 @@ tests that want to exercise the bridge itself install a
 from __future__ import annotations
 
 import threading
-from typing import Callable, Optional, Protocol, Tuple
+from typing import Callable, Optional, Protocol
 
 from . import codec
 
@@ -39,7 +39,13 @@ from .commits import PROTOCOL_VERSION
 
 
 class Transport(Protocol):
-    """The Python -> native half of the bridge."""
+    """The Python -> native half of the bridge.
+
+    Native and browser transports run Yoga beside their widgets. Only the
+    headless [`FakeTransport`][pythonnative.bridge.fake.FakeTransport] lays
+    out in Python, so it alone also answers ``measure`` and accepts frame
+    (``f``) operations.
+    """
 
     name: str
 
@@ -49,9 +55,6 @@ class Transport(Protocol):
     def apply(self, transaction_json: str) -> str:
         """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``."""
 
@@ -61,7 +64,7 @@ class Transport(Protocol):
     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:
+    def set_callback(self, callback: Callable[[str, int, str, str], None]) -> None:
         """Install ``callback`` as the native -> Python entry point."""
 
 
@@ -154,11 +157,11 @@ def handshake() -> int:
             "installed pythonnative package."
         )
     if getattr(get_transport(), "name", "") in {"ios", "android"}:
-        from ..sdk.schema import fingerprint
+        from ..sdk.schema import YOGA_VERSION, fingerprint
 
         reply = codec.loads(get_transport().call("Runtime", "capabilities", codec.dumps({"id": 0, "args": {}})))
         capabilities = reply.get("value", {}) if isinstance(reply, dict) else {}
-        if capabilities.get("schema") != fingerprint() or capabilities.get("yoga") != "3.2.1":
+        if capabilities.get("schema") != fingerprint() or capabilities.get("yoga") != YOGA_VERSION:
             raise RuntimeError("Native component contracts changed. Rebuild the app with 'pn run'.")
     return version
 
@@ -168,74 +171,78 @@ def handshake() -> int:
 # ======================================================================
 
 
-# Callback threads coalesce continuous input before the application loop drains.
+# Callback threads coalesce continuous input before the application loop
+# drains. Native callback threads and the loop both change the table.
 _continuous: dict[tuple[int, str], list[str]] = {}
+_continuous_lock = threading.Lock()
+_CONTINUOUS_EVENTS = frozenset({"on_scroll", "on_window", "on_selection_change", "on_gesture_update"})
 
 
 def _deliver_continuous(tag: int, name: str, slot: list[str]) -> None:
-    if _continuous.get((tag, name)) is slot:
-        _continuous.pop((tag, name), None)
-    native_callback("event", tag, name, slot[0])
+    with _continuous_lock:
+        if _continuous.get((tag, name)) is slot:
+            del _continuous[(tag, name)]
+        payload = slot[0]
+    native_callback("event", tag, name, payload)
 
 
-def native_callback(kind: str, tag: int, name: str, payload: str) -> Optional[str]:
+def native_callback(kind: str, tag: int, name: str, payload: str) -> None:
     """Single entry point for every native -> Python message.
 
+    Native delivers every message asynchronously, from its events thread,
+    and never waits for a result. This function never raises: failures
+    are reported through ``diagnostics`` so nothing propagates into UIKit
+    or the Android looper.
+
     Args:
-        kind: ``"event"``, ``"module"``, ``"host"``, ``"animation"``,
-            or ``"pump"``.
+        kind: ``"event"``, ``"module"``, ``"host"``, ``"animation"``, or
+            ``"layout"``.
         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.
     """
     from ..runtime import _on_loop_thread, get_loop
 
     loop = get_loop()
     if loop.is_running() and not _on_loop_thread(loop):
-        if kind == "event" and name in {"on_scroll", "on_window", "on_selection_change", "on_gesture_update"}:
+        if kind == "event" and name in _CONTINUOUS_EVENTS:
             key = (tag, name)
-            slot = _continuous.get(key)
-            if slot is None:
-                slot = [payload]
-                _continuous[key] = slot
-                loop.call_soon_threadsafe(_deliver_continuous, tag, name, slot)
-            else:
-                slot[0] = payload
+            with _continuous_lock:
+                slot = _continuous.get(key)
+                if slot is not None:
+                    slot[0] = payload
+                    return None
+                slot = _continuous[key] = [payload]
+            loop.call_soon_threadsafe(_deliver_continuous, tag, name, slot)
         else:
-            _continuous.clear()
+            # Later continuous input starts a new slot, delivered after
+            # this discrete message.
+            with _continuous_lock:
+                _continuous.clear()
             loop.call_soon_threadsafe(native_callback, kind, tag, name, payload)
-        return None
+        return
     try:
         if kind == "layout":
             from ..native_views import get_backend
 
             get_backend().accept_layout(codec.loads(payload))
-            return None
-        if kind == "event":
-            return _on_event(int(tag), name, payload)
-        if kind == "module":
+        elif kind == "event":
+            _on_event(int(tag), name, payload)
+        elif kind == "module":
             from ..native_modules.registry import dispatch_module_message
 
             dispatch_module_message(name, codec.loads(payload) or {})
-            return None
-        if kind == "host":
+        elif kind == "host":
             from ..hosts.native import dispatch_host_event
 
-            return dispatch_host_event(int(tag), name, codec.loads(payload))
-        if kind == "animation":
+            dispatch_host_event(int(tag), name, codec.loads(payload))
+        elif 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
-        print(f"[pn.bridge] unknown callback kind {kind!r}")
+        else:
+            print(f"[pn.bridge] unknown callback kind {kind!r}")
     except Exception as exc:
         from .. import diagnostics
 
@@ -243,10 +250,9 @@ def native_callback(kind: str, tag: int, name: str, payload: str) -> Optional[st
             import traceback
 
             traceback.print_exc()
-    return None
 
 
-def _on_event(tag: int, name: str, payload: str) -> Optional[str]:
+def _on_event(tag: int, name: str, payload: str) -> None:
     from ..events import get_event_registry
 
     args = codec.loads(payload)
@@ -255,21 +261,20 @@ def _on_event(tag: int, name: str, payload: str) -> Optional[str]:
     backend = get_backend()
     defer = getattr(backend, "defer_event", None)
     if defer is not None and defer(tag, name, args):
-        return None
+        return
     accept = getattr(backend, "accept_event", None)
     if accept is not None:
         if not accept(tag, name, args):
-            return None
+            return
         args = args["args"]
     if args is None:
         args = []
     elif not isinstance(args, list):
         args = [args]
-    callback = get_event_registry().get(tag, name)
-    if callback is None:
-        return None
+    if get_event_registry().get(tag, name) is None:
+        return
     try:
-        result = get_event_registry().invoke(tag, name, *args)
+        get_event_registry().invoke(tag, name, *args)
     except Exception as exc:
         from .. import diagnostics
 
@@ -277,15 +282,6 @@ def _on_event(tag: int, name: str, payload: str) -> Optional[str]:
             import traceback
 
             traceback.print_exc()
-        return None
-    import inspect
-
-    if result is None or inspect.isawaitable(result):
-        return None
-    try:
-        return codec.dumps(codec.to_jsonable(result))
-    except (TypeError, ValueError):
-        return None
 
 
 def _reset_for_tests() -> None:

{pythonnative-0.48.0 → pythonnative-0.49.0}/src/pythonnative/bridge/android.py

@@ -10,7 +10,7 @@ through Chaquopy; this transport therefore has nothing to register.
 
 from __future__ import annotations
 
-from typing import Any, Callable, Optional, Tuple
+from typing import Any, Callable, Optional
 
 __all__ = ["AndroidTransport"]
 
@@ -44,18 +44,6 @@ class AndroidTransport:
         """Apply one serialized transaction (a JSON array of ops)."""
         return str(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))
@@ -68,7 +56,7 @@ class AndroidTransport:
         """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:
+    def set_callback(self, callback: Callable[[str, int, str, str], None]) -> None:
         """No-op: the Android template installs the host through ``PNBridge.setHost``."""
         del callback
 

{pythonnative-0.48.0 → pythonnative-0.49.0}/src/pythonnative/bridge/commits.py

@@ -1,8 +1,14 @@
 """Versioned commit validation and surface ownership.
 
-A commit is validated in full before it changes a native tree. Revisions are
-strictly consecutive within an application and surface. A failed native mount
-poisons that surface until the host explicitly resets and remounts it.
+A commit's structure is validated in full before it changes a native tree.
+Revisions are strictly consecutive within an application and surface. A
+failed native mount poisons that surface until the host explicitly resets and
+remounts it.
+
+Props are checked against component schemas only in development, where
+Python can name the component and prop that's wrong. The native runtimes
+validate every commit with generated validators in every build, so release
+builds don't pay for the same check twice.
 """
 
 from __future__ import annotations
@@ -15,7 +21,8 @@ from typing import Any, Callable
 from ..profiling import count, profiled
 from .list_store import ListStore
 
-PROTOCOL_VERSION = 4
+PROTOCOL_VERSION = 5
+"""The bridge protocol every runtime speaks; generated native contracts carry it."""
 
 
 class CommitError(RuntimeError):
@@ -103,7 +110,7 @@ class CommitState:
     def prepare(self, envelope: Any) -> CommitState:
         """Validate without mutating this state and return the candidate state."""
         if not isinstance(envelope, dict) or envelope.get("version") != PROTOCOL_VERSION:
-            raise CommitError("Expected a protocol v4 commit envelope; rebuild the native client")
+            raise CommitError(f"Expected a protocol v{PROTOCOL_VERSION} commit envelope; rebuild the native client")
         application, surface, revision = (envelope.get(k) for k in ("application", "surface", "revision"))
         if not isinstance(application, str) or not application or type(surface) is not int or surface <= 0:
             raise CommitError("Invalid application or surface identity")
@@ -209,6 +216,10 @@ class CommitState:
 
     @staticmethod
     def _validate_props(name: str, props: dict[str, Any], partial: bool) -> None:
+        from .. import diagnostics
+
+        if not diagnostics.is_dev():
+            return
         from ..sdk.schema import COMPONENTS
 
         schema = COMPONENTS.get(name)

{pythonnative-0.48.0 → pythonnative-0.49.0}/src/pythonnative/bridge/fake.py

@@ -83,7 +83,7 @@ class FakeTransport:
         """Return the protocol version compiled into the native library."""
         return self._version
 
-    def set_callback(self, callback: Callable[[str, int, str, str], Optional[str]]) -> None:
+    def set_callback(self, callback: Callable[[str, int, str, str], None]) -> None:
         """Install ``callback`` as the native -> Python entry point."""
         self.callback = callback
 
@@ -184,13 +184,13 @@ class FakeTransport:
 
     # -- Playing the native side ------------------------------------------
 
-    def fire(self, tag: int, name: str, *args: Any) -> Any:
-        """Emit a view event as native would; returns the decoded handler result."""
+    def fire(self, tag: int, name: str, *args: Any) -> None:
+        """Emit a view event as native would."""
         self._event_sequence = getattr(self, "_event_sequence", 0) + 1
         envelope = self.commit_state.acknowledgement()
         envelope.pop("ok")
         envelope.update(sequence=self._event_sequence, args=[codec.to_jsonable(a) for a in args])
-        return self._callback("event", tag, name, codec.dumps(envelope))
+        self._callback("event", tag, name, codec.dumps(envelope))
 
     def emit_module_event(self, module: str, event: str, payload: Any = None) -> None:
         """Push an unsolicited module event (``AppState`` ``change``, ...) into Python."""
@@ -209,18 +209,18 @@ class FakeTransport:
             body["error"] = error
         self._callback("module", 0, module, codec.dumps(body))
 
-    def host_event(self, screen: int, event: str, payload: Any = None) -> Any:
-        """Deliver a screen lifecycle event as the native host would; returns the decoded result."""
-        return self._callback("host", screen, event, codec.dumps(codec.to_jsonable(payload)))
+    def host_event(self, screen: int, event: str, payload: Any = None) -> None:
+        """Deliver a screen lifecycle event as the native host would."""
+        self._callback("host", screen, event, codec.dumps(codec.to_jsonable(payload)))
 
     def complete_animation(self, anim_id: int, finished: bool = True) -> None:
         """Report a native animation as finished (or interrupted) to Python."""
         self._callback("animation", 0, "", codec.dumps({"id": anim_id, "finished": finished}))
 
-    def _callback(self, kind: str, tag: int, name: str, payload: str) -> Any:
+    def _callback(self, kind: str, tag: int, name: str, payload: str) -> None:
         if self.callback is None:
             raise AssertionError("FakeTransport has no callback; install it with pythonnative.bridge.set_transport")
-        return codec.loads(self.callback(kind, tag, name, payload))
+        self.callback(kind, tag, name, payload)
 
     # -- Introspection -----------------------------------------------------