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

pythonnative/project/plugins.py

@@ -0,0 +1,366 @@
+"""Native plugin staging for ``pn build``.
+
+A PyPI package can ship Swift and Kotlin next to its Python facade. It
+declares an entry point in the ``pythonnative.plugins`` group whose
+value is an importable package directory containing:
+
+```text
+my_blur/native/
+    pn_plugin.json
+    ios/BlurViewManager.swift
+    android/com/example/myblur/BlurViewManager.kt
+```
+
+``pn_plugin.json`` names the registration entry on each platform:
+
+```json
+{"ios": {"entry": "MyBlurPlugin"}, "android": {"entry": "com.example.myblur.MyBlurPlugin"}}
+```
+
+At build time this module copies each plugin's sources into the staged
+native project (``PythonNativeKit/Sources/PythonNativeKit/Plugins/<name>``
+on iOS, ``pythonnative/src/main/java`` on Android) and regenerates the
+registration file that calls every entry's ``register``. SwiftPM and
+Gradle compile whatever lands under those roots, so no project-file
+surgery is needed.
+
+Projects can also bundle plugins that aren't installed as distributions
+by listing directories under ``[plugins].paths`` in ``pythonnative.toml``;
+each path must contain the same ``pn_plugin.json`` layout.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from dataclasses import dataclass, field
+from importlib import import_module
+from pathlib import Path
+from typing import Callable, Dict, Iterable, List, Optional, Sequence
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "MANIFEST_NAME",
+    "NativePlugin",
+    "PluginError",
+    "discover_plugins",
+    "load_plugin",
+    "stage_android_plugins",
+    "stage_ios_plugins",
+]
+
+ENTRY_POINT_GROUP = "pythonnative.plugins"
+"""Entry-point group whose values name plugin directories (as packages)."""
+
+MANIFEST_NAME = "pn_plugin.json"
+"""File name of the per-plugin manifest."""
+
+Logger = Callable[[str], None]
+
+_IOS_PLUGIN_DIR = ("PythonNativeKit", "Sources", "PythonNativeKit", "Plugins")
+_IOS_REGISTRATION = (*_IOS_PLUGIN_DIR, "PNPluginRegistration.swift")
+_ANDROID_SOURCE_ROOT = ("pythonnative", "src", "main", "java")
+_ANDROID_REGISTRATION = (*_ANDROID_SOURCE_ROOT, "com", "pythonnative", "runtime", "plugins", "GeneratedPlugins.kt")
+
+_SWIFT_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_KOTLIN_FQN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)+$")
+
+
+class PluginError(RuntimeError):
+    """A plugin manifest or source layout is invalid."""
+
+
+@dataclass(frozen=True)
+class NativePlugin:
+    """A discovered native plugin.
+
+    Attributes:
+        name: Stable identifier (the entry-point name or the directory
+            name for path plugins). Used for the iOS subfolder.
+        root: Directory containing ``pn_plugin.json``.
+        ios_entry: Swift type conforming to ``PNPlugin``, or ``None``
+            when the plugin has no iOS side.
+        android_entry: Fully qualified Kotlin object implementing
+            ``PNPlugin``, or ``None`` when the plugin has no Android side.
+        ios_sources: Swift files under ``ios/``.
+        android_sources: Kotlin files under ``android/`` (relative
+            paths are preserved so packages land in the right folders).
+    """
+
+    name: str
+    root: Path
+    ios_entry: Optional[str] = None
+    android_entry: Optional[str] = None
+    ios_sources: Sequence[Path] = field(default_factory=tuple)
+    android_sources: Sequence[Path] = field(default_factory=tuple)
+
+    @property
+    def has_ios(self) -> bool:
+        """Whether this plugin contributes Swift code."""
+        return self.ios_entry is not None
+
+    @property
+    def has_android(self) -> bool:
+        """Whether this plugin contributes Kotlin code."""
+        return self.android_entry is not None
+
+
+# ======================================================================
+# Discovery
+# ======================================================================
+
+
+def load_plugin(root: Path, *, name: Optional[str] = None) -> NativePlugin:
+    """Read ``pn_plugin.json`` under ``root`` and collect its sources.
+
+    Args:
+        root: Directory containing the manifest.
+        name: Identifier override (defaults to the directory name).
+
+    Returns:
+        The parsed plugin.
+
+    Raises:
+        PluginError: If the manifest is missing or malformed, or an
+            entry is declared without any matching sources.
+    """
+    root = Path(root).resolve()
+    manifest_path = root / MANIFEST_NAME
+    if not manifest_path.is_file():
+        raise PluginError(f"{root} has no {MANIFEST_NAME}.")
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise PluginError(f"Could not parse {manifest_path}: {exc}") from exc
+    if not isinstance(manifest, dict):
+        raise PluginError(f"{manifest_path} must contain a JSON object.")
+
+    plugin_name = name or manifest.get("name") or root.name
+    if not _SWIFT_IDENT.match(str(plugin_name).replace("-", "_")):
+        raise PluginError(f"Plugin name {plugin_name!r} must be an identifier.")
+    plugin_name = str(plugin_name).replace("-", "_")
+
+    ios_entry = _entry(manifest, "ios", manifest_path)
+    android_entry = _entry(manifest, "android", manifest_path)
+    if ios_entry is None and android_entry is None:
+        raise PluginError(f"{manifest_path} declares neither an 'ios' nor an 'android' entry.")
+
+    ios_sources: List[Path] = []
+    android_sources: List[Path] = []
+    if ios_entry is not None:
+        if not _SWIFT_IDENT.match(ios_entry):
+            raise PluginError(f"{manifest_path}: ios.entry {ios_entry!r} is not a Swift type name.")
+        ios_sources = sorted(p.relative_to(root) for p in (root / "ios").rglob("*.swift") if p.is_file())
+        if not ios_sources:
+            raise PluginError(f"{root} declares an iOS entry but ios/ contains no .swift files.")
+    if android_entry is not None:
+        if not _KOTLIN_FQN.match(android_entry):
+            raise PluginError(f"{manifest_path}: android.entry {android_entry!r} must be a fully qualified name.")
+        android_sources = sorted(
+            p.relative_to(root) for p in (root / "android").rglob("*") if p.is_file() and p.suffix in (".kt", ".java")
+        )
+        if not android_sources:
+            raise PluginError(f"{root} declares an Android entry but android/ contains no .kt or .java files.")
+
+    return NativePlugin(
+        name=plugin_name,
+        root=root,
+        ios_entry=ios_entry,
+        android_entry=android_entry,
+        ios_sources=tuple(ios_sources),
+        android_sources=tuple(android_sources),
+    )
+
+
+def _entry(manifest: Dict[str, object], platform: str, manifest_path: Path) -> Optional[str]:
+    section = manifest.get(platform)
+    if section is None:
+        return None
+    if not isinstance(section, dict) or not isinstance(section.get("entry"), str):
+        raise PluginError(f"{manifest_path}: '{platform}' must be an object with a string 'entry'.")
+    return str(section["entry"])
+
+
+def discover_plugins(
+    *,
+    extra_paths: Iterable[Path] = (),
+    log: Optional[Logger] = None,
+) -> List[NativePlugin]:
+    """Find every plugin visible to this interpreter.
+
+    Args:
+        extra_paths: Plugin directories to include in addition to the
+            ``pythonnative.plugins`` entry points (from
+            ``[plugins].paths`` in the project config).
+        log: Optional progress logger; broken entry points are reported
+            here and skipped rather than failing the build.
+
+    Returns:
+        Plugins in a stable order (entry points sorted by name, then
+        explicit paths in the order given).
+    """
+    emit: Logger = log or (lambda _message: None)
+    plugins: List[NativePlugin] = []
+    seen: set = set()
+
+    for ep_name, target in sorted(_entry_points().items()):
+        try:
+            root = _resolve_entry_point(target)
+            plugin = load_plugin(root, name=ep_name)
+        except (PluginError, ImportError, AttributeError) as exc:
+            emit(f"Skipping native plugin {ep_name!r}: {exc}")
+            continue
+        if plugin.name in seen:
+            emit(f"Skipping duplicate native plugin {plugin.name!r}.")
+            continue
+        seen.add(plugin.name)
+        plugins.append(plugin)
+
+    for path in extra_paths:
+        plugin = load_plugin(Path(path))
+        if plugin.name in seen:
+            raise PluginError(f"Native plugin {plugin.name!r} is declared twice.")
+        seen.add(plugin.name)
+        plugins.append(plugin)
+
+    return plugins
+
+
+def _entry_points() -> Dict[str, str]:
+    try:
+        from importlib.metadata import entry_points
+    except ImportError:  # pragma: no cover - Python < 3.8
+        return {}
+    try:
+        eps = entry_points()
+    except Exception:
+        return {}
+    selected = []
+    if hasattr(eps, "select"):
+        selected = list(eps.select(group=ENTRY_POINT_GROUP))
+    else:  # pragma: no cover - importlib.metadata < 3.10
+        getter = getattr(eps, "get", None)
+        if callable(getter):
+            selected = list(getter(ENTRY_POINT_GROUP, []))
+    return {ep.name: ep.value for ep in selected}
+
+
+def _resolve_entry_point(target: str) -> Path:
+    """Turn ``"pkg.subpkg"`` (or ``"pkg.subpkg:attr"``) into a directory."""
+    module_name, _, attr = target.partition(":")
+    module = import_module(module_name.strip())
+    if attr:
+        value = getattr(module, attr.strip())
+        return Path(str(value))
+    location = getattr(module, "__file__", None)
+    if location is None:
+        raise PluginError(f"{module_name!r} is a namespace package; point the entry point at a regular package.")
+    return Path(location).resolve().parent
+
+
+# ======================================================================
+# Staging
+# ======================================================================
+
+
+def stage_ios_plugins(project_dir: Path, plugins: Sequence[NativePlugin], *, log: Optional[Logger] = None) -> None:
+    """Copy Swift sources into ``PythonNativeKit`` and write the registration file.
+
+    Args:
+        project_dir: The staged ``ios_template`` directory.
+        plugins: Plugins to bundle; ones without an iOS side are skipped.
+        log: Optional progress logger.
+    """
+    emit: Logger = log or (lambda _message: None)
+    plugins_dir = Path(project_dir).joinpath(*_IOS_PLUGIN_DIR)
+    registration = Path(project_dir).joinpath(*_IOS_REGISTRATION)
+    plugins_dir.mkdir(parents=True, exist_ok=True)
+
+    # Wipe previous plugin folders so removed plugins don't linger in an
+    # incremental build directory; the registration file is regenerated.
+    for child in plugins_dir.iterdir():
+        if child.is_dir():
+            shutil.rmtree(child)
+
+    bundled = [p for p in plugins if p.has_ios]
+    for plugin in bundled:
+        target = plugins_dir / plugin.name
+        for rel in plugin.ios_sources:
+            dest = target / Path(*rel.parts[1:])  # strip the leading "ios/"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(plugin.root / rel, dest)
+    registration.write_text(_render_swift_registration(bundled), encoding="utf-8")
+    if bundled:
+        emit(
+            f"Bundled {len(bundled)} native plugin(s) into PythonNativeKit: " + ", ".join(p.name for p in bundled) + "."
+        )
+
+
+def stage_android_plugins(project_dir: Path, plugins: Sequence[NativePlugin], *, log: Optional[Logger] = None) -> None:
+    """Copy Kotlin sources into the ``pythonnative`` module and write the registration file.
+
+    Args:
+        project_dir: The staged ``android_template`` directory.
+        plugins: Plugins to bundle; ones without an Android side are skipped.
+        log: Optional progress logger.
+    """
+    emit: Logger = log or (lambda _message: None)
+    source_root = Path(project_dir).joinpath(*_ANDROID_SOURCE_ROOT)
+    registration = Path(project_dir).joinpath(*_ANDROID_REGISTRATION)
+    source_root.mkdir(parents=True, exist_ok=True)
+
+    bundled = [p for p in plugins if p.has_android]
+    for plugin in bundled:
+        for rel in plugin.android_sources:
+            dest = source_root / Path(*rel.parts[1:])  # strip the leading "android/"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(plugin.root / rel, dest)
+    registration.parent.mkdir(parents=True, exist_ok=True)
+    registration.write_text(_render_kotlin_registration(bundled), encoding="utf-8")
+    if bundled:
+        emit(
+            f"Bundled {len(bundled)} native plugin(s) into the pythonnative module: "
+            + ", ".join(p.name for p in bundled)
+            + "."
+        )
+
+
+def _render_swift_registration(plugins: Sequence[NativePlugin]) -> str:
+    calls = "".join(f"        {p.ios_entry}.register(into: registry)\n" for p in plugins)
+    body = f" {{\n{calls}    }}" if calls else " {}"
+    return (
+        "// Generated by `pn build`. Do not edit: the PythonNative build tool\n"
+        "// overwrites this file with one `register(into:)` call per bundled plugin.\n"
+        "\n"
+        "/// Registration hook for plugins copied into `Sources/Plugins` by `pn build`.\n"
+        "public enum PNGeneratedPlugins {\n"
+        "    /// Register every generated plugin into `registry`.\n"
+        f"    public static func registerAll(into registry: PNRegistry){body}\n"
+        "}\n"
+    )
+
+
+def _render_kotlin_registration(plugins: Sequence[NativePlugin]) -> str:
+    calls = "".join(f"        {p.android_entry}.register(registry)\n" for p in plugins)
+    if calls:
+        method = f"    fun registerAll(registry: PNRegistry) {{\n{calls}    }}\n"
+    else:
+        method = '    @Suppress("UNUSED_PARAMETER")\n    fun registerAll(registry: PNRegistry) {}\n'
+    return (
+        "package com.pythonnative.runtime.plugins\n"
+        "\n"
+        "import com.pythonnative.runtime.bridge.PNRegistry\n"
+        "\n"
+        "/**\n"
+        " * Plugin registrations generated by `pn build`.\n"
+        " *\n"
+        " * The build tool overwrites this file with one `register` call per\n"
+        " * plugin entry declared in the project's `pythonnative.plugins` entry\n"
+        " * points. Nothing else may depend on its content beyond [registerAll].\n"
+        " */\n"
+        "object GeneratedPlugins {\n"
+        "    /** Register every generated plugin with `registry`. */\n"
+        f"{method}"
+        "}\n"
+    )

pythonnative/runtime.py

@@ -47,12 +47,10 @@ Example:
 from __future__ import annotations
 
 import asyncio
-import ctypes
-import ctypes.util
 import inspect
 import threading
 import time as _time
-from typing import Any, Awaitable, Callable, Coroutine, Dict, Optional, TypeVar, Union
+from typing import Any, Awaitable, Callable, Coroutine, Optional, TypeVar, Union
 
 T = TypeVar("T")
 
@@ -463,28 +461,41 @@ def _has_pump_dispatcher() -> bool:
 
 
 def _dispatch_to_main_queue(fn: Callable[[], None]) -> None:
-    """Enqueue ``fn`` on the platform main queue (never runs inline)."""
+    """Enqueue ``fn`` on the platform main queue (never runs inline).
+
+    On device this is the bridge's
+    [`post_to_main`][pythonnative.bridge.post_to_main]: native schedules
+    a ``pump`` callback on the next main-queue turn and Python drains
+    its queue then. Off device the ``pn preview`` dispatcher takes it;
+    headless tests have no dispatcher and drive the loop with
+    [`drain`][pythonnative.runtime.drain] instead.
+    """
     from .platform import Platform
 
-    if Platform.is_ios:
-        _ios_dispatch_async(fn)
-    elif Platform.is_android:
-        _android_post_to_main(fn)
+    if Platform.is_ios or Platform.is_android:
+        from .bridge import post_to_main
+
+        post_to_main(fn)
     elif _desktop_main_dispatch is not None:
         _desktop_main_dispatch(fn)
-    # Headless: nothing to dispatch to; drain()/run_blocking() pump.
+
+
+def _is_main_thread() -> bool:
+    """Whether the calling thread is the platform main thread.
+
+    Python is initialized on the platform main thread by both app
+    templates, so ``threading.main_thread()`` is the UIKit / Android
+    main thread on device.
+    """
+    return threading.current_thread() is threading.main_thread()
 
 
 def call_on_main_thread(fn: Callable[[], None]) -> None:
     """Run ``fn()`` on the platform UI thread.
 
-    - **iOS**: dispatches ``fn`` onto the main dispatch queue via
-      ``libdispatch.dispatch_async_f`` (called through
-      :class:`ctypes.PyDLL` to keep the GIL held), or runs inline when
-      already on the main thread.
-    - **Android**: posts a ``Runnable`` to
-      ``Handler(Looper.getMainLooper())``, or runs inline on the main
-      looper thread.
+    - **iOS / Android**: runs inline when already on the main thread,
+      otherwise queues ``fn`` through the bridge (one native crossing
+      per batch of queued callables).
     - **Desktop**: enqueues ``fn`` for the ``pn preview`` poll loop
       (or runs inline if no preview is live).
     - **Tests**: runs ``fn()`` inline.
@@ -498,199 +509,20 @@ def call_on_main_thread(fn: Callable[[], None]) -> None:
     """
     from .platform import Platform
 
-    if Platform.is_ios:
-        _ios_call_on_main(fn)
-    elif Platform.is_android:
-        _android_call_on_main(fn)
+    if Platform.is_ios or Platform.is_android:
+        if _is_main_thread():
+            try:
+                fn()
+            except Exception as exc:
+                print(f"[pn.runtime] main-inline callback raised: {exc!r}")
+            return
+        _dispatch_to_main_queue(fn)
     elif Platform.is_desktop and _desktop_main_dispatch is not None:
         _desktop_main_dispatch(fn)
     else:
         fn()
 
 
-# ----------------------------------------------------------------------
-# iOS main-queue dispatch (PyDLL-based, no GIL release)
-# ----------------------------------------------------------------------
-#
-# rubicon-objc loads libobjc via ctypes.CDLL, which RELEASES THE GIL
-# around every ObjC method call. On the iOS simulator (and to a lesser
-# extent on-device), a thread is then parked by the kernel until the
-# next wakeup-coalescing tick (~500ms), making cross-thread ObjC calls
-# absurdly slow. To avoid this, we call libdispatch's
-# ``dispatch_async_f`` directly via ``ctypes.PyDLL`` (which keeps the
-# GIL held), and pass a ``CFUNCTYPE`` trampoline as the work function.
-# The trampoline runs on the main thread, looks up the pending Python
-# callable by an integer key, and invokes it.
-
-_dispatch_lib: Optional[Any] = None
-_dispatch_async_f_c: Optional[Any] = None
-_dispatch_main_q_ptr: int = 0
-_DISPATCH_FN_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p)
-_main_pending: Dict[int, Callable[[], None]] = {}
-_main_pending_lock = threading.Lock()
-_main_next_id: int = 0
-
-
-def _main_trampoline_py(ctx: int) -> None:
-    """Run on the main thread; pop the queued callable and call it."""
-    with _main_pending_lock:
-        fn = _main_pending.pop(ctx, None)
-    if fn is None:
-        return
-    try:
-        fn()
-    except Exception as exc:
-        print(f"[pn.runtime] main-thread trampoline raised: {exc!r}")
-
-
-# Keep a strong reference to the C-callable trampoline forever; if it
-# gets GC'd while libdispatch holds the function pointer, we crash.
-_main_trampoline_c = _DISPATCH_FN_TYPE(_main_trampoline_py)
-
-
-def _ensure_libdispatch_loaded() -> bool:
-    """Locate libdispatch + the main queue. Returns True on success."""
-    global _dispatch_lib, _dispatch_async_f_c, _dispatch_main_q_ptr
-    if _dispatch_lib is not None:
-        return True
-    try:
-        # PyDLL keeps the GIL held during C calls, preventing the
-        # calling thread from being parked after dispatch_async_f.
-        lib = ctypes.PyDLL("/usr/lib/system/libdispatch.dylib")
-    except OSError:
-        try:
-            lib = ctypes.PyDLL(None)  # main program (libdispatch is in libSystem)
-        except OSError as exc:
-            print(f"[pn.runtime] could not load libdispatch via PyDLL: {exc!r}")
-            return False
-    try:
-        fn = lib.dispatch_async_f
-        fn.restype = None
-        fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p]
-        # The main queue is a struct global named ``_dispatch_main_q``
-        # in libdispatch. dispatch_async_f wants a pointer to it.
-        sym = ctypes.c_void_p.in_dll(lib, "_dispatch_main_q")
-        main_q_ptr = ctypes.addressof(sym)
-    except (AttributeError, ValueError) as exc:
-        print(f"[pn.runtime] libdispatch missing expected symbol: {exc!r}")
-        return False
-    _dispatch_lib = lib
-    _dispatch_async_f_c = fn
-    _dispatch_main_q_ptr = main_q_ptr
-    return True
-
-
-_pthread_main_np_c: Optional[Any] = None
-
-
-def _ios_is_main_thread() -> bool:
-    """Cheap main-thread check using pthread_main_np (no GIL release)."""
-    try:
-        # pthread_main_np is in libc; calling via PyDLL keeps the GIL.
-        global _pthread_main_np_c
-        if _pthread_main_np_c is None:
-            libc = ctypes.PyDLL(ctypes.util.find_library("c") or "/usr/lib/libc.dylib")
-            f = libc.pthread_main_np
-            f.restype = ctypes.c_int
-            f.argtypes = []
-            _pthread_main_np_c = f
-        return bool(_pthread_main_np_c())
-    except Exception:
-        # Fall back to threading module (Python-side check).
-        return threading.current_thread().name == "MainThread"
-
-
-def _ios_dispatch_async(fn: Callable[[], None]) -> None:
-    """Enqueue ``fn`` on the iOS main dispatch queue (always queued)."""
-    global _main_next_id
-    if not _ensure_libdispatch_loaded():
-        print("[pn.runtime] libdispatch unavailable; running callback inline")
-        try:
-            fn()
-        except Exception as exc:
-            print(f"[pn.runtime] inline fallback raised: {exc!r}")
-        return
-    with _main_pending_lock:
-        _main_next_id += 1
-        key = _main_next_id
-        _main_pending[key] = fn
-    # dispatch_async_f(queue, context, work): non-blocking; just
-    # enqueues the work onto the main queue and returns.
-    assert _dispatch_async_f_c is not None
-    _dispatch_async_f_c(_dispatch_main_q_ptr, key, _main_trampoline_c)
-
-
-def _ios_call_on_main(fn: Callable[[], None]) -> None:
-    """Run ``fn`` on the iOS main thread (inline when already there)."""
-    if _ios_is_main_thread():
-        try:
-            fn()
-        except Exception as exc:
-            print(f"[pn.runtime] main-inline callback raised: {exc!r}")
-        return
-    _ios_dispatch_async(fn)
-
-
-# Cached Android main-queue plumbing. Posting a pump is a hot path (it
-# runs for every batch of scheduled loop work), so the Runnable proxy
-# class and the main-looper Handler are created once and reused;
-# defining a ``dynamic_proxy`` class per call would register a new JNI
-# class every time.
-_android_runnable_cls: Optional[Any] = None
-_android_main_handler: Optional[Any] = None
-
-
-def _ensure_android_main_handler() -> Any:
-    global _android_runnable_cls, _android_main_handler
-    if _android_main_handler is not None:
-        return _android_main_handler
-    from java import dynamic_proxy, jclass
-
-    Runnable = jclass("java.lang.Runnable")
-
-    class _PNMainRunnable(dynamic_proxy(Runnable)):  # type: ignore[misc]
-        def __init__(self, fn: Callable[[], None]) -> None:
-            super().__init__()
-            self._fn = fn
-
-        def run(self) -> None:
-            try:
-                self._fn()
-            except Exception as exc:  # pragma: no cover - last resort
-                print(f"[pn.runtime] main-thread runnable raised: {exc!r}")
-
-    Looper = jclass("android.os.Looper")
-    Handler = jclass("android.os.Handler")
-    _android_runnable_cls = _PNMainRunnable
-    _android_main_handler = Handler(Looper.getMainLooper())
-    return _android_main_handler
-
-
-def _android_post_to_main(fn: Callable[[], None]) -> None:
-    """Enqueue ``fn`` on the Android main looper (always queued)."""
-    try:
-        handler = _ensure_android_main_handler()
-        assert _android_runnable_cls is not None
-        handler.post(_android_runnable_cls(fn))
-    except Exception as exc:
-        print(f"[pn.runtime] _android_post_to_main failed, falling back inline: {exc!r}")
-        fn()
-
-
-def _android_call_on_main(fn: Callable[[], None]) -> None:
-    """Run ``fn`` on the Android main thread (inline when already there)."""
-    try:
-        from java import jclass
-
-        Looper = jclass("android.os.Looper")
-        if Looper.myLooper() == Looper.getMainLooper():
-            fn()
-            return
-    except Exception:
-        pass
-    _android_post_to_main(fn)
-
-
 __all__ = [
     "call_on_main_thread",
     "call_threadsafe",