tempestroid 0.1.0__py3-none-any.whl

tempestroid/__init__.py

@@ -0,0 +1,198 @@
+"""tempestroid — build native Android apps in typed Python.
+
+Public surface: the typed style model, declarative widget primitives, typed
+events, the reconciler (IR + diff), the app/state loop, and introspection. The
+Qt simulator runner lives under ``tempestroid.renderers.qt`` (needs the ``qt``
+extra) and is imported on demand.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from tempestroid.bridge import (
+    Bridge,
+    DeviceApp,
+    EventMessage,
+    JniBridge,
+    LoopbackBridge,
+    MountMessage,
+    PatchMessage,
+    run_device,
+    serialize_node,
+    serialize_patch,
+)
+from tempestroid.core import (
+    App,
+    Insert,
+    Node,
+    Patch,
+    Path,
+    Remove,
+    Reorder,
+    Replace,
+    Update,
+    build,
+    diff,
+    event_catalog,
+    introspect,
+    widget_catalog,
+)
+from tempestroid.devserver import (
+    DevServer,
+    render_qr,
+    run_dev_client,
+    serve_device,
+)
+from tempestroid.native import notify
+from tempestroid.renderers.compose import to_compose
+from tempestroid.style import (
+    AlignItems,
+    Border,
+    Color,
+    Corners,
+    Curve,
+    Edge,
+    FlexDirection,
+    FontStyle,
+    FontWeight,
+    Gradient,
+    GradientDirection,
+    GradientStop,
+    JustifyContent,
+    Shadow,
+    SideBorder,
+    Style,
+    TextAlign,
+    TextDecoration,
+    TextOverflow,
+    Transition,
+)
+from tempestroid.widgets import (
+    Button,
+    Checkbox,
+    Column,
+    Container,
+    DateChangeEvent,
+    DatePicker,
+    Event,
+    EventHandler,
+    EventValidationError,
+    FilePicker,
+    FileSelectEvent,
+    Icon,
+    Image,
+    ImageFit,
+    Input,
+    KeyboardType,
+    ProgressBar,
+    Row,
+    ScrollView,
+    SlideEvent,
+    Slider,
+    Spinner,
+    Switch,
+    TapEvent,
+    Text,
+    TextArea,
+    TextChangeEvent,
+    ToggleEvent,
+    Widget,
+    parse_event,
+)
+
+try:
+    __version__ = version("tempestroid")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    # Style
+    "Style",
+    "Color",
+    "Edge",
+    "Border",
+    "SideBorder",
+    "Corners",
+    "Shadow",
+    "GradientStop",
+    "Gradient",
+    "Transition",
+    "FlexDirection",
+    "JustifyContent",
+    "AlignItems",
+    "TextAlign",
+    "FontWeight",
+    "FontStyle",
+    "TextDecoration",
+    "TextOverflow",
+    "GradientDirection",
+    "Curve",
+    # Widgets
+    "Widget",
+    "Text",
+    "Button",
+    "Column",
+    "Row",
+    "Container",
+    "ScrollView",
+    "Input",
+    "TextArea",
+    "Checkbox",
+    "Switch",
+    "Slider",
+    "KeyboardType",
+    "DatePicker",
+    "FilePicker",
+    "Image",
+    "ImageFit",
+    "Icon",
+    "ProgressBar",
+    "Spinner",
+    "EventHandler",
+    # Events (typed boundary contract)
+    "Event",
+    "TapEvent",
+    "TextChangeEvent",
+    "ToggleEvent",
+    "SlideEvent",
+    "DateChangeEvent",
+    "FileSelectEvent",
+    "EventValidationError",
+    "parse_event",
+    # Core (IR + reconciler)
+    "Path",
+    "Node",
+    "Replace",
+    "Update",
+    "Insert",
+    "Remove",
+    "Reorder",
+    "Patch",
+    "build",
+    "diff",
+    "App",
+    # Introspection
+    "introspect",
+    "widget_catalog",
+    "event_catalog",
+    # Compose renderer (Python side, phase B4)
+    "to_compose",
+    # Bridge (Python↔Kotlin boundary, phase B3)
+    "Bridge",
+    "LoopbackBridge",
+    "JniBridge",
+    "run_device",
+    "DeviceApp",
+    "MountMessage",
+    "PatchMessage",
+    "EventMessage",
+    "serialize_node",
+    "serialize_patch",
+    # Dev server (LAN code-push, phase B5)
+    "DevServer",
+    "run_dev_client",
+    "serve_device",
+    "render_qr",
+    # Native capabilities (phase B6)
+    "notify",
+]

tempestroid/bridge/__init__.py

@@ -0,0 +1,35 @@
+"""Python↔Kotlin boundary: serialization, handler dispatch, and transport.
+
+Carries the reconciler's IR/patches to the device renderer and validated events
+back. The real device transport is a hand-rolled JNI shim (phase B3, Kotlin
+side); this package is the transport-agnostic Python half, fully testable without
+a device via :class:`LoopbackBridge`.
+"""
+
+from tempestroid.bridge.device import Bridge, DeviceApp, LoopbackBridge
+from tempestroid.bridge.handlers import HandlerRegistry
+from tempestroid.bridge.jni import JniBridge, run_device
+from tempestroid.bridge.protocol import (
+    EventMessage,
+    MountMessage,
+    PatchMessage,
+    event_type_for,
+    handler_token,
+)
+from tempestroid.bridge.serializer import serialize_node, serialize_patch
+
+__all__ = [
+    "Bridge",
+    "LoopbackBridge",
+    "JniBridge",
+    "run_device",
+    "DeviceApp",
+    "HandlerRegistry",
+    "MountMessage",
+    "PatchMessage",
+    "EventMessage",
+    "handler_token",
+    "event_type_for",
+    "serialize_node",
+    "serialize_patch",
+]

tempestroid/bridge/device.py

@@ -0,0 +1,148 @@
+"""Wire an ``App`` to a device over an abstract transport.
+
+``DeviceApp`` is the device-side analogue of ``run_qt``: it owns an ``App`` plus a
+:class:`HandlerRegistry`, serializes the initial tree and every patch batch onto
+a :class:`Bridge`, and feeds incoming events back through the registry (which may
+call ``app.set_state`` and trigger another patch batch).
+
+The :class:`Bridge` is transport-agnostic. The real device transport is the JNI
+shim (phase B3, Kotlin side); :class:`LoopbackBridge` is an in-memory transport
+for tests and local wiring.
+"""
+
+from __future__ import annotations
+
+import abc
+import asyncio
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar
+
+from tempestroid.bridge.handlers import HandlerRegistry
+from tempestroid.bridge.protocol import EventMessage, MountMessage, PatchMessage
+from tempestroid.bridge.serializer import serialize_node, serialize_patch
+from tempestroid.core.ir import Patch
+from tempestroid.core.state import App
+from tempestroid.widgets import Widget
+
+__all__ = ["Bridge", "LoopbackBridge", "DeviceApp"]
+
+S = TypeVar("S")
+
+
+class Bridge(abc.ABC):
+    """A transport that carries serialized messages to the device."""
+
+    @abc.abstractmethod
+    async def send(self, message: dict[str, Any]) -> None:
+        """Send one serialized message to the device.
+
+        Args:
+            message: A JSON-able message dict (``mount`` / ``patch``).
+        """
+        raise NotImplementedError
+
+
+class LoopbackBridge(Bridge):
+    """In-memory bridge that records sent messages (for tests/local wiring)."""
+
+    def __init__(self) -> None:
+        """Create a loopback bridge with an empty outbox."""
+        self.sent: list[dict[str, Any]] = []
+
+    async def send(self, message: dict[str, Any]) -> None:
+        """Record a sent message.
+
+        Args:
+            message: The message dict.
+        """
+        self.sent.append(message)
+
+
+class DeviceApp(Generic[S]):
+    """Runs an ``App`` against a device :class:`Bridge`.
+
+    Type Args:
+        S: The application state type.
+    """
+
+    def __init__(
+        self,
+        state: S,
+        view: Callable[[App[S]], Widget],
+        bridge: Bridge,
+    ) -> None:
+        """Initialize the device app.
+
+        Args:
+            state: The initial application state.
+            view: Builds the widget tree from the app.
+            bridge: The transport to the device.
+        """
+        self._bridge: Bridge = bridge
+        self._registry: HandlerRegistry = HandlerRegistry()
+        self._app: App[S] = App(state, view, apply_patches=self._on_patches)
+        # Strong refs to in-flight send tasks so the loop does not GC them.
+        self._pending: set[asyncio.Task[None]] = set()
+
+    @property
+    def app(self) -> App[S]:
+        """The wrapped app.
+
+        Returns:
+            The app.
+        """
+        return self._app
+
+    async def start(self) -> None:
+        """Build the initial tree, register handlers, and send the mount message."""
+        root = self._app.start()
+        self._registry.refresh(root)
+        await self._bridge.send(MountMessage(root=serialize_node(root)).model_dump())
+
+    def reload(self, view: Callable[[App[S]], Widget]) -> None:
+        """Hot-reload the view, preserving state and patching the device.
+
+        Swaps the running app's view via :meth:`App.swap_view` (which diffs the
+        new tree against the live one and pushes the resulting patch batch over
+        the bridge through :meth:`_on_patches`), then refreshes the handler
+        registry so taps resolve against the reloaded closures even when the tree
+        was structurally unchanged.
+
+        Args:
+            view: The reloaded view function.
+
+        Raises:
+            Exception: Whatever the new view/build raises — the swap is rolled
+                back. The caller (code-push client) falls back to a clean restart.
+        """
+        self._app.swap_view(view)
+        self._registry.refresh(self._app.current_tree)
+
+    async def handle_event(self, message: dict[str, Any]) -> None:
+        """Process an event coming back from the device.
+
+        Validates and dispatches via the registry; any resulting ``set_state``
+        schedules a coalesced rebuild whose patches are sent on the next tick.
+
+        Args:
+            message: A serialized :class:`EventMessage` dict.
+        """
+        event = EventMessage.model_validate(message)
+        await self._registry.dispatch(event.token, event.payload)
+
+    def _on_patches(self, patches: list[Patch]) -> None:
+        """Refresh handlers from the new tree and send the patch batch.
+
+        Called by ``App`` after a rebuild (sync, on the loop). The send is
+        scheduled as a task since the bridge is async.
+
+        Args:
+            patches: The patches produced by the reconciler.
+        """
+        self._registry.refresh(self._app.current_tree)
+        message = PatchMessage(
+            patches=[serialize_patch(p) for p in patches]
+        ).model_dump()
+        task = asyncio.get_running_loop().create_task(self._bridge.send(message))
+        self._pending.add(task)
+        task.add_done_callback(self._pending.discard)

tempestroid/bridge/handlers.py

@@ -0,0 +1,103 @@
+"""Handler registry: map tokens to live callables and dispatch typed events.
+
+The serializer sends handler **tokens** to the device. When the device sends an
+event back, this registry resolves the token to the current Python callable,
+**validates the payload** against the widget's declared event type (the A6
+boundary contract), then invokes the handler. It is refreshed from the current
+tree on every rebuild, so tokens always resolve to the latest callables.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from tempestroid.bridge.protocol import event_type_for, handler_token
+from tempestroid.core.ir import Node
+from tempestroid.widgets import Event, handler_accepts_event, parse_event
+
+__all__ = ["HandlerRegistry"]
+
+
+def _invoke(handler: Callable[..., Any], event: Event | None) -> Any:  # noqa: ANN401 — handler return is arbitrary (a value or a coroutine to await)
+    """Call a handler, passing the typed event only if it accepts one.
+
+    Args:
+        handler: The resolved handler callable.
+        event: The validated event, or ``None`` when the widget emits no typed
+            event.
+
+    Returns:
+        The handler's return value (possibly a coroutine to await).
+    """
+    if event is not None and handler_accepts_event(handler):
+        return handler(event)
+    return handler()
+
+
+class HandlerRegistry:
+    """Resolves handler tokens to callables and dispatches validated events."""
+
+    def __init__(self) -> None:
+        """Create an empty registry."""
+        self._handlers: dict[str, tuple[Callable[[], Any], type[Event] | None]] = {}
+
+    def refresh(self, root: Node | None) -> None:
+        """Rebuild the token→handler map by walking the current tree.
+
+        Args:
+            root: The current root node, or ``None`` to clear.
+        """
+        self._handlers.clear()
+        if root is not None:
+            self._walk(root, ())
+
+    def _walk(self, node: Node, path: tuple[int, ...]) -> None:
+        """Register every handler prop on ``node`` and recurse.
+
+        Args:
+            node: The node to inspect.
+            path: The node's path from the root.
+        """
+        for name, value in node.props.items():
+            if callable(value):
+                token = handler_token(path, name)
+                self._handlers[token] = (value, event_type_for(node.type, name))
+        for index, child in enumerate(node.children):
+            self._walk(child, path + (index,))
+
+    async def dispatch(self, token: str, payload: dict[str, Any]) -> bool:
+        """Validate a payload and invoke the handler for ``token``.
+
+        Args:
+            token: The handler token from an :class:`EventMessage`.
+            payload: The raw event payload.
+
+        Returns:
+            ``True`` if a handler was found and invoked, ``False`` otherwise.
+
+        Raises:
+            EventValidationError: If the payload fails validation for the
+                handler's declared event type.
+        """
+        entry = self._handlers.get(token)
+        if entry is None:
+            return False
+        handler, event_type = entry
+        event: Event | None = None
+        if event_type is not None:
+            # Validate at the boundary before entering the handler (A6 contract).
+            event = parse_event(event_type, payload)
+        result = _invoke(handler, event)
+        if inspect.iscoroutine(result):
+            await result
+        return True
+
+    def tokens(self) -> list[str]:
+        """Return the currently registered tokens (for inspection/tests).
+
+        Returns:
+            The registered handler tokens.
+        """
+        return list(self._handlers)

tempestroid/bridge/jni.py

@@ -0,0 +1,143 @@
+"""Device transport over the hand-rolled JNI bridge (phase B3).
+
+This is the Python half of the on-device bridge. It plugs a :class:`JniBridge`
+(which ships serialized ``mount``/``patch`` messages to Kotlin) and an incoming
+event sink (which feeds device taps/text back into the :class:`DeviceApp`) into
+one asyncio loop.
+
+The native module ``_tempest_host`` is provided by ``libtempest_host.so`` only
+inside the Android app (it registers itself via ``PyImport_AppendInittab`` before
+the interpreter boots). It is therefore imported **lazily**, so this module
+imports cleanly on the desktop (where the framework is developed and tested) and
+only requires the native side when :func:`run_device` actually runs.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any, Protocol, TypeVar, cast
+
+from tempestroid.bridge.device import Bridge, DeviceApp
+from tempestroid.core.state import App
+from tempestroid.widgets import Widget
+
+__all__ = ["JniBridge", "run_device", "run_device_file"]
+
+S = TypeVar("S")
+
+
+class _NativeHost(Protocol):
+    """The surface ``_tempest_host`` exposes to Python (see ``tempest_host.c``)."""
+
+    def send_to_host(self, message_json: str) -> None:
+        """Hand a serialized message to Kotlin (Python → host)."""
+        ...
+
+    def set_event_sink(self, sink: Callable[[str, str], None]) -> None:
+        """Register the callable the host invokes on a device event (host → Python)."""
+        ...
+
+
+def native_host() -> _NativeHost:
+    """Import and return the native ``_tempest_host`` module.
+
+    Returns:
+        The native host module.
+
+    Raises:
+        RuntimeError: If imported off-device, where the module is absent.
+    """
+    try:
+        import _tempest_host  # type: ignore[import-not-found]
+    except ImportError as exc:  # pragma: no cover - desktop path
+        raise RuntimeError(
+            "_tempest_host is unavailable; run_device only works inside the "
+            "Android host (libtempest_host.so registers the module)."
+        ) from exc
+    # The native module has no type stub; trust it implements the Protocol.
+    return cast(_NativeHost, _tempest_host)
+
+
+class JniBridge(Bridge):
+    """A :class:`Bridge` that ships messages to Kotlin via the native host.
+
+    Each message is JSON-encoded and handed to ``_tempest_host.send_to_host``,
+    which marshals it across JNI to ``PythonRuntime.onMessageFromPython`` on the
+    Kotlin side (the Compose renderer consumes it in phase B4).
+    """
+
+    def __init__(self) -> None:
+        """Bind the bridge to the native host module."""
+        self._host: _NativeHost = native_host()
+
+    async def send(self, message: dict[str, Any]) -> None:
+        """Serialize and ship one message to the host.
+
+        Args:
+            message: A JSON-able message dict (``mount`` / ``patch``).
+        """
+        self._host.send_to_host(json.dumps(message))
+
+
+def run_device(state: S, view: Callable[[App[S]], Widget]) -> None:
+    """Boot a :class:`DeviceApp` on a fresh asyncio loop and run it forever.
+
+    This is the device-side analogue of ``run_qt``: it owns the loop, sends the
+    initial ``mount`` over a :class:`JniBridge`, registers the native event sink
+    (which marshals incoming device events back onto the loop), and blocks in
+    ``run_forever``. Call it from the interpreter's main thread inside the host —
+    the Kotlin side already runs the interpreter off the UI thread.
+
+    Args:
+        state: The initial application state.
+        view: Builds the widget tree from the app.
+    """
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    device: DeviceApp[S] = DeviceApp(state, view, JniBridge())
+
+    def _on_event(token: str, payload_json: str) -> None:
+        """Native callback: schedule an incoming event onto the loop.
+
+        Invoked by the host from the UI thread (with the GIL held), so it only
+        hands work to the loop via ``call_soon_threadsafe`` and returns fast.
+
+        Args:
+            token: The handler token addressed by the event.
+            payload_json: The raw JSON payload (``""`` for none).
+        """
+        payload: dict[str, Any] = json.loads(payload_json) if payload_json else {}
+        message: dict[str, Any] = {
+            "kind": "event",
+            "token": token,
+            "payload": payload,
+        }
+        loop.call_soon_threadsafe(
+            lambda: loop.create_task(device.handle_event(message))
+        )
+
+    native_host().set_event_sink(_on_event)
+    loop.create_task(device.start())
+    loop.run_forever()
+
+
+def run_device_file(path: str) -> None:
+    """Load an app file (``make_state`` + ``view``) and run it on the device.
+
+    The device entry point for an APK bundled by ``tempest build``: the user's
+    app source is packaged as an asset, extracted to ``path`` on first launch,
+    and run here. Mirrors :func:`run_device` but sources the state/view from a
+    file via the same loader the dev cockpit and code-push client use.
+
+    Args:
+        path: Absolute path to the extracted app file on the device.
+    """
+    from pathlib import Path
+
+    from tempestroid.cli.app_loader import spec_from_source
+
+    source = Path(path).read_text(encoding="utf-8")
+    spec = spec_from_source(source, filename=path)
+    run_device(spec.make_state(), spec.view)