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

pythonnative/sdk/__init__.py

@@ -2,46 +2,51 @@
 
 The ``pythonnative.sdk`` package collects the *stable* extension
 contract that third-party packages rely on: the
-[`ViewHandler`][pythonnative.sdk.ViewHandler] protocol, the
 [`Style`][pythonnative.sdk.Style] type, the
-[`@native_component`][pythonnative.sdk.native_component] registration
-decorator, and an
+[`@native_component`][pythonnative.sdk.native_component] /
+[`register_component`][pythonnative.sdk.register_component]
+registration helpers, the
 [`element_factory`][pythonnative.sdk.element_factory] helper for
-producing strongly-typed element constructors.
+producing strongly-typed element constructors, the
+[`ViewHandler`][pythonnative.sdk.ViewHandler] protocol for off-device
+stand-ins, and the native module registry
+([`native_module`][pythonnative.sdk.native_module],
+[`register_python_module`][pythonnative.sdk.register_python_module]).
 
 A custom native component is three things:
 
 1. A typed, frozen [`Props`][pythonnative.sdk.Props] dataclass listing
    the public properties the component accepts.
-2. One or more
-   [`ViewHandler`][pythonnative.sdk.ViewHandler] subclasses (one per
-   target platform) implementing creation, update, and child management
-   for the underlying native widget.
-3. A registration call (the
-   [`@native_component`][pythonnative.sdk.native_component] decorator,
-   or
-   [`register_component`][pythonnative.sdk.register_component] for
-   imperative use) that binds the props type and handler into the
-   process-wide registry.
+2. A Swift ``PNComponentManager`` and a Kotlin ``ComponentManager``
+   registered under the component's name by the package's native
+   plugin (``pn_plugin.json`` next to ``ios/`` and ``android/`` source
+   folders; see ``docs/guides/custom-components.md``).
+3. A registration call in Python
+   ([`register_component`][pythonnative.sdk.register_component], or the
+   [`@native_component`][pythonnative.sdk.native_component] decorator
+   when you also supply a desktop
+   [`ViewHandler`][pythonnative.sdk.ViewHandler] for ``pn preview``)
+   that declares the element name and binds its props type.
 
 Once registered, the component appears alongside the built-ins: the
 reconciler, layout engine, and Fast Refresh treat it identically.
 
-PyPI packages can ship handlers without users importing them
-explicitly by declaring an entry point in the
-``pythonnative.handlers`` group; PythonNative discovers and imports
-those modules the first time the registry is asked for a handler.
+A native module (device API without a view) follows the same split: a
+Swift / Kotlin class registered by name in the plugin, a Python facade
+that calls ``native_module(name).call(...)``, and optionally a Python
+implementation registered with ``register_python_module`` for desktop
+and tests.
+
+PyPI packages can ship both without users importing them explicitly
+by declaring entry points in the ``pythonnative.handlers`` (Python
+side) and ``pythonnative.plugins`` (native source) groups; ``pn build``
+compiles the native sources into the app.
 
 Example:
     ```python
     from dataclasses import dataclass
     import pythonnative as pn
-    from pythonnative.sdk import (
-        Props,
-        ViewHandler,
-        element_factory,
-        native_component,
-    )
+    from pythonnative.sdk import Props, element_factory, register_component
 
 
     @dataclass(frozen=True)
@@ -51,17 +56,10 @@ Example:
         style: pn.StyleProp = None
 
 
-    @native_component("Badge", props=BadgeProps, platforms=("ios",))
-    class IOSBadgeHandler(ViewHandler):
-        def create(self, props):
-            ...
-
-        def update(self, view, changed):
-            ...
-
-
+    register_component(name="Badge", props=BadgeProps)
     Badge = element_factory("Badge")
 
+
     @pn.component
     def App():
         return pn.Column(
@@ -72,6 +70,14 @@ Example:
 """
 
 from ..element import Element
+from ..native_modules.registry import (
+    NativeModule,
+    NativeModuleError,
+    PythonModule,
+    emit,
+    native_module,
+    register_python_module,
+)
 from ..native_views.base import ViewHandler, parse_color_int
 from ..style import (
     Color,
@@ -91,6 +97,7 @@ from ._components import (
     ENTRY_POINT_GROUP,
     Props,
     element_factory,
+    get_desktop_handler,
     get_props_type,
     install_into_registry,
     list_components,
@@ -122,10 +129,18 @@ __all__ = [
     "ENTRY_POINT_GROUP",
     "Props",
     "element_factory",
+    "get_desktop_handler",
     "get_props_type",
     "install_into_registry",
     "list_components",
     "native_component",
     "register_component",
     "unregister_component",
+    # Native-module SDK
+    "NativeModule",
+    "NativeModuleError",
+    "PythonModule",
+    "emit",
+    "native_module",
+    "register_python_module",
 ]

pythonnative/sdk/_components.py

@@ -4,26 +4,28 @@ Implements the [`@native_component`][pythonnative.sdk.native_component]
 decorator and supporting helpers that let third-party packages contribute
 new element types to the reconciler.
 
-The registration model is intentionally small. A custom component is a
+On device a custom component is rendered by a Swift
+``PNComponentManager`` and a Kotlin ``ComponentManager`` registered
+under the same type name by the package's native plugin (see
+``docs/guides/custom-components.md``). The Python side only needs to
+know the element name and, optionally, its typed props and a
+[`ViewHandler`][pythonnative.sdk.ViewHandler] that renders a stand-in
+in ``pn preview`` and unit tests. Registration is therefore a
 three-part agreement:
 
-1. A typed, immutable
-   [`Props`][pythonnative.sdk.Props] dataclass declaring the
-   component's public surface.
-2. One or more
-   [`ViewHandler`][pythonnative.sdk.ViewHandler] subclasses
-   (one per platform) implementing the platform-side rendering.
-3. A name (string) used by the reconciler to look up the handler.
-
-The decorator stores the (name, props_type, handler_instance) tuple
-in a process-wide registry. The
-[`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry]
-calls
+1. A typed, immutable [`Props`][pythonnative.sdk.Props] dataclass
+   declaring the component's public surface.
+2. An element factory built with
+   [`element_factory`][pythonnative.sdk.element_factory].
+3. Optionally, a desktop [`ViewHandler`][pythonnative.sdk.ViewHandler]
+   so the component also renders off device.
+
+The registry is process-wide. The view backend calls
 [`install_into_registry`][pythonnative.sdk.install_into_registry] on
 first use; that helper performs entry-point discovery (importing any
 modules registered under
 [`ENTRY_POINT_GROUP`][pythonnative.sdk.ENTRY_POINT_GROUP]) and copies
-every handler matching the active platform into the registry.
+every desktop handler into the registry.
 
 Example:
     ```python
@@ -39,10 +41,10 @@ Example:
         style: pn.StyleProp = None
 
 
-    @native_component("Badge", props=BadgeProps, platforms=("ios",))
-    class IOSBadgeHandler(ViewHandler):
+    @native_component("Badge", props=BadgeProps)
+    class BadgePreviewHandler(ViewHandler):
         def create(self, tag, props):
-            ...
+            ...  # Tkinter stand-in for pn preview
 
         def update(self, view, changed):
             ...
@@ -102,8 +104,8 @@ class Props:
 # Internal registry
 # ---------------------------------------------------------------------- #
 
-# name -> (props_type or None, {platform_name: handler_instance})
-_REGISTRY: Dict[str, Tuple[Optional[type], Dict[str, ViewHandler]]] = {}
+# name -> (props_type or None, desktop handler or None)
+_REGISTRY: Dict[str, Tuple[Optional[type], Optional[ViewHandler]]] = {}
 
 # Caches `_install_into_registry` runs to avoid repeated entry-point
 # discovery once the registry has been populated for a given platform.
@@ -117,27 +119,22 @@ def native_component(
     name: str,
     *,
     props: Optional[type] = None,
-    platforms: Optional[Tuple[str, ...]] = None,
 ) -> Callable[[Type[H]], Type[H]]:
-    """Decorator that registers a [`ViewHandler`][pythonnative.sdk.ViewHandler] under ``name``.
+    """Decorator that registers a desktop [`ViewHandler`][pythonnative.sdk.ViewHandler] under ``name``.
 
     The handler class is instantiated immediately and stored in the
-    process-wide registry. Decorate the same ``name`` once per platform
-    when shipping platform-specific implementations; the decorator
-    accumulates entries in a ``{platform: handler}`` mapping per name.
+    process-wide registry as the component's off-device renderer. The
+    on-device renderers are the Swift and Kotlin component managers the
+    package's native plugin registers under the same ``name``.
 
     Args:
-        name: Element type name (e.g., ``"Badge"``). Must be a valid
-            identifier-like string. Used by the reconciler at lookup time.
+        name: Element type name (e.g., ``"Badge"``). Used by the
+            reconciler and by native component managers at lookup time.
         props: Optional dataclass type describing the component's
             typed props. When supplied, the
             [`element_factory`][pythonnative.sdk.element_factory] helper
             uses this type to validate kwargs and produce frozen prop
             instances.
-        platforms: Tuple of platform identifiers
-            (``"ios"`` / ``"android"``) the handler implements. Defaults
-            to ``("android", "ios")`` so a single cross-platform handler
-            registers everywhere.
 
     Returns:
         A decorator that, when applied to a
@@ -147,31 +144,12 @@ def native_component(
     Raises:
         TypeError: If the decorated object is not a class subclassing
             ``ViewHandler``.
-
-    Example:
-        ```python
-        from dataclasses import dataclass
-        from pythonnative.sdk import Props, ViewHandler, native_component
-
-
-        @dataclass(frozen=True)
-        class BadgeProps(Props):
-            text: str = ""
-            color: str = "#FF3B30"
-
-
-        @native_component("Badge", props=BadgeProps, platforms=("ios",))
-        class IOSBadgeHandler(ViewHandler):
-            def create(self, tag, props):
-                ...
-        ```
     """
-    plats: Tuple[str, ...] = platforms if platforms is not None else ("android", "ios")
 
     def decorator(handler_cls: Type[H]) -> Type[H]:
         if not isinstance(handler_cls, type) or not issubclass(handler_cls, ViewHandler):
             raise TypeError(f"@native_component({name!r}) must decorate a ViewHandler subclass; got {handler_cls!r}")
-        register_component(name=name, props=props, handlers={plat: handler_cls() for plat in plats})
+        register_component(name=name, props=props, handler=handler_cls())
         return handler_cls
 
     return decorator
@@ -181,42 +159,41 @@ def register_component(
     *,
     name: str,
     props: Optional[type] = None,
-    handlers: Dict[str, ViewHandler],
+    handler: Optional[ViewHandler] = None,
 ) -> None:
     """Register a custom native component imperatively.
 
-    Equivalent to applying [`@native_component`][pythonnative.sdk.native_component]
-    one or more times, but useful when constructing handlers
-    programmatically (e.g., parameterized handler instances). Subsequent
-    calls for the same ``name`` merge their ``handlers`` into the
-    existing entry, replacing any previously-registered handler for the
-    same platform.
+    Declares ``name`` as an element type so
+    [`element_factory`][pythonnative.sdk.element_factory] can build it.
+    ``handler`` is the optional desktop / test renderer; native
+    rendering always comes from the platform component managers.
+    Subsequent calls for the same ``name`` merge: a later ``props`` or
+    ``handler`` replaces the earlier one, ``None`` leaves it alone.
 
     Args:
         name: Element type name.
         props: Optional dataclass type describing the typed props.
-        handlers: ``{platform_name: handler_instance}`` mapping. Common
-            keys are ``"ios"`` and ``"android"``.
+        handler: Optional [`ViewHandler`][pythonnative.sdk.ViewHandler]
+            instance used off device.
 
     Raises:
-        TypeError: If any handler is not a
-            [`ViewHandler`][pythonnative.sdk.ViewHandler] instance, or
+        TypeError: If ``handler`` is not a ``ViewHandler`` instance, or
             if ``props`` is not a dataclass type.
     """
     if props is not None and not (isinstance(props, type) and is_dataclass(props)):
         raise TypeError(f"register_component({name!r}): props must be a @dataclass type, got {props!r}")
-    for plat, handler in handlers.items():
-        if not isinstance(handler, ViewHandler):
-            raise TypeError(f"register_component({name!r}): handler for {plat!r} must be a ViewHandler instance")
+    if handler is not None and not isinstance(handler, ViewHandler):
+        raise TypeError(f"register_component({name!r}): handler must be a ViewHandler instance")
 
     existing = _REGISTRY.get(name)
     if existing is None:
-        _REGISTRY[name] = (props, dict(handlers))
+        _REGISTRY[name] = (props, handler)
         return
-    existing_props, plat_map = existing
-    new_props = props if props is not None else existing_props
-    plat_map.update(handlers)
-    _REGISTRY[name] = (new_props, plat_map)
+    existing_props, existing_handler = existing
+    _REGISTRY[name] = (
+        props if props is not None else existing_props,
+        handler if handler is not None else existing_handler,
+    )
 
 
 def unregister_component(name: str) -> None:
@@ -247,11 +224,17 @@ def get_props_type(name: str) -> Optional[type]:
     return entry[0] if entry is not None else None
 
 
-def install_into_registry(registry: Any, platform_name: str) -> None:
-    """Copy registered handlers into a [`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry].
+def get_desktop_handler(name: str) -> Optional[ViewHandler]:
+    """Return the registered off-device handler for ``name`` (or ``None``)."""
+    entry = _REGISTRY.get(name)
+    return entry[1] if entry is not None else None
+
+
+def install_into_registry(registry: Any) -> None:
+    """Copy registered desktop handlers into a view registry.
 
     Called once by the registry on first use. Triggers entry-point
-    discovery on the first call so PyPI-installed handlers register
+    discovery on the first call so PyPI-installed components register
     themselves before the registry snapshot is taken.
 
     Args:
@@ -259,12 +242,9 @@ def install_into_registry(registry: Any, platform_name: str) -> None:
             [`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry]
             (or duck-compatible object) with a ``register(name, handler)``
             method.
-        platform_name: The active platform identifier
-            (``"ios"`` or ``"android"``).
     """
     _discover_entry_points()
-    for name, (_props_type, plat_map) in _REGISTRY.items():
-        handler = plat_map.get(platform_name)
+    for name, (_props_type, handler) in _REGISTRY.items():
         if handler is not None:
             registry.register(name, handler)
 
@@ -418,6 +398,7 @@ __all__ = [
     "ENTRY_POINT_GROUP",
     "Props",
     "element_factory",
+    "get_desktop_handler",
     "get_props_type",
     "install_into_registry",
     "list_components",

pythonnative/storage.py

@@ -1,19 +1,19 @@
 """Cross-platform key/value persistence (``AsyncStorage``).
 
 Mirrors React Native's ``AsyncStorage`` API but with native ``async``
-coroutines and a JSON convenience layer. Values are persisted using
-the platform-appropriate key/value store:
+coroutines and a JSON convenience layer. Values are persisted by the
+native ``Storage`` module:
 
 - **iOS**: ``NSUserDefaults`` (standard user defaults).
 - **Android**: ``SharedPreferences`` (file ``"pn_async_storage"``).
 - **Desktop / tests**: an in-memory dict optionally backed by a JSON
-  file under
-  [`FileSystem.app_dir`][pythonnative.native_modules.file_system.FileSystem.app_dir]
-  for inter-run persistence during local development.
+  file under ``PN_STORAGE_DIR`` for inter-run persistence during local
+  development (see
+  [`DesktopStorage`][pythonnative.native_modules.desktop.DesktopStorage]).
 
-All operations are coroutines so they don't block the framework loop;
-the underlying native calls are dispatched via
-:func:`asyncio.to_thread`.
+Every operation is a coroutine. The platform stores answer in
+microseconds, so calls complete inline on the framework loop without
+a thread hop.
 
 Example:
     ```python
@@ -34,220 +34,16 @@ Example:
 
 from __future__ import annotations
 
-import asyncio
 import json
-import os
-import threading
 from typing import Any, Callable, List, Optional, Tuple, TypeVar
 
-from .utils import IS_ANDROID, IS_IOS
+from .native_modules.registry import NativeModule, native_module
 
 T = TypeVar("T")
 
-# ======================================================================
-# Backend selection
-# ======================================================================
 
-
-_DEFAULTS_SUITE = "pn_async_storage"
-
-
-# Cache the NSUserDefaults class lookup. rubicon.objc's
-# ``ObjCClass("NSUserDefaults")`` walks the ObjC runtime metadata which
-# takes hundreds of milliseconds on first call; resolving once at module
-# import keeps every later get/set/delete in the sub-millisecond range.
-_ios_defaults: Any = None
-
-
-def _ios_get_defaults() -> Any:
-    global _ios_defaults
-    if _ios_defaults is None:
-        from rubicon.objc import ObjCClass
-
-        _ios_defaults = ObjCClass("NSUserDefaults").standardUserDefaults
-    return _ios_defaults
-
-
-def _ios_set(key: str, value: str) -> None:
-    defaults = _ios_get_defaults()
-    defaults.setObject_forKey_(value, key)
-    # ``synchronize()`` is documented as unnecessary on modern iOS and
-    # can block for seconds while it flushes to disk on a busy system;
-    # NSUserDefaults already coalesces writes asynchronously.
-
-
-def _ios_get(key: str) -> Optional[str]:
-    defaults = _ios_get_defaults()
-    val = defaults.stringForKey_(key)
-    if val is None:
-        return None
-    try:
-        return str(val)
-    except Exception:
-        return None
-
-
-def _ios_delete(key: str) -> None:
-    defaults = _ios_get_defaults()
-    defaults.removeObjectForKey_(key)
-
-
-def _ios_all_keys() -> List[str]:
-    defaults = _ios_get_defaults()
-    rep = defaults.dictionaryRepresentation()
-    if rep is None:
-        return []
-    try:
-        keys = rep.allKeys
-        return [str(keys.objectAtIndex_(i)) for i in range(keys.count)]
-    except Exception:
-        return []
-
-
-def _ios_clear() -> None:
-    for key in _ios_all_keys():
-        _ios_delete(key)
-
-
-def _android_prefs() -> Any:
-    from java import jclass
-
-    from .utils import get_android_context
-
-    Context = jclass("android.content.Context")
-    ctx = get_android_context()
-    return ctx.getSharedPreferences(_DEFAULTS_SUITE, Context.MODE_PRIVATE)
-
-
-def _android_set(key: str, value: str) -> None:
-    prefs = _android_prefs()
-    editor = prefs.edit()
-    editor.putString(key, value)
-    editor.apply()
-
-
-def _android_get(key: str) -> Optional[str]:
-    prefs = _android_prefs()
-    if not prefs.contains(key):
-        return None
-    try:
-        return str(prefs.getString(key, None))
-    except Exception:
-        return None
-
-
-def _android_delete(key: str) -> None:
-    prefs = _android_prefs()
-    editor = prefs.edit()
-    editor.remove(key)
-    editor.apply()
-
-
-def _android_all_keys() -> List[str]:
-    prefs = _android_prefs()
-    all_map = prefs.getAll()
-    keys = all_map.keySet()
-    it = keys.iterator()
-    out: List[str] = []
-    while it.hasNext():
-        out.append(str(it.next()))
-    return out
-
-
-def _android_clear() -> None:
-    prefs = _android_prefs()
-    editor = prefs.edit()
-    editor.clear()
-    editor.apply()
-
-
-# ======================================================================
-# Desktop / test backend
-# ======================================================================
-
-
-_desktop_lock = threading.Lock()
-_desktop_store: dict = {}
-_desktop_loaded = False
-
-
-def _desktop_path() -> Optional[str]:
-    # Tests can opt out of disk persistence by leaving the env var unset.
-    base = os.environ.get("PN_STORAGE_DIR")
-    if not base:
-        return None
-    try:
-        os.makedirs(base, exist_ok=True)
-    except OSError:
-        return None
-    return os.path.join(base, "pn_async_storage.json")
-
-
-def _desktop_load() -> None:
-    global _desktop_loaded
-    if _desktop_loaded:
-        return
-    _desktop_loaded = True
-    path = _desktop_path()
-    if path is None or not os.path.exists(path):
-        return
-    try:
-        with open(path, encoding="utf-8") as f:
-            data = json.load(f)
-        if isinstance(data, dict):
-            _desktop_store.update({str(k): str(v) for k, v in data.items()})
-    except OSError:
-        return
-    except json.JSONDecodeError:
-        return
-
-
-def _desktop_persist() -> None:
-    path = _desktop_path()
-    if path is None:
-        return
-    try:
-        with open(path, "w", encoding="utf-8") as f:
-            json.dump(_desktop_store, f)
-    except OSError:
-        pass
-
-
-def _desktop_set(key: str, value: str) -> None:
-    with _desktop_lock:
-        _desktop_load()
-        _desktop_store[key] = value
-        _desktop_persist()
-
-
-def _desktop_get(key: str) -> Optional[str]:
-    with _desktop_lock:
-        _desktop_load()
-        return _desktop_store.get(key)
-
-
-def _desktop_delete(key: str) -> None:
-    with _desktop_lock:
-        _desktop_load()
-        _desktop_store.pop(key, None)
-        _desktop_persist()
-
-
-def _desktop_all_keys() -> List[str]:
-    with _desktop_lock:
-        _desktop_load()
-        return list(_desktop_store.keys())
-
-
-def _desktop_clear() -> None:
-    with _desktop_lock:
-        _desktop_store.clear()
-        _desktop_persist()
-
-
-# ======================================================================
-# Public API
-# ======================================================================
+def _storage() -> NativeModule:
+    return native_module("Storage")
 
 
 class AsyncStorage:
@@ -265,11 +61,8 @@ class AsyncStorage:
     @staticmethod
     async def get(key: str) -> Optional[str]:
         """Return the string stored at ``key``, or ``None`` if missing."""
-        if IS_IOS:
-            return await asyncio.to_thread(_ios_get, key)
-        if IS_ANDROID:
-            return await asyncio.to_thread(_android_get, key)
-        return await asyncio.to_thread(_desktop_get, key)
+        value = _storage().call("get", key=key)
+        return None if value is None else str(value)
 
     @staticmethod
     async def set(key: str, value: str) -> None:
@@ -280,41 +73,23 @@ class AsyncStorage:
         """
         if not isinstance(value, str):
             raise TypeError("AsyncStorage.set requires a str value; use set_json for richer types")
-        if IS_IOS:
-            await asyncio.to_thread(_ios_set, key, value)
-        elif IS_ANDROID:
-            await asyncio.to_thread(_android_set, key, value)
-        else:
-            await asyncio.to_thread(_desktop_set, key, value)
+        _storage().call("set", key=key, value=value)
 
     @staticmethod
     async def delete(key: str) -> None:
         """Remove the entry at ``key`` if present (no-op otherwise)."""
-        if IS_IOS:
-            await asyncio.to_thread(_ios_delete, key)
-        elif IS_ANDROID:
-            await asyncio.to_thread(_android_delete, key)
-        else:
-            await asyncio.to_thread(_desktop_delete, key)
+        _storage().call("delete", key=key)
 
     @staticmethod
     async def all_keys() -> List[str]:
         """Return every persisted key (order is platform-dependent)."""
-        if IS_IOS:
-            return await asyncio.to_thread(_ios_all_keys)
-        if IS_ANDROID:
-            return await asyncio.to_thread(_android_all_keys)
-        return await asyncio.to_thread(_desktop_all_keys)
+        keys = _storage().call("all_keys")
+        return [str(k) for k in keys] if isinstance(keys, list) else []
 
     @staticmethod
     async def clear() -> None:
         """Remove every entry written through ``AsyncStorage``."""
-        if IS_IOS:
-            await asyncio.to_thread(_ios_clear)
-        elif IS_ANDROID:
-            await asyncio.to_thread(_android_clear)
-        else:
-            await asyncio.to_thread(_desktop_clear)
+        _storage().call("clear")
 
     @staticmethod
     async def get_json(key: str) -> Any: