pythonnative 0.6.0__tar.gz → 0.7.0__tar.gz

{pythonnative-0.6.0/src/pythonnative.egg-info → pythonnative-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.6.0
+Version: 0.7.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -88,17 +88,18 @@ Dynamic: license-file
 
 ## Overview
 
-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.
+PythonNative is a cross-platform toolkit for building native Android and iOS apps in Python. It provides a **declarative, React-like component model** with hooks and automatic reconciliation, powered by Chaquopy on Android and rubicon-objc on iOS. Write function components with `use_state`, `use_effect`, and friends, just like React, and let PythonNative handle creating and updating native views.
 
 ## Features
 
 - **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.
+- **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern.
+- **`style` prop:** Pass all visual and layout properties through a single `style` dict, composable via `StyleSheet`.
 - **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 for multi-page apps.
-- **Bundled templates:** Android Gradle and iOS Xcode templates are included — scaffolding requires no network access.
+- **Navigation:** Push and pop screens with argument passing via the `use_navigation()` hook.
+- **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
 
 ## Quick Start
 
@@ -114,21 +115,17 @@ pip install pythonnative
 import pythonnative as pn
 
 
-class MainPage(pn.Page):
-    def __init__(self, native_instance):
-        super().__init__(native_instance)
-        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,
-        )
+@pn.component
+def MainPage():
+    count, set_count = pn.use_state(0)
+    return pn.Column(
+        pn.Text(f"Count: {count}", style={"font_size": 24}),
+        pn.Button(
+            "Tap me",
+            on_click=lambda: set_count(count + 1),
+        ),
+        style={"spacing": 12, "padding": 16},
+    )
 ```
 
 ## Documentation

{pythonnative-0.6.0 → pythonnative-0.7.0}/README.md

@@ -26,17 +26,18 @@
 
 ## Overview
 
-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.
+PythonNative is a cross-platform toolkit for building native Android and iOS apps in Python. It provides a **declarative, React-like component model** with hooks and automatic reconciliation, powered by Chaquopy on Android and rubicon-objc on iOS. Write function components with `use_state`, `use_effect`, and friends, just like React, and let PythonNative handle creating and updating native views.
 
 ## Features
 
 - **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.
+- **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern.
+- **`style` prop:** Pass all visual and layout properties through a single `style` dict, composable via `StyleSheet`.
 - **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 for multi-page apps.
-- **Bundled templates:** Android Gradle and iOS Xcode templates are included — scaffolding requires no network access.
+- **Navigation:** Push and pop screens with argument passing via the `use_navigation()` hook.
+- **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
 
 ## Quick Start
 
@@ -52,21 +53,17 @@ pip install pythonnative
 import pythonnative as pn
 
 
-class MainPage(pn.Page):
-    def __init__(self, native_instance):
-        super().__init__(native_instance)
-        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,
-        )
+@pn.component
+def MainPage():
+    count, set_count = pn.use_state(0)
+    return pn.Column(
+        pn.Text(f"Count: {count}", style={"font_size": 24}),
+        pn.Button(
+            "Tap me",
+            on_click=lambda: set_count(count + 1),
+        ),
+        style={"spacing": 12, "padding": 16},
+    )
 ```
 
 ## Documentation

{pythonnative-0.6.0 → pythonnative-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.6.0"
+version = "0.7.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }

{pythonnative-0.6.0 → pythonnative-0.7.0}/src/pythonnative/__init__.py

@@ -5,28 +5,16 @@ Public API::
     import pythonnative as pn
 
     @pn.component
-    def counter(initial=0):
-        count, set_count = pn.use_state(initial)
+    def App():
+        count, set_count = pn.use_state(0)
         return pn.Column(
-            pn.Text(f"Count: {count}", font_size=24),
+            pn.Text(f"Count: {count}", style={"font_size": 24}),
             pn.Button("+", on_click=lambda: set_count(count + 1)),
-            spacing=12,
+            style={"spacing": 12},
         )
-
-    class MainPage(pn.Page):
-        def __init__(self, native_instance):
-            super().__init__(native_instance)
-
-        def render(self):
-            return pn.Column(
-                counter(initial=0),
-                counter(initial=10),
-                spacing=16,
-                padding=16,
-            )
 """
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 from .components import (
     ActivityIndicator,
@@ -57,10 +45,11 @@ from .hooks import (
     use_context,
     use_effect,
     use_memo,
+    use_navigation,
     use_ref,
     use_state,
 )
-from .page import Page
+from .page import create_page
 from .style import StyleSheet, ThemeContext
 
 __all__ = [
@@ -85,7 +74,7 @@ __all__ = [
     "WebView",
     # Core
     "Element",
-    "Page",
+    "create_page",
     # Hooks
     "component",
     "create_context",
@@ -93,6 +82,7 @@ __all__ = [
     "use_context",
     "use_effect",
     "use_memo",
+    "use_navigation",
     "use_ref",
     "use_state",
     "Provider",

{pythonnative-0.6.0 → pythonnative-0.7.0}/src/pythonnative/cli/pn.py

@@ -48,25 +48,17 @@ def init_project(args: argparse.Namespace) -> None:
             f.write("""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.ScrollView(
-            pn.Column(
-                pn.Text("Hello from PythonNative!", font_size=24, bold=True),
-                pn.Text(f"Tapped {self.state['count']} times"),
-                pn.Button("Tap me", on_click=self.increment),
-                spacing=12,
-                padding=16,
-                alignment="fill",
-            )
+@pn.component
+def MainPage():
+    count, set_count = pn.use_state(0)
+    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)),
+            style={"spacing": 12, "padding": 16, "align_items": "stretch"},
         )
+    )
 """)
 
     # Create config

pythonnative-0.7.0/src/pythonnative/components.py

@@ -0,0 +1,351 @@
+"""Built-in element-creating functions for declarative UI composition.
+
+Each function returns an :class:`Element` describing a native UI widget.
+These are pure data — no native views are created until the reconciler
+mounts the element tree.
+
+All visual and layout properties are passed via the ``style`` parameter,
+which accepts a dict or a list of dicts (later entries override earlier).
+
+Layout properties supported by all components::
+
+    width, height, flex, margin, min_width, max_width, min_height,
+    max_height, align_self
+
+Container-specific layout properties (Column / Row)::
+
+    spacing, padding, align_items, justify_content
+"""
+
+from typing import Any, Callable, Dict, List, Optional
+
+from .element import Element
+from .style import StyleValue, resolve_style
+
+# ======================================================================
+# Leaf components
+# ======================================================================
+
+
+def Text(
+    text: str = "",
+    *,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Display text.
+
+    Style properties: ``font_size``, ``color``, ``bold``, ``text_align``,
+    ``background_color``, ``max_lines``, plus common layout props.
+    """
+    props: Dict[str, Any] = {"text": text}
+    props.update(resolve_style(style))
+    return Element("Text", props, [], key=key)
+
+
+def Button(
+    title: str = "",
+    *,
+    on_click: Optional[Callable[[], None]] = None,
+    enabled: bool = True,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Create a tappable button.
+
+    Style properties: ``color``, ``background_color``, ``font_size``,
+    plus common layout props.
+    """
+    props: Dict[str, Any] = {"title": title}
+    if on_click is not None:
+        props["on_click"] = on_click
+    if not enabled:
+        props["enabled"] = False
+    props.update(resolve_style(style))
+    return Element("Button", props, [], key=key)
+
+
+def TextInput(
+    *,
+    value: str = "",
+    placeholder: str = "",
+    on_change: Optional[Callable[[str], None]] = None,
+    secure: bool = False,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Create a single-line text entry field.
+
+    Style properties: ``font_size``, ``color``, ``background_color``,
+    plus common layout props.
+    """
+    props: Dict[str, Any] = {"value": value}
+    if placeholder:
+        props["placeholder"] = placeholder
+    if on_change is not None:
+        props["on_change"] = on_change
+    if secure:
+        props["secure"] = True
+    props.update(resolve_style(style))
+    return Element("TextInput", props, [], key=key)
+
+
+def Image(
+    source: str = "",
+    *,
+    scale_type: Optional[str] = None,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Display an image from a resource path or URL.
+
+    Style properties: ``background_color``, plus common layout props.
+    """
+    props: Dict[str, Any] = {}
+    if source:
+        props["source"] = source
+    if scale_type is not None:
+        props["scale_type"] = scale_type
+    props.update(resolve_style(style))
+    return Element("Image", props, [], key=key)
+
+
+def Switch(
+    *,
+    value: bool = False,
+    on_change: Optional[Callable[[bool], None]] = None,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Create a toggle switch."""
+    props: Dict[str, Any] = {"value": value}
+    if on_change is not None:
+        props["on_change"] = on_change
+    props.update(resolve_style(style))
+    return Element("Switch", props, [], key=key)
+
+
+def ProgressBar(
+    *,
+    value: float = 0.0,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Show determinate progress (0.0 – 1.0)."""
+    props: Dict[str, Any] = {"value": value}
+    props.update(resolve_style(style))
+    return Element("ProgressBar", props, [], key=key)
+
+
+def ActivityIndicator(
+    *,
+    animating: bool = True,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Show an indeterminate loading spinner."""
+    props: Dict[str, Any] = {"animating": animating}
+    props.update(resolve_style(style))
+    return Element("ActivityIndicator", props, [], key=key)
+
+
+def WebView(
+    *,
+    url: str = "",
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Embed web content."""
+    props: Dict[str, Any] = {}
+    if url:
+        props["url"] = url
+    props.update(resolve_style(style))
+    return Element("WebView", props, [], key=key)
+
+
+def Spacer(
+    *,
+    size: Optional[float] = None,
+    flex: Optional[float] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Insert empty space with an optional fixed size or flex weight."""
+    props: Dict[str, Any] = {}
+    if size is not None:
+        props["size"] = size
+    if flex is not None:
+        props["flex"] = flex
+    return Element("Spacer", props, [], key=key)
+
+
+def Slider(
+    *,
+    value: float = 0.0,
+    min_value: float = 0.0,
+    max_value: float = 1.0,
+    on_change: Optional[Callable[[float], None]] = None,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Continuous value slider."""
+    props: Dict[str, Any] = {
+        "value": value,
+        "min_value": min_value,
+        "max_value": max_value,
+    }
+    if on_change is not None:
+        props["on_change"] = on_change
+    props.update(resolve_style(style))
+    return Element("Slider", props, [], key=key)
+
+
+# ======================================================================
+# Container components
+# ======================================================================
+
+
+def Column(
+    *children: Element,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Arrange children vertically.
+
+    Style properties: ``spacing``, ``padding``, ``align_items``,
+    ``justify_content``, ``background_color``, plus common layout props.
+
+    ``align_items`` controls cross-axis (horizontal) alignment:
+    ``"stretch"`` (default), ``"flex_start"``/``"leading"``,
+    ``"center"``, ``"flex_end"``/``"trailing"``.
+
+    ``justify_content`` controls main-axis (vertical) distribution:
+    ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
+    ``"space_between"``, ``"space_around"``, ``"space_evenly"``.
+    """
+    props: Dict[str, Any] = {}
+    props.update(resolve_style(style))
+    return Element("Column", props, list(children), key=key)
+
+
+def Row(
+    *children: Element,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Arrange children horizontally.
+
+    Style properties: ``spacing``, ``padding``, ``align_items``,
+    ``justify_content``, ``background_color``, plus common layout props.
+
+    ``align_items`` controls cross-axis (vertical) alignment:
+    ``"stretch"`` (default), ``"flex_start"``/``"top"``,
+    ``"center"``, ``"flex_end"``/``"bottom"``.
+
+    ``justify_content`` controls main-axis (horizontal) distribution:
+    ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
+    ``"space_between"``, ``"space_around"``, ``"space_evenly"``.
+    """
+    props: Dict[str, Any] = {}
+    props.update(resolve_style(style))
+    return Element("Row", props, list(children), key=key)
+
+
+def ScrollView(
+    child: Optional[Element] = None,
+    *,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Wrap a single child in a scrollable container."""
+    children = [child] if child is not None else []
+    props: Dict[str, Any] = {}
+    props.update(resolve_style(style))
+    return Element("ScrollView", props, children, key=key)
+
+
+def View(
+    *children: Element,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Generic container view (``UIView`` / ``android.view.View``)."""
+    props: Dict[str, Any] = {}
+    props.update(resolve_style(style))
+    return Element("View", props, list(children), key=key)
+
+
+def SafeAreaView(
+    *children: Element,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Container that respects safe area insets (notch, status bar)."""
+    props: Dict[str, Any] = {}
+    props.update(resolve_style(style))
+    return Element("SafeAreaView", props, list(children), key=key)
+
+
+def Modal(
+    *children: Element,
+    visible: bool = False,
+    on_dismiss: Optional[Callable[[], None]] = None,
+    title: Optional[str] = None,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Overlay modal dialog.
+
+    The modal is shown when ``visible=True`` and hidden when ``False``.
+    """
+    props: Dict[str, Any] = {"visible": visible}
+    if on_dismiss is not None:
+        props["on_dismiss"] = on_dismiss
+    if title is not None:
+        props["title"] = title
+    props.update(resolve_style(style))
+    return Element("Modal", props, list(children), key=key)
+
+
+def Pressable(
+    child: Optional[Element] = None,
+    *,
+    on_press: Optional[Callable[[], None]] = None,
+    on_long_press: Optional[Callable[[], None]] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Wrapper that adds press handling to any child element."""
+    props: Dict[str, Any] = {}
+    if on_press is not None:
+        props["on_press"] = on_press
+    if on_long_press is not None:
+        props["on_long_press"] = on_long_press
+    children = [child] if child is not None else []
+    return Element("Pressable", props, children, key=key)
+
+
+def FlatList(
+    *,
+    data: Optional[List[Any]] = None,
+    render_item: Optional[Callable[[Any, int], Element]] = None,
+    key_extractor: Optional[Callable[[Any, int], str]] = None,
+    separator_height: float = 0,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Scrollable list that renders items from *data* using *render_item*.
+
+    Each item is rendered by calling ``render_item(item, index)``.  If
+    ``key_extractor`` is provided, it is called as ``key_extractor(item, index)``
+    to produce a stable key for each child element.
+    """
+    items: List[Element] = []
+    for i, item in enumerate(data or []):
+        el = render_item(item, i) if render_item else Text(str(item))
+        if key_extractor is not None:
+            el = Element(el.type, el.props, el.children, key=key_extractor(item, i))
+        items.append(el)
+
+    inner = Column(*items, style={"spacing": separator_height} if separator_height else None)
+    sv_props: Dict[str, Any] = {}
+    sv_props.update(resolve_style(style))
+    return Element("ScrollView", sv_props, [inner], key=key)

{pythonnative-0.6.0 → pythonnative-0.7.0}/src/pythonnative/hooks.py

@@ -1,7 +1,8 @@
 """Hook primitives for function components.
 
 Provides React-like hooks for managing state, effects, memoisation,
-and context within function components decorated with :func:`component`.
+context, and navigation within function components decorated with
+:func:`component`.
 
 Usage::
 
@@ -18,7 +19,7 @@ Usage::
 
 import inspect
 import threading
-from typing import Any, Callable, List, Optional, Tuple, TypeVar
+from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
 
 from .element import Element
 
@@ -246,6 +247,52 @@ def Provider(context: Context, value: Any, child: Element) -> Element:
     return Element("__Provider__", {"__context__": context, "__value__": value}, [child])
 
 
+# ======================================================================
+# Navigation
+# ======================================================================
+
+_NavigationContext: Context = create_context(None)
+
+
+class NavigationHandle:
+    """Object returned by :func:`use_navigation` providing push/pop/get_args.
+
+    Navigates by component reference rather than string path, e.g.::
+
+        nav = pn.use_navigation()
+        nav.push(DetailScreen, args={"id": 42})
+    """
+
+    def __init__(self, host: Any) -> None:
+        self._host = host
+
+    def push(self, page: Any, args: Optional[Dict[str, Any]] = None) -> None:
+        """Navigate forward to *page* (a ``@component`` function or class)."""
+        self._host._push(page, args)
+
+    def pop(self) -> None:
+        """Navigate back to the previous screen."""
+        self._host._pop()
+
+    def get_args(self) -> Dict[str, Any]:
+        """Return arguments passed from the previous screen."""
+        return self._host._get_nav_args()
+
+
+def use_navigation() -> NavigationHandle:
+    """Return a :class:`NavigationHandle` for the current screen.
+
+    Must be called inside a ``@component`` function rendered by PythonNative.
+    """
+    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()."
+        )
+    return handle
+
+
 # ======================================================================
 # @component decorator
 # ======================================================================