pythonnative 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

pythonnative/reconciler.py

@@ -0,0 +1,262 @@
+"""Virtual-tree reconciler.
+
+Maintains a tree of :class:`VNode` objects (each wrapping a native view)
+and diffs incoming :class:`Element` trees to apply the minimal set of
+native mutations.
+
+Supports:
+
+- **Native elements** (type is a string like ``"Text"``).
+- **Function components** (type is a callable decorated with
+  ``@component``).  Their hook state is preserved across renders.
+- **Provider elements** (type ``"__Provider__"``), which push/pop
+  context values during tree traversal.
+- **Key-based child reconciliation** for stable identity across
+  re-renders.
+"""
+
+from typing import Any, List, Optional
+
+from .element import Element
+
+
+class VNode:
+    """A mounted element paired with its native view and child VNodes."""
+
+    __slots__ = ("element", "native_view", "children", "hook_state", "_rendered")
+
+    def __init__(self, element: Element, native_view: Any, children: List["VNode"]) -> None:
+        self.element = element
+        self.native_view = native_view
+        self.children = children
+        self.hook_state: Any = None
+        self._rendered: Optional[Element] = None
+
+
+class Reconciler:
+    """Create, diff, and patch native view trees from Element descriptors.
+
+    Parameters
+    ----------
+    backend:
+        An object implementing the :class:`NativeViewRegistry` protocol
+        (``create_view``, ``update_view``, ``add_child``, ``remove_child``,
+        ``insert_child``).
+    """
+
+    def __init__(self, backend: Any) -> None:
+        self.backend = backend
+        self._tree: Optional[VNode] = None
+        self._page_re_render: Optional[Any] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def mount(self, element: Element) -> Any:
+        """Build native views from *element* and return the root native view."""
+        self._tree = self._create_tree(element)
+        return self._tree.native_view
+
+    def reconcile(self, new_element: Element) -> Any:
+        """Diff *new_element* against the current tree and patch native views.
+
+        Returns the (possibly replaced) root native view.
+        """
+        if self._tree is None:
+            self._tree = self._create_tree(new_element)
+            return self._tree.native_view
+
+        self._tree = self._reconcile_node(self._tree, new_element)
+        return self._tree.native_view
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _create_tree(self, element: Element) -> VNode:
+        # Provider: push context, create child, pop context
+        if element.type == "__Provider__":
+            context = element.props["__context__"]
+            context._stack.append(element.props["__value__"])
+            try:
+                child_node = self._create_tree(element.children[0]) if element.children else None
+            finally:
+                context._stack.pop()
+            native_view = child_node.native_view if child_node else None
+            children = [child_node] if child_node else []
+            return VNode(element, native_view, children)
+
+        # Function component: call with hook context
+        if callable(element.type):
+            from .hooks import HookState, _set_hook_state
+
+            hook_state = HookState()
+            hook_state._trigger_render = self._page_re_render
+            _set_hook_state(hook_state)
+            try:
+                rendered = element.type(**element.props)
+            finally:
+                _set_hook_state(None)
+
+            child_node = self._create_tree(rendered)
+            vnode = VNode(element, child_node.native_view, [child_node])
+            vnode.hook_state = hook_state
+            vnode._rendered = rendered
+            return vnode
+
+        # Native element
+        native_view = self.backend.create_view(element.type, element.props)
+        children: List[VNode] = []
+        for child_el in element.children:
+            child_node = self._create_tree(child_el)
+            self.backend.add_child(native_view, child_node.native_view, element.type)
+            children.append(child_node)
+        return VNode(element, native_view, children)
+
+    def _reconcile_node(self, old: VNode, new_el: Element) -> VNode:
+        if not self._same_type(old.element, new_el):
+            new_node = self._create_tree(new_el)
+            self._destroy_tree(old)
+            return new_node
+
+        # Provider
+        if new_el.type == "__Provider__":
+            context = new_el.props["__context__"]
+            context._stack.append(new_el.props["__value__"])
+            try:
+                if old.children and new_el.children:
+                    child = self._reconcile_node(old.children[0], new_el.children[0])
+                    old.children = [child]
+                    old.native_view = child.native_view
+                elif new_el.children:
+                    child = self._create_tree(new_el.children[0])
+                    old.children = [child]
+                    old.native_view = child.native_view
+            finally:
+                context._stack.pop()
+            old.element = new_el
+            return old
+
+        # Function component
+        if callable(new_el.type):
+            from .hooks import _set_hook_state
+
+            hook_state = old.hook_state
+            if hook_state is None:
+                from .hooks import HookState
+
+                hook_state = HookState()
+            hook_state.reset_index()
+            hook_state._trigger_render = self._page_re_render
+            _set_hook_state(hook_state)
+            try:
+                rendered = new_el.type(**new_el.props)
+            finally:
+                _set_hook_state(None)
+
+            if old.children:
+                child = self._reconcile_node(old.children[0], rendered)
+            else:
+                child = self._create_tree(rendered)
+            old.children = [child]
+            old.native_view = child.native_view
+            old.element = new_el
+            old.hook_state = hook_state
+            old._rendered = rendered
+            return old
+
+        # Native element
+        changed = self._diff_props(old.element.props, new_el.props)
+        if changed:
+            self.backend.update_view(old.native_view, old.element.type, changed)
+
+        self._reconcile_children(old, new_el.children)
+        old.element = new_el
+        return old
+
+    def _reconcile_children(self, parent: VNode, new_children: List[Element]) -> None:
+        old_children = parent.children
+        parent_type = parent.element.type
+        is_native = isinstance(parent_type, str) and parent_type != "__Provider__"
+
+        old_by_key: dict = {}
+        old_unkeyed: list = []
+        for child in old_children:
+            if child.element.key is not None:
+                old_by_key[child.element.key] = child
+            else:
+                old_unkeyed.append(child)
+
+        new_child_nodes: List[VNode] = []
+        used_keyed: set = set()
+        unkeyed_iter = iter(old_unkeyed)
+
+        for i, new_el in enumerate(new_children):
+            matched: Optional[VNode] = None
+
+            if new_el.key is not None and new_el.key in old_by_key:
+                matched = old_by_key[new_el.key]
+                used_keyed.add(new_el.key)
+            elif new_el.key is None:
+                matched = next(unkeyed_iter, None)
+
+            if matched is None:
+                node = self._create_tree(new_el)
+                if is_native:
+                    self.backend.add_child(parent.native_view, node.native_view, parent_type)
+                new_child_nodes.append(node)
+            elif not self._same_type(matched.element, new_el):
+                if is_native:
+                    self.backend.remove_child(parent.native_view, matched.native_view, parent_type)
+                self._destroy_tree(matched)
+                node = self._create_tree(new_el)
+                if is_native:
+                    self.backend.insert_child(parent.native_view, node.native_view, parent_type, i)
+                new_child_nodes.append(node)
+            else:
+                updated = self._reconcile_node(matched, new_el)
+                new_child_nodes.append(updated)
+
+        # Destroy unused old nodes
+        for key, node in old_by_key.items():
+            if key not in used_keyed:
+                if is_native:
+                    self.backend.remove_child(parent.native_view, node.native_view, parent_type)
+                self._destroy_tree(node)
+        for node in unkeyed_iter:
+            if is_native:
+                self.backend.remove_child(parent.native_view, node.native_view, parent_type)
+            self._destroy_tree(node)
+
+        parent.children = new_child_nodes
+
+    def _destroy_tree(self, node: VNode) -> None:
+        if node.hook_state is not None:
+            node.hook_state.cleanup_all_effects()
+        for child in node.children:
+            self._destroy_tree(child)
+        node.children = []
+
+    @staticmethod
+    def _same_type(old_el: Element, new_el: Element) -> bool:
+        if isinstance(old_el.type, str):
+            return old_el.type == new_el.type
+        return old_el.type is new_el.type
+
+    @staticmethod
+    def _diff_props(old: dict, new: dict) -> dict:
+        """Return props that changed (callables always count as changed)."""
+        changed = {}
+        for key, new_val in new.items():
+            if key.startswith("__"):
+                continue
+            old_val = old.get(key)
+            if callable(new_val) or old_val != new_val:
+                changed[key] = new_val
+        for key in old:
+            if key.startswith("__"):
+                continue
+            if key not in new:
+                changed[key] = None
+        return changed

pythonnative/style.py

@@ -0,0 +1,115 @@
+"""StyleSheet and theming support.
+
+Provides a :class:`StyleSheet` helper for creating and composing
+reusable style dictionaries, plus a built-in theme context.
+
+Usage::
+
+    import pythonnative as pn
+
+    styles = pn.StyleSheet.create(
+        title={"font_size": 24, "bold": True, "color": "#333"},
+        container={"padding": 16, "spacing": 12},
+    )
+
+    pn.Text("Hello", **styles["title"])
+    pn.Column(..., **styles["container"])
+"""
+
+from typing import Any, Dict
+
+from .hooks import Context, create_context
+
+# ======================================================================
+# StyleSheet
+# ======================================================================
+
+_StyleDict = Dict[str, Any]
+
+
+class StyleSheet:
+    """Utility for creating and composing style dictionaries."""
+
+    @staticmethod
+    def create(**named_styles: _StyleDict) -> Dict[str, _StyleDict]:
+        """Create a set of named styles.
+
+        Each keyword argument is a style name mapping to a dict of
+        property values::
+
+            styles = StyleSheet.create(
+                heading={"font_size": 28, "bold": True},
+                body={"font_size": 16},
+            )
+        """
+        return {name: dict(props) for name, props in named_styles.items()}
+
+    @staticmethod
+    def compose(*styles: _StyleDict) -> _StyleDict:
+        """Merge multiple style dicts, later values overriding earlier ones."""
+        merged: _StyleDict = {}
+        for style in styles:
+            if style:
+                merged.update(style)
+        return merged
+
+    @staticmethod
+    def flatten(styles: Any) -> _StyleDict:
+        """Flatten a style or list of styles into a single dict.
+
+        Accepts a single dict, a list of dicts, or ``None``.
+        """
+        if styles is None:
+            return {}
+        if isinstance(styles, dict):
+            return dict(styles)
+        result: _StyleDict = {}
+        for s in styles:
+            if s:
+                result.update(s)
+        return result
+
+
+# ======================================================================
+# Theming
+# ======================================================================
+
+DEFAULT_LIGHT_THEME: _StyleDict = {
+    "primary_color": "#007AFF",
+    "secondary_color": "#5856D6",
+    "background_color": "#FFFFFF",
+    "surface_color": "#F2F2F7",
+    "text_color": "#000000",
+    "text_secondary_color": "#8E8E93",
+    "error_color": "#FF3B30",
+    "success_color": "#34C759",
+    "warning_color": "#FF9500",
+    "font_size": 16,
+    "font_size_small": 13,
+    "font_size_large": 20,
+    "font_size_title": 28,
+    "spacing": 8,
+    "spacing_large": 16,
+    "border_radius": 8,
+}
+
+DEFAULT_DARK_THEME: _StyleDict = {
+    "primary_color": "#0A84FF",
+    "secondary_color": "#5E5CE6",
+    "background_color": "#000000",
+    "surface_color": "#1C1C1E",
+    "text_color": "#FFFFFF",
+    "text_secondary_color": "#8E8E93",
+    "error_color": "#FF453A",
+    "success_color": "#30D158",
+    "warning_color": "#FF9F0A",
+    "font_size": 16,
+    "font_size_small": 13,
+    "font_size_large": 20,
+    "font_size_title": 28,
+    "spacing": 8,
+    "spacing_large": 16,
+    "border_radius": 8,
+}
+
+ThemeContext: Context = create_context(DEFAULT_LIGHT_THEME)

pythonnative/templates/android_template/app/build.gradle

@@ -20,14 +20,9 @@ android {
             abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
         }
         python {
-            version "3.8"
+            version "3.11"
             pip {
-                install "matplotlib"
-                install "pythonnative"
-
-                // "-r"` followed by a requirements filename, relative to the
-                // project directory:
-//                install "-r", "requirements.txt"
+                install "-r", "requirements.txt"
             }
         }
     }

pythonnative/templates/android_template/app/src/main/java/com/pythonnative/android_template/PageFragment.kt

@@ -65,7 +65,8 @@ class PageFragment : Fragment() {
             utils.callAttr("set_android_fragment_container", view)
             // Now that container exists, invoke on_create so Python can attach its root view
             page?.callAttr("on_create")
-        } catch (_: Exception) {
+        } catch (e: Exception) {
+            Log.e(TAG, "on_create failed", e)
         }
     }
 

pythonnative/templates/android_template/build.gradle

@@ -3,5 +3,5 @@ plugins {
     id 'com.android.application' version '8.2.2' apply false
     id 'com.android.library' version '8.2.2' apply false
     id 'org.jetbrains.kotlin.android' version '1.9.22' apply false
-    id 'com.chaquo.python' version '14.0.2' apply false
+    id 'com.chaquo.python' version '15.0.1' apply false
 }

pythonnative/utils.py

@@ -1,27 +1,29 @@
+"""Platform detection and shared helpers.
+
+This module is imported early by most other modules, so it avoids
+importing platform-specific packages at module level.
+"""
+
 import os
 from typing import Any, Optional
 
-# Platform detection with multiple fallbacks suitable for Chaquopy/Android
+# ======================================================================
+# Platform detection
+# ======================================================================
+
 _is_android: Optional[bool] = None
 
 
 def _detect_android() -> bool:
-    # 1) Direct environment hints commonly present on Android
     env = os.environ
     if "ANDROID_BOOTLOGO" in env or "ANDROID_ROOT" in env or "ANDROID_DATA" in env or "ANDROID_ARGUMENT" in env:
         return True
-
-    # 2) Chaquopy-specific: the builtin 'java' package is available
     try:
-        # Import inside try so importing this module doesn't explode off-device
-        from java import jclass
+        from java import jclass  # noqa: F401
 
-        _ = jclass  # silence linter unused
         return True
     except Exception:
         pass
-
-    # 3) Last resort: some Android Python dists set os.name/others, but avoid false positives
     return False
 
 
@@ -39,53 +41,43 @@ def _get_is_android() -> bool:
 
 IS_ANDROID: bool = _get_is_android()
 
-# Global hooks to access current Android Activity/Context and Fragment container from Python code
+# ======================================================================
+# Android context management
+# ======================================================================
+
 _android_context: Any = None
 _android_fragment_container: Any = None
 
 
 def set_android_context(context: Any) -> None:
-    """Record the current Android Activity/Context for implicit constructor use.
-
-    On Android, Python UI components require a Context to create native views.
-    We capture it when a Page is constructed from the host Activity so component
-    constructors can be platform-consistent and avoid explicit context params.
-    """
-
+    """Record the current Android Activity/Context for view construction."""
     global _android_context
     _android_context = context
 
 
 def set_android_fragment_container(container_view: Any) -> None:
-    """Record the current Fragment root container ViewGroup for rendering pages.
-
-    The current Page's `set_root_view` will attach its native view to this container.
-    """
+    """Record the current Fragment root container ViewGroup."""
     global _android_fragment_container
     _android_fragment_container = container_view
 
 
 def get_android_context() -> Any:
-    """Return the previously set Android Activity/Context or raise if missing."""
-
+    """Return the current Android Activity/Context."""
     if not IS_ANDROID:
         raise RuntimeError("get_android_context() called on non-Android platform")
     if _android_context is None:
         raise RuntimeError(
-            "Android context is not set. Ensure Page is initialized from an Activity " "before constructing views."
+            "Android context not set. Ensure Page is initialized from an Activity before constructing views."
         )
     return _android_context
 
 
 def get_android_fragment_container() -> Any:
-    """Return the previously set Fragment container ViewGroup or raise if missing.
-
-    This is set by the host `PageFragment` when its view is created.
-    """
+    """Return the current Fragment container ViewGroup."""
     if not IS_ANDROID:
         raise RuntimeError("get_android_fragment_container() called on non-Android platform")
     if _android_fragment_container is None:
         raise RuntimeError(
-            "Android fragment container is not set. Ensure PageFragment has been created before set_root_view."
+            "Android fragment container not set. Ensure PageFragment has been created before set_root_view."
         )
     return _android_fragment_container

{pythonnative-0.4.0.dist-info → pythonnative-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.4.0
+Version: 0.6.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -34,12 +34,11 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: User Interfaces
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.31.0
@@ -89,18 +88,17 @@ Dynamic: license-file
 
 ## Overview
 
-PythonNative is a cross-platform toolkit for building native Android and iOS apps in Python. It provides a Pythonic API for native UI components, lifecycle events, and device capabilities, powered by Chaquopy on Android and rubicon-objc on iOS. Write your app once in Python and run it on both platforms with genuinely native interfaces.
+PythonNative is a cross-platform toolkit for building native Android and iOS apps in Python. It provides a **declarative, React-like component model** with automatic reconciliation, powered by Chaquopy on Android and rubicon-objc on iOS. Describe your UI as a tree of elements, manage state with `set_state()`, and let PythonNative handle creating and updating native views.
 
 ## Features
 
-- **Cross-platform native UI:** Build Android and iOS apps from a single Python codebase with truly native rendering.
+- **Declarative UI:** Describe *what* your UI should look like with element functions (`Text`, `Button`, `Column`, `Row`, etc.). PythonNative creates and updates native views automatically.
+- **Reactive state:** Call `self.set_state(key=value)` and the framework re-renders only what changed — no manual view mutation.
+- **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.
-- **Unified component API:** Components like `Page`, `StackView`, `Label`, `Button`, and `WebView` share a consistent interface across platforms.
-- **CLI scaffolding:** `pn init` creates a ready-to-run project structure; `pn run android` and `pn run ios` build and launch your app.
-- **Page lifecycle:** Hooks for `on_create`, `on_start`, `on_resume`, `on_pause`, `on_stop`, and `on_destroy`, with state save and restore.
+- **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 for multi-page apps.
-- **Rich component set:** Core views (Label, Button, TextField, ImageView, WebView, Switch, DatePicker, and more) plus Material Design variants.
-- **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
+- **Bundled templates:** Android Gradle and iOS Xcode templates are included — scaffolding requires no network access.
 
 ## Quick Start
 
@@ -119,15 +117,18 @@ import pythonnative as pn
 class MainPage(pn.Page):
     def __init__(self, native_instance):
         super().__init__(native_instance)
-
-    def on_create(self):
-        super().on_create()
-        stack = pn.StackView()
-        stack.add_view(pn.Label("Hello from PythonNative!"))
-        button = pn.Button("Tap me")
-        button.set_on_click(lambda: print("Button tapped"))
-        stack.add_view(button)
-        self.set_root_view(stack)
+        self.state = {"count": 0}
+
+    def render(self):
+        return pn.Column(
+            pn.Text(f"Count: {self.state['count']}", font_size=24),
+            pn.Button(
+                "Tap me",
+                on_click=lambda: self.set_state(count=self.state["count"] + 1),
+            ),
+            spacing=12,
+            padding=16,
+        )
 ```
 
 ## Documentation