pyweft 0.2.0__py3-none-any.whl

pyweft/component.py

@@ -0,0 +1,487 @@
+"""Component base class and the ``.weft`` loader.
+
+Reactivity model is Blazor's, not React's: there are no observables and no
+proxies. An event handler runs, then the component re-renders and the diff is
+sent. If you mutate state outside a handler (a timer, an async callback), call
+``state_has_changed()`` yourself.
+"""
+
+from __future__ import annotations
+
+import copy
+import functools
+import inspect
+import re
+import textwrap
+import types
+from contextvars import ContextVar
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from .parser import (
+    TElement,
+    TemplateError,
+    TFill,
+    TFor,
+    TIf,
+    TSlot,
+    block_spans,
+    parse_template,
+    split_source,
+)
+from .store import Store
+from .styles import scope_css
+
+
+class Component:
+    __template__: list[Any] = []
+    # Set by the loader when the file has a <style> block: the id stamped on
+    # every element this component renders (as ``data-w-<scope>``) and the
+    # block's CSS with its selectors rewritten to match only those elements.
+    __scope__: str | None = None
+    __style__: str = ""
+    # Tag name -> component class, consulted by the renderer when a template
+    # element's tag is capitalised. Filled by the loader or passed explicitly.
+    components: dict[str, type] = {}
+
+    def __init__(self, **params):
+        self._dirty = True
+        self._on_change: Callable[[Component], None] | None = None
+        self._rendered_once = False
+
+        # Class-level mutable defaults (``history: list = []`` in a code block)
+        # would otherwise be shared by every instance -- a classic Python
+        # footgun that would look like a framework bug. Copy them per instance.
+        cls = type(self)
+        for name in dir(cls):
+            if name.startswith("_") or name == "components":
+                continue
+            try:
+                value = getattr(cls, name)
+            except AttributeError:
+                continue
+            if isinstance(value, (list, dict, set)):
+                setattr(self, name, copy.deepcopy(value))
+
+        for key, value in params.items():
+            setattr(self, key, value)
+
+    # ------------------------------------------------------------ lifecycle
+
+    def on_init(self) -> None:
+        """Called once before the first render. May be ``async``: the part
+        before the first ``await`` is in the first render, and the component
+        renders again when it finishes."""
+
+    def on_after_render(self, first: bool) -> None:
+        """Called after each render has been applied. May be ``async``."""
+
+    def on_dispose(self) -> None:
+        """Called when the component is torn down. Must not be ``async``:
+        the component's tasks are cancelled just before this runs."""
+
+    def start_task(self, awaitable: Any) -> Any:
+        """Run a coroutine (or other awaitable) as a task this component owns,
+        and return the ``asyncio.Task``.
+
+        The component re-renders when the task finishes and the task is
+        cancelled if the component is removed first. Call
+        ``state_has_changed()`` inside it to show progress before the end.
+        Works once the component is rendered, from ``on_init`` onwards.
+        """
+        start = self.__dict__.get("_pw_start")
+        if start is None:
+            if hasattr(awaitable, "close"):
+                awaitable.close()  # no "never awaited" warning on top
+            raise RuntimeError(
+                f"{type(self).__name__}.start_task() needs the component to be "
+                "rendered (call it from on_init or later, not __init__), and "
+                "not yet removed"
+            )
+        return start(awaitable)
+
+    # ---------------------------------------------------------------- focus
+    # Requests carried out by the host once the next render is on the page,
+    # so they can name an element that this very handler makes appear.
+
+    def focus(self, ref: str) -> None:
+        """Move keyboard focus to the element marked ``ref="..."`` in this
+        component's template. On a component tag, focus goes to the first
+        thing inside it that can take focus."""
+        self._pw_request("focus", ref)
+
+    def focus_first(self, ref: str) -> None:
+        """Focus the first focusable element inside ``ref``."""
+        self._pw_request("focus_first", ref)
+
+    def focus_last(self, ref: str) -> None:
+        """Focus the last focusable element inside ``ref``."""
+        self._pw_request("focus_last", ref)
+
+    def scroll_to(self, ref: str) -> None:
+        """Scroll the page so the element marked ``ref`` is in view."""
+        self._pw_request("scroll_to", ref)
+
+    def save_focus(self) -> None:
+        """Remember what has focus now, for ``restore_focus()``: a popup
+        saves it as it opens and gives it back as it closes."""
+        self._pw_request("save_focus")
+
+    def restore_focus(self) -> None:
+        """Focus what the matching ``save_focus()`` remembered, if it is
+        still on the page."""
+        self._pw_request("restore_focus")
+
+    def _pw_request(self, op: str, ref: str | None = None) -> None:
+        command = self.__dict__.get("_pw_command")
+        if command is None:
+            raise RuntimeError(
+                f"{type(self).__name__}.{op}() needs the component to be rendered "
+                "(call it from on_init or later), and not yet removed"
+            )
+        command(op, ref)
+        # Even when nothing else changed, the host must render and settle to
+        # reach the point where it carries requests out.
+        self.state_has_changed()
+
+    # ---------------------------------------------------------------- state
+
+    def state_has_changed(self) -> None:
+        self._dirty = True
+        if self._on_change is not None:
+            self._on_change(self)
+        # Set by the Renderer that owns this instance; how a change made
+        # outside a handler (timer, JS callback, asyncio task) reaches the host.
+        invalidate = self.__dict__.get("_pw_invalidate")
+        if invalidate is not None:
+            invalidate()
+
+    def has_slot(self, name: str = "default") -> bool:
+        """Whether the parent passed content for this slot, for wrappers that
+        should only render around it: ``<If cond="has_slot('footer')">``."""
+        return name in self.__dict__.get("_pw_slots", {})
+
+    def emit(self, event: str, payload: Any = None) -> Any:
+        """Invoke the parent's ``@event`` callback, Vue-style.
+
+        ``<Child @remove="drop(item)" />`` in a parent template arrives here as
+        an ``on_remove`` callable prop; ``self.emit("remove")`` in the child
+        calls it. Emitting an event nobody listens to is a no-op, as in Vue.
+        """
+        callback = getattr(self, f"on_{event}", None)
+        if callable(callback):
+            return callback(payload)
+        return None
+
+
+def compile_code_block(src: str, filename: str) -> Any:
+    """The ``<code>`` block of a ``.weft`` source, compiled so that line
+    numbers in tracebacks are lines of the file, not of the block.
+    (split_source's own output stays unpadded.)"""
+    _, code_src, _ = split_source(src)
+    span = block_spans(src).get("code")
+    if span:
+        code_src = "\n" * src.count("\n", 0, span[0]) + code_src
+    return compile(textwrap.dedent(code_src), filename, "exec")
+
+
+def _imported_helper(value: Any) -> bool:
+    """A function imported into a code block (``from x import toast``), to be
+    called as itself: as a class attribute it would otherwise become a
+    method, and ``toast("Saved")`` in a template would get the component as
+    its message. Functions the code block defines have no ``__module__``
+    (the exec namespace has no ``__name__``); an imported one whose first
+    parameter is ``self`` is meant as a method and stays one."""
+    if not isinstance(value, types.FunctionType) or value.__module__ is None:
+        return False
+    names = value.__code__.co_varnames[: value.__code__.co_argcount]
+    return not names or names[0] != "self"
+
+
+def component_from_source(
+    src: str,
+    name: str = "Component",
+    base: type = Component,
+    components: dict[str, type] | None = None,
+    scope: str | None = None,
+    filename: str | None = None,
+) -> type:
+    """``scope`` is the style scope id; it defaults to the snake-cased ``name``
+    and only matters when the source has a ``<style>`` block. ``filename`` is
+    what tracebacks show for errors in the code block."""
+    template_src, _, style_src = split_source(src)
+    nodes = parse_template(template_src)
+
+    namespace: dict[str, Any] = {}
+    exec(compile_code_block(src, filename or f"<{name}.weft>"), namespace)
+    namespace.pop("__builtins__", None)
+    for key, value in namespace.items():
+        if _imported_helper(value):
+            namespace[key] = staticmethod(value)
+    namespace["__template__"] = nodes
+    if style_src.strip():
+        scope = scope or _snake(name)
+        namespace["__scope__"] = scope
+        namespace["__style__"] = scope_css(style_src, scope).strip()
+    else:
+        namespace["__scope__"] = None
+        namespace["__style__"] = ""
+    # A `components` dict in the code block wins over the passed-in registry.
+    namespace["components"] = {**(components or {}), **namespace.get("components", {})}
+
+    return type(name, (base,), namespace)
+
+
+_CONTROL_TAGS = {"If", "ElseIf", "Else", "For", "Slot", "Fill", "Dynamic"}
+
+
+def is_component_tag(tag: str) -> bool:
+    """``TodoItem`` and ``widgets.Row`` are components; ``div`` is not. The
+    last dotted segment decides, so folder names can stay lowercase."""
+    return tag.rsplit(".", 1)[-1][:1].isupper() and tag not in _CONTROL_TAGS
+
+
+def component_named(cls: type, tag: str) -> type | None:
+    """The component a tag names through the code block's own names:
+    ``from pyweft_ui import ui`` makes ``<ui.Button>`` resolve, and
+    ``from widgets import Row`` makes ``<Row>`` resolve."""
+    target: Any = cls
+    for part in tag.split("."):
+        target = getattr(target, part, None)
+        if target is None:
+            return None
+    if isinstance(target, type) and issubclass(target, Component):
+        return target
+    return None
+
+
+# Not props even though they live on the class: imports, nested classes,
+# methods, computed values, and shared stores (imported, not passed in).
+_NOT_PROPS = (types.ModuleType, type, property, staticmethod, classmethod, Store)
+
+
+@functools.lru_cache(maxsize=1024)
+def declared_props(cls: type) -> frozenset[str]:
+    """Names a parent may set on this component: its fields (annotated or
+    given a default in the code block), including ``on_<event>`` callbacks.
+    Any other attribute written on its tag goes to its root element."""
+    names: set[str] = set()
+    for klass in cls.__mro__:
+        if klass is Component or klass is object:
+            continue
+        try:
+            names.update(inspect.get_annotations(klass))
+        except Exception:
+            pass
+        for name, value in vars(klass).items():
+            if callable(value) or isinstance(value, _NOT_PROPS):
+                continue
+            names.add(name)
+    return frozenset(n for n in names if not n.startswith("_") and n != "components")
+
+
+def _component_tags(nodes: list[Any], found: set[str]) -> set[str]:
+    for node in nodes:
+        if isinstance(node, TElement):
+            if is_component_tag(node.tag):
+                found.add(node.tag)
+            _component_tags(node.children, found)
+        elif isinstance(node, TIf):
+            for _, children in node.branches:
+                _component_tags(children, found)
+        elif isinstance(node, (TFor, TSlot, TFill)):
+            _component_tags(node.children, found)
+    return found
+
+
+def _snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+@dataclass
+class _LoadContext:
+    root: Path  # the app root: where dotted tags resolve from
+    loading: set[Path]  # files being loaded right now, for cycle detection
+    current_dir: Path  # folder of the file whose code block is executing
+    # Files already loaded in this load, so a file used by several components
+    # becomes one class: compiled once, and an unambiguous target when hot
+    # reload moves live instances onto freshly compiled classes.
+    loaded: dict[Path, type]
+    # Prepended to style scope ids, so a library's button.weft and an app's
+    # button.weft cannot share styles.
+    scope_prefix: str | None = None
+
+
+# Set while a .weft file is being loaded, so a load_component() call inside
+# its code block resolves relative paths against that file (not the process
+# cwd, which in the browser is not the app folder) and shares the same root
+# and cycle detection.
+_LOAD: ContextVar[_LoadContext | None] = ContextVar("pyweft_load", default=None)
+
+
+def _scope_id(path: Path, root: Path) -> str:
+    """Style scope id: the path below the app root with folders joined by
+    ``-`` (``widgets/row.weft`` -> ``widgets-row``), so equal file names in
+    different folders cannot share styles. Top-level files keep their stem."""
+    try:
+        rel = path.relative_to(root)
+    except ValueError:
+        return path.stem  # loaded from outside the app root
+    return "-".join(rel.with_suffix("").parts)
+
+
+def _find_component(tag: str, referrer: Path, root: Path) -> Path:
+    *folders, leaf = tag.split(".")
+    for folder in folders:
+        if not folder.isidentifier():
+            raise TemplateError(
+                f"<{tag}> in {referrer.name}: {folder!r} is not a valid folder "
+                "name for a component tag (use letters, digits and underscores)"
+            )
+    base = root.joinpath(*folders) if folders else referrer.parent
+    candidates = (base / f"{leaf}.weft", base / f"{_snake(leaf)}.weft")
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    where = (
+        f"in {'/'.join(folders)}/ under the app root"
+        if folders
+        else f"alongside {referrer.name}"
+    )
+    raise TemplateError(
+        f"component <{tag}> used in {referrer.name} but no {candidates[0].name} "
+        f"or {candidates[1].name} found {where}"
+    )
+
+
+def load_component(
+    path: str | Path,
+    name: str | None = None,
+    *,
+    root: str | Path | None = None,
+    scope_prefix: str | None = None,
+) -> type:
+    """Load a ``.weft`` file and, recursively, the components it uses.
+
+    A capitalised tag is looked up, in order:
+
+    * in the code block's explicit ``components`` dict
+    * through the code block's own names: after ``from pyweft_ui import ui``,
+      ``<ui.Button>`` is ``ui.Button``
+    * on disk: ``<TodoItem>`` is ``TodoItem.weft`` or ``todo_item.weft`` next
+      to the file that uses it; ``<widgets.Row>`` is ``widgets/Row.weft`` or
+      ``widgets/row.weft`` under the app root
+
+    ``root`` defaults to the folder of the first file loaded.
+    """
+    ctx = _LOAD.get()
+    p = Path(path)
+    if not p.is_absolute() and ctx is not None:
+        p = ctx.current_dir / p
+    p = p.resolve()
+    if root is not None:
+        root_dir = Path(root).resolve()
+    elif ctx is not None:
+        root_dir = ctx.root
+        scope_prefix = scope_prefix or ctx.scope_prefix
+    else:
+        root_dir = p.parent
+    loading = ctx.loading if ctx is not None else set()
+    loaded = ctx.loaded if ctx is not None else {}
+
+    if p in loaded:
+        return loaded[p]
+    if p in loading:
+        raise TemplateError(f"circular component reference involving {p.name}")
+    loading.add(p)
+    token = _LOAD.set(_LoadContext(root_dir, loading, p.parent, loaded, scope_prefix))
+    try:
+        text = p.read_text(encoding="utf-8")
+        scope = _scope_id(p, root_dir)
+        if scope_prefix:
+            scope = f"{scope_prefix}-{scope}"
+        try:
+            cls = component_from_source(
+                text, name or p.stem, scope=scope, filename=str(p)
+            )
+        except TemplateError as exc:
+            try:
+                where = p.relative_to(root_dir).as_posix()
+            except ValueError:
+                where = p.name
+            raise TemplateError(f"{where}: {exc}") from exc
+        cls.__weft_file__ = str(p)
+        cls.__weft_src__ = text
+
+        registry = dict(cls.components)
+        for tag in sorted(_component_tags(cls.__template__, set())):
+            if tag not in registry:
+                imported = component_named(cls, tag)
+                if imported is not None:
+                    registry[tag] = imported
+                    continue
+                found = _find_component(tag, p, root_dir)
+                registry[tag] = load_component(found, tag.rsplit(".", 1)[-1])
+        cls.components = registry
+        loaded[p] = cls
+        return cls
+    finally:
+        _LOAD.reset(token)
+        loading.discard(p)
+
+
+class ComponentLibrary:
+    """A folder of ``.weft`` components, as attributes. This is how a package
+    ships components::
+
+        # my_widgets/__init__.py
+        from pathlib import Path
+        from pyweft import ComponentLibrary
+
+        ui = ComponentLibrary(Path(__file__).parent, prefix="ui")
+
+    and how an app uses them: ``from my_widgets import ui`` in its code
+    block, then ``<ui.Button>``, ``<ui.Card>`` in its template.
+
+    ``ui.Button`` loads ``Button.weft`` or ``button.weft`` on first use.
+    Inside the folder, components refer to each other as usual (siblings by
+    name, subfolders by dotted tags from the folder). ``prefix`` keeps the
+    library's scoped styles apart from the app's.
+    """
+
+    def __init__(self, folder: str | Path, prefix: str | None = None):
+        self._folder = Path(folder).resolve()
+        self._prefix = prefix or self._folder.name
+
+    def __getattr__(self, name: str) -> type:
+        if name.startswith("_") or not name[:1].isupper():
+            raise AttributeError(name)
+        for candidate in (self._folder / f"{name}.weft", self._folder / f"{_snake(name)}.weft"):
+            if candidate.is_file():
+                break
+        else:
+            raise AttributeError(
+                f"{self._prefix} has no component {name} (no {name}.weft or "
+                f"{_snake(name)}.weft in {self._folder})"
+            )
+        # A load of its own: the library's root, prefix and cache must not
+        # mix with those of the app that happens to be loading it.
+        token = _LOAD.set(None)
+        try:
+            cls = load_component(candidate, name, root=self._folder, scope_prefix=self._prefix)
+        finally:
+            _LOAD.reset(token)
+        setattr(self, name, cls)  # loaded once; __getattr__ is not asked again
+        return cls
+
+    def __dir__(self) -> list[str]:
+        """Component names, for completion: text_field.weft -> TextField."""
+        stems = (p.stem for p in self._folder.glob("*.weft"))
+        return sorted(
+            s if s[:1].isupper() else "".join(w.capitalize() for w in s.split("_"))
+            for s in stems
+        )
+
+    def __repr__(self) -> str:
+        return f"<ComponentLibrary {self._prefix} at {self._folder}>"