pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/platform.py

@@ -0,0 +1,166 @@
+"""Platform-aware constants and selectors.
+
+A small, RN-style helper for branching app code on the host platform.
+The public surface is the [`Platform`][pythonnative.Platform] class
+exposing ``OS``, ``Version``, ``is_ios``, ``is_android``, ``is_web``,
+and ``select`` so user code can write ``Platform.select({"ios": ..., ...})``
+without importing the ``IS_*`` flags directly.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    title_size = pn.Platform.select({"ios": 17, "android": 16, "default": 16})
+
+    @pn.component
+    def App():
+        return pn.Text(
+            f"Running on {pn.Platform.OS} {pn.Platform.Version}",
+            style={"font_size": title_size},
+        )
+    ```
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Dict, Optional
+
+from .utils import IS_ANDROID, IS_IOS, IS_WEB
+
+
+def _detect_os() -> str:
+    if IS_ANDROID:
+        return "android"
+    if IS_IOS:
+        return "ios"
+    if IS_WEB:
+        return "web"
+    return "test"
+
+
+def _detect_version() -> str:
+    """Return a human-readable platform version string.
+
+    On device this asks the native ``Device`` module (``UIDevice
+    .systemVersion`` / ``Build.VERSION.RELEASE``); the browser preview
+    answers with the browser's user agent family. Off-device (the test
+    environment), returns the host Python's version so user code can
+    still introspect *something*.
+    """
+    if IS_IOS or IS_ANDROID or IS_WEB:
+        try:
+            from .native_modules.registry import native_module
+
+            info = native_module("Device").call("info")
+            if isinstance(info, dict) and info.get("os_version"):
+                return str(info["os_version"])
+        except Exception:
+            pass
+        sim_version = os.environ.get("SIMULATOR_RUNTIME_VERSION")
+        if sim_version:
+            return sim_version
+    return f"python-{sys.version_info.major}.{sys.version_info.minor}"
+
+
+class _LazyVersion:
+    """Resolve ``Platform.Version`` on first access (it needs the bridge on device)."""
+
+    _value: Optional[str] = None
+
+    def __get__(self, obj: object, owner: Optional[type] = None) -> str:
+        if _LazyVersion._value is None:
+            _LazyVersion._value = _detect_version()
+        return _LazyVersion._value
+
+
+class Platform:
+    """Platform-aware constants and the ``select`` dispatcher.
+
+    All attributes are read at import time. ``OS`` is one of
+    ``"ios"``, ``"android"``, ``"web"`` (the browser preview), or
+    ``"test"`` (when running off-device, e.g., in unit tests).
+    """
+
+    OS: str = _detect_os()
+    """``"ios"``, ``"android"``, ``"web"``, or ``"test"``."""
+
+    Version: str = _LazyVersion()  # type: ignore[assignment]
+    """Best-effort OS version string (``"17.4"``, ``"14"``, ``"python-3.11"``)."""
+
+    is_ios: bool = IS_IOS
+    """``True`` when running inside an iOS app bundle."""
+
+    is_android: bool = IS_ANDROID
+    """``True`` when running inside an Android process."""
+
+    is_web: bool = IS_WEB
+    """``True`` when running the browser preview (``pn preview``)."""
+
+    is_test: bool = OS == "test"
+    """``True`` when running off-device (no native runtime)."""
+
+    @staticmethod
+    def select(spec: Dict[str, Any], default: Any = None) -> Any:
+        """Pick the value matching the current platform.
+
+        Looks up ``spec[Platform.OS]``, then falls back to
+        ``spec["native"]`` (matches iOS and Android, *not* the browser
+        preview, which is a development surface), then to
+        ``spec["default"]``, then to the explicit ``default`` argument.
+
+        Args:
+            spec: Mapping from platform name to value. Recognized keys:
+                ``"ios"``, ``"android"``, ``"web"``, ``"test"``,
+                ``"native"``, ``"default"``.
+            default: Value returned when ``spec`` has no matching key
+                and no ``"default"`` entry.
+
+        Returns:
+            The matching value, or ``default`` when nothing matches.
+
+        Example:
+            ```python
+            font = pn.Platform.select(
+                {"ios": "Helvetica", "android": "Roboto", "default": None}
+            )
+            ```
+        """
+        if Platform.OS in spec:
+            return spec[Platform.OS]
+        if (Platform.is_ios or Platform.is_android) and "native" in spec:
+            return spec["native"]
+        if "default" in spec:
+            return spec["default"]
+        return default
+
+
+def get_platform() -> str:
+    """Return the active platform name.
+
+    Equivalent to reading ``Platform.OS``, exposed as a function for
+    introspection from non-component code.
+    """
+    return Platform.OS
+
+
+def _set_platform_for_test(name: Optional[str]) -> None:
+    """Override ``Platform.OS`` for unit tests.
+
+    Production code should not call this. Tests can pass ``"ios"``,
+    ``"android"``, ``"web"``, ``"test"``, or ``None`` (to reset to
+    autodetect).
+    """
+    if name is None:
+        Platform.OS = _detect_os()
+        Platform.is_ios = IS_IOS
+        Platform.is_android = IS_ANDROID
+        Platform.is_web = IS_WEB
+        Platform.is_test = Platform.OS == "test"
+        return
+    Platform.OS = name
+    Platform.is_ios = name == "ios"
+    Platform.is_android = name == "android"
+    Platform.is_web = name == "web"
+    Platform.is_test = name == "test"

pythonnative/platform_metrics.py

@@ -0,0 +1,252 @@
+"""Platform-level metrics shared between screen hosts and view handlers.
+
+The screen host (`pythonnative.hosts`) is the only place that knows
+about native window/safe-area state because it is the only piece of
+code that holds a reference to the native ``UIViewController``
+(iOS) or ``Activity`` (Android). Native view handlers, however, need
+that state to size themselves correctly:
+
+- A bottom tab bar must claim both its visible 49 pt / 56 dp content
+  height **and** the bottom safe-area inset so its background reaches
+  the edge of the screen and the home indicator / gesture bar does
+  not draw on top of the labels.
+- A future safe-area-aware container can read the same values instead
+  of asking each native view for window metrics.
+
+Rather than threading those values through every
+[`measure_intrinsic`][pythonnative.native_views.base.ViewHandler.measure_intrinsic]
+call signature, the screen host writes them here and handlers read
+them on demand. Values are in **dp on Android** and **pt on iOS**,
+i.e., the same "layout units" the layout engine uses on each
+platform, so handlers can add them to other layout-unit values
+without further conversion. On iOS the screen host consumes the top
+safe-area inset by positioning the root view below it, then publishes
+``top=0`` here; Android publishes the raw system-bar insets because
+the host view normally remains full-screen.
+
+Example:
+    >>> from pythonnative.platform_metrics import (
+    ...     get_safe_area_insets, set_safe_area_insets,
+    ... )
+    >>> set_safe_area_insets(top=44.0, left=0.0, bottom=34.0, right=0.0)
+    >>> get_safe_area_insets().bottom
+    34.0
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable, List, NamedTuple
+
+
+class SafeAreaInsets(NamedTuple):
+    """Safe-area insets in layout units (pt on iOS, dp on Android)."""
+
+    top: float
+    left: float
+    bottom: float
+    right: float
+
+
+class WindowDimensions(NamedTuple):
+    """Viewport size in layout units (pt on iOS, dp on Android)."""
+
+    width: float
+    height: float
+
+
+_safe_area_insets: SafeAreaInsets = SafeAreaInsets(0.0, 0.0, 0.0, 0.0)
+_window_dimensions: WindowDimensions = WindowDimensions(0.0, 0.0)
+_keyboard_height: float = 0.0
+
+_subscribers: List[Callable[[], None]] = []
+_subscribers_lock = threading.Lock()
+
+
+def _notify_subscribers() -> None:
+    """Invoke every registered subscriber, swallowing exceptions.
+
+    Called from every metric setter so subscriber callbacks (the React
+    hooks ``use_window_dimensions``/``use_safe_area_insets``/
+    ``use_keyboard_height`` for example) can re-render in response to
+    any metric change. Subscribers are called serially in registration
+    order; any callback that raises is logged-and-skipped so a single
+    misbehaving subscriber can't take down the whole notification
+    cycle.
+    """
+    with _subscribers_lock:
+        callbacks = list(_subscribers)
+    for cb in callbacks:
+        try:
+            cb()
+        except Exception:
+            pass
+
+
+def subscribe(callback: Callable[[], None]) -> Callable[[], None]:
+    """Register *callback* to fire whenever any metric changes.
+
+    Returns an unsubscribe function. Hooks pass a state setter so a
+    component re-renders whenever the platform reports a new value.
+    Threadsafe: multiple subscribers may register/unregister
+    concurrently.
+    """
+    with _subscribers_lock:
+        _subscribers.append(callback)
+
+    def _unsub() -> None:
+        with _subscribers_lock:
+            try:
+                _subscribers.remove(callback)
+            except ValueError:
+                pass
+
+    return _unsub
+
+
+def set_safe_area_insets(top: float, left: float, bottom: float, right: float) -> None:
+    """Publish the current safe-area insets.
+
+    Called by the platform-specific screen host whenever it learns a
+    new value (e.g., on first layout, on rotation, on multitasking
+    split-view changes). Negative inputs are clamped to ``0.0`` so
+    handlers don't have to defend against bad data from native
+    callers.
+
+    Args:
+        top: Distance in layout units from the top of the host
+            container to the safe area (status bar / dynamic island /
+            navigation bar).
+        left: Inset from the left edge.
+        bottom: Inset from the bottom edge (home indicator / gesture
+            bar).
+        right: Inset from the right edge.
+    """
+    global _safe_area_insets
+    new_insets = SafeAreaInsets(
+        max(0.0, float(top)),
+        max(0.0, float(left)),
+        max(0.0, float(bottom)),
+        max(0.0, float(right)),
+    )
+    if new_insets == _safe_area_insets:
+        return
+    _safe_area_insets = new_insets
+    _notify_subscribers()
+
+
+def get_safe_area_insets() -> SafeAreaInsets:
+    """Return the current safe-area insets.
+
+    The default value is ``(0, 0, 0, 0)``; handlers should still
+    function correctly in a unit-test environment where no
+    screen host has published insets.
+    """
+    return _safe_area_insets
+
+
+def reset_safe_area_insets() -> None:
+    """Reset the insets back to ``(0, 0, 0, 0)``.
+
+    Intended for unit tests that need a clean slate between cases.
+    Production code should use
+    [`set_safe_area_insets`][pythonnative.platform_metrics.set_safe_area_insets]
+    instead.
+    """
+    global _safe_area_insets
+    _safe_area_insets = SafeAreaInsets(0.0, 0.0, 0.0, 0.0)
+
+
+def set_window_dimensions(width: float, height: float) -> None:
+    """Publish the viewport size in layout units.
+
+    Called by the screen host on initial layout, rotation, and split-
+    view changes. Notifies subscribers (and therefore re-renders
+    components using ``use_window_dimensions``) only when the size
+    actually changes.
+    """
+    global _window_dimensions
+    new_dims = WindowDimensions(max(0.0, float(width)), max(0.0, float(height)))
+    if new_dims == _window_dimensions:
+        return
+    _window_dimensions = new_dims
+    _notify_subscribers()
+
+
+def get_window_dimensions() -> WindowDimensions:
+    """Return the current viewport size, or ``(0, 0)`` before first layout."""
+    return _window_dimensions
+
+
+def reset_window_dimensions() -> None:
+    """Reset window dimensions back to ``(0, 0)``. Intended for tests."""
+    global _window_dimensions
+    _window_dimensions = WindowDimensions(0.0, 0.0)
+
+
+def set_keyboard_height(height: float) -> None:
+    """Publish the on-screen keyboard height in layout units.
+
+    Negative inputs are clamped to ``0.0``. Notifies subscribers only
+    when the value actually changes.
+    """
+    global _keyboard_height
+    new_h = max(0.0, float(height))
+    if new_h == _keyboard_height:
+        return
+    _keyboard_height = new_h
+    _notify_subscribers()
+
+
+def get_keyboard_height() -> float:
+    """Return the current on-screen keyboard height, or ``0.0`` if hidden."""
+    return _keyboard_height
+
+
+def reset_keyboard_height() -> None:
+    """Reset the keyboard height back to ``0.0``. Intended for tests."""
+    global _keyboard_height
+    _keyboard_height = 0.0
+
+
+# ======================================================================
+# Per-platform tab-bar defaults
+# ======================================================================
+#
+# Only iOS exposes an explicit constant here. The iOS handler can't
+# trust ``UITabBar.sizeThatFits_`` (it has historically returned 0 in
+# some configurations) and the screen host deliberately extends the
+# root view past the bottom safe area so the bar reaches the home
+# indicator; both pieces conspire to require a single source of
+# truth for the height formula.
+#
+# Android intentionally has no equivalent: ``BottomNavigationView``
+# reports a reliable natural height via ``measure(…)`` once attached
+# to the window, and the active-indicator pill is positioned against
+# that natural height. Forcing our own height threw off the pill
+# geometry, so the Android handler defers entirely to the system.
+
+IOS_TAB_BAR_BASE_HEIGHT_PT: float = 49.0
+"""UIKit HIG tab-bar content height in points.
+
+The total bar reaches ``IOS_TAB_BAR_BASE_HEIGHT_PT +
+safe_area_insets.bottom`` so the pill background can extend over the
+home indicator. Apple's HIG places the tab bar flush with the screen
+edge and lets UIKit render its own internal padding for the home
+indicator.
+"""
+
+
+def ios_tab_bar_height() -> float:
+    """Return the iOS tab-bar intrinsic height in points.
+
+    Equal to ``IOS_TAB_BAR_BASE_HEIGHT_PT + safe_area_insets.bottom``
+    so the bar reaches the home indicator. The iOS screen host
+    deliberately extends the root view past the bottom safe area for
+    this very reason; the tab bar absorbs the inset and UIKit
+    renders the pill with internal padding for the home indicator.
+    The Swift ``TabBarManager`` applies the same formula natively;
+    this Python copy keeps the layout engine's expectations testable
+    off device.
+    """
+    return IOS_TAB_BAR_BASE_HEIGHT_PT + get_safe_area_insets().bottom

pythonnative/preview.py

@@ -0,0 +1,287 @@
+"""Development server and browser preview.
+
+The browser is a protocol-2 renderer with Yoga WebAssembly layout. Python runs
+on the standard application asyncio loop; the transport's coordinator and
+network threads forward messages to their owners. The dev server watches app
+sources, synchronizes mobile clients, and applies compatible Fast Refresh.
+
+PN_PLATFORM=web must be set before importing pythonnative; the CLI launches a
+child process with that environment when needed.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+import traceback
+import webbrowser
+from typing import Any, Callable, Dict, List, Optional
+
+__all__ = ["PreviewSession", "serve"]
+
+Logger = Callable[[str], None]
+
+
+class PreviewSession:
+    """Everything one ``pn start`` invocation owns; see [`serve`][pythonnative.preview.serve]."""
+
+    def __init__(
+        self,
+        project_root: str,
+        entry_module: str,
+        *,
+        host: str = "0.0.0.0",
+        port: int = 8765,
+        project_name: str = "",
+        log: Optional[Logger] = None,
+    ) -> None:
+        from .bridge.web import WebTransport
+        from .devserver import DevServer
+
+        self.project_root = os.path.abspath(project_root)
+        self.entry_module = entry_module
+        self.log: Logger = log or (lambda line: print(line, file=sys.stderr, flush=True))
+        self.server = DevServer(
+            self.project_root, entry_module, host=host, port=port, project_name=project_name, log=self.log
+        )
+        self.transport = WebTransport(log=self.log)
+        self.transport.on_peer_changed = self._on_peer_changed
+        self.transport.on_dev_message = self._on_dev_message
+        self._stop = threading.Event()
+        self._unsubscribe: Optional[Callable[[], None]] = None
+
+    # -- lifecycle -------------------------------------------------------
+
+    def start(self) -> None:
+        """Install the transport, start the server, and begin watching."""
+        from . import bridge, diagnostics
+        from .utils import IS_WEB
+
+        if not IS_WEB:
+            raise RuntimeError(
+                "The browser preview needs PN_PLATFORM=web before pythonnative is imported "
+                "(`pn start` and `pn preview` set it for you)."
+            )
+        if self.project_root not in sys.path:
+            sys.path.insert(0, self.project_root)
+        os.environ.setdefault("PN_ENTRY_MODULE", self.entry_module)
+        os.environ.setdefault("PN_STORAGE_DIR", os.path.join(self.project_root, "build", "preview", "storage"))
+        diagnostics.set_dev_mode(True)
+        # Bottom of the reporter stack: screens register their own RedBox
+        # above this, so it only sees errors raised before a screen exists
+        # (a failing import of the entry module, say).
+        diagnostics.set_error_reporter(self, self._report_error)
+        bridge.set_transport(self.transport)
+        from .runtime import start as start_runtime
+
+        start_runtime()
+        self.server.set_preview_channel(self.transport)
+        self._unsubscribe = self.server.add_change_listener(self._on_sources_changed)
+        self.server.start()
+
+    def run(self) -> None:
+        """Run the main loop until ``stop`` (or Ctrl+C)."""
+        try:
+            self.transport.run_main_loop(until=self._stop.is_set)
+        except KeyboardInterrupt:
+            pass
+
+    def stop(self) -> None:
+        """Tear everything down."""
+        self._stop.set()
+        self.transport.stop()
+        if self._unsubscribe is not None:
+            self._unsubscribe()
+            self._unsubscribe = None
+        try:
+            self._destroy_hosts()
+        except Exception:
+            pass
+        self.server.stop()
+        from . import bridge, diagnostics
+
+        diagnostics.set_error_reporter(self, None)
+        bridge.set_transport(None)
+
+    # -- source changes ----------------------------------------------------
+
+    def _on_sources_changed(self, change: Any, snapshot: Any) -> None:
+        """Watcher thread: schedule a reload of the preview's own app."""
+        from .devserver.watcher import modules_for_paths
+
+        modules = modules_for_paths(list(change.changed) + list(change.removed))
+        if not modules:
+            return
+
+        def _apply() -> None:
+            from .hosts import live_hosts
+            from .hot_reload import apply_reload
+
+            hosts = list(live_hosts())
+            started = time.monotonic()
+            result = apply_reload(modules, hosts)
+            elapsed_ms = (time.monotonic() - started) * 1000.0
+            if result.mode == "error":
+                self.log("[pn] reload failed:")
+                for line in (result.error or "").rstrip().split("\n"):
+                    self.log(f"    {line}")
+                self.transport.send_dev({"type": "reload", "ok": False, "error": result.error, "modules": modules})
+                return
+            if result.mode == "none":
+                return
+            label = "Fast Refresh" if result.mode == "fast_refresh" else "Remounted"
+            self.log(f"[pn] {label}: {', '.join(result.reloaded)} ({elapsed_ms:.0f} ms)")
+            self.transport.send_dev(
+                {"type": "reload", "ok": True, "mode": result.mode, "modules": result.reloaded, "ms": elapsed_ms}
+            )
+
+        self.transport.post_to_application(_apply)
+
+    # -- peers -------------------------------------------------------------
+
+    def _on_peer_changed(self, connected: bool) -> None:
+        if connected:
+            self.log("[pn] browser preview connected")
+            self._send_hello()
+            return
+        self.log("[pn] browser preview disconnected")
+        self._destroy_hosts()
+
+    def _send_hello(self) -> None:
+        """Tell the page what to mount; it answers by creating the entry screen."""
+        self.transport.send_dev(
+            {
+                "type": "hello",
+                "entry": self.entry_module,
+                "project": self.server.project_name or os.path.basename(self.project_root),
+            }
+        )
+
+    def _report_error(self, exc: BaseException, phase: str) -> None:
+        """Print an error to the terminal and mirror it into the preview page."""
+        text = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__)).rstrip()
+        self.log(f"[pn] error during {phase}:")
+        for line in text.split("\n"):
+            self.log(f"    {line}")
+        self.transport.send_dev({"type": "error", "phase": phase, "text": text})
+
+    def _destroy_hosts(self) -> None:
+        """Unmount every screen the page created (it is gone, so are its views)."""
+        from .hosts.native import live_hosts
+        from .native_views import get_registry
+
+        for host in list(live_hosts()):
+            try:
+                host.on_destroy()
+            except Exception:
+                traceback.print_exc()
+        backend = get_registry()
+        reset = getattr(backend, "reset", None)
+        if callable(reset):
+            reset()
+
+    def _on_dev_message(self, payload: Dict[str, Any]) -> None:
+        kind = payload.get("type")
+        if kind == "log":
+            self.log(f"[browser] {payload.get('text', '')}")
+        elif kind == "error":
+            self.log(f"[browser error] {payload.get('text', '')}")
+        elif kind == "hello":
+            agent = str(payload.get("user_agent", ""))
+            device = payload.get("device", "")
+            size = f"{payload.get('width', '?')}x{payload.get('height', '?')}"
+            self.log(f"[pn] preview page: {device} {size} ({_browser_family(agent)})")
+        elif kind == "remount":
+            self.log("[pn] remounting the app")
+            self._destroy_hosts()
+            self._send_hello()
+
+    # -- info ----------------------------------------------------------------
+
+    def urls(self) -> List[str]:
+        """Every URL the server can be reached at (local first)."""
+        from .devserver import lan_addresses
+
+        info = self.server.info
+        urls = [info.url("localhost")]
+        for address in lan_addresses():
+            url = info.url(address)
+            if url not in urls:
+                urls.append(url)
+        return urls
+
+
+def _browser_family(user_agent: str) -> str:
+    agent = user_agent.lower()
+    for needle, name in (("firefox", "Firefox"), ("edg/", "Edge"), ("chrome", "Chrome"), ("safari", "Safari")):
+        if needle in agent:
+            return name
+    return "browser"
+
+
+def serve(
+    entry_module: str,
+    *,
+    project_root: Optional[str] = None,
+    host: str = "0.0.0.0",
+    port: int = 8765,
+    project_name: str = "",
+    open_browser: bool = False,
+    log: Optional[Logger] = None,
+    banner: bool = True,
+    ready: Optional[Callable[[PreviewSession], None]] = None,
+) -> None:
+    """Run the dev server (and browser preview) until interrupted.
+
+    Args:
+        entry_module: The app's entry module (``"app.main"``).
+        project_root: Directory containing ``app/``; defaults to the
+            current directory. Added to ``sys.path``.
+        host: Bind address (``0.0.0.0`` so devices can connect).
+        port: TCP port (``0`` picks a free one).
+        project_name: Shown in the preview page.
+        open_browser: Open the preview page in the default browser.
+        log: Where status lines go (stderr by default).
+        banner: Print the connection banner.
+        ready: Called once the server is listening (tests).
+
+    Raises:
+        RuntimeError: If ``PN_PLATFORM=web`` was not set before
+            PythonNative was imported (the CLI sets it for you).
+        OSError: If the port is taken.
+    """
+    session = PreviewSession(
+        project_root or os.getcwd(),
+        entry_module,
+        host=host,
+        port=port,
+        project_name=project_name,
+        log=log,
+    )
+    session.start()
+    urls = session.urls()
+    if banner:
+        emit = session.log
+        emit("")
+        emit(f"  PythonNative dev server for {project_name or entry_module}")
+        emit("")
+        emit(f"  Browser preview:  {urls[0]}")
+        for url in urls[1:]:
+            emit(f"  Devices (LAN):    {url}")
+        emit("")
+        emit("  Debug builds made with `pn run` connect here automatically.")
+        emit("  Press Ctrl+C to stop.")
+        emit("")
+    if open_browser:
+        try:
+            webbrowser.open(urls[0])
+        except Exception:
+            pass
+    if ready is not None:
+        ready(session)
+    try:
+        session.run()
+    finally:
+        session.stop()