pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/sdk/_components.py

@@ -0,0 +1,427 @@
+"""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.
+
+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 unit tests (the browser preview draws unknown types as labeled
+placeholders). Registration is therefore a three-part agreement:
+
+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 test [`ViewHandler`][pythonnative.sdk.ViewHandler]
+   so the component also renders under the Python test backend.
+
+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 test handler into the registry.
+
+Example:
+    ```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)
+    class BadgePreviewHandler(ViewHandler):
+        def create(self, tag, props):
+            ...  # stand-in used by the Python test backend
+
+        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:
+
+```toml
+[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, test 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.
+_DISCOVERED: bool = False
+
+
+H = TypeVar("H", bound=ViewHandler)
+
+
+def native_component(
+    name: str,
+    *,
+    props: Optional[type] = None,
+) -> Callable[[Type[H]], Type[H]]:
+    """Decorator that registers a test [`ViewHandler`][pythonnative.sdk.ViewHandler] under ``name``.
+
+    The handler class is instantiated immediately and stored in the
+    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"``). 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.
+
+    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``.
+    """
+
+    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, handler=handler_cls())
+        return handler_cls
+
+    return decorator
+
+
+def register_component(
+    *,
+    name: str,
+    props: Optional[type] = None,
+    handler: Optional[ViewHandler] = None,
+) -> None:
+    """Register a custom native component imperatively.
+
+    Declares ``name`` as an element type so
+    [`element_factory`][pythonnative.sdk.element_factory] can build it.
+    ``handler`` is the optional 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.
+        handler: Optional [`ViewHandler`][pythonnative.sdk.ViewHandler]
+            instance used off device.
+
+    Raises:
+        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}")
+    if handler is not None and not isinstance(handler, ViewHandler):
+        raise TypeError(f"register_component({name!r}): handler must be a ViewHandler instance")
+
+    if props is not None:
+        from .schema import ComponentSchema, register_schema
+
+        register_schema(ComponentSchema.from_dataclass(name, props))
+    existing = _REGISTRY.get(name)
+    if existing is None:
+        _REGISTRY[name] = (props, handler)
+        return
+    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:
+    """Remove a previously-registered component (primarily for tests).
+
+    Args:
+        name: The element type name to unregister.
+    """
+    _REGISTRY.pop(name, None)
+    from .schema import COMPONENTS
+
+    COMPONENTS.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 get_test_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 test handlers into a view registry.
+
+    Called once by the registry on first use. Triggers entry-point
+    discovery on the first call so PyPI-installed components register
+    themselves before the registry snapshot is taken.
+
+    Args:
+        registry: A
+            [`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry]
+            (or duck-compatible object) with a ``register(name, handler)``
+            method.
+    """
+    _discover_entry_points()
+    for name, (_props_type, handler) in _REGISTRY.items():
+        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
+
+    try:
+        from importlib.metadata import entry_points
+    except ImportError:
+        return
+
+    try:
+        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.
+
+    Args:
+        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)
+        if props_type is not None:
+            from .schema import ComponentSchema
+
+            ComponentSchema.from_dataclass(name, props_type).validate(props_dict)
+        # 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)
+
+    import inspect
+
+    props_type = get_props_type(name)
+    if props_type is not None:
+        factory.__signature__ = inspect.signature(props_type)
+        from .schema import ComponentSchema, register_schema
+
+        register_schema(ComponentSchema.from_dataclass(name, props_type))
+    factory.__name__ = name
+    factory.__doc__ = f"Construct an Element of type {name!r}."
+    return factory
+
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "Props",
+    "element_factory",
+    "get_test_handler",
+    "get_props_type",
+    "install_into_registry",
+    "list_components",
+    "native_component",
+    "register_component",
+    "unregister_component",
+]

pythonnative/sdk/builtins.py

@@ -0,0 +1,91 @@
+"""Native contracts derived from the annotated built-in Python factories."""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+import typing
+from typing import Any, Callable
+
+from ..style import Style
+from .schema import COMPONENTS, ComponentSchema, NativeField, register_schema, type_schema
+
+# These types own native child layout or physical child presentation.
+CONTAINERS = frozenset(
+    {"View", "Column", "Row", "ScrollView", "Screen", "ScreenStack", "Modal", "Portal", "VirtualList"}
+)
+
+
+def install(factories: dict[str, Any]) -> None:
+    """Compile ordinary Python annotations into the shared native contract."""
+    style_fields = {name: type_schema(annotation) for name, annotation in typing.get_type_hints(Style).items()}
+    for name, factory in factories.items():
+        if not inspect.isfunction(factory) or not name[:1].isupper() or name.startswith("_"):
+            continue
+        signature = inspect.signature(factory)
+        hints = typing.get_type_hints(factory)
+        fields: list[Any] = []
+        for key, parameter in signature.parameters.items():
+            if key in {"style", "ref", "key"} or parameter.kind in {parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD}:
+                continue
+            annotation = hints.get(key, Any)
+            default = parameter.default
+            fields.append(
+                (key, annotation)
+                if default is inspect.Parameter.empty
+                else (key, annotation, dataclasses.field(default=default))
+            )
+        props_type = dataclasses.make_dataclass(f"{name}Props", fields, frozen=True, kw_only=True)
+        schema = ComponentSchema.from_dataclass(
+            name, props_type, measurement="container" if name in CONTAINERS else "intrinsic"
+        )
+        wire = dict(style_fields) | schema.props
+        wire.update(ref={}, on_layout=type_schema(Callable[..., Any]))
+        for key in wire:
+            wire[key] = dict(wire[key])
+            wire[key]["native"] = dataclasses.asdict(
+                NativeField(
+                    invalidates_layout=key in style_fields or key in {"text", "value", "title", "source", "spans"},
+                    recreate=key in {"multiline"},
+                    animated=key
+                    in {
+                        "opacity",
+                        "background_color",
+                        "color",
+                        "rotate",
+                        "translate_x",
+                        "translate_y",
+                        "scale",
+                        "scale_x",
+                        "scale_y",
+                    },
+                )
+            )
+        if name == "Text":
+            wire.update(text={"type": "string"}, spans={"type": "array"})
+        register_schema(dataclasses.replace(schema, props=wire, required=()))
+    base = COMPONENTS["View"]
+    for name, extra in {
+        "Screen": {"route_key": {"type": "string"}, "title": {"type": "string"}, "active": {"type": "boolean"}},
+        "ScreenStack": {"on_native_back": {"type": "event"}},
+        "VirtualList": {
+            "keys": {"type": "array"},
+            "revision": {"type": "integer"},
+            "count": {"type": "integer"},
+            "estimated_item_size": {"type": "number"},
+            "on_bind_row": {"type": "event"},
+        },
+    }.items():
+        register_schema(ComponentSchema(name, base.props | extra, measurement="container"))
+
+
+def validate_props(name: str, props: dict[str, Any]) -> None:
+    """Check known built-in arguments while preserving composed internal props."""
+    schema = COMPONENTS.get(name)
+    if schema is None:
+        return
+    for key, value in props.items():
+        if value is not None and key in schema.props:
+            from .schema import validate
+
+            validate(value, schema.props[key], f"{name}.{key}")

pythonnative/sdk/codegen.py

@@ -0,0 +1,149 @@
+"""Generate component props decoders and portable native metadata."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..bridge.codec import to_jsonable
+from .schema import COMPONENTS, fingerprint, manifest
+
+
+def generate(destination: str | Path) -> list[Path]:
+    """Write deterministic Swift, Kotlin, Python, and browser schema artifacts."""
+    destination = Path(destination)
+    destination.mkdir(parents=True, exist_ok=True)
+    spec = manifest()
+    encoded = json.dumps(spec, indent=2, sort_keys=True, default=str) + "\n"
+    swift = ["import Foundation", "", "// Generated from Python schemas. Regenerate instead of editing."]
+    kotlin = [
+        "package com.pythonnative.generated",
+        "",
+        "import org.json.JSONObject",
+        "",
+        "// Generated from Python schemas.",
+    ]
+    python = [
+        '"""Generated native component factories."""',
+        "from typing import Any",
+        "from pythonnative.element import Element",
+        "from pythonnative.sdk.schema import COMPONENTS",
+        "",
+    ]
+    docs = ["# Native contracts", "", f"Runtime fingerprint: `{fingerprint()}`.", ""]
+    names = {
+        "string": ("String", "String", "str"),
+        "boolean": ("Bool", "Boolean", "bool"),
+        "integer": ("Int", "Int", "int"),
+        "number": ("Double", "Double", "float"),
+    }
+    for name, component in sorted(COMPONENTS.items()):
+        if not name.isidentifier():
+            raise ValueError(f"Invalid native component name {name!r}")
+        swift.extend(
+            [
+                f"public struct {name}Props {{",
+                "    public let values: [String: Any]",
+                "    public init(_ values: [String: Any]) throws {",
+                "        self.values = values",
+            ]
+        )
+        kotlin.extend([f"data class {name}Props(val values: JSONObject) {{", "    init {"])
+        parameters = []
+        values = []
+        for key, field in component.props.items():
+            if not key.isidentifier():
+                raise ValueError(f"Invalid property name {key!r}")
+            kind = field.get("type")
+            swift_type, kotlin_type, python_type = names.get(kind, ("Any", "Any", "Any"))
+            if key in component.required:
+                swift.append(
+                    f'        guard values["{key}"] is {swift_type} else {{ '
+                    f'throw NativeDecodeError.invalid("{name}.{key}") }}'
+                )
+                kotlin.append(
+                    f'        require(values.has("{key}") && !values.isNull("{key}")) {{ "Missing {name}.{key}" }}'
+                )
+            default = component.defaults.get(key)
+            if hasattr(default, "value"):
+                default = default.value
+            if default is None and python_type != "Any":
+                python_type += " | None"
+            parameters.append(f"{key}: {python_type}" + (f" = {default!r}" if key not in component.required else ""))
+            values.append(f'"{key}": {key}')
+        swift.append("    }")
+        kotlin.append("    }")
+        for key, field in component.props.items():
+            kind = field.get("type")
+            st, kt, _ = names.get(kind, ("Any", "Any", "Any"))
+            expression = f'values["{key}"]' + (f" as? {st}" if st != "Any" else "")
+            swift.append(f"    public var {key}: {st}? {{ {expression} }}")
+            accessor = {"string": "getString", "boolean": "getBoolean", "integer": "getInt", "number": "getDouble"}.get(
+                kind, "get"
+            )
+            kotlin.append(
+                f'    val {key}: {kt}? get() = if (values.isNull("{key}")) null else values.{accessor}("{key}")'
+            )
+        swift.extend(["}", ""])
+        kotlin.extend(["}", ""])
+        python.extend(
+            [
+                f"def {name}(*children: Element, "
+                + ", ".join(parameters + ["key: str | None = None"])
+                + ") -> Element:",
+                f'    """Create a validated {name} native element."""',
+                "    props = {" + ", ".join(values) + "}",
+                f'    COMPONENTS["{name}"].validate(props)',
+                f'    return Element("{name}", props, list(children), key=key)',
+                "",
+            ]
+        )
+        docs.extend(
+            [
+                f"## {name}",
+                "",
+                f"Measurement: {component.measurement}.",
+                "",
+                "| Property | Type | Required |",
+                "| --- | --- | --- |",
+            ]
+        )
+        docs.extend(
+            f"| `{key}` | `{field.get('type', 'union')}` | {key in component.required} |"
+            for key, field in component.props.items()
+        )
+        docs.append("")
+    swift.extend(["public enum NativeDecodeError: Error { case invalid(String) }", ""])
+    outputs: dict[str, Any] = {
+        "schema.json": encoded,
+        "schema.js": "export default " + encoded.strip() + ";\n",
+        "NativeProps.swift": "\n".join(swift),
+        "NativeProps.kt": "\n".join(kotlin),
+        "components.py": "\n".join(python),
+        "README.md": "\n".join(docs),
+    }
+    compact = json.dumps(to_jsonable(spec), separators=(",", ":"), sort_keys=True)
+    templates = Path(__file__).with_name("templates")
+    for extension in ("swift", "kt"):
+        template = (templates / f"contracts.{extension}").read_text(encoding="utf-8")
+        # Escaped Swift strings and Kotlin raw strings have different interpolation rules.
+        data = (
+            compact.replace("\\", "\\\\")
+            if extension == "swift"
+            else ",\n".join(
+                '"""' + compact[i : i + 8000].replace("$", "${'$'}") + '"""' for i in range(0, len(compact), 8000)
+            )
+        )
+        outputs[f"PNContracts.{extension}"] = template.replace("{{fingerprint}}", fingerprint()).replace(
+            "{{specification}}", data
+        )
+    from .module_codegen import generate_modules
+
+    outputs.update(generate_modules())
+    paths = []
+    for name, contents in outputs.items():
+        path = destination / name
+        path.write_text(contents, encoding="utf-8")
+        paths.append(path)
+    return paths