blu-react 0.0.1__py3-none-any.whl

blu/_nodes.py

@@ -0,0 +1,771 @@
+from collections.abc import Callable, Generator
+import importlib
+import inspect
+from logging import getLogger
+from numbers import Number
+import re
+
+from blu._exceptions import WrongEnvironmentError
+from blu._utils.typing import Any, Mapping, Protocol, Sequence, cast
+from blu._utils.client import is_client
+
+log = getLogger("blu")
+
+"""
+JSON-serializable primitive value.
+"""
+type JsonPrimitive = bool | Number | str | None
+
+
+"""JSON-serializable value."""
+type Jsonable = JsonPrimitive | Sequence[Jsonable] | Mapping[str, Jsonable]
+
+"""Basic item that can serialized and sent from server to client."""
+type SerializableItem = JsonPrimitive | Node
+
+"""Can be serialized and sent from server to client."""
+type Serializable = (
+    SerializableItem | Sequence[Serializable] | Mapping[str, Serializable]
+)
+
+type Node = """
+    ClientElement |
+    HTMLElement |
+    Key |
+    Iterable[Node] |
+    str |
+    int |
+    float |
+    None
+"""
+
+"""Valid value for a prop of a `ReactElement`."""
+type PropValue = Jsonable | Node
+
+
+def is_jsonable(item: Any) -> bool:
+    if item is None:
+        return True
+    elif isinstance(item, (bool, Number, str)):
+        return True
+    elif isinstance(item, Sequence):
+        items = cast(Sequence[Any], item)
+        return all(is_jsonable(x) for x in items)
+    elif isinstance(item, Mapping):
+        props = cast(Mapping[str, Any], item)
+        return all(is_jsonable(v) for v in props.values())
+    else:
+        return False
+
+
+def is_node(item: Any) -> bool:
+    """
+    :return: :py:data:`True` if ``item`` is a valid :type:`Node`,
+        otherwise :py:data:`False`.
+    """
+    node_types = (bool, Number, str, HTMLElement, CustomElement)
+    if item is None:
+        return True
+    elif isinstance(item, node_types):
+        return True
+    elif isinstance(item, Sequence):
+        seq = cast(Sequence[Any], item)
+        return all(is_node(x) for x in seq)
+    else:
+        return False
+
+
+"""Valid props for a `ReactElement`."""
+type Props = Mapping[str, PropValue]
+
+"""Valid children of a `ReactElement`."""
+type Children = list[Node]
+
+
+class HTMLElement:
+    """
+    A `React DOM component instance
+    <https://react.dev/reference/react-dom/components>`_. Created using
+    the :mod:`blu.html` module.
+
+    .. code-block:: python
+
+        from blu.html import div
+
+        div(id='my-id')[
+            'Hello World!',
+        ]
+
+    .. code-block:: html
+
+        <div id="my-id">Hello World!</div>
+    """
+
+    _tagname: str
+    """
+    The tag name of the element.
+
+    .. code-block:: python
+
+        from blu.html import span
+
+        span.tagname == 'span'
+    """
+
+    _attrs: Props
+    """
+    The element's props, minus children.
+
+    .. code-block:: python
+
+        from blu.html import div
+
+        div(id='my-id')['Hello!'].props == {'id': 'my-id'}
+    """
+
+    _children: list[Node]
+    """
+    The element's children.
+
+    .. code-block:: python
+
+        from blu.html import div, span
+
+        div[span['Hello'], 'Hi.'].children == [span['Hello'], 'Hi.']
+    """
+
+    def __init__(self, tagname: str, props: Props, children: list[Node]):
+        self._tagname = tagname
+        self._attrs = props
+        self._children = children
+
+    def __call__(self, props: Props = {}, /, **kwargs: PropValue) -> "HTMLElement":
+        """
+        Create a copy of ``self`` with React props set based on the
+        given keyword arguments.
+
+        .. code-block:: python
+
+            from blu.html import div
+
+            div(id='my-div')
+
+        .. code-block:: html
+
+            <div id="my-div"></div>
+
+        :param props: A mapping of prop names to prop values. This is an
+            escape hatch for cases when the prop name can't be
+            represented as a keyword argument name.
+
+        :param kwargs: The new props, where the argument name is the
+            prop's key and the argument value is the prop's value. This
+            is the usual way to specify props.
+
+        :return: A copy of ``self`` with the same children, but with
+            props set as follows:
+
+            1. For any key-value pair in the ``props`` argument, the
+               prop named by the key will be set to the value.
+
+               For example, ``div(props={'my_prop_': 45})`` results in
+               the React element ``<div my_prop_={45} />``
+
+            2. For any keyword argument, the value will be set to a key
+               derived from:
+
+               - Removing the last trailing underscore (if any).
+               - Replacing all other underscores with dashes.
+
+               For example, ``div(my_prop_=45)`` results in the React
+               element ``<div my-prop={45} />``.
+
+            3. If there is any conflict between the ``props`` argument
+               and the keyword arguments, the prop that has the conflict
+               will be set based on the ``props`` argument as described
+               in (1). Any props that do not have conflicts will be set
+               the same way they otherwise would, irrespective of the
+               props that do have conflicts.
+
+               For example,
+               ``div(props={'props-only': 'props', 'shared': 'props'}, shared='kw', kw_only='kw')``
+               results in the React element
+               ``<div props-only="props" shared="props" kw-only="kw" />``
+        """
+        all_props = {
+            **props,
+            **self._rename_props(kwargs),
+        }
+        for prop_name in all_props:
+            if not is_client and prop_name.startswith("on"):
+                raise WrongEnvironmentError(
+                    f'Could not add attribute "{prop_name}" to {self._tagname} '
+                    f'element. Event-handling attributes like "{prop_name}" '
+                    "can only be set in client-side rendering; this code was "
+                    "run server-side."
+                )
+        return HTMLElement(
+            self._tagname,
+            props=all_props,
+            children=self._children,
+        )
+
+    def __getitem__(self, children: Node | tuple[Node, ...]) -> "HTMLElement":
+        """
+        Create a copy of ``self`` whose child nodes are set to the items
+        passed in.
+
+        .. code-block:: python
+
+            from blu.html import div
+
+            div['Hello World!']
+
+        .. code-block:: html
+
+            <div>Hello World!</div>
+
+        :param children: A :type:`blu.Node` or a :py:class:`tuple` of
+            :type:`blu.Node`\\ s.
+        :return:
+            - If ``children`` is a :type:`blu.Node`: A copy of
+              :data:`self` whose children are set to ``[children]``.
+            - If ``children`` is a :py:class:`tuple` of
+              :type:`blu.Node`\\ s: A copy of :data:`self` whose
+              children are set to ``list(children)``.
+        """
+        return HTMLElement(
+            self._tagname,
+            props=self._attrs,
+            children=_get_children(children),
+        )
+
+    def _rename_props(self, props: Props) -> Props:
+        return {py_to_html_name(k): v for k, v in props.items()}
+
+
+def _get_children(index: Node | tuple[Node, ...]) -> list[Node]:
+    if is_client:
+        from pyodide.ffi import JsProxy
+
+        if isinstance(index, JsProxy):
+            index = cast(Node, index.unwrap())
+    if isinstance(index, tuple):
+        children = list(cast(tuple[Node], index))
+    else:
+        children = [index]
+    return [_convert_to_string(x) for x in children]
+
+
+def _convert_to_string(item: Node) -> Node:
+    str_types = (float, bool)
+    if is_client:
+        from pyodide.ffi import jsnull
+
+        if item == jsnull:
+            return str(item)
+    if isinstance(item, str_types):
+        return str(item)
+    else:
+        return item
+
+
+class Key:
+    """
+    A keyed fragment of React nodes.
+
+    .. code-block:: python
+
+        from blu import Key
+        from blu.html import b
+
+        Key('my-id')[
+            'Hello, ',
+            b['World'],
+            '!',
+        ]
+
+    .. code-block:: html
+
+        Hello, <b>World</b>!
+
+    :param key: A key to be used by React to uniquely identify the
+        fragment.
+    :return: An empty fragment identified by ``key``.
+
+    In most cases, you won't need to use :class:`blu.Key`, but it is
+    required when rendering an item in an
+    :py:class:`Iterable <collections.abc.Iterable>` (unless that
+    :py:class:`Iterable <collections.abc.Iterable>` is a :py:class:`str`
+    or :py:class:`tuple`):
+
+    .. code-block:: python
+
+        from blu import Key
+        from blu.html import b
+
+        PEOPLE = [
+            {'id': 1, name: 'Andy'},
+            {'id': 2, name: 'Brittany'},
+            {'id': 3, name: 'Calvin'},
+        ]
+
+        Key(person['id'])[
+            'Hello, ',
+            b[person['name']],
+            '!',
+        ]
+        for person in PEOPLE
+
+    .. code-block:: html
+
+        Hello, <b>Andy</b>!
+        Hello, <b>Brittany</b>!
+        Hello, <b>Calvin</b>!
+    """
+
+    _key: Any
+    _children: list[Node]
+
+    def __init__(self, key: Any):
+        self._key = key
+        self._children = []
+
+    def __getitem__(self, children: Node | tuple[Node, ...]) -> "Key":
+        """
+        Create a copy of ``self`` with the given children.
+
+        .. code-block:: python
+
+            from blu import Key
+            from blu.html import b
+
+            Key('my-id')[
+                'Hello, ',
+                b['World'],
+                '!',
+            ]
+
+        .. code-block:: html
+
+            Hello, <b>World</b>!
+
+        :param children: A :type:`blu.Node` or :py:class:`tuple` of
+            :type:`blu.Node`\\s.
+        :return: If ``children`` is a :py:class:`tuple`, a frament whose
+            children are ``list(children)``. Otherwise, a fragment whose
+            children are ``[children]``.
+        """
+        copy = Key(self._key)
+        copy._children = _get_children(children)
+        return copy
+
+
+type ClientRenderer = Callable[..., Node | Generator[None, Node, Node]]
+
+
+class Element[**P](Protocol):
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> "Element[P]": ...
+
+    def __getitem__(self, *children: "Node") -> "Element[P]": ...
+
+
+UNSET = object()
+
+
+def noop():
+    pass
+
+
+class ClientElement:
+    """
+    A custom element to be rendered client-side. Created using the
+    :func:`blu.client` decorator.
+
+    .. code-block:: python
+
+        from blu import client
+        from blu.html import b, span
+
+        __client__ = True
+
+
+        @client
+        def ColorfulText(color, bold):
+            colorful_span = span(style={'color': color})[
+                (yield)
+            ]
+            if bold:
+                return b[colorful_span]
+            else:
+                return colorful_span
+
+
+        ColorfulText('red', bold=True)[
+            'Danger! The world said hello back.',
+        ]
+
+    .. code-block:: html
+
+        <b>
+            <span style="color: red">
+                Danger! The world said hello back.
+            </span>
+        </b>
+    """
+
+    _args: tuple[Any, ...]
+    _kwargs: dict[str, Any]
+    _children: list[Node]
+    _renderer: ClientRenderer
+    _key: Any
+    _has_key: bool
+
+    def __init__(
+        self,
+        renderer: ClientRenderer,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        children: list[Node],
+        key: Any,
+        has_key: bool,
+    ):
+        self._renderer = renderer
+        self._args = args
+        self._kwargs = kwargs
+        self._children = children
+        self._key = key
+        self._has_key = has_key
+
+    def __call__(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> "ClientElement":
+        """
+        Create a copy of ``self`` that will be rendered with the given
+        arguments.
+
+        .. code-block:: python
+
+            from blu import client
+            from blu.html import div
+
+            __client__ = True
+
+
+            @client
+            def Greeting(name='World'):
+                return div[f'Hello, {name}!']
+
+
+            div[
+                Greeting('Arnold'),
+                Greeting(name='Hailey'),
+                Greeting,
+            ]
+
+        .. code-block:: html
+
+                <div>Hello, Arnold!</div>
+                <div>Hello, Hailey!</div>
+                <div>Hello, World!</div>
+
+        :param args: The positional arguments to pass into the
+            element's render function when it is rendered.
+        :param kwargs: The keyword arguments to pass into the
+            element's render function when it is rendered, as well as an
+            optional keyword argument ``key``, which will be used by
+            React to uniquely identify the element when it is rendered.
+            Usually, you won't need to pass in a ``key``, but it's
+            required for any :py:class:`ClientElement <blu.ClientElement>` that is
+            rendered as an item in an
+            :py:class:`Iterable <collections.abc.Iterable>` (unless that
+            :py:class:`Iterable <collections.abc.Iterable>` is a
+            :py:class:`str` or a :py:class:`tuple`).
+
+        :return: A copy of ``self`` that will be rendered by calling its
+            render function with ``*args`` and ``**kwargs``, with the
+            exception that the keyword argument ``key`` will not be
+            passed on to the render function and will instead be used by
+            React to identify the new element. If the original had a
+            key, it will not be retained in the copy, and the copy will
+            have a key if and only if ``**kwargs`` contains the ``key``
+            argument.
+
+        Below is an example of using the ``key`` argument:
+
+        .. code-block:: python
+
+            from blu import client
+            from blu.html import div
+
+            PEOPLE = [
+                {'id': 0, 'name': 'Allison'},
+                {'id': 1, 'name': 'Bill'},
+                {'id': 2, 'name': 'Carrie'},
+            ]
+
+
+            @client
+            def Greeting(name):
+                return div[f'Hello, {name}!']
+
+
+            [Greeting(x['name'], key=x['id']) for x in PEOPLE]
+
+        .. code-block:: html
+
+            <div>Hello, Allison!</div>
+            <div>Hello, Bill!</div>
+            <div>Hello, Carrie!</div>
+        """
+        kwargs_copy = {**kwargs}
+        try:
+            del kwargs_copy["key"]
+        except KeyError:
+            pass
+        return ClientElement(
+            self._renderer,
+            args,
+            kwargs,
+            self._children,
+            key=kwargs.get("key", None),
+            has_key="key" in kwargs,
+        )
+
+    def __getitem__(self, children: Node) -> "ClientElement":
+        """
+        Create a copy of ``self`` that will render with the given
+        children displayed where the render function uses the ``yield``
+        keyword.
+
+        .. code-block:: python
+
+            from blu import client
+            from blu.html import span
+
+
+            @client
+            def RedText(text):
+                return span(style={'color': 'red'})[(yield)]
+
+
+            RedText['Danger! This text is red.']
+
+        .. code-block:: html
+
+            <span style="color: red">Danger! This text is red.</span>
+
+        :param children: Any valid :type:`blu.Node` or a
+            :py:class:`tuple` of :type:`blu.Node`\\s.
+        :return: A copy of ``self`` that will render with ``children``
+            displayed where the element's render function uses the
+            ``yield`` keyword. If no children were specified, nothing
+            will be rendered where the ``yield`` keyword is used.
+        :raises: :py:class:`TypeError` if element's rendering function
+            is not a :py:class:`Generator <collections.abc.Generator>`,
+            i.e. doesn't contain a ``yield`` statement.
+        """
+        if not inspect.isgeneratorfunction(self._renderer):
+            log.info("INFO")
+            log.debug(f"Non-generator function: {self._renderer}")
+            raise TypeError("This element does not accept any children.")
+        log.error(f"ClientElement children: {children}")
+        return ClientElement(
+            self._renderer,
+            self._args,
+            self._kwargs,
+            _get_children(children),
+            key=self._key,
+            has_key=self._has_key,
+        )
+
+    def _get_key(self):
+        if not self._has_key:
+            raise LookupError("This element has no key.")
+        return self._key
+
+    def __reduce__(self):
+        module = self._renderer.__module__
+        name = self._renderer.__name__
+        return (
+            _import_client_module,
+            (
+                module,
+                name,
+                self._args,
+                self._kwargs,
+                self._children,
+                self._key,
+                self._has_key,
+            ),
+        )
+
+
+def _import_client_module(
+    module: str,
+    name: str,
+    args: tuple[Any],
+    kwargs: dict[str, Any],
+    children: list[Any],
+    key: Any,
+    has_key: bool,
+):
+    base = getattr(importlib.import_module(module), name)
+    if has_key:
+        all_kwargs = {**kwargs, "key": key}
+    else:
+        all_kwargs = kwargs
+    with_args = base(*args, **all_kwargs)
+    if children:
+        return with_args[children]
+    else:
+        return with_args
+
+
+def py_to_html_name(py_name: str) -> str:
+    return re.sub("_$", "", py_name).replace("_", "-")
+
+
+def create_html_element(tagname: str) -> HTMLElement:
+    """
+    Create an HTML element. Usually, you will use the :mod:`blu.html`
+    module to create HTML elements, but in rare cases where you cannot
+    import the tag name you need from :mod:`blu.html`, you can use this
+    function to create an HTML element from any valid tag name.
+
+    .. code-block:: python
+
+        from blu import create_rare_html_element
+
+        my_element = create_rare_html_element('my_element-')
+
+        my_element(id='my-id')['Hello, World!']
+
+
+    .. code-block:: html
+
+        <my_element->Hello, World!</my_element->
+
+    :param tagname: A valid HTML tag name.
+    :return: A :class:`blu.HTMLElement` whose tag name is ``tagname``,
+        with no props set.
+    """
+    return HTMLElement(tagname, {}, [])
+
+
+if is_client:
+    from pyscript.ffi import create_proxy  # type: ignore
+
+
+def client(renderer: ClientRenderer) -> ClientElement:
+    """
+    Decorator that converts a rendering function into a
+    :class:`blu.ClientElement`.
+
+    .. code-block:: python
+
+        from blu import client
+        from blu.html import span
+
+
+        @client
+        def ColoredText(color):
+            return span(style={'color': color})[(yield)]
+
+    :param renderer: The function that should be used to render the
+        :class:`ClientElement <blu.ClientElement>`.
+
+    :return: An element that will be rendered client-side using
+        ``renderer``.
+
+    When a :class:`ClientElement <blu.ClientElement>` is rendered, the
+    rendering function it was created from is called with whatever
+    arguments were passed in using :meth:`ClientElement.__call__()
+    <blu.ClientElement.__call__>`:
+
+    .. code-block:: python
+
+        from blu import client
+
+
+        @client
+        def Greeting(name='World'):
+            return f'Hello, {name}!'
+
+
+        Greeting('Gary')
+
+    .. code-block:: html
+
+        Hello, Gary!
+
+    If arguments were never set using :meth:`ClientElement.__call__()
+    <blu.ClientElement.__call__>`, then the render function will be
+    called with no arguments:
+
+    .. code-block:: python
+
+        from blu import client
+
+
+        @client
+        def Greeting(name='World'):
+            return f'Hello, {name}!'
+
+
+        Greeting
+
+    .. code-block:: html
+
+        Hello, World!
+
+    A render function may use the yield keyword (only once) to get the
+    children set using :meth:`ClientElement.__getitem__()
+    <blu.ClientElement.__getitem__>`:
+
+    .. code-block:: python
+
+        from blu import client
+        from blu.html import span
+
+
+        @client
+        def RedText():
+            return span(style={'color': 'red'})[(yield)]
+
+
+        RedText['Danger!']
+
+    .. code-block:: html
+
+        <span style='color: red'>Danger!</span>
+
+    If the element's children were never set using
+    :meth:`ClientElement.__getitem__() <blu.ClientElement.__getitem__>`,
+    it won't have any children:
+
+    .. code-block:: python
+
+        from blu import client
+        from blu.html import span
+
+
+        @client
+        def RedText():
+            return span(style={'color': 'red'})[(yield)]
+
+
+        RedText
+
+    .. code-block:: html
+
+        <span style='color: red'></span>
+
+    """
+    element = ClientElement(renderer, (), {}, [], None, False)
+    if is_client:
+        create_proxy(element)  # type: ignore
+    return element