pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/diagnostics.py

@@ -0,0 +1,241 @@
+"""Developer diagnostics: dev mode, warnings, and error reporting.
+
+PythonNative distinguishes **dev mode** (the `pn preview` window, `pn
+run` with hot reload, or any process with ``PN_DEV=1``) from production.
+Dev mode turns on:
+
+- **Validation warnings** ([`warn`][pythonnative.diagnostics.warn] /
+  [`warn_once`][pythonnative.diagnostics.warn_once]): unknown style
+  keys, duplicate list keys, and similar mistakes are printed once with
+  a suggestion instead of failing silently.
+- **Hook-order checking**: calling hooks conditionally corrupts slot
+  state; in dev mode the mismatch raises a
+  [`HookOrderError`][pythonnative.diagnostics.HookOrderError]
+  immediately instead of cross-wiring state.
+- **The RedBox**: uncaught errors from render, effects, and event
+  handlers are routed to the screen host, which presents a full-screen
+  error overlay (see `pythonnative.hosts`) instead of crashing or
+  swallowing the traceback.
+
+In production none of this runs: validation is skipped, hook-order
+checks are skipped, and errors propagate exactly as raised.
+
+This module has no dependencies on the rest of PythonNative, so any
+module (hooks, reconciler, events) may import it freely.
+"""
+
+import os
+import sys
+import threading
+import traceback
+from collections import deque
+from typing import Any, Callable, Deque, List, Optional, Set, Tuple
+
+__all__ = [
+    "HookOrderError",
+    "set_dev_mode",
+    "is_dev",
+    "warn",
+    "warn_once",
+    "swallowed",
+    "get_warnings",
+    "clear_warnings",
+    "set_error_reporter",
+    "report_error",
+]
+
+
+class HookOrderError(RuntimeError):
+    """Raised in dev mode when hooks are called in a different order than the previous render.
+
+    Hooks map to state slots by call order, so calling them inside
+    conditionals or loops (or returning early between hook calls)
+    silently cross-wires state in production. Dev mode detects the
+    mismatch and raises this error with the offending component and
+    slot so the bug is caught at the source.
+    """
+
+
+# ======================================================================
+# Dev mode
+# ======================================================================
+
+# Tri-state: ``None`` means "not explicitly set, consult the environment".
+_dev_mode: Optional[bool] = None
+
+
+def set_dev_mode(enabled: bool) -> None:
+    """Explicitly enable or disable dev mode for this process.
+
+    Called automatically by ``pn preview`` and by the screen host's
+    ``enable_hot_reload`` (which the device templates invoke on debug
+    builds). An explicit call wins over the ``PN_DEV`` environment
+    variable.
+
+    Args:
+        enabled: ``True`` to turn on dev diagnostics.
+    """
+    global _dev_mode
+    _dev_mode = bool(enabled)
+
+
+def is_dev() -> bool:
+    """Return whether dev diagnostics are active.
+
+    Resolution order: an explicit
+    [`set_dev_mode`][pythonnative.diagnostics.set_dev_mode] call, then
+    the ``PN_DEV`` environment variable, then ``False``.
+    """
+    if _dev_mode is not None:
+        return _dev_mode
+    return os.environ.get("PN_DEV", "").lower() in {"1", "true", "yes", "on"}
+
+
+# ======================================================================
+# Warnings (LogBox-lite)
+# ======================================================================
+
+_MAX_WARNINGS = 200
+
+_warn_lock = threading.Lock()
+_warned_keys: Set[str] = set()
+_warnings: Deque[str] = deque(maxlen=_MAX_WARNINGS)
+
+
+def warn(message: str) -> None:
+    """Print a dev warning and record it in the warning log.
+
+    No-op in production. Warnings are prefixed with ``[PN] WARN`` on
+    stderr and retained (most recent 200) for inspection via
+    [`get_warnings`][pythonnative.diagnostics.get_warnings].
+
+    Args:
+        message: Human-readable description of the problem, ideally
+            with a suggestion for the fix.
+    """
+    if not is_dev():
+        return
+    with _warn_lock:
+        _warnings.append(message)
+    try:
+        print(f"[PN] WARN: {message}", file=sys.stderr, flush=True)
+    except Exception:
+        pass
+
+
+def warn_once(message: str, key: Optional[str] = None) -> None:
+    """Like [`warn`][pythonnative.diagnostics.warn], but at most once per ``key``.
+
+    Use for per-render validation (style keys, list keys) so a warning
+    fires once instead of sixty times a second.
+
+    Args:
+        message: The warning message.
+        key: Dedupe key, e.g. ``"style:Text:font_siez"``. Defaults to
+            the message itself.
+    """
+    if not is_dev():
+        return
+    dedupe = key if key is not None else message
+    with _warn_lock:
+        if dedupe in _warned_keys:
+            return
+        _warned_keys.add(dedupe)
+    warn(message)
+
+
+def swallowed(context: str) -> None:
+    """Surface a suppressed native-backend exception (dev mode only).
+
+    The native view/module backends intentionally degrade gracefully in
+    production: a failed style application or a missing OS API must not
+    crash the app. Call this from the ``except`` block instead of
+    ``pass`` so that, in dev mode, each suppression is reported once per
+    call site instead of disappearing.
+
+    Args:
+        context: Where the suppression happened, e.g.
+            ``"ios.TextHandler._apply"``.
+    """
+    if not is_dev():
+        return
+    exc = sys.exc_info()[1]
+    if exc is None:
+        return
+    frame = sys._getframe(1)
+    location = f"{os.path.basename(frame.f_code.co_filename)}:{frame.f_lineno}"
+    warn_once(
+        f"{context} suppressed {type(exc).__name__}: {exc} ({location})",
+        key=f"swallowed:{context}:{location}",
+    )
+
+
+def get_warnings() -> List[str]:
+    """Return a snapshot of the recorded warnings (oldest first)."""
+    with _warn_lock:
+        return list(_warnings)
+
+
+def clear_warnings() -> None:
+    """Drop all recorded warnings and dedupe keys (test helper)."""
+    with _warn_lock:
+        _warnings.clear()
+        _warned_keys.clear()
+
+
+# ======================================================================
+# Error reporting (RedBox routing)
+# ======================================================================
+#
+# Screen hosts register themselves as error reporters. When an error
+# escapes user code in a context that would otherwise be swallowed
+# (event handlers) or crash the process (async tasks), dev mode routes
+# it to the most recently registered reporter, which shows the RedBox.
+# Reporters form a stack: the top entry is the most recently created
+# (and therefore frontmost) screen.
+
+_reporter_lock = threading.Lock()
+_reporters: List[Tuple[int, Callable[[BaseException, str], None]]] = []
+
+
+def set_error_reporter(owner: Any, reporter: Optional[Callable[[BaseException, str], None]]) -> None:
+    """Register or unregister ``owner``'s RedBox reporter.
+
+    Args:
+        owner: Any object identifying the registration (a screen
+            host); keyed by ``id(owner)``.
+        reporter: ``reporter(exc, phase)`` callable, or ``None`` to
+            unregister the owner's reporter.
+    """
+    key = id(owner)
+    with _reporter_lock:
+        _reporters[:] = [(k, r) for (k, r) in _reporters if k != key]
+        if reporter is not None:
+            _reporters.append((key, reporter))
+
+
+def report_error(exc: BaseException, phase: str = "runtime") -> bool:
+    """Route ``exc`` to the active RedBox reporter (dev mode only).
+
+    Args:
+        exc: The exception to display.
+        phase: Where it came from: ``"render"``, ``"effect"``,
+            ``"event"``, or ``"async"``.
+
+    Returns:
+        ``True`` when a reporter accepted the error, ``False`` when no
+        reporter is registered (or dev mode is off), in which case the
+        caller should fall back to its default behavior.
+    """
+    if not is_dev():
+        return False
+    with _reporter_lock:
+        reporter = _reporters[-1][1] if _reporters else None
+    if reporter is None:
+        return False
+    try:
+        reporter(exc, phase)
+        return True
+    except Exception:
+        traceback.print_exc()
+        return False

pythonnative/element.py

@@ -0,0 +1,159 @@
+"""Lightweight element descriptors for the virtual view tree.
+
+An [`Element`][pythonnative.Element] is an immutable description of a UI
+node, analogous to a React element. It captures a type, a props dict,
+and an ordered list of children without creating any native platform
+objects. The reconciler consumes these trees to determine what native
+views must be created, updated, or removed.
+
+An element's ``type`` is one of three things:
+
+- a ``str`` naming a **native view** (``"Text"``, ``"View"``, ...),
+- a [`Component`][pythonnative.Component] produced by
+  [`@component`][pythonnative.component.component], or
+- a **structural type**: one of the singletons defined here
+  ([`FRAGMENT`][pythonnative.element.FRAGMENT],
+  [`ERROR_BOUNDARY`][pythonnative.element.ERROR_BOUNDARY],
+  [`SUSPENSE`][pythonnative.element.SUSPENSE]) or a
+  [`Context`][pythonnative.Context] (whose elements are providers).
+
+Structural types are real objects rather than magic strings so the
+reconciler can dispatch on them with identity checks and no user
+element can collide with them.
+
+Elements are produced by built-in factories such as
+[`Text`][pythonnative.Text], [`Button`][pythonnative.Button], and
+[`Column`][pythonnative.Column], or by calling components.
+
+Example:
+    ```python
+    from pythonnative import Element
+
+    node = Element("Text", {"text": "Hello"}, [])
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+__all__ = [
+    "ERROR_BOUNDARY",
+    "FRAGMENT",
+    "SUSPENSE",
+    "Element",
+    "Node",
+    "StructuralType",
+    "type_label",
+]
+
+
+class StructuralType:
+    """Identity object naming a reconciler-owned element kind.
+
+    Instances are singletons compared by identity; ``repr`` shows the
+    kind for debugging (``<Fragment>``).
+    """
+
+    __slots__ = ("name",)
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"<{self.name}>"
+
+
+FRAGMENT = StructuralType("Fragment")
+"""Type of [`Fragment`][pythonnative.Fragment] elements: a transparent group."""
+
+ERROR_BOUNDARY = StructuralType("ErrorBoundary")
+"""Type of [`ErrorBoundary`][pythonnative.ErrorBoundary] elements."""
+
+SUSPENSE = StructuralType("Suspense")
+"""Type of [`Suspense`][pythonnative.Suspense] elements."""
+
+
+class Element:
+    """Immutable description of a single UI node.
+
+    Built-in elements use a string ``type`` (``"Text"``, ``"Button"``,
+    ``"Column"``, etc.); components use the
+    [`Component`][pythonnative.Component] object itself as ``type``;
+    structural elements use a [`StructuralType`][pythonnative.element.StructuralType]
+    or a [`Context`][pythonnative.Context]. The reconciler dispatches on
+    this distinction when mounting the tree.
+
+    Attributes:
+        type: The element kind (see the module docstring).
+        props: Dict of properties passed to the native handler or the
+            component function.
+        children: Ordered list of child nodes. ``None`` and ``False``
+            entries are permitted and dropped during reconciliation, so
+            conditional children (``cond and Text(...)``) need no special
+            casing. Components receive these as their ``*children``.
+        key: Optional stable identity used by the reconciler when
+            diffing keyed lists. Two elements with the same ``type`` and
+            ``key`` are treated as the same logical node across renders.
+    """
+
+    __slots__ = ("type", "props", "children", "key")
+
+    def __init__(
+        self,
+        type_: Any,
+        props: Optional[Dict[str, Any]] = None,
+        children: Optional[Iterable[Any]] = None,
+        key: Optional[str] = None,
+    ) -> None:
+        self.type = type_
+        self.props: Dict[str, Any] = props if props is not None else {}
+        self.children: List[Any] = list(children) if children is not None else []
+        self.key = key
+
+    def __repr__(self) -> str:
+        return f"Element({type_label(self.type)!r}, props={sorted(self.props)}, children={len(self.children)})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Element):
+            return NotImplemented
+        return (
+            self.type == other.type
+            and self.props == other.props
+            and self.children == other.children
+            and self.key == other.key
+        )
+
+    def __ne__(self, other: object) -> bool:
+        result = self.__eq__(other)
+        if result is NotImplemented:
+            return result
+        return not result
+
+    __hash__ = None  # type: ignore[assignment,unused-ignore]
+
+    def with_key(self, key: Optional[str]) -> "Element":
+        """Return a copy of this element carrying ``key``.
+
+        Handy when a factory result needs a key after the fact, for
+        example while building a list comprehension over elements
+        produced by a helper that doesn't take ``key``.
+        """
+        return Element(self.type, self.props, self.children, key=key)
+
+
+Node = Union[Element, None, bool, Iterable[Any]]
+"""Anything a component may render: an element, ``None`` / ``False``
+for "nothing", or a (possibly nested) iterable of nodes."""
+
+
+def type_label(type_obj: Any) -> str:
+    """Return a human-readable name for an element type (for messages)."""
+    if isinstance(type_obj, str):
+        return type_obj
+    if isinstance(type_obj, StructuralType):
+        return type_obj.name
+    name = getattr(type_obj, "display_name", None) or getattr(type_obj, "__name__", None)
+    if name:
+        return str(name)
+    return repr(type_obj)

pythonnative/equality.py

@@ -0,0 +1,19 @@
+"""Equality rules for immutable application snapshots.
+
+Identity is equal. Scalar boolean equality is respected. Objects whose
+comparison returns a nonboolean result (such as arrays) require a new
+identity to signal a change. In-place mutations don't signal updates.
+"""
+
+from typing import Any
+
+
+def equal(left: Any, right: Any) -> bool:
+    """Compare values without coercing array expressions to booleans."""
+    if left is right:
+        return True
+    try:
+        result = left == right
+        return result if isinstance(result, bool) else False
+    except Exception:
+        return False

pythonnative/events.py

@@ -0,0 +1,231 @@
+"""Tag-based event routing between native views and Python callbacks.
+
+Before the batched-commit overhaul, every event prop (``on_press``,
+``on_change``, …) was wired by storing the Python callable on (or next
+to) the native view, and every re-render re-pushed fresh closures across
+the bridge. This module replaces that with a single dispatch channel:
+
+- The reconciler strips callable props out of the payload sent to
+  native handlers and registers them here, keyed by ``(tag, name)``.
+- Handlers wire their platform listener **once** at view creation; the
+  listener calls [`dispatch_event`][pythonnative.events.dispatch_event]
+  with the view's tag and the event name.
+- Re-renders only mutate this Python-side registry; no native call is
+  made when just a callback identity changes.
+
+The set of event names present on an element is forwarded to handlers
+under the [`EVENTS_PROP`][pythonnative.events.EVENTS_PROP] key (a
+``frozenset``), so handlers that wire expensive listeners (scroll
+delegates, gesture recognizers) can do so conditionally. Dispatching an
+event nobody listens to is a cheap dict miss.
+"""
+
+import threading
+from typing import Any, Callable, Dict, FrozenSet, Optional, Tuple
+
+EVENTS_PROP = "_pn_events"
+"""Prop key carrying the ``frozenset`` of event names wired on an element."""
+
+GESTURES_PROP = "gestures"
+"""Prop key carrying gesture descriptors (see ``pythonnative.gestures``)."""
+
+# Prop dicts that may carry nested callables, mapped to the event name
+# each nested key is hoisted to.
+_NESTED_EVENT_PROPS: Dict[str, Dict[str, str]] = {
+    "refresh_control": {"on_refresh": "on_refresh"},
+}
+
+
+class EventRegistry:
+    """Process-wide map of ``(tag, event name) -> Python callback``.
+
+    Thread-safe: native backends may dispatch from the platform UI
+    thread while the reconciler updates registrations from the render
+    thread.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._scopes: Dict[int, Any] = {}
+        self._callbacks: Dict[int, Dict[str, Callable[..., Any]]] = {}
+
+    def set_events(self, tag: int, events: Dict[str, Callable[..., Any]]) -> None:
+        """Replace every registration for ``tag`` with ``events``."""
+        with self._lock:
+            if events:
+                self._callbacks[tag] = dict(events)
+            else:
+                self._callbacks.pop(tag, None)
+
+    def set_scope(self, tag: int, scope: Any) -> None:
+        """Associate callbacks with the component that owns this view."""
+        self._scopes[tag] = scope
+
+    def invoke(self, tag: int, name: str, *args: Any) -> Any:
+        """Invoke a sync or async handler with component cancellation."""
+        from .runtime import invoke
+
+        callback = self.get(tag, name)
+        if callback is not None:
+            return invoke(callback, *args, scope=self._scopes.get(tag))
+        return None
+
+    def clear(self, tag: int) -> None:
+        """Drop every registration for ``tag`` (called on view destroy)."""
+        with self._lock:
+            self._callbacks.pop(tag, None)
+            self._scopes.pop(tag, None)
+
+    def get(self, tag: int, name: str) -> Optional[Callable[..., Any]]:
+        """Return the callback for ``(tag, name)``, or ``None``."""
+        with self._lock:
+            bucket = self._callbacks.get(tag)
+            if bucket is None:
+                return None
+            return bucket.get(name)
+
+    def has(self, tag: int, name: str) -> bool:
+        """Return whether a callback is registered for ``(tag, name)``."""
+        return self.get(tag, name) is not None
+
+    def dispatch(self, tag: int, name: str, *args: Any) -> bool:
+        """Invoke the callback for ``(tag, name)`` with ``args``.
+
+        Returns:
+            ``True`` when a callback existed and was invoked (even if
+            it raised: exceptions never propagate into the platform's
+            UI thread; in dev mode they are routed to the RedBox via
+            [`report_error`][pythonnative.diagnostics.report_error],
+            otherwise the traceback is printed), ``False`` when nothing
+            is registered.
+        """
+        callback = self.get(tag, name)
+        if callback is None:
+            return False
+        try:
+            self.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 True
+
+    def reset(self) -> None:
+        """Drop every registration (test helper)."""
+        with self._lock:
+            self._callbacks.clear()
+            self._scopes.clear()
+
+
+_registry = EventRegistry()
+
+
+def get_event_registry() -> EventRegistry:
+    """Return the process-wide [`EventRegistry`][pythonnative.events.EventRegistry]."""
+    return _registry
+
+
+def dispatch_event(tag: int, name: str, *args: Any) -> bool:
+    """Dispatch an event from a native view into Python.
+
+    This is the single entry point platform handlers call when a
+    native listener fires.
+
+    Args:
+        tag: The view's reconciler-assigned tag.
+        name: Event name, the original prop name (``"on_press"``,
+            ``"on_change"``, …) or a gesture channel (``"gesture:0"``).
+        *args: Positional arguments forwarded to the user callback,
+            preserving each prop's documented signature.
+
+    Returns:
+        Whether a callback was registered for ``(tag, name)``.
+    """
+    return _registry.dispatch(tag, name, *args)
+
+
+# ======================================================================
+# Prop splitting
+# ======================================================================
+
+
+def extract_events(props: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Callable[..., Any]]]:
+    """Split ``props`` into native-safe props and Python event callbacks.
+
+    Rules:
+
+    - Top-level callables named ``on_*`` become events under their prop
+      name and are removed from the native payload.
+    - ``refresh_control`` dicts have their nested ``on_refresh``
+      hoisted to the ``"on_refresh"`` event; the remaining keys
+      (``refreshing``, ``tint_color``) stay in the payload.
+    - ``gestures`` lists of gesture descriptors are serialized to plain
+      dicts (handlers wire recognizers from them) while their callbacks
+      are folded into per-gesture ``"gesture:<i>"`` routers.
+    - The resulting payload carries ``_pn_events`` (a frozenset of the
+      event names present), so handlers can wire listeners
+      conditionally and the prop differ can detect listener
+      addition/removal without comparing closures.
+
+    Args:
+        props: Raw element props (already stripped of reconciler-owned
+            keys).
+
+    Returns:
+        ``(clean_props, events)`` where ``clean_props`` contains no
+        callables and ``events`` maps event names to callbacks.
+    """
+    clean: Dict[str, Any] = {}
+    events: Dict[str, Callable[..., Any]] = {}
+
+    for key, value in props.items():
+        if key.startswith("on_") and callable(value):
+            events[key] = value
+            continue
+        nested_spec = _NESTED_EVENT_PROPS.get(key)
+        if nested_spec is not None and isinstance(value, dict):
+            remainder: Dict[str, Any] = {}
+            for nested_key, nested_value in value.items():
+                event_name = nested_spec.get(nested_key)
+                if event_name is not None and callable(nested_value):
+                    events[event_name] = nested_value
+                else:
+                    remainder[nested_key] = nested_value
+            clean[key] = remainder
+            continue
+        if key == GESTURES_PROP and value:
+            from .gestures import serialize_gestures
+
+            specs, gesture_events = serialize_gestures(value)
+            clean[key] = specs
+            events.update(gesture_events)
+            continue
+        clean[key] = value
+
+    if events:
+        clean[EVENTS_PROP] = frozenset(events)
+    return clean, events
+
+
+def event_names(props: Dict[str, Any]) -> FrozenSet[str]:
+    """Return the event-name set a handler should consult for ``props``."""
+    names = props.get(EVENTS_PROP)
+    if isinstance(names, frozenset):
+        return names
+    if isinstance(names, (set, list, tuple)):
+        return frozenset(names)
+    return frozenset()
+
+
+__all__ = [
+    "EVENTS_PROP",
+    "GESTURES_PROP",
+    "EventRegistry",
+    "get_event_registry",
+    "dispatch_event",
+    "extract_events",
+    "event_names",
+]