pythonnative/src/pythonnative/sdk/_components.py at main · pythonnative/pythonnative

429 lines (340 loc) · 14.3 KB
"""Custom native-component registration.
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
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]
[`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.
    ```python
    from dataclasses import dataclass
    import pythonnative as pn
    from pythonnative.sdk import Props, ViewHandler, element_factory, native_component
    @dataclass(frozen=True)
    class BadgeProps(Props):
        text: str = ""
        color: str = "#FF3B30"
        style: pn.StyleProp = None
    @native_component("Badge", props=BadgeProps, platforms=("ios",))
    class IOSBadgeHandler(ViewHandler):
        def create(self, props):
        def update(self, view, changed):
    Badge = element_factory("Badge")
from dataclasses import dataclass, fields, is_dataclass
from typing import Any, Callable, Dict, List, Optional, Tuple, Type, TypeVar
from ..element import Element
from ..native_views.base import ViewHandler
ENTRY_POINT_GROUP = "pythonnative.handlers"
"""Entry-point group used by PyPI packages to register native handlers.
Packages declare entries like:
[project.entry-points."pythonnative.handlers"]
my_blur = "my_pkg.blur:register"
PythonNative imports the referenced module the first time the
[`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry] is
materialized; the decorators inside that module populate the registry
during import.
@dataclass(frozen=True)
class Props:
    """Optional base class for typed prop dataclasses.
    Subclassing is not strictly required (any
    ``@dataclass(frozen=True)`` works), but inheriting from
    ``Props`` gives third-party components a clear, searchable marker
    in their public API and a stable place to add framework-wide
    behavior in the future.
    Example:
        ```python
        from dataclasses import dataclass
        from pythonnative.sdk import Props
        @dataclass(frozen=True)
        class BadgeProps(Props):
            text: str = ""
            color: str = "#FF3B30"
        ```
# ---------------------------------------------------------------------- #
# Internal registry
# ---------------------------------------------------------------------- #
# name -> (props_type or None, {platform_name: handler_instance})
_REGISTRY: Dict[str, Tuple[Optional[type], Dict[str, ViewHandler]]] = {}
# Caches `_install_into_registry` runs to avoid repeated entry-point
# discovery once the registry has been populated for a given platform.
_DISCOVERED: bool = False
H = TypeVar("H", bound=ViewHandler)
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``.
    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.
        name: Element type name (e.g., ``"Badge"``). Must be a valid
            identifier-like string. Used by the reconciler 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
        [`ViewHandler`][pythonnative.sdk.ViewHandler] subclass, registers
        it and returns the class unchanged.
    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, 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; " f"got {handler_cls!r}"
        register_component(name=name, props=props, handlers={plat: handler_cls() for plat in plats})
        return handler_cls
    return decorator
def register_component(
    name: str,
    props: Optional[type] = None,
    handlers: Dict[str, ViewHandler],
    """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.
        name: Element type name.
        props: Optional dataclass type describing the typed props.
        handlers: ``{platform_name: handler_instance}`` mapping. Common
            keys are ``"ios"`` and ``"android"``.
    Raises:
        TypeError: If any handler is not a
            [`ViewHandler`][pythonnative.sdk.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")
    existing = _REGISTRY.get(name)
    if existing is None:
        _REGISTRY[name] = (props, dict(handlers))
        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)
def unregister_component(name: str) -> None:
    """Remove a previously-registered component (primarily for tests).
        name: The element type name to unregister.
    _REGISTRY.pop(name, None)
def list_components() -> List[str]:
    """Return the names of every registered custom component.
    Useful for diagnostics and tests.
    Returns:
        Sorted list of names registered via
        [`@native_component`][pythonnative.sdk.native_component] or
        [`register_component`][pythonnative.sdk.register_component].
    return sorted(_REGISTRY)
def get_props_type(name: str) -> Optional[type]:
    """Return the registered props dataclass for ``name`` (or ``None``)."""
    entry = _REGISTRY.get(name)
    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].
    Called once by the registry on first use. Triggers entry-point
    discovery on the first call so PyPI-installed handlers register
    themselves before the registry snapshot is taken.
        registry: A
            [`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)
        if handler is not None:
            registry.register(name, handler)
def _discover_entry_points() -> None:
    """Import every module registered under ``ENTRY_POINT_GROUP``.
    Idempotent and safe to call repeatedly; the actual discovery only
    runs once per process. Exceptions raised by individual entry points
    are swallowed (with the offending name printed to stderr) so a
    single broken plugin never prevents the rest of the process from
    rendering.
    global _DISCOVERED
    if _DISCOVERED:
        return
    _DISCOVERED = True
        from importlib.metadata import entry_points
    except ImportError:
        return
        eps = entry_points()
    except Exception:
        return
    # importlib.metadata's API changed across Python versions; both
    # ``select`` and direct ``.get`` are normalized here.
    selected: List[Any] = []
    if hasattr(eps, "select"):
        try:
            selected = list(eps.select(group=ENTRY_POINT_GROUP))
        except Exception:
            selected = []
    if not selected:
        try:
            getter = getattr(eps, "get", None)
            if getter is not None:
                selected = list(getter(ENTRY_POINT_GROUP, []))
        except Exception:
            selected = []
    for ep in selected:
        name = getattr(ep, "name", "?")
        try:
            ep.load()
        except Exception as exc:  # pragma: no cover - defensive
            import sys
            print(
                f"[pythonnative.sdk] Failed to load handler entry point {name!r}: {exc!r}",
                file=sys.stderr,
                flush=True,
def _reset_discovery_state_for_tests() -> None:
    """Reset the entry-point discovery flag (for tests only)."""
    global _DISCOVERED
    _DISCOVERED = False
# ---------------------------------------------------------------------- #
# Element factories
# ---------------------------------------------------------------------- #
def _props_to_dict(value: Any) -> Dict[str, Any]:
    """Convert a typed props dataclass to a flat dict of non-None fields."""
    if isinstance(value, dict):
        return {k: v for k, v in value.items() if v is not None}
    if is_dataclass(value):
        out: Dict[str, Any] = {}
        for f in fields(value):
            field_value = getattr(value, f.name)
            if field_value is not None:
                out[f.name] = field_value
        return out
    raise TypeError(f"Expected a dataclass instance or dict, got {type(value).__name__!r}")
def element_factory(name: str) -> Callable[..., Element]:
    """Return a callable that builds [`Element`][pythonnative.Element] instances of type ``name``.
    The returned factory accepts:
    - Children as positional arguments (any number).
    - ``key=`` (optional, keyword-only) for keyed reconciliation.
    - Either ``props=`` (a dataclass instance) or per-field keyword
      arguments matching the registered props dataclass.
    If no ``props`` dataclass was registered for ``name``, kwargs flow
    through unmodified — useful when iterating before locking down a
    prop schema.
        name: An element type name previously registered via
            [`@native_component`][pythonnative.sdk.native_component] or
            [`register_component`][pythonnative.sdk.register_component].
    Returns:
        A callable producing fresh
        [`Element`][pythonnative.Element] instances of type ``name``.
    Raises:
        KeyError: If ``name`` is not registered.
    Example:
        ```python
        Badge = element_factory("Badge")
        Badge(text="3", color="#0A84FF")
        Badge(props=BadgeProps(text="3"))
        ```
    if name not in _REGISTRY:
        raise KeyError(
            f"No component registered under name {name!r}. " "Use @native_component or register_component first."
    def factory(*children: Element, key: Optional[str] = None, props: Any = None, **kwargs: Any) -> Element:
        props_type = get_props_type(name)
        if props is not None:
            if kwargs:
                raise TypeError("Pass either props=... or keyword props, not both")
            props_dict = _props_to_dict(props)
        elif props_type is not None:
            try:
                instance = props_type(**kwargs)
            except TypeError as exc:
                raise TypeError(f"Invalid props for {name!r}: {exc}") from exc
            props_dict = _props_to_dict(instance)
        else:
            props_dict = dict(kwargs)
        # Style props pass through resolve_style at the boundary so list
        # forms / None get flattened identically to built-in factories.
        from ..style import resolve_style as _resolve
        style_value = props_dict.pop("style", None)
        style_dict = _resolve(style_value)
        merged: Dict[str, Any] = {**style_dict, **props_dict}
        return Element(name, merged, list(children), key=key)
    factory.__name__ = name
    factory.__doc__ = f"Construct an Element of type {name!r}."
    return factory
__all__ = [
    "ENTRY_POINT_GROUP",
    "Props",
    "element_factory",
    "get_props_type",
    "install_into_registry",
    "list_components",
    "native_component",
    "register_component",
    "unregister_component",
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

_components.py

Latest commit

History

_components.py

File metadata and controls
