pythonnative 0.35.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

pythonnative/native_views/bridge_backend.py

@@ -0,0 +1,264 @@
+"""The on-device view backend: every mutation crosses the bridge as one transaction.
+
+[`BridgeBackend`][pythonnative.native_views.bridge_backend.BridgeBackend]
+implements the same protocol the reconciler expects from
+[`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry]
+(``apply_mutations``, ``resolve_view``, ``measure_intrinsic``,
+``command``, and the animation hooks) but owns no native objects. It
+serializes each commit with
+[`encode_transaction`][pythonnative.bridge.codec.encode_transaction]
+and hands the JSON to the platform transport; Swift and Kotlin
+component managers do the rest.
+
+Python keeps two small pieces of per-tag state:
+
+- A **prop sidecar** for values that can't cross the bridge (the
+  ``render_row`` callable of a ``VirtualList``).
+- **Row pools** for virtualized lists, so the synchronous
+  ``on_bind_row`` protocol can mount a row subtree and answer with its
+  root tag.
+
+Views are addressed by tag everywhere. ``resolve_view`` returns a
+[`NativeViewRef`][pythonnative.native_views.bridge_backend.NativeViewRef],
+the opaque handle refs receive.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from ..bridge import codec, get_transport
+from ..mutations import CreateOp, DestroyOp, Mutation, UpdateOp
+
+__all__ = ["BridgeBackend", "NativeViewRef"]
+
+_MEASURE_UNBOUNDED = 1e6
+
+
+class NativeViewRef:
+    """Opaque handle to a native view living on the other side of the bridge.
+
+    Attributes:
+        tag: The reconciler-assigned tag; pass it to
+            ``Reconciler.dispatch_command`` or ``get_registry().command``.
+        type_name: The element type (``"Text"``, ``"ScrollView"``, ...).
+    """
+
+    __slots__ = ("tag", "type_name")
+
+    def __init__(self, tag: int, type_name: str) -> None:
+        self.tag = tag
+        self.type_name = type_name
+
+    def __repr__(self) -> str:
+        return f"<NativeViewRef {self.type_name} tag={self.tag}>"
+
+    def __int__(self) -> int:
+        return self.tag
+
+
+class BridgeBackend:
+    """Registry protocol implementation that forwards to the native runtime."""
+
+    def __init__(self, transport: Any = None) -> None:
+        self._transport = transport
+        self._types: Dict[int, str] = {}
+        self._refs: Dict[int, NativeViewRef] = {}
+        self._python_props: Dict[int, Dict[str, Any]] = {}
+        self._row_pools: Dict[int, Any] = {}
+        self._handlers: Dict[str, Any] = {}
+
+    @property
+    def transport(self) -> Any:
+        """The transport in use (resolved lazily on first access)."""
+        if self._transport is None:
+            self._transport = get_transport()
+        return self._transport
+
+    # ------------------------------------------------------------------
+    # Registration (kept for protocol parity with NativeViewRegistry)
+    # ------------------------------------------------------------------
+
+    def register(self, type_name: str, handler: Any) -> None:
+        """Record a Python handler for diagnostics only.
+
+        On device, rendering is native; a Python ``ViewHandler`` can't
+        create platform views. The registration is kept so
+        ``handler_for`` can answer introspection questions and so the
+        SDK's install step doesn't fail, but it is never invoked.
+        """
+        self._handlers[type_name] = handler
+
+    def handler_for(self, type_name: str) -> Any:
+        """Return the diagnostic Python handler registered for ``type_name``."""
+        return self._handlers.get(type_name)
+
+    # ------------------------------------------------------------------
+    # Tag table
+    # ------------------------------------------------------------------
+
+    def resolve_view(self, tag: int) -> Optional[NativeViewRef]:
+        """Return the handle for ``tag`` (``None`` if the view is gone)."""
+        return self._refs.get(tag)
+
+    def type_of(self, tag: int) -> Optional[str]:
+        """Return the element type registered for ``tag``."""
+        return self._types.get(tag)
+
+    def live_view_count(self) -> int:
+        """Number of views currently alive on the native side."""
+        return len(self._types)
+
+    def python_props(self, tag: int) -> Dict[str, Any]:
+        """Props held Python-side for ``tag`` (callables never sent to native)."""
+        return self._python_props.get(tag, {})
+
+    # ------------------------------------------------------------------
+    # Commit channel
+    # ------------------------------------------------------------------
+
+    def apply_mutations(self, ops: Sequence[Mutation]) -> None:
+        """Serialize ``ops`` and apply them natively in one crossing."""
+        if not ops:
+            return
+        # Bookkeeping first so a native failure never leaves Python
+        # believing a destroyed tag is still live.
+        destroyed: List[int] = []
+        for op in ops:
+            if isinstance(op, CreateOp):
+                self._types[op.tag] = op.type_name
+                self._refs[op.tag] = NativeViewRef(op.tag, op.type_name)
+            elif isinstance(op, DestroyOp):
+                destroyed.append(op.tag)
+        payload, sidecar = codec.encode_transaction(ops)
+        for tag, props in sidecar:
+            self._python_props.setdefault(tag, {}).update(props)
+        for op in ops:
+            if isinstance(op, UpdateOp):
+                # A prop that changed from a callable to None arrives
+                # as None in the wire dict; drop the stale sidecar copy.
+                bucket = self._python_props.get(op.tag)
+                if bucket:
+                    for key, value in op.changed_props.items():
+                        if value is None:
+                            bucket.pop(key, None)
+                    if not bucket:
+                        self._python_props.pop(op.tag, None)
+        self.transport.apply(payload)
+        for tag in destroyed:
+            self._forget(tag)
+
+    def _forget(self, tag: int) -> None:
+        self._types.pop(tag, None)
+        self._refs.pop(tag, None)
+        self._python_props.pop(tag, None)
+        pool = self._row_pools.pop(tag, None)
+        if pool is not None:
+            pool.release_all()
+
+    # ------------------------------------------------------------------
+    # Imperative escape hatches
+    # ------------------------------------------------------------------
+
+    def measure_intrinsic(self, tag: int, max_width: float, max_height: float) -> Tuple[float, float]:
+        """Ask native for the natural size of ``tag`` under the constraints."""
+        if tag not in self._types:
+            return (0.0, 0.0)
+        w, h = self.transport.measure(tag, _bound(max_width), _bound(max_height))
+        return (max(0.0, float(w)), max(0.0, float(h)))
+
+    def command(self, tag: int, name: str, args: Optional[Dict[str, Any]] = None) -> Any:
+        """Run an imperative command on one view; returns its JSON result or ``None``."""
+        if tag not in self._types:
+            return None
+        result = self.transport.command(tag, name, codec.dumps(codec.to_jsonable(args or {})))
+        return codec.loads(result)
+
+    def set_animated_property(self, tag: int, prop_name: str, value: Any) -> None:
+        """Write one animated property value without animating (a Python-driven frame)."""
+        if tag not in self._types:
+            return
+        self.transport.animate(tag, codec.dumps({"op": "set", "prop": prop_name, "value": codec.to_jsonable(value)}))
+
+    def start_animation(self, tag: int, anim_id: int, prop_name: str, spec: Dict[str, Any]) -> bool:
+        """Start a native-driven animation; returns whether native accepted it."""
+        if tag not in self._types:
+            return False
+        request = {"op": "start", "id": int(anim_id), "prop": prop_name, "spec": codec.to_jsonable(spec)}
+        result = codec.loads(self.transport.animate(tag, codec.dumps(request)))
+        return bool(isinstance(result, dict) and result.get("ok"))
+
+    def cancel_animation(self, tag: int, anim_id: int) -> Any:
+        """Cancel a native animation and return its presentation value, if known."""
+        if tag not in self._types:
+            return None
+        result = codec.loads(self.transport.animate(tag, codec.dumps({"op": "cancel", "id": int(anim_id)})))
+        if isinstance(result, dict):
+            return result.get("value")
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal (native-originated) events
+    # ------------------------------------------------------------------
+
+    def handle_internal_event(self, tag: int, name: str, args: List[Any]) -> Any:
+        """Serve request-style events that no user callback owns.
+
+        Currently the virtualized-list row protocol:
+
+        - ``on_bind_row`` ``[{"container", "index", "width", "height"}]``
+          mounts or rebinds the row subtree and returns ``{"root": tag}``.
+        - ``on_unbind_row`` ``[{"container"}]`` releases it.
+        """
+        if name == "on_bind_row":
+            return self._bind_row(tag, args[0] if args else {})
+        if name == "on_unbind_row":
+            info = args[0] if args else {}
+            pool = self._row_pools.get(tag)
+            if pool is not None and isinstance(info, dict):
+                pool.release(int(info.get("container", 0)))
+            return None
+        return None
+
+    def _bind_row(self, tag: int, info: Any) -> Dict[str, Any]:
+        if not isinstance(info, dict):
+            return {"root": None}
+        render_row = self._python_props.get(tag, {}).get("render_row")
+        if not callable(render_row):
+            return {"root": None}
+        from ..virtual_rows import RowHostPool
+
+        pool = self._row_pools.get(tag)
+        if pool is None:
+            pool = RowHostPool()
+            self._row_pools[tag] = pool
+        index = int(info.get("index", 0))
+        width = float(info.get("width", 0.0) or 0.0)
+        height = float(info.get("height", 0.0) or 0.0)
+        root = pool.bind(int(info.get("container", 0)), lambda: render_row(index), width, height)
+        root_tag = getattr(root, "tag", None)
+        return {"root": int(root_tag) if root_tag is not None else None}
+
+    # ------------------------------------------------------------------
+    # Test helpers
+    # ------------------------------------------------------------------
+
+    def _reset_for_tests(self) -> None:
+        for pool in list(self._row_pools.values()):
+            pool.release_all()
+        self._row_pools.clear()
+        self._types.clear()
+        self._refs.clear()
+        self._python_props.clear()
+
+
+def _bound(value: float) -> float:
+    """Clamp ``math.inf`` to the wire's "unconstrained" sentinel."""
+    try:
+        f = float(value)
+    except (TypeError, ValueError):
+        return _MEASURE_UNBOUNDED
+    if not math.isfinite(f) or f > _MEASURE_UNBOUNDED:
+        return _MEASURE_UNBOUNDED
+    return max(0.0, f)

pythonnative/platform.py

@@ -43,33 +43,37 @@ def _detect_os() -> str:
 def _detect_version() -> str:
     """Return a human-readable platform version string.
 
-    On iOS, reads the Simulator/device's reported OS version. On
-    Android, reads ``Build.VERSION.RELEASE``. Off-device (the test
+    On device this asks the native ``Device`` module (``UIDevice
+    .systemVersion`` / ``Build.VERSION.RELEASE``). Off-device (the test
     environment), returns the host Python's version so user code can
     still introspect *something*.
     """
-    if IS_IOS:
+    if IS_IOS or IS_ANDROID:
         try:
-            from rubicon.objc import ObjCClass
+            from .native_modules.registry import native_module
 
-            UIDevice = ObjCClass("UIDevice")
-            return str(UIDevice.currentDevice.systemVersion)
+            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
-    if IS_ANDROID:
-        try:
-            from java import jclass
-
-            Build = jclass("android.os.Build$VERSION")
-            return str(Build.RELEASE)
-        except Exception:
-            pass
     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.
 
@@ -82,7 +86,7 @@ class Platform:
     OS: str = _detect_os()
     """``"ios"``, ``"android"``, ``"desktop"``, or ``"test"``."""
 
-    Version: str = _detect_version()
+    Version: str = _LazyVersion()  # type: ignore[assignment]
     """Best-effort OS version string (``"17.4"``, ``"14"``, ``"python-3.11"``)."""
 
     is_ios: bool = IS_IOS

pythonnative/platform_metrics.py

@@ -245,8 +245,8 @@ def ios_tab_bar_height() -> float:
     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.
-    Used by ``pythonnative.native_views.ios.TabBarHandler``; exposed
-    here so the formula is testable without importing the iOS
-    handler module (which requires ``rubicon-objc``).
+    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/project/android.py

@@ -512,9 +512,6 @@ def collect_logcat_filters() -> List[str]:
     return [
         "python.stdout:V",
         "python.stderr:V",
-        "MainActivity:V",
-        "ScreenFragment:V",
-        "Navigator:V",
         "PythonNative:V",
         "AndroidRuntime:E",
         "System.err:W",

pythonnative/project/builder.py

@@ -28,6 +28,7 @@ from __future__ import annotations
 import compileall
 import os
 import platform as platform_module
+import shutil
 import subprocess
 import sys
 from dataclasses import dataclass, field
@@ -37,6 +38,7 @@ from typing import Callable, List, Optional, Sequence, Union
 
 from . import android as android_config
 from . import ios as ios_config
+from . import plugins as native_plugins
 from . import runtime_assets
 from .android import AndroidLayout
 from .config import AppConfig
@@ -177,6 +179,20 @@ class BuildArtifacts:
 
 _TEMPLATE_NAMES = {"android": "android_template", "ios": "ios_template"}
 
+# A source checkout accumulates Gradle, SwiftPM, and Xcode outputs next to
+# the native library sources; a staged project must start from a clean tree.
+_TEMPLATE_IGNORE = shutil.ignore_patterns(
+    "build",
+    ".build",
+    ".gradle",
+    ".swiftpm",
+    "xcuserdata",
+    "DerivedData",
+    "__pycache__",
+    "*.pyc",
+    ".DS_Store",
+)
+
 
 def stage_template(template_name: str, destination: Path) -> Path:
     """Copy a bundled native template into ``destination``.
@@ -196,22 +212,20 @@ def stage_template(template_name: str, destination: Path) -> Path:
     Raises:
         BuildError: If no bundled copy can be located.
     """
-    import shutil
-
     dest_path = destination / template_name
     destination.mkdir(parents=True, exist_ok=True)
 
     # Dev-first: local source package templates.
     local = Path(__file__).resolve().parents[1] / "templates" / template_name
     if local.is_dir():
-        shutil.copytree(local, dest_path, dirs_exist_ok=True)
+        shutil.copytree(local, dest_path, dirs_exist_ok=True, ignore=_TEMPLATE_IGNORE)
         return dest_path
 
     try:
         candidate = resources.files("pythonnative").joinpath("templates").joinpath(template_name)
         with resources.as_file(candidate) as resolved:
             if Path(resolved).is_dir():
-                shutil.copytree(resolved, dest_path, dirs_exist_ok=True)
+                shutil.copytree(resolved, dest_path, dirs_exist_ok=True, ignore=_TEMPLATE_IGNORE)
                 return dest_path
     except (ModuleNotFoundError, FileNotFoundError, OSError):
         pass
@@ -280,6 +294,7 @@ class Builder:
         build_dir = self.build_root / platform
         build_dir.mkdir(parents=True, exist_ok=True)
         project_dir = stage_template(_TEMPLATE_NAMES[platform], build_dir)
+        plugins = self._discover_plugins()
 
         if platform == "android":
             layout = android_config.configure(
@@ -288,6 +303,7 @@ class Builder:
                 dev_lib_root=self.dev_lib_root,
                 log=self.log,
             )
+            native_plugins.stage_android_plugins(project_dir, plugins, log=self.log)
             return PreparedProject(
                 platform=platform,
                 build_dir=build_dir,
@@ -297,6 +313,7 @@ class Builder:
             )
 
         ios_layout = ios_config.configure(project_dir, self.config, log=self.log)
+        native_plugins.stage_ios_plugins(project_dir, plugins, log=self.log)
         self._stage_ios_python(project_dir, release=release)
         self._link_ios_runtime(project_dir)
         return PreparedProject(
@@ -307,6 +324,20 @@ class Builder:
             ios=ios_layout,
         )
 
+    def _discover_plugins(self) -> List[native_plugins.NativePlugin]:
+        """Collect native plugins from entry points and ``[plugins].paths``.
+
+        Raises:
+            BuildError: If a project-local plugin directory is invalid.
+        """
+        try:
+            return native_plugins.discover_plugins(
+                extra_paths=[self.config.resolve_path(p) for p in self.config.plugin_paths],
+                log=self.log,
+            )
+        except native_plugins.PluginError as exc:
+            raise BuildError(f"Invalid native plugin: {exc}") from exc
+
     def _stage_ios_python(self, project_dir: Path, *, release: bool) -> None:
         """Stage ``app/`` and ``app_packages/`` at the Xcode project root.
 
@@ -314,8 +345,6 @@ class Builder:
         and the "Install Python runtime" build phase converts any
         binary modules inside them into signed frameworks.
         """
-        import shutil
-
         app_dir = project_dir / "app"
         packages_dir = project_dir / "app_packages"
         for directory in (app_dir, packages_dir):
@@ -336,14 +365,9 @@ class Builder:
                 ignore=android_config.LIB_IGNORE,
             )
 
-        # rubicon-objc supplies the iOS Objective-C bridge; user
-        # requirements ride along in the same site directory.
-        result = self.runner.run(
-            [sys.executable, "-m", "pip", "install", "--no-deps", "--upgrade", "rubicon-objc", "-t", str(packages_dir)],
-            capture=True,
-        )
-        if not result.ok:
-            raise BuildError(f"pip install rubicon-objc failed:\n{result.stderr}")
+        # The framework has no Python-side native dependencies (the
+        # bridge into PythonNativeKit is ctypes); only user requirements
+        # are installed into the site directory.
         if self.config.requirements:
             result = self.runner.run(
                 [sys.executable, "-m", "pip", "install", "-t", str(packages_dir), *self.config.requirements],
@@ -389,8 +413,6 @@ class Builder:
         framework is hundreds of megabytes); staging falls back to a
         copy when symlinks are unavailable.
         """
-        import shutil
-
         runtime = self._ios_runtime()
         link = project_dir / "Python.xcframework"
         if link.is_symlink() or link.is_file():

pythonnative/project/config.py

@@ -34,6 +34,9 @@ splash = "assets/splash.png"  # splash/launch image
 [requirements]
 packages = ["humanize", "httpx"]
 
+[plugins]
+paths = ["native/my_plugin"]  # local native plugins (pn_plugin.json + ios/ + android/)
+
 [ios]
 deployment_target = "13.0"
 development_team = "ABCDE12345"
@@ -235,6 +238,9 @@ class AppConfig:
         icon: Optional source icon path (``[assets].icon``).
         splash: Optional splash image path (``[assets].splash``).
         requirements: Third-party pip packages (``[requirements].packages``).
+        plugin_paths: Project-local native plugin directories
+            (``[plugins].paths``); installed packages contribute plugins
+            through the ``pythonnative.plugins`` entry point group instead.
         ios: Nested [`IOSConfig`][pythonnative.project.config.IOSConfig].
         android: Nested
             [`AndroidConfig`][pythonnative.project.config.AndroidConfig].
@@ -254,6 +260,7 @@ class AppConfig:
     icon: Optional[str] = None
     splash: Optional[str] = None
     requirements: List[str] = field(default_factory=list)
+    plugin_paths: List[str] = field(default_factory=list)
     ios: IOSConfig = field(default_factory=IOSConfig)
     android: AndroidConfig = field(default_factory=AndroidConfig)
     project_root: Path = field(default_factory=Path.cwd)
@@ -345,8 +352,8 @@ class AppConfig:
 
         Args:
             data: A parsed TOML mapping (top-level tables: ``app``,
-                ``permissions``, ``assets``, ``requirements``, ``ios``,
-                ``android``).
+                ``permissions``, ``assets``, ``requirements``, ``plugins``,
+                ``ios``, ``android``).
             project_root: Directory the config came from, used to resolve
                 relative paths.
 
@@ -382,6 +389,9 @@ class AppConfig:
         requirements = _expect_table(data, "requirements", optional=True)
         config.requirements = _opt_str_list(requirements, "packages")
 
+        plugins = _expect_table(data, "plugins", optional=True)
+        config.plugin_paths = _opt_str_list(plugins, "paths")
+
         config.validate()
         return config