pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/refresh.py

@@ -0,0 +1,55 @@
+"""Conservative component compatibility for Fast Refresh."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+from typing import Any, Callable
+
+
+def hook_signature(function: Callable[..., Any], _seen: frozenset[int] = frozenset()) -> tuple[str, ...] | None:
+    """Record hook order and binding names before the source file changes.
+
+    Binding names distinguish inserting or moving hooks of the same kind.
+    Uninspectable functions remount instead of risking slot corruption.
+    """
+    if id(function) in _seen:
+        return None
+    _seen = _seen | {id(function)}
+    try:
+        tree = ast.parse(textwrap.dedent(inspect.getsource(function)))
+    except (OSError, TypeError, SyntaxError):
+        return None
+    result = []
+    parents = {id(child): node for node in ast.walk(tree) for child in ast.iter_child_nodes(node)}
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        name = (
+            node.func.id
+            if isinstance(node.func, ast.Name)
+            else node.func.attr if isinstance(node.func, ast.Attribute) else ""
+        )
+        if not name.startswith("use_"):
+            continue
+        owner = parents.get(id(node))
+        binding = (
+            ast.dump(owner.targets[0])
+            if isinstance(owner, ast.Assign)
+            else ast.dump(owner.target) if isinstance(owner, ast.AnnAssign) else ""
+        )
+        signature = name + ":" + binding
+        target = None
+        if isinstance(node.func, ast.Name):
+            target = function.__globals__.get(node.func.id)
+        elif isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            owner = function.__globals__.get(node.func.value.id)
+            target = getattr(owner, node.func.attr, None)
+        if inspect.isfunction(target) and not target.__module__.startswith("pythonnative."):
+            nested = hook_signature(target, _seen)
+            if nested is None:
+                return None
+            signature += repr(nested)
+        result.append((node.lineno, node.col_offset, signature))
+    return tuple(value for _, _, value in sorted(result))

pythonnative/runtime.py

@@ -0,0 +1,306 @@
+"""Application execution on a standard asyncio event loop.
+
+Mobile hosts start one application thread with :func:`start`. All Python
+rendering, callbacks, and tasks run there. Native hosts own their UI threads
+and marshal view operations themselves. Headless programs can instead drive
+an ordinary local loop with :func:`run_blocking` and :func:`drain`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import inspect
+import threading
+from typing import Any, Awaitable, Callable, Coroutine, TypeVar
+
+T = TypeVar("T")
+Awaitlike = Coroutine[Any, Any, T] | Awaitable[T]
+_loop: asyncio.AbstractEventLoop | None = None
+_thread: threading.Thread | None = None
+_owner: threading.Thread | None = None
+_lock = threading.RLock()
+_scope: contextvars.ContextVar[TaskScope | None] = contextvars.ContextVar("pn_task_scope", default=None)
+
+
+class TaskScope:
+    """Own tasks until an application or component is disposed.
+
+    Closing a scope cancels its tasks and rejects new work. A task removes
+    itself when it finishes, including when it fails or is cancelled.
+    """
+
+    def __init__(self, name: str = "application") -> None:
+        self.name = name
+        self.closed = False
+        self._tasks: set[Any] = set()
+
+    @property
+    def pending(self) -> int:
+        """Number of unfinished tasks owned by this scope."""
+        return sum(not task.done() for task in self._tasks)
+
+    def create_task(self, awaitable: Awaitlike[T], *, report_errors: bool = False) -> Any:
+        """Schedule work with this scope's lifetime and context."""
+        if self.closed:
+            if inspect.iscoroutine(awaitable):
+                awaitable.close()
+            raise RuntimeError(f"Task scope {self.name!r} is closed")
+        token = _scope.set(self)
+        try:
+            task = _schedule(awaitable)
+        finally:
+            _scope.reset(token)
+        self._tasks.add(task)
+
+        def finished(done: Any) -> None:
+            self._tasks.discard(done)
+            if report_errors and not done.cancelled():
+                error = done.exception()
+                if error is not None:
+                    from .diagnostics import report_error
+
+                    if not report_error(error, phase=f"task in {self.name}"):
+                        get_loop().call_exception_handler(
+                            {"message": f"Task in {self.name} failed", "exception": error}
+                        )
+
+        task.add_done_callback(finished)
+        return task
+
+    def close(self) -> None:
+        """Cancel owned work; calling this more than once is harmless."""
+        self.closed = True
+        for task in tuple(self._tasks):
+            if (
+                isinstance(task, asyncio.Future)
+                and task.get_loop().is_running()
+                and not _on_loop_thread(task.get_loop())
+            ):
+                task.get_loop().call_soon_threadsafe(task.cancel)
+            else:
+                task.cancel()
+        self._tasks.clear()
+
+
+_application_scope = TaskScope()
+
+
+def start() -> asyncio.AbstractEventLoop:
+    """Start the application thread once and return its event loop."""
+    global _loop, _thread, _owner
+    with _lock:
+        if _thread is not None and _thread.is_alive():
+            assert _loop is not None
+            return _loop
+        if _loop is not None and not _loop.is_closed():
+            raise RuntimeError("Start the application runtime before creating headless tasks")
+        ready = threading.Event()
+        loop = asyncio.new_event_loop()
+        _loop = loop
+
+        def serve() -> None:
+            asyncio.set_event_loop(loop)
+            ready.set()
+            try:
+                loop.run_forever()
+            finally:
+                loop.run_until_complete(_cancel_tasks(loop))
+                loop.run_until_complete(loop.shutdown_asyncgens())
+                loop.run_until_complete(loop.shutdown_default_executor())
+                loop.close()
+
+        _thread = threading.Thread(target=serve, name="PythonNative", daemon=True)
+        _owner = _thread
+        _thread.start()
+        ready.wait()
+        return loop
+
+
+def get_loop() -> asyncio.AbstractEventLoop:
+    """Return the application loop, or the caller's loop in headless mode."""
+    global _loop, _owner
+    if _thread is not None and _thread.is_alive():
+        assert _loop is not None
+        return _loop
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        with _lock:
+            if _loop is None or _loop.is_closed():
+                _loop = asyncio.new_event_loop()
+                _owner = threading.current_thread()
+            return _loop
+
+
+def _on_loop_thread(loop: asyncio.AbstractEventLoop) -> bool:
+    try:
+        return asyncio.get_running_loop() is loop
+    except RuntimeError:
+        return loop is _loop and threading.current_thread() is _owner
+
+
+async def _ensure_coro(awaitable: Awaitlike[T]) -> T:
+    return await awaitable
+
+
+def _schedule(awaitable: Awaitlike[T]) -> Any:
+    loop = get_loop()
+    if _on_loop_thread(loop):
+        return asyncio.ensure_future(awaitable, loop=loop)
+    return asyncio.run_coroutine_threadsafe(_ensure_coro(awaitable), loop)
+
+
+def run_async(awaitable: Awaitlike[T]) -> Any:
+    """Schedule work in the current component scope or the application scope.
+
+    Returns an asyncio task on the application thread and a concurrent
+    future on other threads. Both handles support cancellation.
+    """
+    return (_scope.get() or _application_scope).create_task(awaitable)
+
+
+def run_application_task(awaitable: Awaitlike[T]) -> Any:
+    """Start work that should survive the component that requested it."""
+    return _application_scope.create_task(awaitable)
+
+
+def invoke(callback: Callable[..., Any], *args: Any, scope: TaskScope | None = None) -> Any:
+    """Invoke a callback and schedule an awaitable result in its owner's scope."""
+    owner = scope or _scope.get() or _application_scope
+    if owner.closed:
+        return None
+    token = _scope.set(owner)
+    try:
+        result = callback(*args)
+        if inspect.isawaitable(result):
+            return owner.create_task(result, report_errors=True)
+        return result
+    finally:
+        _scope.reset(token)
+
+
+def run_blocking(awaitable: Awaitlike[T], timeout: float | None = None) -> T:
+    """Wait for work from synchronous code; never block the application loop."""
+    loop = get_loop()
+    if loop.is_running() and _on_loop_thread(loop):
+        if inspect.iscoroutine(awaitable):
+            awaitable.close()
+        raise RuntimeError("run_blocking() cannot run inside the event loop; await the result")
+
+    async def bounded() -> T:
+        async with asyncio.timeout(timeout):
+            return await awaitable
+
+    if loop.is_running():
+        return asyncio.run_coroutine_threadsafe(bounded(), loop).result()
+    return loop.run_until_complete(bounded())
+
+
+def drain(timeout: float = 1.0, *, until: Callable[[], bool] | None = None) -> bool:
+    """Settle headless work or wait for application tasks from a test thread.
+
+    Long-lived application tasks require an explicit ``until`` predicate.
+    This uses public asyncio APIs and never inspects selector internals.
+    """
+
+    async def settle() -> bool:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        idle_turns = 0
+        while loop.time() < deadline:
+            await asyncio.sleep(0)
+            if until is not None and until():
+                return True
+            pending = [task for task in asyncio.all_tasks() if task is not asyncio.current_task() and not task.done()]
+            if until is None and not pending:
+                idle_turns += 1
+                if idle_turns >= 3:
+                    return True
+            else:
+                idle_turns = 0
+            await asyncio.sleep(0.001)
+        return False
+
+    return run_blocking(settle())
+
+
+def call_threadsafe(callback: Callable[..., Any], *args: Any) -> None:
+    """Enqueue a callback on the application event loop from any thread."""
+    get_loop().call_soon_threadsafe(callback, *args)
+
+
+def call_on_application_thread(fn: Callable[[], None]) -> None:
+    """Execute Python work on its owner thread, inline when already there."""
+    loop = get_loop()
+    if _on_loop_thread(loop):
+        fn()
+    else:
+        loop.call_soon_threadsafe(fn)
+
+
+def resolve_future(future: asyncio.Future[T], value: T) -> None:
+    """Complete a future from any thread unless it was cancelled."""
+
+    def complete() -> None:
+        if not future.done():
+            future.set_result(value)
+
+    future.get_loop().call_soon_threadsafe(complete)
+
+
+def reject_future(future: asyncio.Future[Any], error: BaseException) -> None:
+    """Fail a future from any thread unless it was cancelled."""
+
+    def complete() -> None:
+        if not future.done():
+            future.set_exception(error)
+
+    future.get_loop().call_soon_threadsafe(complete)
+
+
+def create_future() -> asyncio.Future[Any]:
+    """Create a future for completion by a native request."""
+    return get_loop().create_future()
+
+
+async def _cancel_tasks(loop: asyncio.AbstractEventLoop) -> None:
+    tasks = [task for task in asyncio.all_tasks(loop) if task is not asyncio.current_task()]
+    for task in tasks:
+        task.cancel()
+    await asyncio.gather(*tasks, return_exceptions=True)
+
+
+def _shutdown_for_tests() -> None:
+    global _loop, _thread, _owner, _application_scope
+    with _lock:
+        loop, thread = _loop, _thread
+        _application_scope.close()
+        if loop is not None and not loop.is_closed():
+            if thread is not None:
+                loop.call_soon_threadsafe(loop.stop)
+                thread.join(timeout=5)
+                if thread.is_alive():
+                    raise RuntimeError("Application thread did not stop")
+            elif not loop.is_running():
+                loop.run_until_complete(_cancel_tasks(loop))
+                loop.run_until_complete(loop.shutdown_asyncgens())
+                loop.close()
+        _loop = _thread = _owner = None
+        _application_scope = TaskScope()
+
+
+__all__ = [
+    "TaskScope",
+    "call_on_application_thread",
+    "call_threadsafe",
+    "create_future",
+    "drain",
+    "get_loop",
+    "reject_future",
+    "resolve_future",
+    "run_application_task",
+    "run_async",
+    "run_blocking",
+    "start",
+]

pythonnative/scheduler.py

@@ -0,0 +1,159 @@
+"""Update scheduling primitives shared by hooks and the reconciler.
+
+Two pieces live here:
+
+- [`batch_updates`][pythonnative.scheduler.batch_updates], a context manager that
+  coalesces the render triggers fired by several state setters into
+  one, tracked per execution context (so it composes with ``async``
+  code).
+- [`TransitionQueue`][pythonnative.scheduler.TransitionQueue], the
+  per-reconciler queue behind
+  [`use_transition`][pythonnative.use_transition]: renders marked as
+  transitions are deferred to a later turn of the framework loop so
+  urgent updates (typing, presses) stay responsive.
+
+Nothing here is global mutable state beyond context variables, so
+several reconcilers (screens, list rows, tests) never interfere.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Callable, Generator, List, Optional
+
+from . import diagnostics
+
+__all__ = ["TransitionQueue", "batch_updates", "in_transition", "run_in_transition", "schedule_trigger"]
+
+# Depth of nested ``batch_updates`` blocks plus the triggers deferred by
+# the outermost block, per execution context.
+_batch_depth: ContextVar[int] = ContextVar("pn_batch_depth", default=0)
+_batch_pending: ContextVar[Optional[List[Callable[[], None]]]] = ContextVar("pn_batch_pending", default=None)
+
+# Whether state updates in the current execution context are marked as
+# transitions (see ``use_transition``).
+_transition_var: ContextVar[bool] = ContextVar("pn_transition", default=False)
+
+
+def schedule_trigger(trigger: Callable[[], None]) -> None:
+    """Run ``trigger`` now, or defer it to the end of the enclosing ``batch_updates`` block."""
+    pending = _batch_pending.get()
+    if _batch_depth.get() > 0 and pending is not None:
+        if trigger not in pending:
+            pending.append(trigger)
+    else:
+        trigger()
+
+
+@contextmanager
+def batch_updates() -> Generator[None, None, None]:
+    """Coalesce multiple state updates into a single re-render.
+
+    State setters called inside the ``with`` block defer their
+    re-render trigger until the block exits, so any number of
+    ``set_*`` calls produce at most one render pass.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        with pn.batch_updates():
+            set_count(1)
+            set_name("hello")
+        ```
+    """
+    depth = _batch_depth.get()
+    depth_token = _batch_depth.set(depth + 1)
+    pending_token = None
+    if depth == 0:
+        pending_token = _batch_pending.set([])
+    try:
+        yield
+    finally:
+        _batch_depth.reset(depth_token)
+        if pending_token is not None:
+            triggers = _batch_pending.get() or []
+            _batch_pending.reset(pending_token)
+            for trigger in triggers:
+                trigger()
+
+
+def in_transition() -> bool:
+    """Whether state updates in the current context are transitions."""
+    return _transition_var.get()
+
+
+def run_in_transition(fn: Callable[[], None]) -> None:
+    """Run ``fn`` with its state updates marked as transitions."""
+    token = _transition_var.set(True)
+    try:
+        fn()
+    finally:
+        _transition_var.reset(token)
+
+
+class TransitionQueue:
+    """Deferred render triggers and completion callbacks for one reconciler.
+
+    Triggers added via [`defer`][pythonnative.scheduler.TransitionQueue.defer]
+    run together on a later loop turn; callbacks added via
+    [`on_complete`][pythonnative.scheduler.TransitionQueue.on_complete]
+    run right after them (this is how ``use_transition`` flips its
+    ``is_pending`` flag back off once the deferred render committed).
+    """
+
+    __slots__ = ("_triggers", "_callbacks", "_scheduled")
+
+    def __init__(self) -> None:
+        self._triggers: List[Callable[[], None]] = []
+        self._callbacks: List[Callable[[], None]] = []
+        self._scheduled = False
+
+    def defer(self, trigger: Callable[[], None]) -> None:
+        """Queue ``trigger`` for the next flush."""
+        if trigger not in self._triggers:
+            self._triggers.append(trigger)
+        self._ensure_scheduled()
+
+    def on_complete(self, callback: Callable[[], None]) -> None:
+        """Queue ``callback`` to run after the next flush's triggers."""
+        self._callbacks.append(callback)
+        self._ensure_scheduled()
+
+    @property
+    def pending(self) -> bool:
+        """Whether a flush is scheduled or work is queued."""
+        return self._scheduled or bool(self._triggers) or bool(self._callbacks)
+
+    def flush(self) -> None:
+        """Run every deferred trigger, then the completion callbacks."""
+        self._scheduled = False
+        triggers = self._triggers
+        callbacks = self._callbacks
+        self._triggers = []
+        self._callbacks = []
+        for fn in triggers + callbacks:
+            try:
+                fn()
+            except Exception as exc:
+                if not diagnostics.report_error(exc, phase="transition"):
+                    raise
+
+    def clear(self) -> None:
+        """Drop queued work (used on unmount)."""
+        self._triggers = []
+        self._callbacks = []
+        self._scheduled = False
+
+    def _ensure_scheduled(self) -> None:
+        if self._scheduled:
+            return
+        self._scheduled = True
+        from .runtime import get_loop
+
+        get_loop().call_soon(self._flush_if_scheduled)
+
+    def _flush_if_scheduled(self) -> None:
+        if self._scheduled:
+            self.flush()

pythonnative/sdk/__init__.py

@@ -0,0 +1,153 @@
+"""Public extension surface for PythonNative.
+
+The ``pythonnative.sdk`` package collects the *stable* extension
+contract that third-party packages rely on: the
+[`Style`][pythonnative.sdk.Style] type, the
+[`@native_component`][pythonnative.sdk.native_component] /
+[`register_component`][pythonnative.sdk.register_component]
+registration helpers, the
+[`element_factory`][pythonnative.sdk.element_factory] helper for
+producing strongly-typed element constructors, the
+[`ViewHandler`][pythonnative.sdk.ViewHandler] protocol for off-device
+stand-ins, and the native module registry
+([`native_module`][pythonnative.sdk.native_module],
+[`register_python_module`][pythonnative.sdk.register_python_module]).
+
+A custom native component is three things:
+
+1. A typed, frozen [`Props`][pythonnative.sdk.Props] dataclass listing
+   the public properties the component accepts.
+2. A Swift ``PNComponentManager`` and a Kotlin ``ComponentManager``
+   registered under the component's name by the package's native
+   plugin (``pn_plugin.json`` next to ``ios/`` and ``android/`` source
+   folders; see ``docs/guides/custom-components.md``).
+3. A registration call in Python
+   ([`register_component`][pythonnative.sdk.register_component], or the
+   [`@native_component`][pythonnative.sdk.native_component] decorator
+   when you also supply a test
+   [`ViewHandler`][pythonnative.sdk.ViewHandler] for the Python backend)
+   that declares the element name and binds its props type.
+
+Once registered, the component appears alongside the built-ins: the
+reconciler, layout engine, and Fast Refresh treat it identically.
+
+A native module (device API without a view) follows the same split: a
+Swift / Kotlin class registered by name in the plugin, a Python facade
+that calls ``native_module(name).call(...)``, and optionally a Python
+implementation registered with ``register_python_module`` for the
+browser preview and tests.
+
+PyPI packages can ship both without users importing them explicitly
+by declaring entry points in the ``pythonnative.handlers`` (Python
+side) and ``pythonnative.plugins`` (native source) groups; ``pn build``
+compiles the native sources into the app.
+
+Example:
+    ```python
+    from dataclasses import dataclass
+    import pythonnative as pn
+    from pythonnative.sdk import Props, element_factory, register_component
+
+
+    @dataclass(frozen=True)
+    class BadgeProps(Props):
+        text: str = ""
+        color: str = "#FF3B30"
+        style: pn.StyleProp = None
+
+
+    register_component(name="Badge", props=BadgeProps)
+    Badge = element_factory("Badge")
+
+
+    @pn.component
+    def App():
+        return pn.Column(
+            Badge(text="3", color="#0A84FF"),
+            pn.Text("Inbox"),
+        )
+    ```
+"""
+
+from ..element import Element
+from ..native_modules.registry import (
+    NativeModule,
+    NativeModuleError,
+    PythonModule,
+    emit,
+    native_module,
+    register_python_module,
+)
+from ..native_views.base import ViewHandler, parse_color_int
+from ..style import (
+    Color,
+    Dimension,
+    EdgeInsets,
+    EdgeValue,
+    FlexDirection,
+    JustifyContent,
+    Overflow,
+    Position,
+    Style,
+    StyleProp,
+    TransformSpec,
+    style,
+)
+from ._components import (
+    ENTRY_POINT_GROUP,
+    Props,
+    element_factory,
+    get_props_type,
+    get_test_handler,
+    install_into_registry,
+    list_components,
+    native_component,
+    register_component,
+    unregister_component,
+)
+from .codegen import generate
+from .schema import ComponentSchema, ModuleSchema, NativeField, register_schema
+
+__all__ = [
+    "ComponentSchema",
+    "ModuleSchema",
+    "NativeField",
+    "register_schema",
+    "generate",
+    # Core types
+    "Element",
+    "ViewHandler",
+    # Style types
+    "Color",
+    "Dimension",
+    "EdgeInsets",
+    "EdgeValue",
+    "FlexDirection",
+    "JustifyContent",
+    "Overflow",
+    "Position",
+    "Style",
+    "StyleProp",
+    "TransformSpec",
+    "style",
+    # SDK helpers (re-exported so users only import from one place)
+    "parse_color_int",
+    # Native-component SDK
+    "ENTRY_POINT_GROUP",
+    "Props",
+    "element_factory",
+    "get_test_handler",
+    "get_props_type",
+    "install_into_registry",
+    "list_components",
+    "native_component",
+    "register_component",
+    "unregister_component",
+    # Native-module SDK
+    "NativeModule",
+    "NativeModuleError",
+    "PythonModule",
+    "emit",
+    "native_module",
+    "register_python_module",
+]