pythonnative 0.12.0__tar.gz → 0.13.0__tar.gz

{pythonnative-0.12.0/src/pythonnative.egg-info → pythonnative-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.12.0
+Version: 0.13.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -101,7 +101,8 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation.
 - **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
-- **Navigation:** Push and pop screens with argument passing via the `use_navigation()` hook.
+- **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect.
+- **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
 - **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
 
 ## Quick Start
@@ -119,7 +120,7 @@ import pythonnative as pn
 
 
 @pn.component
-def MainPage():
+def App():
     count, set_count = pn.use_state(0)
     return pn.Column(
         pn.Text(f"Count: {count}", style={"font_size": 24}),

{pythonnative-0.12.0 → pythonnative-0.13.0}/README.md

@@ -37,7 +37,8 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation.
 - **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
-- **Navigation:** Push and pop screens with argument passing via the `use_navigation()` hook.
+- **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect.
+- **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
 - **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
 
 ## Quick Start
@@ -55,7 +56,7 @@ import pythonnative as pn
 
 
 @pn.component
-def MainPage():
+def App():
     count, set_count = pn.use_state(0)
     return pn.Column(
         pn.Text(f"Count: {count}", style={"font_size": 24}),

{pythonnative-0.12.0 → pythonnative-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.12.0"
+version = "0.13.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -61,6 +61,7 @@ Issues = "https://github.com/pythonnative/pythonnative/issues"
 Documentation = "https://docs.pythonnative.com/"
 
 
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

{pythonnative-0.12.0 → pythonnative-0.13.0}/src/pythonnative/__init__.py

@@ -41,7 +41,7 @@ Example:
     ```
 """
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
 
 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-0.12.0 → pythonnative-0.13.0}/src/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-0.12.0 → pythonnative-0.13.0}/src/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-0.12.0 → pythonnative-0.13.0}/src/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:
@@ -191,7 +205,7 @@ class ModuleReloader:
         """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
@@ -250,7 +264,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 +287,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 +468,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 +491,5 @@ 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])
+        ModuleReloader.reload_screen(screen_instance, [str(module) for module in modules])
         return version