pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/animation_graph.py

@@ -0,0 +1,78 @@
+"""Portable animation expressions evaluated by the native UI thread."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def serialize(root: Any) -> dict[str, Any]:
+    """Serialize one connected animation graph in dependency order."""
+    from .animated import AnimatedInterpolation, AnimatedNode, AnimatedValue, _AnimatedDiffClamp, _AnimatedOperation
+
+    connected: dict[int, Any] = {}
+
+    def discover(node: Any) -> None:
+        if not isinstance(node, AnimatedNode) or id(node) in connected:
+            return
+        connected[id(node)] = node
+        for child in list(node._children):
+            discover(child)
+        for parent in getattr(node, "_parents", [getattr(node, "_parent", None)]):
+            discover(parent)
+
+    discover(root)
+    encoded: dict[int, dict[str, Any]] = {}
+
+    def encode(node: Any) -> Any:
+        if not isinstance(node, AnimatedNode):
+            return {"constant": float(node)}
+        identity = id(node)
+        if identity not in encoded:
+            definition: dict[str, Any] = {"id": identity}
+            if isinstance(node, AnimatedValue):
+                definition.update(kind="value", value=node.value)
+            elif isinstance(node, AnimatedInterpolation):
+                definition.update(
+                    kind="interpolate",
+                    inputs=[encode(node._parent)],
+                    ranges=node._inputs,
+                    outputs=node._outputs,
+                    color=node._kind == "color",
+                    left=node._left,
+                    right=node._right,
+                )
+            elif isinstance(node, _AnimatedOperation):
+                definition.update(kind=node._op, inputs=[encode(parent) for parent in node._parents])
+            elif isinstance(node, _AnimatedDiffClamp):
+                definition.update(
+                    kind="diff_clamp",
+                    inputs=[encode(node._parent)],
+                    minimum=node._min,
+                    maximum=node._max,
+                    previous=node._last_input,
+                    value=node.value,
+                )
+            else:
+                raise TypeError(f"Unsupported animated node {type(node).__name__}")
+            encoded[identity] = definition
+        return {"node": identity}
+
+    for node in connected.values():
+        encode(node)
+    bindings = [[tag, prop, id(node)] for node in connected.values() for tag, prop in node.attachments()]
+    return {"id": min(connected), "nodes": list(encoded.values()), "bindings": bindings}
+
+
+def install(node: Any, *, detached_tag: int | None = None) -> dict[str, Any] | None:
+    """Synchronize native graph ownership when a binding is attached or removed."""
+    from .animated import _backend
+
+    backend = _backend()
+    handler = getattr(backend, "install_animation_graph", None)
+    if handler is None:
+        return None
+    graph = serialize(node)
+    tag = graph["bindings"][0][0] if graph["bindings"] else detached_tag
+    if tag is not None:
+        handler(tag, graph)
+    return graph

pythonnative/appearance.py

@@ -0,0 +1,124 @@
+"""System color-scheme (light / dark mode) tracking.
+
+The platform screen host publishes the operating system's current
+appearance here (Android: ``Configuration.uiMode``; iOS:
+``UITraitCollection.userInterfaceStyle``), and components read it back
+through [`use_color_scheme`][pythonnative.use_color_scheme] or
+[`use_theme`][pythonnative.use_theme], both of which re-render when
+the scheme changes.
+
+Apps can also *override* the scheme (e.g. an in-app appearance
+setting) with [`set_color_scheme`][pythonnative.appearance.set_color_scheme];
+the override wins over the system value until cleared with ``None``.
+
+Example:
+    >>> from pythonnative import appearance
+    >>> appearance.get_color_scheme()
+    'light'
+    >>> appearance.set_color_scheme("dark")   # app-level override
+    >>> appearance.get_color_scheme()
+    'dark'
+    >>> appearance.set_color_scheme(None)     # follow the system again
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable, List, Literal, Optional
+
+ColorScheme = Literal["light", "dark"]
+"""The two supported appearance values."""
+
+_system_scheme: str = "light"
+_override_scheme: Optional[str] = None
+
+_subscribers: List[Callable[[], None]] = []
+_subscribers_lock = threading.Lock()
+
+
+def _notify_subscribers() -> None:
+    """Invoke every registered subscriber, swallowing exceptions."""
+    with _subscribers_lock:
+        callbacks = list(_subscribers)
+    for cb in callbacks:
+        try:
+            cb()
+        except Exception:
+            pass
+
+
+def subscribe(callback: Callable[[], None]) -> Callable[[], None]:
+    """Register ``callback`` to fire whenever the effective scheme changes.
+
+    Returns an unsubscribe function. Threadsafe.
+    """
+    with _subscribers_lock:
+        _subscribers.append(callback)
+
+    def _unsub() -> None:
+        with _subscribers_lock:
+            try:
+                _subscribers.remove(callback)
+            except ValueError:
+                pass
+
+    return _unsub
+
+
+def _coerce(scheme: object) -> Optional[str]:
+    if scheme in ("light", "dark"):
+        return str(scheme)
+    return None
+
+
+def set_system_color_scheme(scheme: str) -> None:
+    """Publish the operating system's current scheme.
+
+    Called by the platform screen host on create/resume and whenever
+    the system reports an appearance change. Invalid values are
+    ignored. Subscribers are only notified when the *effective* scheme
+    (after any app override) actually changes.
+    """
+    global _system_scheme
+    coerced = _coerce(scheme)
+    if coerced is None or coerced == _system_scheme:
+        return
+    effective_before = get_color_scheme()
+    _system_scheme = coerced
+    if get_color_scheme() != effective_before:
+        _notify_subscribers()
+
+
+def set_color_scheme(scheme: Optional[str]) -> None:
+    """Set (or clear) the app-level scheme override.
+
+    Args:
+        scheme: ``"light"`` or ``"dark"`` to force that appearance
+            regardless of the system setting, or ``None`` to follow
+            the system again.
+    """
+    global _override_scheme
+    coerced = _coerce(scheme) if scheme is not None else None
+    if scheme is not None and coerced is None:
+        return
+    effective_before = get_color_scheme()
+    _override_scheme = coerced
+    if get_color_scheme() != effective_before:
+        _notify_subscribers()
+
+
+def get_color_scheme() -> str:
+    """Return the effective scheme: the app override if set, else the system value."""
+    return _override_scheme if _override_scheme is not None else _system_scheme
+
+
+def get_system_color_scheme() -> str:
+    """Return the system-reported scheme, ignoring any app override."""
+    return _system_scheme
+
+
+def reset_color_scheme() -> None:
+    """Reset to system ``"light"`` with no override. Intended for tests."""
+    global _system_scheme, _override_scheme
+    _system_scheme = "light"
+    _override_scheme = None

pythonnative/bootstrap.py

@@ -0,0 +1,100 @@
+"""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, 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
+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, the dev
+            client). Debug templates pass ``True``.
+        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": 2, "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 .runtime import start as start_runtime
+
+        start_runtime()
+        from .sdk.schema import load_bundled_contracts
+
+        load_bundled_contracts()
+        from . import bridge
+
+        status_["protocol"] = bridge.handshake()
+        dev_mode = bool(dev or os.environ.get("PN_DEV") in ("1", "true"))
+        if dev_mode:
+            from . import diagnostics
+
+            diagnostics.set_dev_mode(True)
+        # 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()
+        if dev_mode:
+            # Debug builds are dev clients: connect to `pn start` when
+            # the build (or a remembered connection) names a server.
+            from . import devclient
+
+            client = devclient.start_if_configured()
+            status_["dev_server"] = client.url if client is not None else None
+    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,302 @@
+"""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``.
+
+Under ``pn preview`` the native side is a browser page, reached through
+[`WebTransport`][pythonnative.bridge.web.WebTransport]; the preview
+installs it with [`set_transport`][pythonnative.bridge.set_transport]
+before any screen mounts. In headless tests there is no transport at
+all: native modules fall back to their Python implementations, and
+tests that want to exercise the bridge itself install a
+[`FakeTransport`][pythonnative.bridge.fake.FakeTransport].
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable, Optional, Protocol, Tuple
+
+from . import codec
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "Transport",
+    "get_transport",
+    "has_transport",
+    "handshake",
+    "native_callback",
+    "set_transport",
+]
+
+from .commits import PROTOCOL_VERSION
+
+"""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) -> 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``."""
+
+    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, IS_WEB
+
+    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()
+    if IS_WEB:
+        raise RuntimeError(
+            "PN_PLATFORM=web is set but no browser preview transport is installed. "
+            "Start the app with `pn preview` (or `pn start`), which installs the WebTransport."
+        )
+    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 browser 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, IS_WEB
+
+    return bool(IS_IOS or IS_ANDROID or IS_WEB)
+
+
+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."
+        )
+    if getattr(get_transport(), "name", "") in {"ios", "android"}:
+        from ..sdk.schema import 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":
+            raise RuntimeError("Native component contracts changed. Rebuild the app with 'pn run'.")
+    return version
+
+
+# ======================================================================
+# native -> Python
+# ======================================================================
+
+
+# Callback threads coalesce continuous input before the application loop drains.
+_continuous: dict[tuple[int, str], list[str]] = {}
+
+
+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])
+
+
+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.
+    """
+    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_selection_change", "on_gesture_update"}:
+            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
+        else:
+            _continuous.clear()
+            loop.call_soon_threadsafe(native_callback, kind, tag, name, payload)
+        return None
+    try:
+        if kind == "layout":
+            from ..native_views import get_registry
+
+            backend = get_registry()
+            if backend.on_layout is not None:
+                backend.on_layout(codec.loads(payload))
+            return None
+        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
+        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)
+    from ..native_views import get_registry
+
+    backend = get_registry()
+    accept = getattr(backend, "accept_event", None)
+    if accept is not None:
+        if not accept(tag, name, args):
+            return None
+        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:
+        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 = get_event_registry().invoke(tag, name, *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
+    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:
+    """Drop the transport for test isolation."""
+    global _transport, _explicit
+    with _transport_lock:
+        _transport = None
+        _explicit = False

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) -> str:
+        """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))
+
+    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)