pythonnative 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

pythonnative/hooks.py

@@ -19,7 +19,8 @@ Usage::
 
 import inspect
 import threading
-from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, Generator, List, Optional, Tuple, TypeVar
 
 from .element import Element
 
@@ -29,6 +30,7 @@ _SENTINEL = object()
 
 _hook_context: threading.local = threading.local()
 
+_batch_context: threading.local = threading.local()
 
 # ======================================================================
 # Hook state container
@@ -36,9 +38,22 @@ _hook_context: threading.local = threading.local()
 
 
 class HookState:
-    """Stores all hook data for a single function component instance."""
+    """Stores all hook data for a single function component instance.
 
-    __slots__ = ("states", "effects", "memos", "refs", "hook_index", "_trigger_render")
+    Effects are **queued** during the render phase and **flushed** after
+    the reconciler commits native-view mutations.  This guarantees that
+    effect callbacks can safely interact with the committed native tree.
+    """
+
+    __slots__ = (
+        "states",
+        "effects",
+        "memos",
+        "refs",
+        "hook_index",
+        "_trigger_render",
+        "_pending_effects",
+    )
 
     def __init__(self) -> None:
         self.states: List[Any] = []
@@ -47,15 +62,24 @@ class HookState:
         self.refs: List[dict] = []
         self.hook_index: int = 0
         self._trigger_render: Optional[Callable[[], None]] = None
+        self._pending_effects: List[Tuple[int, Callable, Any]] = []
 
     def reset_index(self) -> None:
         self.hook_index = 0
 
-    def run_pending_effects(self) -> None:
-        """Execute effects whose deps changed during the last render pass."""
-        for i, (deps, cleanup) in enumerate(self.effects):
-            if deps is _SENTINEL:
-                continue
+    def flush_pending_effects(self) -> None:
+        """Execute effects queued during the render pass (called after commit)."""
+        pending = self._pending_effects
+        self._pending_effects = []
+        for idx, effect_fn, deps in pending:
+            _, prev_cleanup = self.effects[idx]
+            if callable(prev_cleanup):
+                try:
+                    prev_cleanup()
+                except Exception:
+                    pass
+            cleanup = effect_fn()
+            self.effects[idx] = (list(deps) if deps is not None else None, cleanup)
 
     def cleanup_all_effects(self) -> None:
         """Run all outstanding cleanup functions (called on unmount)."""
@@ -66,6 +90,7 @@ class HookState:
                 except Exception:
                     pass
             self.effects[i] = (_SENTINEL, None)
+        self._pending_effects = []
 
 
 # ======================================================================
@@ -91,6 +116,45 @@ def _deps_changed(prev: Any, current: Any) -> bool:
     return any(p is not c and p != c for p, c in zip(prev, current))
 
 
+# ======================================================================
+# Batching helpers
+# ======================================================================
+
+
+def _schedule_trigger(trigger: Callable[[], None]) -> None:
+    """Call *trigger* now, or defer it if inside :func:`batch_updates`."""
+    if getattr(_batch_context, "depth", 0) > 0:
+        _batch_context.pending_trigger = trigger
+    else:
+        trigger()
+
+
+@contextmanager
+def batch_updates() -> Generator[None, None, None]:
+    """Batch multiple state updates so only one re-render occurs.
+
+    Usage::
+
+        with pn.batch_updates():
+            set_count(1)
+            set_name("hello")
+        # single re-render happens here
+    """
+    depth = getattr(_batch_context, "depth", 0)
+    _batch_context.depth = depth + 1
+    if depth == 0:
+        _batch_context.pending_trigger = None
+    try:
+        yield
+    finally:
+        _batch_context.depth -= 1
+        if _batch_context.depth == 0:
+            trigger = _batch_context.pending_trigger
+            _batch_context.pending_trigger = None
+            if trigger is not None:
+                trigger()
+
+
 # ======================================================================
 # Public hooks
 # ======================================================================
@@ -121,13 +185,60 @@ def use_state(initial: Any = None) -> Tuple[Any, Callable]:
         if ctx.states[idx] is not new_value and ctx.states[idx] != new_value:
             ctx.states[idx] = new_value
             if ctx._trigger_render:
-                ctx._trigger_render()
+                _schedule_trigger(ctx._trigger_render)
 
     return current, setter
 
 
+def use_reducer(reducer: Callable[[Any, Any], Any], initial_state: Any) -> Tuple[Any, Callable]:
+    """Return ``(state, dispatch)`` for reducer-based state management.
+
+    The *reducer* is called as ``reducer(current_state, action)`` and
+    must return the new state.  If *initial_state* is callable it is
+    invoked once (lazy initialisation).
+
+    Usage::
+
+        def reducer(state, action):
+            if action == "increment":
+                return state + 1
+            if action == "reset":
+                return 0
+            return state
+
+        count, dispatch = pn.use_reducer(reducer, 0)
+        # dispatch("increment") -> re-render with count = 1
+    """
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_reducer must be called inside a @component function")
+
+    idx = ctx.hook_index
+    ctx.hook_index += 1
+
+    if idx >= len(ctx.states):
+        val = initial_state() if callable(initial_state) else initial_state
+        ctx.states.append(val)
+
+    current = ctx.states[idx]
+
+    def dispatch(action: Any) -> None:
+        new_state = reducer(ctx.states[idx], action)
+        if ctx.states[idx] is not new_state and ctx.states[idx] != new_state:
+            ctx.states[idx] = new_state
+            if ctx._trigger_render:
+                _schedule_trigger(ctx._trigger_render)
+
+    return current, dispatch
+
+
 def use_effect(effect: Callable, deps: Optional[list] = None) -> None:
-    """Schedule *effect* to run after render.
+    """Schedule *effect* to run **after** the native tree is committed.
+
+    Effects are queued during the render pass and flushed once the
+    reconciler has finished applying all native-view mutations.  This
+    means effects can safely measure layout or interact with committed
+    native views.
 
     *deps* controls when the effect re-runs:
 
@@ -146,18 +257,12 @@ def use_effect(effect: Callable, deps: Optional[list] = None) -> None:
 
     if idx >= len(ctx.effects):
         ctx.effects.append((_SENTINEL, None))
+        ctx._pending_effects.append((idx, effect, deps))
+        return
 
-    prev_deps, prev_cleanup = ctx.effects[idx]
+    prev_deps, _prev_cleanup = ctx.effects[idx]
     if _deps_changed(prev_deps, deps):
-        if callable(prev_cleanup):
-            try:
-                prev_cleanup()
-            except Exception:
-                pass
-        cleanup = effect()
-        ctx.effects[idx] = (list(deps) if deps is not None else None, cleanup)
-    else:
-        ctx.effects[idx] = (prev_deps, prev_cleanup)
+        ctx._pending_effects.append((idx, effect, deps))
 
 
 def use_memo(factory: Callable[[], T], deps: list) -> T:
@@ -255,27 +360,28 @@ _NavigationContext: Context = create_context(None)
 
 
 class NavigationHandle:
-    """Object returned by :func:`use_navigation` providing push/pop/get_args.
+    """Object returned by :func:`use_navigation` providing navigation methods.
 
-    Navigates by component reference rather than string path, e.g.::
+    ::
 
         nav = pn.use_navigation()
-        nav.push(DetailScreen, args={"id": 42})
+        nav.navigate(DetailScreen, params={"id": 42})
+        nav.go_back()
     """
 
     def __init__(self, host: Any) -> None:
         self._host = host
 
-    def push(self, page: Any, args: Optional[Dict[str, Any]] = None) -> None:
-        """Navigate forward to *page* (a ``@component`` function or class)."""
-        self._host._push(page, args)
+    def navigate(self, page: Any, params: Optional[Dict[str, Any]] = None) -> None:
+        """Navigate forward to *page* with optional *params*."""
+        self._host._push(page, params)
 
-    def pop(self) -> None:
+    def go_back(self) -> None:
         """Navigate back to the previous screen."""
         self._host._pop()
 
-    def get_args(self) -> Dict[str, Any]:
-        """Return arguments passed from the previous screen."""
+    def get_params(self) -> Dict[str, Any]:
+        """Return parameters passed from the previous screen."""
         return self._host._get_nav_args()
 
 

pythonnative/hot_reload.py

@@ -137,7 +137,7 @@ class ModuleReloader:
     @staticmethod
     def reload_page(page_instance: Any) -> None:
         """Force a page re-render after module reload."""
-        from .page import _re_render
+        from .page import _request_render
 
         if hasattr(page_instance, "_reconciler") and page_instance._reconciler is not None:
-            _re_render(page_instance)
+            _request_render(page_instance)

pythonnative/native_views/__init__.py

@@ -0,0 +1,87 @@
+"""Platform-specific native view creation and update logic.
+
+This package provides the :class:`NativeViewRegistry` that maps element type
+names to platform-specific :class:`~.base.ViewHandler` implementations.
+
+Platform handlers live in dedicated submodules:
+
+- :mod:`~.base` — shared :class:`~.base.ViewHandler` protocol and utilities
+- :mod:`~.android` — Android handlers (Chaquopy / Java bridge)
+- :mod:`~.ios` — iOS handlers (rubicon-objc)
+
+All platform-branching is handled at registration time via lazy imports,
+so the package can be imported on any platform for testing.
+"""
+
+from typing import Any, Dict, Optional
+
+from .base import ViewHandler
+
+
+class NativeViewRegistry:
+    """Maps element type names to platform-specific :class:`ViewHandler` instances."""
+
+    def __init__(self) -> None:
+        self._handlers: Dict[str, ViewHandler] = {}
+
+    def register(self, type_name: str, handler: ViewHandler) -> None:
+        self._handlers[type_name] = handler
+
+    def create_view(self, type_name: str, props: Dict[str, Any]) -> Any:
+        handler = self._handlers.get(type_name)
+        if handler is None:
+            raise ValueError(f"Unknown element type: {type_name!r}")
+        return handler.create(props)
+
+    def update_view(self, native_view: Any, type_name: str, changed_props: Dict[str, Any]) -> None:
+        handler = self._handlers.get(type_name)
+        if handler is not None:
+            handler.update(native_view, changed_props)
+
+    def add_child(self, parent: Any, child: Any, parent_type: str) -> None:
+        handler = self._handlers.get(parent_type)
+        if handler is not None:
+            handler.add_child(parent, child)
+
+    def remove_child(self, parent: Any, child: Any, parent_type: str) -> None:
+        handler = self._handlers.get(parent_type)
+        if handler is not None:
+            handler.remove_child(parent, child)
+
+    def insert_child(self, parent: Any, child: Any, parent_type: str, index: int) -> None:
+        handler = self._handlers.get(parent_type)
+        if handler is not None:
+            handler.insert_child(parent, child, index)
+
+
+# ======================================================================
+# Singleton registry
+# ======================================================================
+
+_registry: Optional[NativeViewRegistry] = None
+
+
+def get_registry() -> NativeViewRegistry:
+    """Return the singleton registry, lazily creating platform handlers."""
+    global _registry
+    if _registry is not None:
+        return _registry
+    _registry = NativeViewRegistry()
+
+    from ..utils import IS_ANDROID
+
+    if IS_ANDROID:
+        from .android import register_handlers
+
+        register_handlers(_registry)
+    else:
+        from .ios import register_handlers
+
+        register_handlers(_registry)
+    return _registry
+
+
+def set_registry(registry: NativeViewRegistry) -> None:
+    """Inject a custom or mock registry (primarily for testing)."""
+    global _registry
+    _registry = registry