pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/testing/harness.py

@@ -0,0 +1,369 @@
+"""Render components into a fake backend and query the result.
+
+```python
+import pythonnative as pn
+from pythonnative.testing import render
+
+def test_counter():
+    result = render(Counter())
+    assert result.get_by_text("Count: 0")
+    result.press(result.get_by_text("+"))
+    assert result.get_by_text("Count: 1")
+```
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Dict, Generic, List, Optional, Pattern, Tuple, TypeVar, Union
+
+from ..element import Element, Node
+from ..events import dispatch_event, get_event_registry
+from .backend import FakeBackend, FakeView
+
+__all__ = ["FakeHost", "HookResult", "RenderResult", "render", "render_hook", "settle"]
+
+T = TypeVar("T")
+Matcher = Union[str, Pattern[str], Callable[[Optional[str]], bool]]
+Target = Union[FakeView, int]
+
+DEFAULT_VIEWPORT: Tuple[float, float] = (390.0, 844.0)
+
+
+def _matches(value: Optional[str], matcher: Matcher, *, exact: bool) -> bool:
+    if callable(matcher) and not isinstance(matcher, (str, re.Pattern)):
+        return bool(matcher(value))
+    if value is None:
+        return False
+    if isinstance(matcher, re.Pattern):
+        return matcher.search(value) is not None
+    return value == matcher if exact else matcher in value
+
+
+def settle(reconciler: Any = None, timeout: float = 1.0) -> None:
+    """Pump the framework loop and flush pending renders until everything is idle.
+
+    Use after triggering async work (``use_resource``, ``use_query``,
+    transitions, coroutines started by handlers) so assertions see the
+    settled tree.
+    """
+    from .. import runtime
+
+    for _ in range(50):
+        idle = runtime.drain(timeout)
+        if reconciler is not None:
+            reconciler.flush_dirty()
+            if reconciler.transitions.pending:
+                reconciler.transitions.flush()
+                continue
+        if idle and (reconciler is None or not reconciler._has_dirty_work()):
+            return
+
+
+class FakeHost:
+    """Application lifecycle and restoration host for navigation tests.
+
+    Pass as ``render(..., host=FakeHost())`` to provide restoration state.
+    Screens remain in the logical tree. ``set_focused`` simulates the
+    application entering or leaving the foreground.
+    """
+
+    def __init__(self, initial_state: Optional[Dict[str, Any]] = None) -> None:
+        self.is_focused = True
+        self.initial_state = initial_state
+        self.options: List[Dict[str, Any]] = []
+        self._focus_listeners: List[Callable[[bool], None]] = []
+
+    def initial_navigation_state(self) -> Optional[Dict[str, Any]]:
+        """Return the ``initial_state`` the host was constructed with (``None`` for a fresh root)."""
+        return self.initial_state
+
+    def set_screen_options(self, options: Dict[str, Any]) -> None:
+        """Append a copy of ``options`` to ``options`` (see the ``title`` property)."""
+        self.options.append(dict(options))
+
+    def add_focus_listener(self, callback: Callable[[bool], None]) -> Callable[[], None]:
+        """Register a focus callback fired by ``set_focused``; returns an unsubscribe callable."""
+        self._focus_listeners.append(callback)
+        return lambda: self._focus_listeners.remove(callback)
+
+    def set_focused(self, focused: bool) -> None:
+        """Simulate the platform covering (``False``) or revealing (``True``) the screen."""
+        self.is_focused = focused
+        for cb in list(self._focus_listeners):
+            cb(focused)
+
+    @property
+    def title(self) -> Optional[str]:
+        """The most recent ``title`` passed to ``set_screen_options``."""
+        for options in reversed(self.options):
+            if "title" in options:
+                return options["title"]
+        return None
+
+
+class RenderResult:
+    """Handle to a mounted tree: queries, events, re-render, unmount.
+
+    Query methods come in three flavors, mirroring Testing Library:
+    ``get_by_*`` returns exactly one match or raises ``LookupError``
+    (with the tree dumped in the message), ``query_by_*`` returns the
+    match or ``None``, ``get_all_by_*`` returns every match. Matchers
+    are exact strings, compiled regexes, or predicates. Views inside a
+    ``display: "none"`` subtree (inactive tabs, covered stack screens)
+    are skipped unless ``hidden=True`` is passed.
+    """
+
+    def __init__(self, reconciler: Any, backend: FakeBackend, wrap: Callable[[Node], Element]) -> None:
+        self.reconciler = reconciler
+        self.backend = backend
+        self._wrap = wrap
+
+    # -- tree -----------------------------------------------------------
+
+    @property
+    def root(self) -> Optional[FakeView]:
+        """The root native view (``None`` after unmount)."""
+        return self.reconciler.root_view()
+
+    def views(self, *, hidden: bool = False) -> List[FakeView]:
+        """Every live view, root first (includes detached ``Portal`` overlays)."""
+        root = self.root
+        out = list(root.walk(include_hidden=hidden)) if root is not None else []
+        seen = {id(v) for v in out}
+        for view in self.backend.views.values():
+            if view.parent is None and view is not root and id(view) not in seen:
+                out.extend(view.walk(include_hidden=hidden))
+        return out
+
+    def dump(self) -> str:
+        """Indented text rendering of the live tree."""
+        root = self.root
+        return root.dump() if root is not None else "<unmounted>"
+
+    def text(self, *, hidden: bool = False) -> List[str]:
+        """Visible strings in document order."""
+        return [v.text for v in self.views(hidden=hidden) if v.text is not None]
+
+    # -- queries --------------------------------------------------------
+
+    def _all(self, predicate: Callable[[FakeView], bool], hidden: bool = False) -> List[FakeView]:
+        return [v for v in self.views(hidden=hidden) if predicate(v)]
+
+    def _one(self, kind: str, matcher: Any, found: List[FakeView]) -> FakeView:
+        if len(found) == 1:
+            return found[0]
+        detail = "no matches" if not found else f"{len(found)} matches: {found}"
+        raise LookupError(f"get_by_{kind}({matcher!r}): {detail}\n\n{self.dump()}")
+
+    def get_all_by_text(self, matcher: Matcher, *, exact: bool = True, hidden: bool = False) -> List[FakeView]:
+        """Return every view whose visible text matches ``matcher`` (``exact=False`` matches substrings)."""
+        return self._all(lambda v: _matches(v.text, matcher, exact=exact), hidden)
+
+    def get_by_text(self, matcher: Matcher, *, exact: bool = True, hidden: bool = False) -> FakeView:
+        """Return the single view whose visible text matches ``matcher``; raise ``LookupError`` otherwise."""
+        return self._one("text", matcher, self.get_all_by_text(matcher, exact=exact, hidden=hidden))
+
+    def query_by_text(self, matcher: Matcher, *, exact: bool = True, hidden: bool = False) -> Optional[FakeView]:
+        """Return the first view whose visible text matches ``matcher``, or ``None``."""
+        found = self.get_all_by_text(matcher, exact=exact, hidden=hidden)
+        return found[0] if found else None
+
+    def get_all_by_test_id(self, matcher: Matcher, *, hidden: bool = False) -> List[FakeView]:
+        """Return every view whose ``test_id`` prop matches ``matcher``."""
+        return self._all(lambda v: _matches(v.test_id, matcher, exact=True), hidden)
+
+    def get_by_test_id(self, matcher: Matcher, *, hidden: bool = False) -> FakeView:
+        """Return the single view whose ``test_id`` prop matches ``matcher``; raise ``LookupError`` otherwise."""
+        return self._one("test_id", matcher, self.get_all_by_test_id(matcher, hidden=hidden))
+
+    def query_by_test_id(self, matcher: Matcher, *, hidden: bool = False) -> Optional[FakeView]:
+        """Return the first view whose ``test_id`` prop matches ``matcher``, or ``None``."""
+        found = self.get_all_by_test_id(matcher, hidden=hidden)
+        return found[0] if found else None
+
+    def get_all_by_label(self, matcher: Matcher, *, hidden: bool = False) -> List[FakeView]:
+        """Return every view whose ``accessibility_label`` prop matches ``matcher``."""
+        return self._all(lambda v: _matches(v.label, matcher, exact=True), hidden)
+
+    def get_by_label(self, matcher: Matcher, *, hidden: bool = False) -> FakeView:
+        """Return the single view whose ``accessibility_label`` matches ``matcher``; raise ``LookupError`` if not."""
+        return self._one("label", matcher, self.get_all_by_label(matcher, hidden=hidden))
+
+    def query_by_label(self, matcher: Matcher, *, hidden: bool = False) -> Optional[FakeView]:
+        """Return the first view whose ``accessibility_label`` prop matches ``matcher``, or ``None``."""
+        found = self.get_all_by_label(matcher, hidden=hidden)
+        return found[0] if found else None
+
+    def get_all_by_type(self, type_name: str, *, hidden: bool = False) -> List[FakeView]:
+        """Return every view of native type ``type_name`` (for example ``"Text"``)."""
+        return self._all(lambda v: v.type_name == type_name, hidden)
+
+    def get_by_type(self, type_name: str, *, hidden: bool = False) -> FakeView:
+        """Return the single view of native type ``type_name``; raise ``LookupError`` otherwise."""
+        return self._one("type", type_name, self.get_all_by_type(type_name, hidden=hidden))
+
+    def query_by_type(self, type_name: str, *, hidden: bool = False) -> Optional[FakeView]:
+        """Return the first view of native type ``type_name``, or ``None``."""
+        found = self.get_all_by_type(type_name, hidden=hidden)
+        return found[0] if found else None
+
+    # -- events ---------------------------------------------------------
+
+    def fire(self, target: Target, event: str, *args: Any) -> None:
+        """Dispatch ``event`` (an ``on_*`` prop name) to ``target`` and settle.
+
+        Raises:
+            LookupError: If no handler is registered for the event.
+        """
+        tag = target.tag if isinstance(target, FakeView) else int(target)
+        if not get_event_registry().has(tag, event):
+            raise LookupError(f"fire({target!r}, {event!r}): no handler registered\n\n{self.dump()}")
+        dispatch_event(tag, event, *args)
+        self.settle()
+
+    def press(self, target: Target) -> None:
+        """Fire ``on_press`` on ``target``."""
+        self.fire(target, "on_press")
+
+    def change_text(self, target: Target, value: str) -> None:
+        """Fire ``on_change`` on a ``TextInput``."""
+        self.fire(target, "on_change", value)
+
+    def back(self) -> bool:
+        """Simulate the system back action; returns whether a handler consumed it."""
+        consumed = bool(self.reconciler.dispatch_back_press())
+        self.settle()
+        return consumed
+
+    # -- lifecycle ------------------------------------------------------
+
+    def settle(self, timeout: float = 1.0) -> None:
+        """Flush pending renders and async work (see [`settle`][pythonnative.testing.settle])."""
+        settle(self.reconciler, timeout)
+
+    def rerender(self, element: Node) -> None:
+        """Reconcile a new root element (new props from outside the tree)."""
+        self.reconciler.reconcile(self._wrap(element))
+        self.settle()
+
+    def unmount(self) -> None:
+        """Unmount the tree, running effect cleanups and destroying every view."""
+        self.reconciler.unmount()
+
+    def __enter__(self) -> "RenderResult":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.unmount()
+
+
+def render(
+    element: Node,
+    *,
+    viewport: Optional[Tuple[float, float]] = DEFAULT_VIEWPORT,
+    backend: Optional[FakeBackend] = None,
+    host: Optional[FakeHost] = None,
+    settle_first: bool = True,
+) -> RenderResult:
+    """Mount ``element`` into a [`FakeBackend`][pythonnative.testing.FakeBackend].
+
+    Args:
+        element: The element (or component call) to render.
+        viewport: Size for the layout pass; ``None`` skips layout.
+        backend: Reuse an existing backend (defaults to a fresh one).
+        host: Render under a [`HostRoot`][pythonnative.navigation.host.HostRoot]
+            with this fake host for focus and restoration state.
+        settle_first: Drain async work and effects before returning.
+    """
+    from ..reconciler import Reconciler
+
+    backend = backend if backend is not None else FakeBackend()
+    reconciler = Reconciler(backend)
+    if viewport is not None:
+        reconciler.set_viewport_size(float(viewport[0]), float(viewport[1]))
+
+    def wrap(node: Node) -> Element:
+        if host is not None:
+            from ..navigation.host import HostRoot
+
+            return HostRoot(node, host=host)
+        if isinstance(node, Element):
+            return node
+        from ..components import Fragment
+
+        return Fragment(*(node if isinstance(node, (list, tuple)) else [node]))
+
+    reconciler.mount(wrap(element))
+    result = RenderResult(reconciler, backend, wrap)
+    if settle_first:
+        result.settle()
+    return result
+
+
+class HookResult(Generic[T]):
+    """Handle returned by [`render_hook`][pythonnative.testing.render_hook].
+
+    Attributes:
+        current: The hook's most recent return value.
+    """
+
+    def __init__(self, result: RenderResult, box: Dict[str, Any], rerender: Callable[..., None]) -> None:
+        self._result = result
+        self._box = box
+        self._rerender = rerender
+
+    @property
+    def current(self) -> T:
+        """The value the hook returned on its most recent render."""
+        return self._box["value"]
+
+    @property
+    def render_count(self) -> int:
+        """How many times the hook has run since ``render_hook`` was called."""
+        return self._box["renders"]
+
+    def act(self, fn: Callable[[], Any]) -> None:
+        """Run ``fn`` (typically a state setter) and settle."""
+        fn()
+        self._result.settle()
+
+    def rerender(self, *args: Any, **kwargs: Any) -> None:
+        """Re-run the hook with new arguments."""
+        self._rerender(*args, **kwargs)
+
+    def settle(self) -> None:
+        """Flush pending renders and async work started by the hook."""
+        self._result.settle()
+
+    def unmount(self) -> None:
+        """Unmount the harness component, running the hook's effect cleanups."""
+        self._result.unmount()
+
+
+def render_hook(hook: Callable[..., T], *args: Any, host: Optional[FakeHost] = None, **kwargs: Any) -> HookResult[T]:
+    """Run ``hook(*args, **kwargs)`` inside a throwaway component.
+
+    ```python
+    result = render_hook(lambda: pn.use_state(0))
+    value, set_value = result.current
+    result.act(lambda: set_value(5))
+    assert result.current[0] == 5
+    ```
+    """
+    from ..component import component
+
+    box: Dict[str, Any] = {"value": None, "renders": 0}
+
+    @component
+    def Harness(*, args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> None:
+        box["value"] = hook(*args, **kwargs)
+        box["renders"] += 1
+        return None
+
+    result = render(Harness(args=tuple(args), kwargs=dict(kwargs)), host=host)
+
+    def rerender(*new_args: Any, **new_kwargs: Any) -> None:
+        result.rerender(Harness(args=tuple(new_args) or tuple(args), kwargs={**kwargs, **new_kwargs}))
+
+    return HookResult(result, box, rerender)

pythonnative/utils.py

@@ -0,0 +1,145 @@
+"""Platform detection and shared helpers.
+
+This module is imported early by most other modules, so it avoids
+importing platform-specific packages at module level. The detection
+results are cached the first time
+[`IS_ANDROID`][pythonnative.utils.IS_ANDROID],
+[`IS_IOS`][pythonnative.utils.IS_IOS], and
+[`IS_WEB`][pythonnative.utils.IS_WEB] are read.
+
+Attributes:
+    IS_ANDROID: `True` when running inside an Android process
+        (`sys.platform == "android"` on the embedded CPython 3.13+, or
+        Chaquopy's `java` module imports successfully).
+    IS_IOS: `True` when running inside an iOS app bundle
+        (`sys.platform == "ios"` on the embedded CPython 3.13+, or the
+        explicit `PN_PLATFORM=ios` override).
+    IS_WEB: `True` when running the browser preview (signaled by
+        `PN_PLATFORM=web`, set by ``pn preview`` / ``pn start``). The
+        reconciler then commits through the bridge to a browser page
+        instead of to Swift or Kotlin.
+"""
+
+import os
+import sys
+from typing import Optional
+
+# ======================================================================
+# Platform detection
+# ======================================================================
+
+_is_android: Optional[bool] = None
+_is_ios: Optional[bool] = None
+_is_web: Optional[bool] = None
+
+
+def _detect_android() -> bool:
+    """Return whether we're running inside an Android process.
+
+    CPython 3.13+ reports ``sys.platform == "android"`` (PEP 738); the
+    Chaquopy ``java`` module import is kept as a secondary signal.
+    """
+    if sys.platform == "android":
+        return True
+    try:
+        from java import jclass  # noqa: F401
+
+        return True
+    except Exception:
+        pass
+    return False
+
+
+def _detect_ios() -> bool:
+    """Detect whether we're running inside an iOS app bundle.
+
+    Signals, in priority order:
+
+    - `sys.platform == "ios"`: CPython 3.13+ reports this on both
+      devices and the Simulator (PEP 730), so it is the canonical
+      signal for the embedded runtime.
+    - Explicit `PN_PLATFORM=ios` env var: set by the iOS template before
+      Python starts as a belt-and-braces override, and by tests.
+
+    Running on macOS is never enough on its own: the browser preview
+    and unit tests run there and must not be mistaken for iOS.
+    """
+    if sys.platform == "ios":
+        return True
+    return os.environ.get("PN_PLATFORM") == "ios"
+
+
+def _detect_web() -> bool:
+    """Detect whether we're running the browser preview.
+
+    The only signal is the explicit ``PN_PLATFORM=web`` env var, set by
+    ``pn preview`` / ``pn start`` before importing PythonNative. Web is
+    a *development* target: the app renders in a browser tab through
+    the bridge protocol so the inner dev loop doesn't require a device
+    build. Off-device unit tests deliberately leave this flag ``False``
+    so they keep using an injected fake backend and
+    ``Platform.OS == "test"``.
+    """
+    return os.environ.get("PN_PLATFORM") == "web"
+
+
+def _ensure_platform_detection() -> None:
+    """Populate `_is_android` / `_is_ios` / `_is_web` once, then reuse."""
+    global _is_android, _is_ios, _is_web
+    if _is_android is None:
+        _is_android = _detect_android()
+    if _is_ios is None:
+        _is_ios = (not _is_android) and _detect_ios()
+    if _is_web is None:
+        _is_web = (not _is_android) and (not _is_ios) and _detect_web()
+
+
+def _get_is_android() -> bool:
+    """Return the cached Android-detection result."""
+    _ensure_platform_detection()
+    assert _is_android is not None
+    return _is_android
+
+
+def _get_is_ios() -> bool:
+    """Return the cached iOS-detection result."""
+    _ensure_platform_detection()
+    assert _is_ios is not None
+    return _is_ios
+
+
+def _get_is_web() -> bool:
+    """Return the cached web-detection result."""
+    _ensure_platform_detection()
+    assert _is_web is not None
+    return _is_web
+
+
+IS_ANDROID: bool = _get_is_android()
+"""``True`` when running inside an Android process.
+
+The flag is computed once at import time, from ``sys.platform ==
+"android"`` or a successful import of Chaquopy's `java` module.
+"""
+
+IS_IOS: bool = _get_is_ios()
+"""``True`` when running inside an iOS app bundle.
+
+The flag is computed once at import time, from ``sys.platform ==
+"ios"`` or the explicit `PN_PLATFORM=ios` override.
+"""
+
+IS_WEB: bool = _get_is_web()
+"""``True`` when running the browser preview.
+
+Set by ``pn preview`` / ``pn start`` via ``PN_PLATFORM=web``. Mutually
+exclusive with `IS_ANDROID` / `IS_IOS`. Off-device unit tests leave
+this ``False`` and inject a fake backend instead.
+"""
+
+IS_NATIVE: bool = IS_ANDROID or IS_IOS or IS_WEB
+"""``True`` whenever the reconciler commits through the bridge.
+
+All three of iOS, Android, and the browser preview render through a
+bridge transport; only headless tests have no native side at all.
+"""

pythonnative-0.40.0.dist-info/DELVEWHEEL

@@ -0,0 +1,2 @@
+Version: 1.13.1
+Arguments: ['C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-7660rwxu\\cp313-win_amd64\\build\\venv\\Scripts\\delvewheel', 'repair', '-w', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-7660rwxu\\cp313-win_amd64\\repaired_wheel', '-v', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-7660rwxu\\cp313-win_amd64\\built_wheel\\pythonnative-0.40.0-cp313-cp313-win_amd64.whl']

pythonnative-0.40.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: pythonnative
+Version: 0.40.0
+Summary: Cross-platform native UI toolkit for Android and iOS
+Author: Owen Carey
+License: MIT License
+        
+        Copyright (c) 2026 Owen Carey
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+        THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/pythonnative/pythonnative
+Project-URL: Repository, https://github.com/pythonnative/pythonnative
+Project-URL: Issues, https://github.com/pythonnative/pythonnative/issues
+Project-URL: Documentation, https://pythonnative.com/
+Classifier: Development Status :: 2 - Pre-Alpha
+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.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: build
+Requires-Dist: Pillow>=10.0; extra == "build"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/banner.jpg" alt="PythonNative" width="800" />
+</p>
+
+<p align="center">
+  <em>Build native Android and iOS apps in Python.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/pythonnative/pythonnative/actions/workflows/ci.yml"><img src="https://github.com/pythonnative/pythonnative/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/pythonnative/pythonnative/actions/workflows/release.yml"><img src="https://github.com/pythonnative/pythonnative/actions/workflows/release.yml/badge.svg" alt="Release" /></a>
+  <a href="https://pypi.org/project/pythonnative/"><img src="https://img.shields.io/pypi/v/pythonnative" alt="PyPI Version" /></a>
+  <a href="https://pypi.org/project/pythonnative/"><img src="https://img.shields.io/pypi/pyversions/pythonnative" alt="Python Versions" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/pypi/l/pythonnative" alt="License: MIT" /></a>
+  <a href="https://pythonnative.com/"><img src="https://img.shields.io/website?url=https%3A%2F%2Fpythonnative.com&label=docs" alt="Docs" /></a>
+</p>
+
+<p align="center">
+  <a href="https://pythonnative.com/">Documentation</a> ·
+  <a href="https://pythonnative.com/getting-started/">Getting Started</a> ·
+  <a href="https://pythonnative.com/examples/">Examples</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+---
+
+## 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 hooks and automatic reconciliation on top of a **native rendering core** written in Swift and Kotlin. 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.
+- **Rich component library:** 25+ built-in components backed by real native widgets: `TextInput`, `Image` / `ImageBackground`, `ScrollView`, `FlatList` / `SectionList`, `Modal`, `Pressable` / `TouchableOpacity`, `Switch` / `Checkbox`, `Slider`, `SegmentedControl`, `Picker`, `DatePicker`, `ProgressBar` / `ActivityIndicator`, `WebView`, and more.
+- **Device APIs:** Cross-platform modules for `Camera`, `Location`, `FileSystem`, `Notifications`, `Clipboard`, `Share`, `Linking`, `Permissions`, `AppState`, `NetInfo`, `SecureStore`, `Battery`, `Haptics` / `Vibration`, and `Biometrics`, plus reactive `use_app_state` and `use_net_info` hooks.
+- **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect` / `use_layout_effect`, refs and imperative handles with `use_ref` / `use_imperative_handle`, and navigation with `use_navigation`, all through one consistent pattern. Components can return a single element, a list of siblings, or `None`, and `Fragment`, `Portal`, and reactive `Provider` context work the way they do in React.
+- **Async-first rendering:** One `asyncio` event loop runs the whole framework on the platform's main thread. Components can be `async def` and `await` data directly in the body; `Suspense` boundaries show declarative loading states while they wait. `use_resource` fetches during render, `use_effect` accepts coroutine callbacks (cancelled automatically on unmount), `lazy` code-splits components, and `use_transition` / `use_deferred_value` keep the UI responsive during expensive updates.
+- **Developer feedback that finds your bugs:** In dev mode (`pn start`, `pn preview`, debug builds from `pn run`, or `PN_DEV=1`), uncaught errors from renders, effects, and event handlers show a full-screen RedBox with the traceback; unknown style keys and duplicate list keys print "did you mean" warnings; and conditional hooks raise a `HookOrderError` at the source instead of silently cross-wiring state.
+- **Typed `style` prop and theme:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`, and read design tokens from a typed, immutable `pn.Theme` via `use_theme()` that follows light and dark mode by default.
+- **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.
+- **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally**: only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements, so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.
+- **Native-driven animations:** The `Animated` API (timing / spring / decay / loop / stagger, awaitable or fire-and-forget) hands animations to Core Animation and `ViewPropertyAnimator` whenever possible, so no Python code runs per frame; a pure-Python ticker covers the rest. `interpolate`, arithmetic operators on animated nodes, `Animated.event` scroll binding, and `diff_clamp` cover the scroll-driven patterns (collapsing headers, parallax) that define native feel.
+- **Native gesture system:** Attach `Tap`, `LongPress`, `Pan`, `Swipe`, `Fling`, `Pinch`, and `Rotation` recognizers to any view via the `gestures=` prop, backed by `UIGestureRecognizer` on iOS and a unit-testable pure-Python arbiter on Android and in the browser preview. Compose them with `Race`, `Exclusive`, and `Simultaneous` for cross-gesture arbitration (single vs. double tap, drag vs. long press).
+- **Virtualized lists:** `FlatList` / `SectionList` window their rows in Python over the platform scroll view: uniform, exact, or measured variable heights, grids, headers/footers, infinite scroll, and an imperative scroll controller, identical on every platform.
+- **Native rendering core:** each commit is one serialized transaction applied by Swift and Kotlin component managers, the same shape as React Native's Fabric. Device APIs are native modules registered by name (TurboModules-style), callable from thin Python facades.
+- **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
+- **Metro-style dev loop:** `pn start` runs one dev server that serves the browser preview and every connected debug build. Save a file and each client Fast Refreshes in place, keeping component state; their `print` output and tracebacks stream back into the same terminal. `pn run android` / `pn run ios` bakes the server URL into a debug build and rebuilds the native project only when a native input actually changed, so relaunching after a Python edit takes seconds, not minutes.
+- **PyPI packages, binary wheels included:** List requirements in `pythonnative.toml` and the CLI resolves them for the *device* (iOS wheels via PEP 730 and BeeWare's index, Android wheels via PEP 738 and Chaquopy), bundling numpy, Pillow, cryptography, and friends alongside pure-Python packages. `pn deps` reports what each target resolves to before you build, and a weekly-checked compatibility matrix keeps the docs honest.
+- **Browser preview:** `pn preview` renders your app in a browser tab inside a phone frame (pick a device, rotate, toggle dark mode) with Fast Refresh on every save. The page is a bridge peer exactly like the Swift and Kotlin runtimes, so the reconciler, hooks, layout engine, navigation, and screen host are the same code that ships to the phone; only the leaf widgets are DOM elements.
+- **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; `use_back_handler` intercepts the back action when a screen needs to.
+- **Dev client:** Build a shell app once with `pn run ios --dev-client` and point it at any project's dev server from a connect screen, the way Expo Go does; physical phones on the same Wi-Fi get the same Fast Refresh as simulators.
+- **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
+
+## Quick Start
+
+### Installation
+
+Requires Python 3.13 or newer.
+
+```bash
+pip install pythonnative
+```
+
+### Usage
+
+```python
+import pythonnative as pn
+
+
+@pn.component
+def App():
+    count, set_count = pn.use_state(0)
+    return pn.Column(
+        pn.Text(f"Count: {count}", style=pn.style(font_size=24, bold=True)),
+        pn.Button(
+            "Tap me",
+            on_press=lambda: set_count(count + 1),
+        ),
+        style=pn.style(spacing=12, padding=16),
+    )
+```
+
+### Develop
+
+```bash
+pn init my-app && cd my-app
+pn preview          # dev server + browser preview with Fast Refresh
+pn run ios          # in another terminal: debug build that connects to the same server
+pn run android
+pn build ios        # standalone release artifacts
+```
+
+## Documentation
+
+Visit [pythonnative.com](https://pythonnative.com/) for the full documentation, including getting started guides, platform-specific instructions for Android and iOS, API reference, and working examples.
+
+## Contributing
+
+Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, coding standards, and guidelines for submitting pull requests.
+
+## License
+
+[MIT](LICENSE)