pythonnative 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

pythonnative/page.py

@@ -1,32 +1,29 @@
-"""
-Your current approach, which involves creating an Android Activity in Kotlin
-and then passing it to Python, is necessary due to the restrictions inherent
-in Android's lifecycle. You are correctly following the Android way of managing
-Activities. In Android, the system is in control of when and how Activities are
-created and destroyed. It is not possible to directly create an instance of an
-Activity from Python because that would bypass Android's lifecycle management,
-leading to unpredictable results.
-
-Your Button example works because Button is a View, not an Activity. View
-instances in Android can be created and managed directly by your code. This is
-why you are able to create an instance of Button from Python.
-
-Remember that Activities in Android are not just containers for your UI like a
-ViewGroup, they are also the main entry points into your app and are closely
-tied to the app's lifecycle. Therefore, Android needs to maintain tight control
-over them. Activities aren't something you instantiate whenever you need them;
-they are created in response to a specific intent and their lifecycle is
-managed by Android.
-
-So, to answer your question: Yes, you need to follow this approach for
-Activities in Android. You cannot instantiate an Activity from Python like you
-do for Views.
-
-On the other hand, for iOS, you can instantiate a UIViewController directly
-from Python. The example code you provided for this is correct.
-
-Just ensure that your PythonNative UI framework is aware of these platform
-differences and handles them appropriately.
+"""Page — the root component that bridges native lifecycle and declarative UI.
+
+A ``Page`` subclass is the entry point for each screen.  It owns a
+:class:`~pythonnative.reconciler.Reconciler` and automatically mounts /
+re-renders the element tree returned by :meth:`render` whenever state
+changes.
+
+Usage::
+
+    import pythonnative as pn
+
+    class MainPage(pn.Page):
+        def __init__(self, native_instance):
+            super().__init__(native_instance)
+            self.state = {"count": 0}
+
+        def increment(self):
+            self.set_state(count=self.state["count"] + 1)
+
+        def render(self):
+            return pn.Column(
+                pn.Text(f"Count: {self.state['count']}", font_size=24),
+                pn.Button("Increment", on_click=self.increment),
+                spacing=12,
+                padding=16,
+            )
 """
 
 import json
@@ -34,55 +31,50 @@ from abc import ABC, abstractmethod
 from typing import Any, Optional, Union
 
 from .utils import IS_ANDROID, set_android_context
-from .view import ViewBase
 
-# ========================================
-# Base class
-# ========================================
+# ======================================================================
+# Base class (platform-independent)
+# ======================================================================
 
 
 class PageBase(ABC):
+    """Abstract base defining the Page interface."""
+
     @abstractmethod
     def __init__(self) -> None:
         super().__init__()
 
     @abstractmethod
-    def set_root_view(self, view) -> None:
-        pass
+    def render(self) -> Any:
+        """Return an Element tree describing this page's UI."""
+
+    def set_state(self, **updates: Any) -> None:
+        """Merge *updates* into ``self.state`` and trigger a re-render."""
 
-    @abstractmethod
     def on_create(self) -> None:
-        pass
+        """Called when the page is first created. Triggers initial render."""
 
-    @abstractmethod
     def on_start(self) -> None:
         pass
 
-    @abstractmethod
     def on_resume(self) -> None:
         pass
 
-    @abstractmethod
     def on_pause(self) -> None:
         pass
 
-    @abstractmethod
     def on_stop(self) -> None:
         pass
 
-    @abstractmethod
     def on_destroy(self) -> None:
         pass
 
-    @abstractmethod
     def on_restart(self) -> None:
         pass
 
-    @abstractmethod
     def on_save_instance_state(self) -> None:
         pass
 
-    @abstractmethod
     def on_restore_instance_state(self) -> None:
         pass
 
@@ -99,141 +91,182 @@ class PageBase(ABC):
         pass
 
     def get_args(self) -> dict:
-        """Return arguments provided to this Page (empty dict if none)."""
-        # Concrete classes should set self._args; default empty
+        """Return navigation arguments (empty dict if none)."""
         return getattr(self, "_args", {})
 
-    # Back-compat: navigate_to delegates to push
-    def navigate_to(self, page) -> None:
+    def navigate_to(self, page: Any) -> None:
         self.push(page)
-        pass
 
 
-if IS_ANDROID:
-    # ========================================
-    # Android class
-    # https://developer.android.com/reference/android/app/Activity
-    # ========================================
+# ======================================================================
+# Shared declarative rendering helpers
+# ======================================================================
+
+
+def _init_page_common(page: Any) -> None:
+    """Common initialisation shared by both platform Page classes."""
+    page.state = {}
+    page._args = {}
+    page._reconciler = None
+    page._root_native_view = None
+
+
+def _set_state(page: Any, **updates: Any) -> None:
+    page.state.update(updates)
+    if page._reconciler is not None:
+        _re_render(page)
+
+
+def _on_create(page: Any) -> None:
+    from .native_views import get_registry
+    from .reconciler import Reconciler
+
+    page._reconciler = Reconciler(get_registry())
+    element = page.render()
+    page._root_native_view = page._reconciler.mount(element)
+    page._attach_root(page._root_native_view)
+
+
+def _re_render(page: Any) -> None:
+    element = page.render()
+    new_root = page._reconciler.reconcile(element)
+    if new_root is not page._root_native_view:
+        page._detach_root(page._root_native_view)
+        page._root_native_view = new_root
+        page._attach_root(new_root)
+
 
+def _resolve_page_path(page_ref: Union[str, Any]) -> str:
+    if isinstance(page_ref, str):
+        return page_ref
+    module = getattr(page_ref, "__module__", None)
+    name = getattr(page_ref, "__name__", None)
+    if module and name:
+        return f"{module}.{name}"
+    cls = page_ref.__class__
+    return f"{cls.__module__}.{cls.__name__}"
+
+
+def _set_args(page: Any, args: Optional[dict]) -> None:
+    if isinstance(args, str):
+        try:
+            page._args = json.loads(args) or {}
+        except Exception:
+            page._args = {}
+        return
+    page._args = args or {}
+
+
+# ======================================================================
+# Platform implementations
+# ======================================================================
+
+if IS_ANDROID:
     from java import jclass
 
-    class Page(PageBase, ViewBase):
-        def __init__(self, native_instance) -> None:
+    class Page(PageBase):
+        """Android Page backed by an Activity and Fragment navigation."""
+
+        def __init__(self, native_instance: Any) -> None:
             super().__init__()
             self.native_class = jclass("android.app.Activity")
             self.native_instance = native_instance
-            # self.native_instance = self.native_class()
-            # Stash the Activity so child views can implicitly acquire a Context
             set_android_context(native_instance)
-            self._args: dict = {}
+            _init_page_common(self)
 
-        def set_root_view(self, view) -> None:
-            # In fragment-based navigation, attach child view to the current fragment container.
-            try:
-                from .utils import get_android_fragment_container
+        def render(self) -> Any:
+            raise NotImplementedError("Page subclass must implement render()")
 
-                container = get_android_fragment_container()
-                # Remove previous children if any, then add the new root
-                try:
-                    container.removeAllViews()
-                except Exception:
-                    pass
-                container.addView(view.native_instance)
-            except Exception:
-                # Fallback to setting content view directly on the Activity
-                self.native_instance.setContentView(view.native_instance)
+        def set_state(self, **updates: Any) -> None:
+            _set_state(self, **updates)
 
         def on_create(self) -> None:
-            print("Android on_create() called")
+            _on_create(self)
 
         def on_start(self) -> None:
-            print("Android on_start() called")
+            pass
 
         def on_resume(self) -> None:
-            print("Android on_resume() called")
+            pass
 
         def on_pause(self) -> None:
-            print("Android on_pause() called")
+            pass
 
         def on_stop(self) -> None:
-            print("Android on_stop() called")
+            pass
 
         def on_destroy(self) -> None:
-            print("Android on_destroy() called")
+            pass
 
         def on_restart(self) -> None:
-            print("Android on_restart() called")
+            pass
 
         def on_save_instance_state(self) -> None:
-            print("Android on_save_instance_state() called")
+            pass
 
         def on_restore_instance_state(self) -> None:
-            print("Android on_restore_instance_state() called")
+            pass
 
         def set_args(self, args: Optional[dict]) -> None:
-            # Accept dict or JSON string for convenience when crossing language boundaries
-            if isinstance(args, str):
-                try:
-                    self._args = json.loads(args) or {}
-                    return
-                except Exception:
-                    self._args = {}
-                    return
-            self._args = args or {}
-
-        def _resolve_page_path(self, page: Union[str, Any]) -> str:
-            if isinstance(page, str):
-                return page
-            # If a class or instance is passed, derive dotted path
-            try:
-                module = getattr(page, "__module__", None)
-                name = getattr(page, "__name__", None)
-                if module and name:
-                    return f"{module}.{name}"
-                # Instance: use its class
-                cls = page.__class__
-                return f"{cls.__module__}.{cls.__name__}"
-            except Exception:
-                raise ValueError("Unsupported page reference; expected dotted string or class/instance")
+            _set_args(self, args)
 
         def push(self, page: Union[str, Any], args: Optional[dict] = None) -> None:
-            # Delegate to Navigator.push to navigate to PageFragment with arguments
-            page_path = self._resolve_page_path(page)
-            try:
-                Navigator = jclass(f"{self.native_instance.getPackageName()}.Navigator")
-                args_json = json.dumps(args) if args else None
-                Navigator.push(self.native_instance, page_path, args_json)
-            except Exception:
-                # As a last resort, do nothing rather than crash
-                pass
+            page_path = _resolve_page_path(page)
+            Navigator = jclass(f"{self.native_instance.getPackageName()}.Navigator")
+            args_json = json.dumps(args) if args else None
+            Navigator.push(self.native_instance, page_path, args_json)
 
         def pop(self) -> None:
-            # Delegate to Navigator.pop for back-stack pop
             try:
                 Navigator = jclass(f"{self.native_instance.getPackageName()}.Navigator")
                 Navigator.pop(self.native_instance)
             except Exception:
+                self.native_instance.finish()
+
+        def _attach_root(self, native_view: Any) -> None:
+            try:
+                from .utils import get_android_fragment_container
+
+                container = get_android_fragment_container()
                 try:
-                    self.native_instance.finish()
+                    container.removeAllViews()
                 except Exception:
                     pass
+                LayoutParams = jclass("android.view.ViewGroup$LayoutParams")
+                lp = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
+                container.addView(native_view, lp)
+            except Exception:
+                self.native_instance.setContentView(native_view)
+
+        def _detach_root(self, native_view: Any) -> None:
+            try:
+                from .utils import get_android_fragment_container
+
+                container = get_android_fragment_container()
+                container.removeAllViews()
+            except Exception:
+                pass
 
 else:
-    # ========================================
-    # iOS class
-    # https://developer.apple.com/documentation/uikit/uiviewcontroller
-    # ========================================
+    from typing import Dict as _Dict
+
+    _rubicon_available = False
+    try:
+        from rubicon.objc import ObjCClass, ObjCInstance
 
-    from typing import Dict
+        _rubicon_available = True
 
-    from rubicon.objc import ObjCClass, ObjCInstance
+        import gc as _gc
 
-    # Global registry mapping native UIViewController pointer address to Page instances.
-    _IOS_PAGE_REGISTRY: Dict[int, Any] = {}
+        _gc.disable()
+    except ImportError:
+        pass
+
+    _IOS_PAGE_REGISTRY: _Dict[int, Any] = {}
 
     def _ios_register_page(vc_instance: Any, page_obj: Any) -> None:
         try:
-            ptr = int(vc_instance.ptr)  # rubicon ObjCInstance -> c_void_p convertible to int
+            ptr = int(vc_instance.ptr)
             _IOS_PAGE_REGISTRY[ptr] = page_obj
         except Exception:
             pass
@@ -246,151 +279,190 @@ else:
             pass
 
     def forward_lifecycle(native_addr: int, event: str) -> None:
-        """Forward a lifecycle event from Swift ViewController to the registered Page.
-
-        :param native_addr: Integer pointer address of the UIViewController
-        :param event: One of 'on_start', 'on_resume', 'on_pause', 'on_stop', 'on_destroy',
-            'on_save_instance_state', 'on_restore_instance_state'.
-        """
+        """Forward a lifecycle event from Swift ViewController to the registered Page."""
         page = _IOS_PAGE_REGISTRY.get(int(native_addr))
-        if not page:
+        if page is None:
             return
-        try:
-            handler = getattr(page, event, None)
-            if handler:
-                handler()
-        except Exception:
-            # Avoid surfacing exceptions across the Swift/Python boundary in lifecycle
-            pass
+        handler = getattr(page, event, None)
+        if handler:
+            handler()
 
-    class Page(PageBase, ViewBase):
-        def __init__(self, native_instance) -> None:
-            super().__init__()
-            self.native_class = ObjCClass("UIViewController")
-            # If Swift passed us an integer pointer, wrap it as an ObjCInstance.
-            if isinstance(native_instance, int):
-                try:
-                    native_instance = ObjCInstance(native_instance)
-                except Exception:
-                    native_instance = None
-            self.native_instance = native_instance
-            # self.native_instance = self.native_class.alloc().init()
-            self._args: dict = {}
-            # Register for lifecycle forwarding
-            if self.native_instance is not None:
-                _ios_register_page(self.native_instance, self)
-
-        def set_root_view(self, view) -> None:
-            # UIViewController.view is a property; access without calling.
-            root_view = self.native_instance.view
-            # Size the root child to fill the controller's view and enable autoresizing
-            try:
-                bounds = root_view.bounds
-                view.native_instance.setFrame_(bounds)
-                # UIViewAutoresizingFlexibleWidth (2) | UIViewAutoresizingFlexibleHeight (16)
-                view.native_instance.setAutoresizingMask_(2 | 16)
-            except Exception:
-                pass
-            root_view.addSubview_(view.native_instance)
+    if _rubicon_available:
 
-        def on_create(self) -> None:
-            print("iOS on_create() called")
+        class Page(PageBase):
+            """iOS Page backed by a UIViewController."""
 
-        def on_start(self) -> None:
-            print("iOS on_start() called")
+            def __init__(self, native_instance: Any) -> None:
+                super().__init__()
+                self.native_class = ObjCClass("UIViewController")
+                if isinstance(native_instance, int):
+                    try:
+                        native_instance = ObjCInstance(native_instance)
+                    except Exception:
+                        native_instance = None
+                self.native_instance = native_instance
+                _init_page_common(self)
+                if self.native_instance is not None:
+                    _ios_register_page(self.native_instance, self)
 
-        def on_resume(self) -> None:
-            print("iOS on_resume() called")
+            def render(self) -> Any:
+                raise NotImplementedError("Page subclass must implement render()")
 
-        def on_pause(self) -> None:
-            print("iOS on_pause() called")
+            def set_state(self, **updates: Any) -> None:
+                _set_state(self, **updates)
 
-        def on_stop(self) -> None:
-            print("iOS on_stop() called")
+            def on_create(self) -> None:
+                _on_create(self)
 
-        def on_destroy(self) -> None:
-            print("iOS on_destroy() called")
-            if self.native_instance is not None:
-                _ios_unregister_page(self.native_instance)
+            def on_start(self) -> None:
+                pass
 
-        def on_restart(self) -> None:
-            print("iOS on_restart() called")
+            def on_resume(self) -> None:
+                pass
 
-        def on_save_instance_state(self) -> None:
-            print("iOS on_save_instance_state() called")
+            def on_pause(self) -> None:
+                pass
 
-        def on_restore_instance_state(self) -> None:
-            print("iOS on_restore_instance_state() called")
+            def on_stop(self) -> None:
+                pass
 
-        def set_args(self, args: Optional[dict]) -> None:
-            if isinstance(args, str):
-                try:
-                    self._args = json.loads(args) or {}
-                    return
-                except Exception:
-                    self._args = {}
-                    return
-            self._args = args or {}
+            def on_destroy(self) -> None:
+                if self.native_instance is not None:
+                    _ios_unregister_page(self.native_instance)
 
-        def _resolve_page_path(self, page: Union[str, Any]) -> str:
-            if isinstance(page, str):
-                return page
-            try:
-                module = getattr(page, "__module__", None)
-                name = getattr(page, "__name__", None)
-                if module and name:
-                    return f"{module}.{name}"
-                cls = page.__class__
-                return f"{cls.__module__}.{cls.__name__}"
-            except Exception:
-                raise ValueError("Unsupported page reference; expected dotted string or class/instance")
+            def on_restart(self) -> None:
+                pass
 
-        def push(self, page: Union[str, Any], args: Optional[dict] = None) -> None:
-            page_path = self._resolve_page_path(page)
-            # Resolve the Swift ViewController class. Swift classes are namespaced by
-            # the module name (CFBundleName). Try plain name first, then Module.Name.
-            ViewController = None
-            try:
-                ViewController = ObjCClass("ViewController")
-            except Exception:
+            def on_save_instance_state(self) -> None:
+                pass
+
+            def on_restore_instance_state(self) -> None:
+                pass
+
+            def set_args(self, args: Optional[dict]) -> None:
+                _set_args(self, args)
+
+            def push(self, page: Union[str, Any], args: Optional[dict] = None) -> None:
+                page_path = _resolve_page_path(page)
+                ViewController = None
                 try:
-                    NSBundle = ObjCClass("NSBundle")
-                    bundle = NSBundle.mainBundle
-                    module_name = None
+                    ViewController = ObjCClass("ViewController")
+                except Exception:
                     try:
-                        # Prefer CFBundleName; fallback to CFBundleExecutable
+                        NSBundle = ObjCClass("NSBundle")
+                        bundle = NSBundle.mainBundle
                         module_name = bundle.objectForInfoDictionaryKey_("CFBundleName")
                         if module_name is None:
                             module_name = bundle.objectForInfoDictionaryKey_("CFBundleExecutable")
+                        if module_name:
+                            ViewController = ObjCClass(f"{module_name}.ViewController")
                     except Exception:
-                        module_name = None
-                    if module_name:
-                        ViewController = ObjCClass(f"{module_name}.ViewController")
+                        pass
+
+                if ViewController is None:
+                    raise NameError("ViewController class not found; ensure Swift class is ObjC-visible")
+
+                next_vc = ViewController.alloc().init()
+                try:
+                    next_vc.setValue_forKey_(page_path, "requestedPagePath")
+                    if args:
+                        next_vc.setValue_forKey_(json.dumps(args), "requestedPageArgsJSON")
+                except Exception:
+                    pass
+                nav = getattr(self.native_instance, "navigationController", None)
+                if nav is None:
+                    raise RuntimeError(
+                        "No UINavigationController available; ensure template embeds root in navigation controller"
+                    )
+                nav.pushViewController_animated_(next_vc, True)
+
+            def pop(self) -> None:
+                nav = getattr(self.native_instance, "navigationController", None)
+                if nav is not None:
+                    nav.popViewControllerAnimated_(True)
+
+            def _attach_root(self, native_view: Any) -> None:
+                root_view = self.native_instance.view
+                native_view.setTranslatesAutoresizingMaskIntoConstraints_(False)
+                root_view.addSubview_(native_view)
+                try:
+                    safe = root_view.safeAreaLayoutGuide
+                    native_view.topAnchor.constraintEqualToAnchor_(safe.topAnchor).setActive_(True)
+                    native_view.bottomAnchor.constraintEqualToAnchor_(safe.bottomAnchor).setActive_(True)
+                    native_view.leadingAnchor.constraintEqualToAnchor_(safe.leadingAnchor).setActive_(True)
+                    native_view.trailingAnchor.constraintEqualToAnchor_(safe.trailingAnchor).setActive_(True)
                 except Exception:
-                    ViewController = None
+                    native_view.setTranslatesAutoresizingMaskIntoConstraints_(True)
+                    try:
+                        native_view.setFrame_(root_view.bounds)
+                        native_view.setAutoresizingMask_(2 | 16)
+                    except Exception:
+                        pass
 
-            if ViewController is None:
-                raise NameError("ViewController class not found; ensure Swift class is ObjC-visible")
+            def _detach_root(self, native_view: Any) -> None:
+                try:
+                    native_view.removeFromSuperview()
+                except Exception:
+                    pass
 
-            next_vc = ViewController.alloc().init()
-            try:
-                # Use KVC to pass metadata to Swift
-                next_vc.setValue_forKey_(page_path, "requestedPagePath")
-                if args:
-                    next_vc.setValue_forKey_(json.dumps(args), "requestedPageArgsJSON")
-            except Exception:
+    else:
+
+        class Page(PageBase):
+            """Desktop stub — no native runtime available.
+
+            Fully functional for testing with a mock backend via
+            ``native_views.set_registry()``.
+            """
+
+            def __init__(self, native_instance: Any = None) -> None:
+                super().__init__()
+                self.native_instance = native_instance
+                _init_page_common(self)
+
+            def render(self) -> Any:
+                raise NotImplementedError("Page subclass must implement render()")
+
+            def set_state(self, **updates: Any) -> None:
+                _set_state(self, **updates)
+
+            def on_create(self) -> None:
+                _on_create(self)
+
+            def on_start(self) -> None:
                 pass
-            # On iOS, `navigationController` is exposed as a property; treat it as such.
-            nav = getattr(self.native_instance, "navigationController", None)
-            if nav is None:
-                # If no navigation controller, this push will be a no-op; rely on template to embed one.
-                raise RuntimeError(
-                    "No UINavigationController available; ensure template embeds root in navigation controller"
-                )
-            # Method name maps from pushViewController:animated:
-            nav.pushViewController_animated_(next_vc, True)
 
-        def pop(self) -> None:
-            nav = getattr(self.native_instance, "navigationController", None)
-            if nav is not None:
-                nav.popViewControllerAnimated_(True)
+            def on_resume(self) -> None:
+                pass
+
+            def on_pause(self) -> None:
+                pass
+
+            def on_stop(self) -> None:
+                pass
+
+            def on_destroy(self) -> None:
+                pass
+
+            def on_restart(self) -> None:
+                pass
+
+            def on_save_instance_state(self) -> None:
+                pass
+
+            def on_restore_instance_state(self) -> None:
+                pass
+
+            def set_args(self, args: Optional[dict]) -> None:
+                _set_args(self, args)
+
+            def push(self, page: Union[str, Any], args: Optional[dict] = None) -> None:
+                raise RuntimeError("push() requires a native runtime (iOS or Android)")
+
+            def pop(self) -> None:
+                raise RuntimeError("pop() requires a native runtime (iOS or Android)")
+
+            def _attach_root(self, native_view: Any) -> None:
+                pass
+
+            def _detach_root(self, native_view: Any) -> None:
+                pass