pythonnative 0.22.1__py3-none-any.whl → 0.24.0__py3-none-any.whl

pythonnative/diagnostics.py

@@ -0,0 +1,214 @@
+"""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.screen`) 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",
+    "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 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

@@ -36,7 +36,10 @@ class Element:
             components decorated with [`component`][pythonnative.component].
         props: Dict of properties passed to the native handler or
             component function.
-        children: Ordered list of child `Element` instances.
+        children: Ordered list of child `Element` instances. `None` and
+            `False` entries are permitted and dropped during
+            reconciliation, so conditional children (`cond and Text(...)`)
+            need no special casing.
         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.
@@ -48,7 +51,7 @@ class Element:
         self,
         type_name: Union[str, Any],
         props: Dict[str, Any],
-        children: List["Element"],
+        children: List[Any],
         key: Optional[str] = None,
     ) -> None:
         self.type = type_name

pythonnative/events.py

@@ -1,6 +1,6 @@
 """Tag-based event routing between native views and Python callbacks.
 
-Before the batched-commit overhaul, every event prop (``on_click``,
+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:
@@ -78,19 +78,24 @@ class EventRegistry:
 
         Returns:
             ``True`` when a callback existed and was invoked (even if
-            it raised: exceptions are swallowed so a buggy app
-            callback can't crash the platform's UI thread), ``False``
-            when nothing is registered.
+            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:
             callback(*args)
-        except Exception:
-            import traceback
+        except Exception as exc:
+            from . import diagnostics
 
-            traceback.print_exc()
+            if not diagnostics.report_error(exc, phase=f"event {name!r}"):
+                import traceback
+
+                traceback.print_exc()
         return True
 
     def reset(self) -> None:
@@ -115,7 +120,7 @@ def dispatch_event(tag: int, name: str, *args: Any) -> bool:
 
     Args:
         tag: The view's reconciler-assigned tag.
-        name: Event name, the original prop name (``"on_click"``,
+        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.