pythonnative 0.12.0__py3-none-any.whl → 0.13.1__py3-none-any.whl

pythonnative/__init__.py

@@ -41,7 +41,7 @@ Example:
     ```
 """
 
-__version__ = "0.12.0"
+__version__ = "0.13.1"
 
 from .alerts import Alert
 from .animated import Animated, AnimatedValue
@@ -98,8 +98,8 @@ from .navigation import (
     use_focus_effect,
     use_route,
 )
-from .page import create_page
 from .platform import Platform
+from .screen import create_screen
 from .style import StyleSheet, ThemeContext
 
 __all__ = [
@@ -130,7 +130,7 @@ __all__ = [
     "WebView",
     # Core
     "Element",
-    "create_page",
+    "create_screen",
     # Hooks
     "batch_updates",
     "component",

pythonnative/cli/pn.py

@@ -32,9 +32,9 @@ from typing import Any, Dict, List, Optional
 def init_project(args: argparse.Namespace) -> None:
     """Scaffold a new PythonNative project in the current directory.
 
-    Creates `app/main_page.py`, `pythonnative.json`,
-    `requirements.txt`, and `.gitignore`. Refuses to overwrite
-    existing files unless `--force` is passed.
+    Creates `app/main.py`, `pythonnative.json`, `requirements.txt`,
+    and `.gitignore`. Refuses to overwrite existing files unless
+    `--force` is passed.
 
     Args:
         args: The parsed argparse namespace. Recognized attributes:
@@ -68,30 +68,55 @@ def init_project(args: argparse.Namespace) -> None:
 
     os.makedirs(app_dir, exist_ok=True)
 
-    main_page_py = os.path.join(app_dir, "main_page.py")
-    if not os.path.exists(main_page_py) or args.force:
-        with open(main_page_py, "w", encoding="utf-8") as f:
+    main_py = os.path.join(app_dir, "main.py")
+    if not os.path.exists(main_py) or args.force:
+        with open(main_py, "w", encoding="utf-8") as f:
             f.write("""import pythonnative as pn
 
+Stack = pn.create_stack_navigator()
+
 
 @pn.component
-def MainPage():
+def HomeScreen():
     count, set_count = pn.use_state(0)
+    nav = pn.use_navigation()
     return pn.ScrollView(
         pn.Column(
             pn.Text("Hello from PythonNative!", style={"font_size": 24, "bold": True}),
             pn.Text(f"Tapped {count} times"),
             pn.Button("Tap me", on_click=lambda: set_count(count + 1)),
+            pn.Button("Open detail", on_click=lambda: nav.navigate("Detail", {"count": count})),
             style={"spacing": 12, "padding": 16, "align_items": "stretch"},
         )
     )
+
+
+@pn.component
+def DetailScreen():
+    nav = pn.use_navigation()
+    params = pn.use_route()
+    return pn.Column(
+        pn.Text(f"Detail: count was {params.get('count', 0)}", style={"font_size": 20}),
+        pn.Button("Back", on_click=nav.go_back),
+        style={"spacing": 12, "padding": 16},
+    )
+
+
+@pn.component
+def App():
+    return pn.NavigationContainer(
+        Stack.Navigator(
+            Stack.Screen("Home", component=HomeScreen, options={"title": "Home"}),
+            Stack.Screen("Detail", component=DetailScreen, options={"title": "Detail"}),
+        )
+    )
 """)
 
     # Create config
     config = {
         "name": project_name,
         "appId": "com.example." + project_name.replace(" ", "").lower(),
-        "entryPoint": "app/main_page.py",
+        "entryPoint": "app/main.py",
         "pythonVersion": "3.11",
         "ios": {},
         "android": {},
@@ -319,7 +344,7 @@ ANDROID_LOGCAT_FILTERS: list[str] = [
     "python.stdout:V",
     "python.stderr:V",
     "MainActivity:V",
-    "PageFragment:V",
+    "ScreenFragment:V",
     "Navigator:V",
     "PythonNative:V",
     "AndroidRuntime:E",

pythonnative/hooks.py

@@ -511,13 +511,13 @@ def use_window_dimensions() -> Dict[str, float]:
     """Return the current viewport size and re-render when it changes.
 
     Equivalent to React Native's ``useWindowDimensions``. The values
-    are pushed by the page host whenever the platform reports a new
+    are pushed by the screen host whenever the platform reports a new
     size (initial layout, rotation, multitasking split-view).
 
     Returns:
         A dict with ``"width"`` and ``"height"`` floats in layout
         units (pt on iOS, dp on Android). Both are ``0.0`` until the
-        page host has run its first layout pass.
+        screen host has run its first layout pass.
 
     Raises:
         RuntimeError: If called outside a `@component` function.
@@ -717,8 +717,13 @@ _NavigationContext: Context = create_context(None)
 class NavigationHandle:
     """Handle returned by [`use_navigation`][pythonnative.use_navigation].
 
-    Wraps the host's push/pop primitives so screens can navigate without
-    knowing the underlying native navigation stack.
+    Wraps the host's push/pop primitives so screens can navigate
+    without knowing the underlying native navigation stack. The
+    typical user-facing surface is the declarative handle returned by
+    a [`Stack`][pythonnative.create_stack_navigator] — this class is
+    the lower-level fallback used when no navigator is rendered (and
+    as the bridge that declarative navigators delegate to when they
+    need to push real native screens).
 
     Example:
         ```python
@@ -729,7 +734,7 @@ class NavigationHandle:
             nav = pn.use_navigation()
             return pn.Button(
                 "Open Detail",
-                on_click=lambda: nav.navigate(DetailScreen, params={"id": 42}),
+                on_click=lambda: nav.navigate("Detail", {"id": 42}),
             )
         ```
     """
@@ -737,16 +742,20 @@ class NavigationHandle:
     def __init__(self, host: Any) -> None:
         self._host = host
 
-    def navigate(self, page: Any, params: Optional[Dict[str, Any]] = None) -> None:
-        """Push `page` onto the navigation stack.
+    def navigate(self, component: Any, params: Optional[Dict[str, Any]] = None) -> None:
+        """Push ``component`` onto the navigation stack.
 
         Args:
-            page: Either a `@component` function or a dotted Python
-                path (e.g., `"app.detail.DetailScreen"`).
+            component: A ``@component`` function or a dotted Python
+                path (e.g. ``"app.detail.DetailScreen"``). When a
+                Stack navigator is the root of the app, prefer the
+                declarative ``nav.navigate("Detail", params)`` form
+                returned by ``use_navigation()`` (it pushes by route
+                name and the host re-uses its own ``App`` component).
             params: Optional dict of arguments serialized into the
                 target screen.
         """
-        self._host._push(page, params)
+        self._host._push(component, params)
 
     def go_back(self) -> None:
         """Pop the current screen and return to the previous one."""
@@ -771,13 +780,13 @@ def use_navigation() -> NavigationHandle:
 
     Raises:
         RuntimeError: If called outside a component rendered via
-            [`create_page`][pythonnative.create_page].
+            [`create_screen`][pythonnative.create_screen].
     """
     handle = use_context(_NavigationContext)
     if handle is None:
         raise RuntimeError(
-            "use_navigation() called outside a PythonNative page. "
-            "Ensure your component is rendered via create_page()."
+            "use_navigation() called outside a PythonNative screen. "
+            "Ensure your component is rendered via create_screen()."
         )
     return handle
 

pythonnative/hot_reload.py

@@ -3,16 +3,30 @@
 Two cooperating pieces:
 
 - **Host-side**: [`FileWatcher`][pythonnative.hot_reload.FileWatcher]
-  polls the developer's `app/` directory for `.py` changes and
-  triggers a callback (typically `adb push` on Android or a
-  `simctl` file copy on iOS).
+  polls the developer's ``app/`` directory for ``.py`` changes and
+  triggers a callback (typically ``adb push`` on Android or a
+  ``simctl`` file copy on iOS).
 - **Device-side**:
   [`ModuleReloader`][pythonnative.hot_reload.ModuleReloader] reloads
-  changed Python modules using `importlib.reload` and asks the page
-  host to re-render the current tree.
+  changed Python modules using ``importlib`` and asks the screen
+  host to re-render its current tree.
+
+Two strategies share the device-side surface:
+
+- **Fast Refresh** (default): after reloading the changed modules
+  the reconciler tree is walked and every component function whose
+  module was reloaded is swapped in place. Hook state, navigation
+  state, and even scroll positions survive because the underlying
+  ``VNode`` objects are reused — the next render simply calls the
+  new function bodies through the old slots.
+- **Full remount**: when the in-place swap fails (e.g. the new
+  module raised at import time, or a render exception bubbled out
+  while running the new function), the host falls back to building
+  a brand-new reconciler tree. State is lost but the app keeps
+  running.
 
 Example:
-    Integrated into `pn run --hot-reload`:
+    Integrated into ``pn run --hot-reload``:
 
     ```python
     from pythonnative.hot_reload import FileWatcher
@@ -33,7 +47,7 @@ import os
 import sys
 import threading
 import time
-from typing import Any, Callable, Dict, List, Optional, Sequence
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Set
 
 DEV_ROOT_DIR = "pythonnative_dev"
 """Name of the writable on-device directory that shadows bundled app code."""
@@ -46,7 +60,7 @@ def configure_dev_environment(writable_root: str) -> str:
     """Create and prioritize the writable hot-reload source overlay.
 
     The returned directory is inserted at the front of `sys.path`, so a
-    pushed `app/main_page.py` shadows the copy bundled into the native
+    pushed `app/main.py` shadows the copy bundled into the native
     application. Templates call this before importing user code.
 
     Args:
@@ -182,16 +196,25 @@ class ModuleReloader:
     """Reload changed Python modules on device and trigger a re-render.
 
     Designed to be invoked from device-side glue when a hot-reload
-    push completes. The class itself holds no state; all methods are
-    static.
+    push completes. All public methods are static; the class holds a
+    single piece of process-wide state — the manifest version that
+    has most recently been applied to ``sys.modules`` — so that
+    multiple screen hosts polling the same manifest do not each
+    re-execute the user-app modules. The first host to see a new
+    version pays the ``reload_modules`` cost; subsequent hosts on the
+    same version refresh only their own reconciler tree against the
+    already-fresh modules.
     """
 
+    _last_reloaded_version: Optional[str] = None
+    _reload_lock = threading.Lock()
+
     @staticmethod
     def reload_module(module_name: str) -> bool:
         """Reload a single module by its dotted name.
 
         Args:
-            module_name: Dotted module name (e.g., `"app.main_page"`).
+            module_name: Dotted module name (e.g., `"app.main"`).
 
         Returns:
             `True` if the module imported successfully from the current
@@ -240,6 +263,139 @@ class ModuleReloader:
                 reloaded.append(module_name)
         return reloaded
 
+    @staticmethod
+    def reload_modules_for_version(
+        module_names: Sequence[str],
+        version: Optional[str],
+    ) -> List[str]:
+        """Reload ``module_names`` for ``version``, deduping across hosts.
+
+        Each native screen host on iOS / Android runs its own poll
+        loop and would otherwise call
+        [`reload_modules`][pythonnative.hot_reload.ModuleReloader.reload_modules]
+        independently for the same manifest version. That re-executes
+        every user-app module N times (once per host) per file change,
+        producing N different generations of the same function objects
+        in ``sys.modules`` and leaving each host's reconciler tree
+        pointing at a different generation. Beyond the wasted work,
+        the inconsistent state has been observed to crash UIKit on iOS
+        with ``CALayerInvalidGeometry`` (NaN values fed into ``setFrame_:``
+        during the interleaved renders).
+
+        This helper serializes on
+        [`_reload_lock`][pythonnative.hot_reload.ModuleReloader] and uses
+        [`_last_reloaded_version`][pythonnative.hot_reload.ModuleReloader]
+        to ensure only the *first* host to see a given ``version``
+        actually re-executes the modules. Subsequent hosts on the same
+        version get back the already-fresh entries from ``sys.modules``
+        so their own
+        [`refresh_in_place`][pythonnative.hot_reload.ModuleReloader.refresh_in_place]
+        pass can still rewrite their tree against the same generation.
+
+        Args:
+            module_names: Dotted module names to reload.
+            version: Manifest version this reload is processing. When
+                ``None`` (e.g. tests calling reload directly) the call
+                falls back to the unconditional
+                [`reload_modules`][pythonnative.hot_reload.ModuleReloader.reload_modules]
+                behavior.
+
+        Returns:
+            The list of module names that are currently fresh in
+            ``sys.modules`` — either freshly reloaded by this call, or
+            already reloaded by an earlier host for the same version.
+        """
+        with ModuleReloader._reload_lock:
+            if version is not None and version == ModuleReloader._last_reloaded_version:
+                return [name for name in module_names if name in sys.modules]
+            reloaded = ModuleReloader.reload_modules(module_names)
+            if reloaded and version is not None:
+                ModuleReloader._last_reloaded_version = version
+            return reloaded
+
+    @staticmethod
+    def expand_reload_targets(changed_modules: Sequence[str], component_path: str) -> List[str]:
+        """Expand a manifest of changed modules into the full reload order.
+
+        When a user edits ``app/screens/home.py``, only that file is in
+        the manifest. But the entry-point module ``app.main`` has
+        bindings like ``from app.screens.home import HomeScreen`` that
+        need to be re-evaluated against the freshly-loaded
+        ``app.screens.home``; likewise other user-app modules may carry
+        transitive bindings (e.g. through a shared ``app/theme.py``)
+        that go stale if only the changed file is reloaded.
+
+        This helper computes the full ordered reload list:
+
+        1. Explicitly changed modules first (in the order given), so
+           their fresh source replaces the cached version in
+           ``sys.modules`` before any dependent modules re-execute.
+        2. All other currently-imported modules under the entry-point's
+           top-level package, deepest first. The depth heuristic biases
+           toward leaves so re-executing a screen file picks up the
+           newest shared utilities before the file that imports it does.
+        3. The entry-point module itself, last, so its
+           ``from ... import`` bindings rebind against everything that
+           was refreshed in steps 1 and 2.
+
+        Modules outside the entry-point's top-level package
+        (``pythonnative.*``, stdlib, third-party) are never included;
+        framework code is not reloaded.
+
+        Args:
+            changed_modules: Modules reported as changed by the host
+                file-watcher (already in dotted form).
+            component_path: The host's entry-point identifier, either a
+                module path (``"app.main"``) or a dotted attribute path
+                (``"app.main.RootScreen"``).
+
+        Returns:
+            The ordered list of modules to feed to
+            [`reload_modules`][pythonnative.hot_reload.ModuleReloader.reload_modules].
+        """
+        entry_module: Optional[str] = None
+        if component_path in sys.modules:
+            entry_module = component_path
+        elif "." in component_path:
+            parent = component_path.rsplit(".", 1)[0]
+            if parent in sys.modules:
+                entry_module = parent
+
+        app_prefix: Optional[str] = None
+        if entry_module:
+            app_prefix = entry_module.split(".")[0]
+        else:
+            for m in changed_modules:
+                if m:
+                    app_prefix = m.split(".")[0]
+                    break
+
+        app_modules: Set[str] = set()
+        if app_prefix:
+            for name in list(sys.modules):
+                if name == app_prefix or name.startswith(app_prefix + "."):
+                    app_modules.add(name)
+
+        ordered: List[str] = []
+        seen: Set[str] = set()
+        for m in changed_modules:
+            if m and m not in seen:
+                ordered.append(m)
+                seen.add(m)
+
+        others = [m for m in app_modules if m not in seen and m != entry_module]
+        others.sort(key=lambda m: (-m.count("."), m))
+        for m in others:
+            ordered.append(m)
+            seen.add(m)
+
+        if entry_module:
+            if entry_module in seen:
+                ordered.remove(entry_module)
+            ordered.append(entry_module)
+
+        return ordered
+
     @staticmethod
     def file_to_module(file_path: str, base_dir: str = "") -> Optional[str]:
         """Convert a file path to a dotted module name.
@@ -250,7 +406,7 @@ class ModuleReloader:
                 If empty, `file_path` is treated as already relative.
 
         Returns:
-            The dotted module name (e.g., `"app.pages.home"`), or
+            The dotted module name (e.g., `"app.screens.home"`), or
             `None` for an empty path.
         """
         rel = os.path.relpath(file_path, base_dir) if base_dir else file_path
@@ -273,28 +429,180 @@ class ModuleReloader:
         return modules
 
     @staticmethod
-    def reload_page(page_instance: Any, module_names: Optional[Sequence[str]] = None) -> None:
-        """Force a page re-render after a module reload.
+    def reload_screen(screen_instance: Any, module_names: Optional[Sequence[str]] = None) -> None:
+        """Force a screen re-render after a module reload.
 
         Args:
-            page_instance: An `_AppHost` instance (or duck-typed
+            screen_instance: A `_ScreenHost` instance (or duck-typed
                 equivalent) that exposes a `_reconciler` attribute.
             module_names: Optional modules that changed. Reload-aware
-                page hosts use this to refresh imports before re-render.
+                screen hosts use this to refresh imports before re-render.
         """
-        reload_fn = getattr(page_instance, "reload", None)
+        reload_fn = getattr(screen_instance, "reload", None)
         if callable(reload_fn):
             reload_fn(list(module_names or []))
             return
 
-        from .page import _request_render
+        from .screen import _request_render
 
-        if hasattr(page_instance, "_reconciler") and page_instance._reconciler is not None:
-            _request_render(page_instance)
+        if hasattr(screen_instance, "_reconciler") and screen_instance._reconciler is not None:
+            _request_render(screen_instance)
+
+    @staticmethod
+    def find_replacement_function(old_fn: Any) -> Optional[Any]:
+        """Locate a function's post-reload counterpart by qualname.
+
+        Functions decorated with [`component`][pythonnative.component]
+        store the user's original function on the wrapper's
+        ``__wrapped__`` attribute and forward ``__module__`` /
+        ``__qualname__`` so that the reconciler's stored
+        ``element.type`` (the unwrapped function) still has the
+        information needed to re-resolve after a module reload.
+
+        Args:
+            old_fn: The function captured in an
+                [`Element`][pythonnative.Element]'s ``type`` slot.
+
+        Returns:
+            The reloaded module's matching function, ``None`` if no
+            replacement was found, or the original function itself
+            when the module has not been reloaded (so callers can
+            skip the swap).
+        """
+        module_name = getattr(old_fn, "__module__", None)
+        qualname = getattr(old_fn, "__qualname__", None) or getattr(old_fn, "__name__", None)
+        if not module_name or not qualname:
+            return None
+        if "<locals>" in qualname:
+            return None  # nested functions are not addressable from the module surface
+
+        module = sys.modules.get(module_name)
+        if module is None:
+            return None
+
+        obj: Any = module
+        for part in qualname.split("."):
+            obj = getattr(obj, part, None)
+            if obj is None:
+                return None
+
+        if getattr(obj, "_pn_component", False):
+            obj = getattr(obj, "__wrapped__", obj)
+
+        if obj is old_fn:
+            return None
+        return obj
+
+    @staticmethod
+    def build_replacement_map(reconciler: Any, reloaded_modules: Iterable[str]) -> Dict[Any, Any]:
+        """Compute ``{old_function: new_function}`` for one tree.
+
+        The reconciler's stored tree references the *pre-reload*
+        component functions through ``VNode.element.type``. This
+        method walks the tree, collects every callable type whose
+        ``__module__`` was just reloaded, and asks
+        [`find_replacement_function`][pythonnative.hot_reload.ModuleReloader.find_replacement_function]
+        for its successor.
+
+        Args:
+            reconciler: The reconciler whose
+                ``_tree`` should be inspected.
+            reloaded_modules: Set of module names that were just
+                reloaded (only callables from these modules are
+                considered).
+
+        Returns:
+            A mapping suitable for passing to
+            [`swap_components_in_tree`][pythonnative.hot_reload.ModuleReloader.swap_components_in_tree].
+        """
+        modules: Set[str] = {m for m in reloaded_modules if m}
+        if not modules or reconciler is None or getattr(reconciler, "_tree", None) is None:
+            return {}
+
+        seen: Set[int] = set()
+        mapping: Dict[Any, Any] = {}
+
+        def visit(vnode: Any) -> None:
+            if vnode is None:
+                return
+            elem = getattr(vnode, "element", None)
+            if elem is not None and callable(elem.type):
+                fn = elem.type
+                fn_id = id(fn)
+                if fn_id not in seen:
+                    seen.add(fn_id)
+                    if getattr(fn, "__module__", None) in modules:
+                        replacement = ModuleReloader.find_replacement_function(fn)
+                        if replacement is not None and replacement is not fn:
+                            mapping[fn] = replacement
+            for child in getattr(vnode, "children", []) or []:
+                visit(child)
+
+        visit(reconciler._tree)
+        return mapping
+
+    @staticmethod
+    def swap_components_in_tree(reconciler: Any, replacement_map: Dict[Any, Any]) -> int:
+        """Apply a ``{old: new}`` map to every node in the reconciler tree.
+
+        Mutates ``vnode.element.type`` directly so the NEXT diff sees
+        identical types and reuses VNodes (preserving hook state).
+        Pending ``Element`` trees stored on ``vnode._rendered`` are
+        rewritten too because the reconciler reads from them when
+        comparing keys across renders.
+
+        Returns:
+            The number of element type references that were rewritten.
+        """
+        if not replacement_map or reconciler is None or getattr(reconciler, "_tree", None) is None:
+            return 0
+
+        rewrites = 0
+
+        def rewrite_element_tree(element: Any) -> None:
+            nonlocal rewrites
+            if element is None:
+                return
+            new_type = replacement_map.get(element.type)
+            if new_type is not None:
+                element.type = new_type
+                rewrites += 1
+            for child in element.children or []:
+                rewrite_element_tree(child)
+
+        def visit(vnode: Any) -> None:
+            if vnode is None:
+                return
+            if getattr(vnode, "element", None) is not None:
+                rewrite_element_tree(vnode.element)
+            rendered = getattr(vnode, "_rendered", None)
+            if rendered is not None:
+                rewrite_element_tree(rendered)
+            for child in getattr(vnode, "children", []) or []:
+                visit(child)
+
+        visit(reconciler._tree)
+        return rewrites
+
+    @staticmethod
+    def refresh_in_place(reconciler: Any, reloaded_modules: Iterable[str]) -> bool:
+        """Try a state-preserving Fast Refresh for one reconciler.
+
+        Returns:
+            ``True`` if any component function was replaced (callers
+            should then trigger a re-render). ``False`` means the
+            tree already references the latest functions (or has no
+            nodes from the reloaded modules at all).
+        """
+        replacement_map = ModuleReloader.build_replacement_map(reconciler, reloaded_modules)
+        if not replacement_map:
+            return False
+        rewrites = ModuleReloader.swap_components_in_tree(reconciler, replacement_map)
+        return rewrites > 0
 
     @staticmethod
     def reload_from_manifest(
-        page_instance: Any,
+        screen_instance: Any,
         manifest_path: str,
         *,
         last_version: Optional[str] = None,
@@ -302,9 +610,9 @@ class ModuleReloader:
         """Apply a reload manifest if it is newer than `last_version`.
 
         Args:
-            page_instance: Page host to refresh.
+            screen_instance: Screen host to refresh.
             manifest_path: JSON manifest written by the CLI.
-            last_version: Version already applied by this page host.
+            last_version: Version already applied by this screen host.
 
         Returns:
             The manifest version after applying, or `last_version` when
@@ -325,5 +633,13 @@ class ModuleReloader:
             files = manifest.get("files", [])
             modules = ModuleReloader.modules_from_files(files if isinstance(files, list) else [])
 
-        ModuleReloader.reload_page(page_instance, [str(module) for module in modules])
+        # Stash the version on the host so `_reload_host` can dedupe
+        # `reload_modules` across multiple hosts polling the same
+        # manifest. See `reload_modules_for_version`.
+        previous_pending = getattr(screen_instance, "_hot_reload_pending_version", None)
+        try:
+            screen_instance._hot_reload_pending_version = version
+            ModuleReloader.reload_screen(screen_instance, [str(module) for module in modules])
+        finally:
+            screen_instance._hot_reload_pending_version = previous_pending
         return version