pythonnative 0.38.0__tar.gz → 0.39.0__tar.gz

{pythonnative-0.38.0/src/pythonnative.egg-info → pythonnative-0.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.38.0
+Version: 0.39.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -82,20 +82,20 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **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 preview`, hot reload, 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.
+- **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 desktop. Compose them with `Race`, `Exclusive`, and `Simultaneous` for cross-gesture arbitration (single vs. double tap, drag vs. long press).
+- **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.
-- **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
+- **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.
-- **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save: iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
+- **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.
-- **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
+- **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
@@ -127,6 +127,16 @@ def App():
     )
 ```
 
+### 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.

{pythonnative-0.38.0 → pythonnative-0.39.0}/README.md

@@ -35,20 +35,20 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **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 preview`, hot reload, 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.
+- **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 desktop. Compose them with `Race`, `Exclusive`, and `Simultaneous` for cross-gesture arbitration (single vs. double tap, drag vs. long press).
+- **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.
-- **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
+- **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.
-- **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save: iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
+- **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.
-- **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
+- **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
@@ -80,6 +80,16 @@ def App():
     )
 ```
 
+### 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.

{pythonnative-0.38.0 → pythonnative-0.39.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.38.0"
+version = "0.39.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -88,11 +88,13 @@ where = ["src"]
 [tool.setuptools]
 license-files = ["LICENSE*"]
 
-# Include template directories inside the package so importlib.resources can find them
+# Include template directories and the browser preview's page assets inside
+# the package so importlib.resources can find them
 [tool.setuptools.package-data]
 pythonnative = [
   "py.typed",
   "templates/**",
+  "devserver/static/*",
 ]
 
 [tool.ruff]
@@ -127,7 +129,6 @@ ignore = ["D107", "D105", "D203", "D213"]
 # docstrings would only add boilerplate that repeats the ABC.
 "src/pythonnative/native_views/android.py" = ["D101", "D102"]
 "src/pythonnative/native_views/ios.py" = ["D101", "D102"]
-"src/pythonnative/native_views/desktop.py" = ["D101", "D102"]
 # ios.py embeds a LaunchScreen storyboard as an XML string literal whose
 # lines exceed the limit; the XML must stay on single lines for Xcode.
 "src/pythonnative/project/ios.py" = ["E501"]

{pythonnative-0.38.0 → pythonnative-0.39.0}/src/pythonnative/__init__.py

@@ -62,7 +62,7 @@ Example:
     ```
 """
 
-__version__ = "0.38.0"
+__version__ = "0.39.0"
 
 from . import appearance, diagnostics, gestures, images, runtime, sdk
 from .alerts import Alert

{pythonnative-0.38.0 → pythonnative-0.39.0}/src/pythonnative/alerts.py

@@ -52,7 +52,7 @@ async def _present(
     "default"|"cancel"|"destructive"}`` dicts. The module resolves with
     the index the user picked, or ``-1`` if the dialog was dismissed
     without a selection. Off device the
-    [`DesktopAlert`][pythonnative.native_modules.desktop.DesktopAlert]
+    [`FallbackAlert`][pythonnative.native_modules.fallback.FallbackAlert]
     implementation records the call and answers from the queue set by
     [`Alert.set_test_response`][pythonnative.alerts.Alert.set_test_response].
     """

{pythonnative-0.38.0 → pythonnative-0.39.0}/src/pythonnative/animated.py

@@ -40,7 +40,7 @@ native view the value is attached to
   callback when the animation settles, updates the
   [`AnimatedValue`][pythonnative.animated.AnimatedValue], and resolves
   any awaiting tasks.
-- **Declined** (desktop preview, unattached values, callable easings,
+- **Declined** (unattached values, callable easings,
   values feeding Python-side listeners or derived nodes): a single
   background thread ticks the animation at ~60 Hz from Python, pushing
   each frame through ``set_animated_property``. Semantics are

{pythonnative-0.38.0 → pythonnative-0.39.0}/src/pythonnative/bootstrap.py

@@ -8,9 +8,10 @@ import pythonnative.bootstrap; pythonnative.bootstrap.start()
 
 [`start`][pythonnative.bootstrap.start] connects the two halves of the
 bridge (installing the native -> Python callback on iOS), verifies the
-protocol version, routes ``print()`` to the console on iOS, and warms
-the asyncio runtime. From then on the native runtime drives everything
-through ``callback("host", ...)``; see ``docs/concepts/bridge.md``.
+protocol version, routes ``print()`` to the console on iOS, warms the
+asyncio runtime, and, in debug builds, starts the dev client that syncs
+sources from ``pn start``. From then on the native runtime drives
+everything through ``callback("host", ...)``; see ``docs/concepts/bridge.md``.
 """
 
 from __future__ import annotations
@@ -29,8 +30,8 @@ def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
     """Connect the bridge and prepare the runtime.
 
     Args:
-        dev: Enable dev mode (RedBox, validation warnings). Debug
-            templates pass ``True``; hot reload turns it on as well.
+        dev: Enable dev mode (RedBox, validation warnings, the dev
+            client). Debug templates pass ``True``.
         strict: Re-raise the failure after recording it. The templates
             pass ``True`` so a broken bridge surfaces as a bootstrap
             error screen with the full traceback.
@@ -59,7 +60,8 @@ def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
         from . import bridge
 
         status_["protocol"] = bridge.handshake()
-        if dev or os.environ.get("PN_DEV") in ("1", "true"):
+        dev_mode = bool(dev or os.environ.get("PN_DEV") in ("1", "true"))
+        if dev_mode:
             from . import diagnostics
 
             diagnostics.set_dev_mode(True)
@@ -73,6 +75,13 @@ def start(dev: bool = False, strict: bool = False) -> Dict[str, Any]:
         from .native_views import get_registry
 
         get_registry()
+        if dev_mode:
+            # Debug builds are dev clients: connect to `pn start` when
+            # the build (or a remembered connection) names a server.
+            from . import devclient
+
+            client = devclient.start_if_configured()
+            status_["dev_server"] = client.url if client is not None else None
     except Exception as exc:
         status_["error"] = f"{type(exc).__name__}: {exc}"
         print(f"[pn.bootstrap] start failed: {exc!r}", file=sys.stderr)

{pythonnative-0.38.0 → pythonnative-0.39.0}/src/pythonnative/bridge/__init__.py

@@ -7,11 +7,13 @@ Everything that crosses into native code goes through a
 [`native_callback`][pythonnative.bridge.native_callback]. The protocol
 is documented in ``docs/concepts/bridge.md``.
 
-Off-device (tests, ``pn preview``) there is no transport; the desktop
-registry renders with Tkinter and native modules fall back to their
-Python implementations. Tests that want to exercise the bridge itself
-install a [`FakeTransport`][pythonnative.bridge.fake.FakeTransport]
-with [`set_transport`][pythonnative.bridge.set_transport].
+Under ``pn preview`` the native side is a browser page, reached through
+[`WebTransport`][pythonnative.bridge.web.WebTransport]; the preview
+installs it with [`set_transport`][pythonnative.bridge.set_transport]
+before any screen mounts. In headless tests there is no transport at
+all: native modules fall back to their Python implementations, and
+tests that want to exercise the bridge itself install a
+[`FakeTransport`][pythonnative.bridge.fake.FakeTransport].
 """
 
 from __future__ import annotations
@@ -74,7 +76,7 @@ _explicit = False
 
 
 def _create_platform_transport() -> Optional[Transport]:
-    from ..utils import IS_ANDROID, IS_IOS
+    from ..utils import IS_ANDROID, IS_IOS, IS_WEB
 
     if IS_IOS:
         from .ios import IOSTransport
@@ -86,6 +88,11 @@ def _create_platform_transport() -> Optional[Transport]:
         from .android import AndroidTransport
 
         return AndroidTransport()
+    if IS_WEB:
+        raise RuntimeError(
+            "PN_PLATFORM=web is set but no browser preview transport is installed. "
+            "Start the app with `pn preview` (or `pn start`), which installs the WebTransport."
+        )
     return None
 
 
@@ -104,7 +111,7 @@ def get_transport() -> Transport:
             if created is None:
                 raise RuntimeError(
                     "No native bridge is available on this platform (running off-device). "
-                    "Use `pn preview` for the desktop renderer or install a FakeTransport in tests."
+                    "Use `pn preview` for the browser renderer or install a FakeTransport in tests."
                 )
             _transport = created
     return _transport
@@ -116,9 +123,9 @@ def has_transport() -> bool:
         return True
     if _explicit:
         return False
-    from ..utils import IS_ANDROID, IS_IOS
+    from ..utils import IS_ANDROID, IS_IOS, IS_WEB
 
-    return bool(IS_IOS or IS_ANDROID)
+    return bool(IS_IOS or IS_ANDROID or IS_WEB)
 
 
 def set_transport(transport: Optional[Transport]) -> None:

{pythonnative-0.38.0 → pythonnative-0.39.0}/src/pythonnative/bridge/codec.py

@@ -104,7 +104,7 @@ def encode_transaction(
 
     Args:
         ops: Ordered mutations from the reconciler.
-        prop_filter: Unused hook kept for symmetry with the desktop
+        prop_filter: Unused hook kept for symmetry with the test
             registry; reserved for per-type prop rewriting.
 
     Returns: