pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/component.py

@@ -0,0 +1,271 @@
+"""The ``@component`` decorator and the [`Component`][pythonnative.Component] type.
+
+A component is a plain Python function that takes props and returns a
+[`Node`][pythonnative.element.Node]: an [`Element`][pythonnative.Element],
+a list of elements, or ``None``. Decorating it with
+[`@component`][pythonnative.component.component] turns it into a
+[`Component`][pythonnative.Component]: a callable that *describes* a
+render (it returns an ``Element`` whose ``type`` is the component)
+instead of performing one. The reconciler invokes the function body
+later, with hook state installed.
+
+The decorator preserves the function's signature for type checkers via
+:class:`typing.ParamSpec`, so ``Greeting(nme="x")`` is a static error
+and editors autocomplete props from the function definition.
+
+Children
+--------
+
+Children are positional. A component that accepts children declares a
+``*children`` parameter, exactly like the built-in containers:
+
+```python
+@pn.component
+def Card(*children: pn.Element, title: str = "") -> pn.Element:
+    return pn.Column(pn.Text(title, style=pn.style(bold=True)), *children)
+
+Card(pn.Text("body"), title="Hello")
+```
+
+Positional arguments to a component *without* ``*children`` bind to its
+positional parameters, so ``Greeting("World")`` works for
+``def Greeting(name: str)``.
+
+Keys
+----
+
+Every component accepts ``key=`` at the call site for keyed
+reconciliation. ``key`` is consumed by the framework and is not passed
+to the function unless the function declares a ``key`` parameter
+itself. Declaring it (``key: str | None = None``) is the way to keep
+strict type checkers happy when a component is rendered in a list;
+otherwise use [`Element.with_key`][pythonnative.element.Element.with_key].
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Awaitable, Callable, Dict, Generic, List, Optional, ParamSpec, Tuple, Union, overload
+
+from .element import Element, Node
+
+__all__ = ["Component", "RenderFn", "component", "memo", "is_component"]
+
+P = ParamSpec("P")
+
+RenderFn = Callable[P, Union[Node, Awaitable[Node]]]
+"""A component body: returns a [`Node`][pythonnative.element.Node], or awaits one when ``async def``."""
+
+
+class Component(Generic[P]):
+    """A render-function wrapped by [`@component`][pythonnative.component.component].
+
+    Calling a ``Component`` does not run the function; it returns an
+    [`Element`][pythonnative.Element] describing the call so the
+    reconciler can mount it, preserve its hook state across renders,
+    and re-run it when its state or props change.
+
+    Attributes:
+        fn: The original render function.
+        display_name: Name shown in diagnostics and dev tooling
+            (defaults to ``fn.__name__``).
+        memoized: Whether [`memo`][pythonnative.memo] was applied, in
+            which case the reconciler skips re-rendering this component
+            when its props are shallowly equal to the previous render.
+        accepts_children: Whether ``fn`` declares ``*children``.
+    """
+
+    __slots__ = (
+        "fn",
+        "display_name",
+        "memoized",
+        "props_equal",
+        "accepts_children",
+        "_positional",
+        "_declares_key",
+        "_is_async",
+        "refresh_signature",
+        "__wrapped__",
+        "__dict__",
+    )
+
+    def __init__(self, fn: RenderFn[P], *, display_name: Optional[str] = None) -> None:
+        if isinstance(fn, Component):
+            raise TypeError(f"{fn!r} is already a component; remove the duplicate @component")
+        sig = inspect.signature(fn)
+        positional: List[str] = []
+        accepts_children = False
+        declares_key = False
+        for name, param in sig.parameters.items():
+            if param.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
+                positional.append(name)
+            elif param.kind is inspect.Parameter.VAR_POSITIONAL:
+                accepts_children = True
+            if name == "key":
+                declares_key = True
+        from .refresh import hook_signature
+
+        self.refresh_signature = hook_signature(fn)
+        self.fn = fn
+        self.display_name = display_name or getattr(fn, "__name__", "Component")
+        self.memoized = False
+        self.props_equal: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None
+        self.accepts_children = accepts_children
+        self._positional: Tuple[str, ...] = tuple(positional)
+        self._declares_key = declares_key
+        self._is_async = inspect.iscoroutinefunction(fn)
+        self.__wrapped__ = fn
+        functools.update_wrapper(self, fn, updated=())
+
+    # ------------------------------------------------------------------
+    # Element construction
+    # ------------------------------------------------------------------
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Element:
+        """Describe a render of this component with the given props."""
+        props: Dict[str, Any] = dict(kwargs)
+        key = props.pop("key", None) if not self._declares_key else props.get("key")
+        children: List[Any] = []
+        if args:
+            if self.accepts_children:
+                children = list(args)
+            else:
+                names = self._positional
+                if len(args) > len(names):
+                    raise TypeError(
+                        f"{self.display_name}() takes {len(names)} positional argument(s) but "
+                        f"{len(args)} were given. Declare *children to accept child elements."
+                    )
+                for name, value in zip(names, args):
+                    if name in props:
+                        raise TypeError(f"{self.display_name}() got multiple values for argument {name!r}")
+                    props[name] = value
+        return Element(self, props, children, key=key if isinstance(key, str) or key is None else str(key))
+
+    # ------------------------------------------------------------------
+    # Rendering (used by the reconciler)
+    # ------------------------------------------------------------------
+
+    def render(self, element: Element) -> Any:
+        """Invoke the render function for ``element``.
+
+        Children stored on the element are passed positionally; props
+        are passed by keyword. Returns whatever the function returned
+        (an element, a list, ``None``, or a coroutine for ``async def``
+        bodies).
+        """
+        if self.accepts_children:
+            return self.fn(*element.children, **element.props)
+        return self.fn(**element.props)  # type: ignore[call-arg]
+
+    @property
+    def is_async(self) -> bool:
+        """Whether the render function is an ``async def``."""
+        return self._is_async
+
+    def __repr__(self) -> str:
+        flags = " memo" if self.memoized else ""
+        return f"<Component {self.display_name}{flags}>"
+
+    def __get__(self, instance: Any, owner: Any = None) -> "Component[P]":
+        # Components stored on classes (rare) should not bind ``self``.
+        return self
+
+
+def component(fn: RenderFn[P]) -> Component[P]:
+    """Turn a render function into a [`Component`][pythonnative.Component].
+
+    The decorated function may use hooks (``use_state``, ``use_effect``,
+    etc.) and returns an [`Element`][pythonnative.Element] tree, a list
+    of elements, or ``None``. Each call site creates an independent
+    component instance with its own hook state.
+
+    Args:
+        fn: The render function. May be ``async def``; the body is then
+            driven by the reconciler and suspends on pending awaits (see
+            [`Suspense`][pythonnative.Suspense]).
+
+    Returns:
+        A ``Component`` whose call signature mirrors ``fn`` (plus the
+        framework ``key=`` keyword).
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def Greeting(name: str = "World"):
+            return pn.Text(f"Hello, {name}!")
+        ```
+    """
+    return Component(fn)
+
+
+@overload
+def memo(
+    target: Component[P], *, equal: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None
+) -> Component[P]: ...
+
+
+@overload
+def memo(
+    target: None = None, *, equal: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None
+) -> Callable[[Component[P]], Component[P]]: ...
+
+
+def memo(
+    target: Optional[Component[P]] = None,
+    *,
+    equal: Optional[Callable[[Dict[str, Any], Dict[str, Any]], bool]] = None,
+) -> Any:
+    """Skip a component's render when its props haven't changed.
+
+    Apply on top of ``@component``. When the reconciler re-renders the
+    parent tree, a memoized child is skipped (its previously-rendered
+    subtree is reused) iff its props and children are equal to the
+    previous render and none of its own state setters fired. Props are
+    compared shallowly by default: callables by identity, everything
+    else by ``==``.
+
+    Pair with [`use_callback`][pythonnative.use_callback] when passing
+    callbacks as props, otherwise a fresh closure defeats the memo.
+
+    Args:
+        target: A [`Component`][pythonnative.Component].
+        equal: Optional custom comparator ``(old_props, new_props) ->
+            bool`` replacing the shallow comparison.
+
+    Returns:
+        The same component, marked for memoization (or a decorator when
+        called with keyword arguments only).
+
+    Example:
+        ```python
+        @pn.memo
+        @pn.component
+        def ExpensiveRow(label: str):
+            ...
+
+        @pn.memo(equal=lambda a, b: a["id"] == b["id"])
+        @pn.component
+        def Row(id: int, extra: dict):
+            ...
+        ```
+    """
+
+    def apply(comp: Component[P]) -> Component[P]:
+        if not isinstance(comp, Component):
+            raise TypeError("@memo must wrap a @component; write @memo above @component")
+        comp.memoized = True
+        comp.props_equal = equal
+        return comp
+
+    if target is None:
+        return apply
+    return apply(target)
+
+
+def is_component(obj: Any) -> bool:
+    """Return whether ``obj`` is a [`Component`][pythonnative.Component]."""
+    return isinstance(obj, Component)

pythonnative/components/__init__.py

@@ -0,0 +1,111 @@
+"""Built-in element factories.
+
+Each factory function (``Text``, ``Button``, …) is a fully-typed thin
+wrapper that builds an [`Element`][pythonnative.Element] through the
+shared ``_make_element`` helper, so style resolution, ``ref``
+attachment, ``None``-default dropping, and forced overrides (e.g.
+``Column``'s fixed ``flex_direction``) live in exactly one place. The
+factory signatures themselves are the canonical prop schemas: editors
+and type checkers validate calls directly against them.
+
+The factories are grouped by concern into submodules (``text``,
+``media``, ``controls``, ``layout``, ``pressable``, ``overlays``,
+``structural``, ``lists``); everything public is re-exported here, so
+``from pythonnative.components import Text`` keeps working.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    pn.Column(
+        pn.Text("Hello", style=pn.style(font_size=18)),
+        pn.Button("Tap", on_press=lambda: print("tapped")),
+        style=pn.style(spacing=12, padding=16),
+    )
+    ```
+"""
+
+from ._base import _SPAN_STYLE_KEYS, _flatten_text_spans, _make_element  # noqa: F401
+from .controls import (
+    ActivityIndicator,
+    Checkbox,
+    DatePicker,
+    Picker,
+    ProgressBar,
+    RefreshControl,
+    SegmentedControl,
+    Slider,
+    StatusBar,
+    Switch,
+)
+from .layout import (  # noqa: F401
+    _SAFE_AREA_EDGES,
+    Column,
+    KeyboardAvoidingView,
+    Row,
+    SafeAreaView,
+    ScrollView,
+    Spacer,
+    View,
+    _KeyboardAvoidingContainer,
+    _numeric_edge_padding,
+    _SafeAreaContainer,
+)
+from .lists import (  # noqa: F401
+    _DEFAULT_ROW_EXTENT,
+    FlatList,
+    ListController,
+    SectionList,
+    _dispatch_scroll_command,
+    _native_lists_supported,
+    _NativeList,
+    _RowSpec,
+    _VirtualizedList,
+)
+from .media import Image, ImageBackground, WebView
+from .overlays import Modal, Portal
+from .pressable import Pressable, TouchableOpacity, _StatefulPressable  # noqa: F401
+from .structural import ErrorBoundary, Fragment, Suspense
+from .text import Button, Text, TextInput
+
+__all__ = [
+    "ActivityIndicator",
+    "Button",
+    "Checkbox",
+    "Column",
+    "DatePicker",
+    "ErrorBoundary",
+    "FlatList",
+    "Fragment",
+    "Image",
+    "ImageBackground",
+    "KeyboardAvoidingView",
+    "ListController",
+    "Modal",
+    "Picker",
+    "Portal",
+    "Pressable",
+    "ProgressBar",
+    "RefreshControl",
+    "Row",
+    "SafeAreaView",
+    "ScrollView",
+    "SectionList",
+    "SegmentedControl",
+    "Slider",
+    "Spacer",
+    "StatusBar",
+    "Suspense",
+    "Switch",
+    "Text",
+    "TextInput",
+    "TouchableOpacity",
+    "View",
+    "WebView",
+]
+
+# Factories are the single source for Python signatures and native contracts.
+from ..sdk.builtins import install as _install_native_contracts
+
+_install_native_contracts(globals())
+del _install_native_contracts

pythonnative/components/_base.py

@@ -0,0 +1,166 @@
+"""Shared private helpers behind the built-in element factories.
+
+Every factory in this package routes through :func:`_make_element`, so
+style resolution, ``ref`` attachment, ``None``-default dropping, and
+forced overrides live in exactly one place. The rich-text span
+flattening used by ``Text`` also lives here so it can be shared.
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..element import Element
+from ..hooks import Ref
+from ..style import StyleProp, resolve_style, validate_style_keys
+
+# ======================================================================
+# Canonical element builder
+# ======================================================================
+
+
+def _make_element(
+    name: str,
+    *children: Element,
+    style: StyleProp = None,
+    ref: Optional[Ref] = None,
+    key: Optional[str] = None,
+    _defaults: Optional[Dict[str, Any]] = None,
+    _forced: Optional[Dict[str, Any]] = None,
+    **props: Any,
+) -> Element:
+    """Build an [`Element`][pythonnative.Element] of type ``name``.
+
+    This is the single helper every built-in factory routes through, so
+    the cross-cutting concerns that used to be duplicated per component
+    live in one place:
+
+    1. ``style`` is flattened via
+       [`resolve_style`][pythonnative.style.resolve_style] (list-of-dicts
+       and ``None`` both handled).
+    2. ``_defaults`` are filled in for keys not already present (used for
+       things like ``View``'s default ``flex_direction: "column"`` that
+       a user style may legitimately override).
+    3. ``**props`` are merged on top, with ``None`` values *dropped* so
+       optional kwargs don't pollute the prop dict.
+    4. ``ref`` is attached under the reserved ``"ref"`` key.
+    5. ``_forced`` overrides everything (used by ``Column`` / ``Row`` to
+       lock their flex direction regardless of user style).
+
+    Args:
+        name: Element type name (e.g. ``"Text"``).
+        *children: Child elements.
+        style: Style dict, list of dicts, or ``None``.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``; the
+            reconciler populates ``ref.current`` with the underlying
+            native view.
+        key: Stable identity for keyed reconciliation.
+        _defaults: Internal: fill-only-if-missing prop defaults.
+        _forced: Internal: prop overrides applied last.
+        **props: Per-component props. ``None`` values are dropped.
+
+    Returns:
+        A fresh [`Element`][pythonnative.Element].
+    """
+    from ..sdk.builtins import validate_props
+
+    validate_props(name, props)
+    out: Dict[str, Any] = dict(resolve_style(style))
+    if out:
+        validate_style_keys(out, owner=name)
+    if _defaults:
+        for k, v in _defaults.items():
+            out.setdefault(k, v)
+    for k, v in props.items():
+        if v is not None:
+            out[k] = v
+    if ref is not None:
+        out["ref"] = ref
+    if _forced:
+        out.update(_forced)
+    return Element(name, out, list(children), key=key)
+
+
+# ======================================================================
+# RefreshControl attachment
+# ======================================================================
+
+REFRESH_CONTROL_TYPE = "RefreshControl"
+"""Element type produced by [`RefreshControl`][pythonnative.RefreshControl]."""
+
+
+def _refresh_control_props(control: Optional[Element], *, owner: str) -> Optional[Dict[str, Any]]:
+    """Turn a ``RefreshControl`` element into the ``refresh_control`` wire prop.
+
+    Scroll containers hold their refresh control as a prop rather than
+    a child (the native side attaches a ``UIRefreshControl`` /
+    ``SwipeRefreshLayout`` to the scroll view itself), so the element
+    is unwrapped here into the flat dict the bridge and the event
+    extractor expect. Keeping it an element on the Python side means
+    users build it like every other piece of UI and get a clear error
+    if they pass the wrong thing.
+
+    Raises:
+        TypeError: If ``control`` is not a ``RefreshControl`` element.
+    """
+    if control is None:
+        return None
+    if not isinstance(control, Element) or control.type != REFRESH_CONTROL_TYPE:
+        raise TypeError(
+            f"{owner}(refresh_control=...) expects pn.RefreshControl(...), got {type(control).__name__}: {control!r}"
+        )
+    return dict(control.props)
+
+
+# ======================================================================
+# Rich text spans
+# ======================================================================
+
+
+# Style keys that can vary per span inside a rich-text run. Layout
+# keys are excluded: spans are inline fragments of one paragraph and
+# have no boxes of their own.
+_SPAN_STYLE_KEYS = (
+    "color",
+    "background_color",
+    "font_size",
+    "font_family",
+    "font_weight",
+    "bold",
+    "italic",
+    "text_decoration",
+    "letter_spacing",
+)
+
+
+def _flatten_text_spans(
+    parts: Tuple[Any, ...],
+    inherited: Dict[str, Any],
+) -> List[Dict[str, Any]]:
+    """Flatten nested ``Text`` parts into a flat list of styled spans.
+
+    Strings become spans carrying only the inherited style overrides;
+    nested ``Text`` elements contribute their own span-style keys
+    (merged over what they inherit) and recurse into their parts.
+    """
+    spans: List[Dict[str, Any]] = []
+    for part in parts:
+        if part is None:
+            continue
+        if isinstance(part, Element):
+            props = part.props or {}
+            child_style = dict(inherited)
+            for k in _SPAN_STYLE_KEYS:
+                if props.get(k) is not None:
+                    child_style[k] = props[k]
+            nested = props.get("spans")
+            if nested:
+                for span in nested:
+                    merged = dict(child_style)
+                    for k in _SPAN_STYLE_KEYS:
+                        if span.get(k) is not None:
+                            merged[k] = span[k]
+                    spans.append({"text": span.get("text", ""), **merged})
+            else:
+                spans.append({"text": str(props.get("text", "")), **child_style})
+        else:
+            spans.append({"text": str(part), **inherited})
+    return spans