pythonnative 0.18.0__py3-none-any.whl → 0.19.0__py3-none-any.whl

pythonnative/screen.py

@@ -50,7 +50,7 @@ import sys
 import threading
 from typing import Any, Dict, Optional, Sequence
 
-from .utils import IS_ANDROID, IS_IOS, set_android_context
+from .utils import IS_ANDROID, IS_DESKTOP, IS_IOS, set_android_context
 
 _MAX_RENDER_PASSES = 25
 _DEBUG_ENV = "PYTHONNATIVE_DEBUG"
@@ -87,6 +87,20 @@ def _resolve_component_path(component_ref: Any) -> str:
     raise ValueError(f"Cannot resolve component path for {component_ref!r}")
 
 
+def _missing_module_is_target(exc: ModuleNotFoundError, dotted: str) -> bool:
+    """Return ``True`` when ``exc`` means ``dotted`` itself is absent.
+
+    Distinguishes "the component module/package cannot be found" (so the
+    caller should fall through to the next resolution strategy) from "the
+    module exists but raised :class:`ModuleNotFoundError` while importing
+    one of *its own* dependencies". The latter must propagate so the
+    developer sees the real missing import (e.g. ``No module named
+    'emoji'``) instead of a misleading "could not resolve component".
+    """
+    missing = exc.name or ""
+    return missing == dotted or dotted.startswith(missing + ".")
+
+
 def _import_component(component_path: str) -> Any:
     """Import a component by module or dotted-attribute path.
 
@@ -117,11 +131,16 @@ def _import_component(component_path: str) -> Any:
         The resolved component callable.
 
     Raises:
-        ImportError: If neither resolution path succeeds.
+        ImportError: If the module or dotted path cannot be found.
+            Errors raised *inside* a resolvable module (such as a
+            missing third-party dependency it imports) propagate
+            unchanged so the real cause stays visible.
     """
     try:
         module = importlib.import_module(component_path)
-    except ModuleNotFoundError:
+    except ModuleNotFoundError as exc:
+        if not _missing_module_is_target(exc, component_path):
+            raise
         module = None
     if module is not None:
         component = getattr(module, "App", None)
@@ -132,7 +151,9 @@ def _import_component(component_path: str) -> Any:
         module_path, attr = component_path.rsplit(".", 1)
         try:
             parent = importlib.import_module(module_path)
-        except ModuleNotFoundError:
+        except ModuleNotFoundError as exc:
+            if not _missing_module_is_target(exc, module_path):
+                raise
             parent = None
         if parent is not None:
             component = getattr(parent, attr, None)
@@ -868,6 +889,165 @@ if IS_ANDROID:
             """Public hook for native code to push viewport sizes (Maestro/tests)."""
             _push_viewport_size(self, width, height)
 
+elif IS_DESKTOP:
+    # ------------------------------------------------------------------
+    # Desktop preview host (Tkinter), driven by ``pn preview``.
+    #
+    # The screen host owns the reconciler + lifecycle just like the
+    # device hosts; placement of the root view and the navigation stack
+    # are delegated to the ``DesktopApp`` controller in
+    # ``pythonnative.preview`` (passed in as ``native_instance``). The
+    # controller runs the Tk event loop on the main thread and polls
+    # ``drain_desktop_scheduled_renders`` so renders requested from the
+    # asyncio worker thread are applied on the main thread.
+    # ------------------------------------------------------------------
+
+    _DESKTOP_SCHEDULED_RENDER_HOSTS: Dict[int, Any] = {}
+    _desktop_render_lock = threading.Lock()
+
+    def _schedule_render_async(host: Any) -> bool:
+        """Queue an off-main-thread render for the Tk poll loop to drain.
+
+        Renders requested on the Tk main thread (button handlers, etc.)
+        run synchronously (returns ``False``); requests from the asyncio
+        worker thread are queued and applied by
+        [`drain_desktop_scheduled_renders`][pythonnative.screen.drain_desktop_scheduled_renders].
+        """
+        if not IS_DESKTOP:
+            return False
+        if threading.current_thread() is threading.main_thread():
+            return False
+        if getattr(host, "_render_scheduled", False):
+            return True
+        host._render_scheduled = True
+        with _desktop_render_lock:
+            _DESKTOP_SCHEDULED_RENDER_HOSTS[id(host)] = host
+        return True
+
+    def drain_desktop_scheduled_renders() -> None:
+        """Apply renders queued from worker threads (called on the main thread)."""
+        with _desktop_render_lock:
+            hosts = list(_DESKTOP_SCHEDULED_RENDER_HOSTS.values())
+            _DESKTOP_SCHEDULED_RENDER_HOSTS.clear()
+        _flush_scheduled_renders(hosts)
+
+    class _ScreenHost:
+        """Desktop host backed by a Tk window and an in-process nav stack.
+
+        Created by ``pythonnative.preview`` for
+        each screen on the navigation stack. ``native_instance`` is the
+        ``DesktopApp`` controller, which provides the stage frame,
+        viewport size, and push/pop primitives.
+        """
+
+        def __init__(self, native_instance: Any = None, component_path: str = "", component_func: Any = None) -> None:
+            self.native_instance = native_instance
+            _init_host_common(self, component_path, component_func)
+
+        def on_create(self) -> None:
+            _on_create(self)
+
+        def on_start(self) -> None:
+            pass
+
+        def on_resume(self) -> None:
+            _set_host_focused(self, True)
+
+        def on_layout(self) -> None:
+            pass
+
+        def on_pause(self) -> None:
+            _set_host_focused(self, False)
+
+        def on_stop(self) -> None:
+            pass
+
+        def on_destroy(self) -> None:
+            pass
+
+        def enable_hot_reload(self, manifest_path: str, source_root: Optional[str] = None) -> None:
+            _enable_hot_reload(self, manifest_path)
+
+        def hot_reload_tick(self) -> bool:
+            return _hot_reload_tick(self)
+
+        def reload(self, changed_modules: Optional[Sequence[str]] = None) -> None:
+            _reload_host(self, changed_modules)
+
+        def on_restart(self) -> None:
+            pass
+
+        def on_save_instance_state(self) -> None:
+            pass
+
+        def on_restore_instance_state(self) -> None:
+            pass
+
+        def set_args(self, args: Any) -> None:
+            _set_args(self, args)
+
+        def _get_nav_args(self) -> Dict[str, Any]:
+            return self._args
+
+        def _push(self, component: Any, args: Optional[Dict[str, Any]] = None) -> None:
+            screen_path = _resolve_component_path(component)
+            app = self.native_instance
+            if app is None or not hasattr(app, "push_screen"):
+                raise RuntimeError("desktop navigation requires a running `pn preview` session")
+            app.push_screen(screen_path, args)
+
+        def _pop(self) -> None:
+            app = self.native_instance
+            if app is not None and hasattr(app, "pop_screen"):
+                app.pop_screen()
+
+        def _reset_to_root(self) -> None:
+            app = self.native_instance
+            if app is not None and hasattr(app, "reset_to_root"):
+                try:
+                    app.reset_to_root()
+                except Exception:
+                    pass
+
+        def _set_screen_options(self, options: Dict[str, Any]) -> None:
+            title = options.get("title") if isinstance(options, dict) else None
+            app = self.native_instance
+            if title and app is not None and hasattr(app, "set_title"):
+                try:
+                    app.set_title(str(title))
+                except Exception:
+                    pass
+
+        def _attach_root(self, native_view: Any) -> None:
+            from .native_views import desktop as _desktop_backend
+
+            stage = _desktop_backend.get_root_container()
+            if stage is not None and native_view is not None:
+                try:
+                    native_view.place(in_=stage, x=0, y=0, relwidth=1.0, relheight=1.0)
+                    native_view.lift()
+                except Exception:
+                    pass
+            app = self.native_instance
+            if app is not None and hasattr(app, "viewport_size"):
+                try:
+                    width, height = app.viewport_size()
+                    if width > 0 and height > 0:
+                        _push_viewport_size(self, float(width), float(height))
+                except Exception:
+                    pass
+
+        def _detach_root(self, native_view: Any) -> None:
+            if native_view is not None:
+                try:
+                    native_view.place_forget()
+                except Exception:
+                    pass
+
+        def set_viewport_size(self, width: float, height: float) -> None:
+            """Push a viewport-size change (called on window resize)."""
+            _push_viewport_size(self, width, height)
+
 else:
     from typing import Dict as _Dict
 

pythonnative/utils.py

@@ -19,6 +19,10 @@ Attributes:
         `PN_PLATFORM=ios`, `sys.platform == "ios"`, or a Simulator
         `HOME` path). Importing `rubicon-objc` alone is intentionally
         not enough to trigger this flag.
+    IS_DESKTOP: `True` when running the desktop preview backend
+        (signaled by `PN_PLATFORM=desktop`, set by ``pn preview``).
+        This drives the Tkinter native-view registry so a PythonNative
+        app can render in a real OS window for fast local iteration.
 """
 
 import os
@@ -31,6 +35,7 @@ from typing import Any, Optional
 
 _is_android: Optional[bool] = None
 _is_ios: Optional[bool] = None
+_is_desktop: Optional[bool] = None
 
 
 def _detect_android() -> bool:
@@ -75,13 +80,29 @@ def _detect_ios() -> bool:
     return False
 
 
+def _detect_desktop() -> bool:
+    """Detect whether we're running the desktop (Tkinter) preview backend.
+
+    The only signal is the explicit ``PN_PLATFORM=desktop`` env var,
+    set by ``pn preview`` before importing PythonNative. Desktop is a
+    *development* target: it renders the app in a native OS window via
+    the pure-Python Tkinter registry 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 mock registry
+    and ``Platform.OS == "test"``.
+    """
+    return os.environ.get("PN_PLATFORM") == "desktop"
+
+
 def _ensure_platform_detection() -> None:
-    """Populate `_is_android` / `_is_ios` once, then reuse."""
-    global _is_android, _is_ios
+    """Populate `_is_android` / `_is_ios` / `_is_desktop` once, then reuse."""
+    global _is_android, _is_ios, _is_desktop
     if _is_android is None:
         _is_android = _detect_android()
     if _is_ios is None:
         _is_ios = (not _is_android) and _detect_ios()
+    if _is_desktop is None:
+        _is_desktop = (not _is_android) and (not _is_ios) and _detect_desktop()
 
 
 def _get_is_android() -> bool:
@@ -98,6 +119,13 @@ def _get_is_ios() -> bool:
     return _is_ios
 
 
+def _get_is_desktop() -> bool:
+    """Return the cached desktop-detection result."""
+    _ensure_platform_detection()
+    assert _is_desktop is not None
+    return _is_desktop
+
+
 IS_ANDROID: bool = _get_is_android()
 """``True`` when running inside an Android process.
 
@@ -113,6 +141,14 @@ The flag is computed once at import time, by checking
 `HOME` path.
 """
 
+IS_DESKTOP: bool = _get_is_desktop()
+"""``True`` when running the desktop (Tkinter) preview backend.
+
+Set by ``pn preview`` via ``PN_PLATFORM=desktop``. Mutually exclusive
+with `IS_ANDROID` / `IS_IOS`. Off-device unit tests leave this
+``False`` and inject a mock registry instead.
+"""
+
 # ======================================================================
 # Android context management
 # ======================================================================

{pythonnative-0.18.0.dist-info → pythonnative-0.19.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.18.0
+Version: 0.19.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -106,6 +106,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
 - **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.
+- **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.
 - **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.
 - **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.
 - **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.

{pythonnative-0.18.0.dist-info → pythonnative-0.19.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pythonnative/__init__.py,sha256=EI_-TSD1LQJDBMpGt94xZ6ht9htAM46FV1eOcxJK_ts,8042
+pythonnative/__init__.py,sha256=DL38DFeaNGmeg_IX75zEoNoXza9oHVloG2XhPpVEe4M,8042
 pythonnative/_ios_log.py,sha256=Oi7V28VxcVoZyrpAirvLeEmUW18McqnU87V4d37Zzlw,2582
 pythonnative/alerts.py,sha256=mIANysFlaHwL5EqKnvNcyiJN9rGiZi9XDrD9Jpz1RFM,9340
 pythonnative/animated.py,sha256=bAgG_sGODAdl5eVQjX_vryaKI1hyjI92QH1PNx7Tqyg,24491
@@ -9,16 +9,17 @@ pythonnative/hot_reload.py,sha256=j7z2c7o2Hdoyd-p4nQY15LTW7CBH_1z0TSAzLCer-aA,25
 pythonnative/layout.py,sha256=siU7PeVOjL_G1f-1q31ssrKWlxz2UBmvMwNXtmqyOxw,36586
 pythonnative/navigation.py,sha256=skMZFh3AXEJgTU6qQpATFN1Lp4GB94K_ACNNXZjEOEE,35579
 pythonnative/net.py,sha256=UI-39-BmGYWLE_vMAFoAbkzWZvfhIFj9yX_gexp1loc,8091
-pythonnative/platform.py,sha256=jEya1KTDc3WfwpmrQkk3DIFyt7CWO4Vc3pej_wDiSR8,4629
+pythonnative/platform.py,sha256=cqG37hPY1fh6QzgO_AfHObg8R1fiMZmDeMu_2TIXqO0,4997
 pythonnative/platform_metrics.py,sha256=m2u8M8x52n5THNsYdspcaI9mlWWMbfSJWai1svjD0NM,8976
+pythonnative/preview.py,sha256=ZtDupXfQdW07i2JD-fnoikAd3zHKVPYoPSMob1K8KQs,16990
 pythonnative/reconciler.py,sha256=dJUSXX65Ckdj5iSmpPtXYnNk0pfg54aesmSlAV0vLbM,43996
-pythonnative/runtime.py,sha256=wQnMMG7ibDGR4zFtwSbh7pR6o5nRe1R_vyPYI0dVcfk,17116
-pythonnative/screen.py,sha256=hcOjs1ZP2jeag55NkbyzOCXiae8cUs5IUhSDwHKIFLQ,57666
+pythonnative/runtime.py,sha256=8xQvhZvMQJYJ0eozWTwKvC-H1GN5vikl6OCxt8f5uI0,18267
+pythonnative/screen.py,sha256=azubUCJYh9-TYC_7-cvjL2nPibimM1IkXN0GDHJCfPc,64906
 pythonnative/storage.py,sha256=hLgSI44ADq6wj29eeYbHaAUNpxYPzJ2ZLn1L7AHkPZY,12010
 pythonnative/style.py,sha256=yDJv-G6iZIgrscpc-IZS_cbEQvY2o7R02PTQZ4BV8RA,15162
-pythonnative/utils.py,sha256=pQSxa3QW06_Y9JzBSnK0g0eMV1VhXww8Qym6HPOGzgM,6064
+pythonnative/utils.py,sha256=-hwe_YS19ebpjeygdl3dGeVsYzO4G74rYD53svSi0rI,7593
 pythonnative/cli/__init__.py,sha256=NM1psvKe8jT0vzp8Ak4MMoygZz4P_msk5g-YEsY8xLk,232
-pythonnative/cli/pn.py,sha256=yWhDELAN7-UOE3qiv3ir29plcbXUp_gRT23Y7sRSVZQ,49133
+pythonnative/cli/pn.py,sha256=wd6mpPxO5nMzt_jJWbw_Vp4Rz-BceQZHHu2o3CaE6KE,53795
 pythonnative/native_modules/__init__.py,sha256=pgigpHuzT-rqwcjlwJvu93_4L8Nozal1HJid0S_JlmM,2636
 pythonnative/native_modules/app_state.py,sha256=EnfChi_YWEgUpZosUiBQh0CmblBZFw8ZGaW1NKIJ4WM,2666
 pythonnative/native_modules/battery.py,sha256=gOU9aN5fCmWfHgTXPD-BgvatdQnyUjfVfsJM7PQ_ARA,4317
@@ -34,9 +35,10 @@ pythonnative/native_modules/notifications.py,sha256=WVtzdimc_aGfnxU6syCFPkjHF9YR
 pythonnative/native_modules/permissions.py,sha256=adRiO_LGxZ1PSJaCoJx_3nheuh9lLWNrPIb47O_A6-Y,6710
 pythonnative/native_modules/secure_store.py,sha256=YC25T2n2Nkfgks_qrCM1CR232AeSkh1_78NOJEBQ800,5956
 pythonnative/native_modules/share.py,sha256=B9ovknmnjeQvGQ8MQ14Hmq6E1x-JA469APMburJ0KUg,4727
-pythonnative/native_views/__init__.py,sha256=yP0IdOmQ3Cco4kJKBcgkMBUPX30ditM_Sp6ZotKAen4,11820
+pythonnative/native_views/__init__.py,sha256=PCb2twVEIwEgMS5NZxsjoe4DeZwm1LRh0Q4QKYHS--A,12347
 pythonnative/native_views/android.py,sha256=z2ypAqMcgL9WNjVcTw-oINgbcFZJR27awC2jS_cWqJ0,114036
 pythonnative/native_views/base.py,sha256=LXDQYRM8wJa3MmGPwslkVyvlu36_s1_J6aO7wwhwYpA,6173
+pythonnative/native_views/desktop.py,sha256=Z4r-72B3zbuvnqbJ5um35UqPM_iTj8wrEz61qcg0SZA,54931
 pythonnative/native_views/ios.py,sha256=F-DTStyva9fsESHAR5qZkNwrQKH_q2BoSGzgKPKJCBA,142727
 pythonnative/sdk/__init__.py,sha256=btIRfW2yy2d2LzjdpFnlc6ym-G3iJj9sVUbb2IlFMOI,3384
 pythonnative/sdk/_components.py,sha256=Hw0cqiyJ1NEzUrhOIT8zsC_mnVtf0jgpPUsireQG2qM,14644
@@ -92,9 +94,9 @@ pythonnative/templates/ios_template/ios_template.xcodeproj/project.xcworkspace/x
 pythonnative/templates/ios_template/ios_templateTests/ios_templateTests.swift,sha256=YnwzZx7yXB13xKAXEGNgz17VuhWeqkHTRTtBJ2Vu3_E,1238
 pythonnative/templates/ios_template/ios_templateUITests/ios_templateUITests.swift,sha256=l2Pwa50F_rv-qPu2go6e4bQernM6PTQJeNPFl_c4ivY,1387
 pythonnative/templates/ios_template/ios_templateUITests/ios_templateUITestsLaunchTests.swift,sha256=f5JrG0uVtLMeJQy26Yyz7Om-JUkT220osqcbeIVkj2g,815
-pythonnative-0.18.0.dist-info/licenses/LICENSE,sha256=A69iG7TIAe6KkGQf6xoVHkc5JSZtOr5eRSvC5iuivnI,1067
-pythonnative-0.18.0.dist-info/METADATA,sha256=wDTaZFQc6eK0lCtvBIoBVJHIVrsx0LRm5H3saFg13UE,8644
-pythonnative-0.18.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-pythonnative-0.18.0.dist-info/entry_points.txt,sha256=iUtDawWSAJAEyWTycpZxDuYz73ol31butpzDIEAgPO0,48
-pythonnative-0.18.0.dist-info/top_level.txt,sha256=kT4SEATY2ywzrZ2Pgea6_zxyym44Q_PbOsUoOYjJLFE,13
-pythonnative-0.18.0.dist-info/RECORD,,
+pythonnative-0.19.0.dist-info/licenses/LICENSE,sha256=A69iG7TIAe6KkGQf6xoVHkc5JSZtOr5eRSvC5iuivnI,1067
+pythonnative-0.19.0.dist-info/METADATA,sha256=DxxW1C3XkGCiWBiTcDUypeTu5i21hHzz85pG_MlQRuk,8972
+pythonnative-0.19.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pythonnative-0.19.0.dist-info/entry_points.txt,sha256=iUtDawWSAJAEyWTycpZxDuYz73ol31butpzDIEAgPO0,48
+pythonnative-0.19.0.dist-info/top_level.txt,sha256=kT4SEATY2ywzrZ2Pgea6_zxyym44Q_PbOsUoOYjJLFE,13
+pythonnative-0.19.0.dist-info/RECORD,,