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

pythonnative/__init__.py

@@ -14,12 +14,13 @@ Public API::
         )
 """
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 
 from .components import (
     ActivityIndicator,
     Button,
     Column,
+    ErrorBoundary,
     FlatList,
     Image,
     Modal,
@@ -39,6 +40,7 @@ from .components import (
 from .element import Element
 from .hooks import (
     Provider,
+    batch_updates,
     component,
     create_context,
     use_callback,
@@ -46,9 +48,18 @@ from .hooks import (
     use_effect,
     use_memo,
     use_navigation,
+    use_reducer,
     use_ref,
     use_state,
 )
+from .navigation import (
+    NavigationContainer,
+    create_drawer_navigator,
+    create_stack_navigator,
+    create_tab_navigator,
+    use_focus_effect,
+    use_route,
+)
 from .page import create_page
 from .style import StyleSheet, ThemeContext
 
@@ -57,6 +68,7 @@ __all__ = [
     "ActivityIndicator",
     "Button",
     "Column",
+    "ErrorBoundary",
     "FlatList",
     "Image",
     "Modal",
@@ -76,16 +88,25 @@ __all__ = [
     "Element",
     "create_page",
     # Hooks
+    "batch_updates",
     "component",
     "create_context",
     "use_callback",
     "use_context",
     "use_effect",
+    "use_focus_effect",
     "use_memo",
     "use_navigation",
+    "use_reducer",
     "use_ref",
+    "use_route",
     "use_state",
     "Provider",
+    # Navigation
+    "NavigationContainer",
+    "create_drawer_navigator",
+    "create_stack_navigator",
+    "create_tab_navigator",
     # Styling
     "StyleSheet",
     "ThemeContext",

pythonnative/components.py

@@ -9,12 +9,18 @@ which accepts a dict or a list of dicts (later entries override earlier).
 
 Layout properties supported by all components::
 
-    width, height, flex, margin, min_width, max_width, min_height,
-    max_height, align_self
+    width, height, flex, flex_grow, flex_shrink, margin,
+    min_width, max_width, min_height, max_height, align_self
 
-Container-specific layout properties (Column / Row)::
+Flex container properties (View / Column / Row)::
 
-    spacing, padding, align_items, justify_content
+    flex_direction, justify_content, align_items, overflow,
+    spacing, padding
+
+``View`` is the universal flex container (like React Native's ``View``).
+It defaults to ``flex_direction: "column"``.  ``Column`` and ``Row``
+are convenience wrappers that fix the direction to ``"column"`` and
+``"row"`` respectively.
 """
 
 from typing import Any, Callable, Dict, List, Optional
@@ -204,15 +210,48 @@ def Slider(
 # ======================================================================
 
 
+def View(
+    *children: Element,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Universal flex container (like React Native's ``View``).
+
+    Defaults to ``flex_direction: "column"``.  Override via ``style``::
+
+        pn.View(child_a, child_b, style={"flex_direction": "row"})
+
+    Flex container properties (inside ``style``):
+
+    - ``flex_direction`` — ``"column"`` (default), ``"row"``,
+      ``"column_reverse"``, ``"row_reverse"``
+    - ``justify_content`` — main-axis distribution:
+      ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
+      ``"space_between"``, ``"space_around"``, ``"space_evenly"``
+    - ``align_items`` — cross-axis alignment:
+      ``"stretch"`` (default), ``"flex_start"``, ``"center"``,
+      ``"flex_end"``
+    - ``overflow`` — ``"visible"`` (default) or ``"hidden"``
+    - ``spacing``, ``padding``, ``background_color``
+    """
+    props: Dict[str, Any] = {"flex_direction": "column"}
+    props.update(resolve_style(style))
+    return Element("View", props, list(children), key=key)
+
+
 def Column(
     *children: Element,
     style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Arrange children vertically.
+    """Arrange children vertically (``flex_direction: "column"``).
+
+    Convenience wrapper around :func:`View`.  The direction is fixed;
+    use :func:`View` directly if you need ``flex_direction: "row"``.
 
     Style properties: ``spacing``, ``padding``, ``align_items``,
-    ``justify_content``, ``background_color``, plus common layout props.
+    ``justify_content``, ``background_color``, ``overflow``,
+    plus common layout props.
 
     ``align_items`` controls cross-axis (horizontal) alignment:
     ``"stretch"`` (default), ``"flex_start"``/``"leading"``,
@@ -222,8 +261,9 @@ def Column(
     ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
     ``"space_between"``, ``"space_around"``, ``"space_evenly"``.
     """
-    props: Dict[str, Any] = {}
+    props: Dict[str, Any] = {"flex_direction": "column"}
     props.update(resolve_style(style))
+    props["flex_direction"] = "column"
     return Element("Column", props, list(children), key=key)
 
 
@@ -232,10 +272,14 @@ def Row(
     style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Arrange children horizontally.
+    """Arrange children horizontally (``flex_direction: "row"``).
+
+    Convenience wrapper around :func:`View`.  The direction is fixed;
+    use :func:`View` directly if you need ``flex_direction: "column"``.
 
     Style properties: ``spacing``, ``padding``, ``align_items``,
-    ``justify_content``, ``background_color``, plus common layout props.
+    ``justify_content``, ``background_color``, ``overflow``,
+    plus common layout props.
 
     ``align_items`` controls cross-axis (vertical) alignment:
     ``"stretch"`` (default), ``"flex_start"``/``"top"``,
@@ -245,8 +289,9 @@ def Row(
     ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
     ``"space_between"``, ``"space_around"``, ``"space_evenly"``.
     """
-    props: Dict[str, Any] = {}
+    props: Dict[str, Any] = {"flex_direction": "row"}
     props.update(resolve_style(style))
+    props["flex_direction"] = "row"
     return Element("Row", props, list(children), key=key)
 
 
@@ -263,17 +308,6 @@ def ScrollView(
     return Element("ScrollView", props, children, key=key)
 
 
-def View(
-    *children: Element,
-    style: StyleValue = None,
-    key: Optional[str] = None,
-) -> Element:
-    """Generic container view (``UIView`` / ``android.view.View``)."""
-    props: Dict[str, Any] = {}
-    props.update(resolve_style(style))
-    return Element("View", props, list(children), key=key)
-
-
 def SafeAreaView(
     *children: Element,
     style: StyleValue = None,
@@ -323,6 +357,29 @@ def Pressable(
     return Element("Pressable", props, children, key=key)
 
 
+def ErrorBoundary(
+    child: Optional[Element] = None,
+    *,
+    fallback: Optional[Any] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Catch render errors in *child* and display *fallback* instead.
+
+    *fallback* may be an ``Element`` or a callable that receives the
+    exception and returns an ``Element``::
+
+        pn.ErrorBoundary(
+            MyRiskyComponent(),
+            fallback=lambda err: pn.Text(f"Error: {err}"),
+        )
+    """
+    props: Dict[str, Any] = {}
+    if fallback is not None:
+        props["__fallback__"] = fallback
+    children = [child] if child is not None else []
+    return Element("__ErrorBoundary__", props, children, key=key)
+
+
 def FlatList(
     *,
     data: Optional[List[Any]] = None,

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