nativelayout 1.2.0__py3-none-any.whl

nativelayout/core/layout_host.py

@@ -0,0 +1,248 @@
+"""Contract of the host and render session (port of LayoutHost.kt).
+
+`next_event` is asynchronous (`suspend` in Kotlin): in Kivy it runs on asyncio.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from . import scopes as Scopes
+from .differ import Change, diff
+from .layout_engine import LayoutEngine, LayoutWarning
+from .tree import Native, native_children
+
+# Key of the event the host sends when the system back button is pressed.
+BACK_EVENT_KEY = "\u0000back"
+
+
+@dataclass(frozen=True)
+class LayoutEvent:
+    key: str
+
+
+class LayoutHost(ABC):
+    @abstractmethod
+    def apply_changes(self, changes: list[Change]) -> None: ...
+
+    @abstractmethod
+    async def next_event(self) -> LayoutEvent | None: ...
+
+    @abstractmethod
+    def field_text(self, id: str) -> str | None: ...
+
+    @abstractmethod
+    def field_checked(self, id: str) -> bool | None: ...
+
+    @abstractmethod
+    def set_value(self, id: str, text: str) -> None: ...
+
+    @abstractmethod
+    def save(self, key: str, text: str) -> None: ...
+
+    @abstractmethod
+    def load(self, key: str) -> str | None: ...
+
+    @abstractmethod
+    def exists(self, key: str) -> bool: ...
+
+    @abstractmethod
+    def delete(self, key: str) -> None: ...
+
+    @abstractmethod
+    def close(self) -> None: ...
+
+    def show_error(self, text: str) -> None:
+        """Shows an error in place of the screen (optional)."""
+
+    def post_back(self) -> None:
+        """Wakes the program with the back-button event (optional)."""
+
+
+@dataclass
+class FilledMarkup:
+    html: str
+    line: int
+    variables: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class PreparedRender:
+    """Result of `LayoutSession.prepare`: plain data, it can be built on any thread."""
+    root: Native
+    by_key: dict[str, Native]
+    by_id: dict[str, Native]
+    changes: list[Change]
+    warnings: list[LayoutWarning]
+
+
+class LayoutSession:
+    def __init__(self, host: LayoutHost):
+        self._host = host
+        self._tree: Native | None = None
+        self._by_key: dict[str, Native] = {}
+        self._by_id: dict[str, Native] = {}
+        self._last_event: LayoutEvent | None = None
+        self._clicked_index = -1
+        self._closed = False
+        self._items: dict[str, object] = {}
+        self.warnings: list[LayoutWarning] = []
+
+    def prepare(self, m: FilledMarkup) -> PreparedRender:
+        """Heavy part: builds the tree, indexes it and diffs it against the one on screen. Does not touch the host."""
+        r = LayoutEngine.build(m.html, m.line, m.variables)
+        changes = diff(self._tree, r.root)
+        by_key: dict[str, Native] = {}
+        self._index(r.root, by_key)
+        return PreparedRender(r.root, by_key, r.by_id, changes, r.warnings)
+
+    async def commit(self, p: PreparedRender) -> bool:
+        """Light part: applies the changes to the views and waits for the next event (on the thread of the views)."""
+        if self._closed:
+            return False
+        for a in p.warnings:
+            if not any(w.message == a.message and w.line == a.line for w in self.warnings):
+                self.warnings.append(a)
+        if p.changes:
+            self._host.apply_changes(p.changes)
+        self._tree = p.root
+        self._by_key = p.by_key
+        self._by_id = p.by_id
+        self._last_event = None
+        self._clicked_index = -1
+
+        event = await self._host.next_event()
+        if event is None:
+            self._closed = True
+            self._tree = None
+            self._host.close()
+            return False
+        self._last_event = event
+        return True
+
+    async def render(self, m: FilledMarkup) -> bool:
+        return await self.commit(self.prepare(m))
+
+    # ---- identity inside a `for` (section 5.7)
+    def set_scope_items(self, items: dict[str, object]) -> None:
+        self._items = items
+
+    def _tapped_scope(self) -> str | None:
+        if self._last_event is None:
+            return None
+        n = self._by_key.get(self._last_event.key)
+        return n.scope if n is not None else None
+
+    def clicked_item(self, name: str):
+        path = self._tapped_scope()
+        if path is None:
+            raise RuntimeError(f"clicked('{name}'): the tapped element is not inside a 'for'")
+        segments = path.split("/")
+        for i in range(len(segments) - 1, -1, -1):
+            if Scopes.variable_of(segments[i]) == name:
+                prefix = "/".join(segments[:i + 1])
+                if prefix not in self._items:
+                    break
+                return self._items[prefix]
+        raise RuntimeError(f"clicked('{name}'): the tapped element is not inside 'for {name} in ...'")
+
+    def scoped_id(self, id: str, given: list | None = None) -> str | None:
+        given = given or []
+        if not given:
+            if id in self._by_id:
+                return id
+            prefix = id + Scopes.SEP
+            sample = next((k for k in self._by_id if k.startswith(prefix)), None)
+            if sample is None:
+                return None
+            segs = sample[len(prefix):].split("/")
+            vars_ = ", ".join(Scopes.variable_of(s) for s in segs)
+            raise RuntimeError(f"'{id}' is repeated: give {len(segs)} item(s), one for each of: {vars_}")
+        prefix = id + Scopes.SEP
+        candidates = [k for k in self._by_id if k.startswith(prefix)]
+        if not candidates:
+            return None
+        for c in candidates:
+            segments = c[len(prefix):].split("/")
+            if len(segments) != len(given):
+                continue
+            ok = True
+            path = ""
+            for k, seg in enumerate(segments):
+                path = seg if k == 0 else path + "/" + seg
+                if path not in self._items or not Scopes.same_item(
+                        given[k], self._items[path], Scopes.token_of(seg)):
+                    ok = False
+                    break
+            if ok:
+                return c
+        return None
+
+    def click(self, target: str) -> bool:
+        ev = self._last_event
+        if ev is None:
+            return False
+        node = self._by_key.get(ev.key)
+        if node is None:
+            return False
+        if target.startswith("."):
+            cls = target[1:]
+            if cls not in node.classes:
+                return False
+            all_: list[Native] = []
+            if self._tree is not None:
+                self._collect_class(self._tree, cls, all_)
+            self._clicked_index = next((i for i, n in enumerate(all_) if n.key == node.key), -1)
+            return True
+        nid = node.id
+        if nid == target or (nid is not None and node.scope is not None
+                             and nid.split(Scopes.SEP, 1)[0] == target):
+            self._clicked_index = -1
+            return True
+        return False
+
+    def click_index(self) -> int:
+        return self._clicked_index
+
+    def is_back(self) -> bool:
+        return self._last_event is not None and self._last_event.key == BACK_EVENT_KEY
+
+    def reset(self) -> None:
+        """Forgets the tree on screen: the next render builds everything from scratch (the screen changed)."""
+        self._tree = None
+
+    def field_text(self, id: str, given: list | None = None) -> str | None:
+        s = self.scoped_id(id, given)
+        return self._host.field_text(s) if s is not None else None
+
+    def field_checked(self, id: str, given: list | None = None) -> bool | None:
+        s = self.scoped_id(id, given)
+        return self._host.field_checked(s) if s is not None else None
+
+    def set_value(self, id: str, text: str, given: list | None = None) -> None:
+        s = self.scoped_id(id, given)
+        if s is not None:
+            self._host.set_value(s, text)
+
+    def save(self, key: str, text: str) -> None:
+        self._host.save(key, text)
+
+    def load(self, key: str) -> str | None:
+        return self._host.load(key)
+
+    def exists(self, key: str) -> bool:
+        return self._host.exists(key)
+
+    def delete(self, key: str) -> None:
+        self._host.delete(key)
+
+    def _index(self, n: Native, result: dict[str, Native]) -> None:
+        result[n.key] = n
+        for f in native_children(n):
+            self._index(f, result)
+
+    def _collect_class(self, n: Native, cls: str, result: list[Native]) -> None:
+        if cls in n.classes:
+            result.append(n)
+        for f in native_children(n):
+            self._collect_class(f, cls, result)

nativelayout/core/program.py

@@ -0,0 +1,290 @@
+"""Program side: the verbs of the spec (section 8) on top of the engine.
+
+The part of `NativeView` that does not depend on the platform. Each host (Kivy/android, Kivy/desktop)
+provides the `LayoutHost`, the `loader` and the dark theme.
+
+Two styles, as in the spec:
+  - screen functions: `def panel(): s = state({...}); if click("add"): ...; return view("panel.nl", s)`
+  - base layer:       `while await ui.render(screen, data): ...`
+"""
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import traceback
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable
+
+from .errors import NativeLayoutError
+from .expander import Expander
+from .layout_host import FilledMarkup, LayoutHost, LayoutSession
+
+MAX_HOPS = 8
+
+
+class Page:
+    """What a screen function returns: `view(...)`, `go(...)` or `go_back()`."""
+
+
+class ViewPage(Page):
+    def __init__(self, screen: "Screen", data: dict):
+        self.screen = screen
+        self.data = data
+
+
+class GoPage(Page):
+    def __init__(self, next_: Callable[[], Page], root: bool = False):
+        self.next = next_
+        self.root = root
+
+
+class BackPage(Page):
+    pass
+
+
+_BACK = BackPage()
+
+
+class Screen:
+    def __init__(self, name: str, source: str):
+        self.name = name
+        self.source = source
+
+
+_current: contextvars.ContextVar["NativeViewBase | None"] = contextvars.ContextVar(
+    "nativelayout_current", default=None)
+
+
+class NativeViewBase:
+    def __init__(self, host: LayoutHost, loader: Callable[[str], str | None],
+                 app: Callable[[], Page] | None = None, body=None,
+                 is_dark: Callable[[], bool] = lambda: False):
+        self._host = host
+        self._loader = loader
+        self._app = app
+        self._body = body
+        self._is_dark = is_dark
+        self._session = LayoutSession(host)
+        self._worker = ThreadPoolExecutor(max_workers=1, thread_name_prefix="nativelayout-prepare")
+        self._closed = False
+        self._screens: dict[str, Screen] = {}
+        self._slots: list = []
+        self._slot_index = 0
+        self._fresh = False
+        self._history: list[Callable[[], Page]] = []
+        self._back_handled = False
+        self._last_shown: ViewPage | None = None
+        # called when the back button is pressed on the first screen and the program did not handle it
+        self.on_exit: Callable[[], None] | None = None
+
+    # ---- base layer
+    def screen(self, name: str) -> Screen:
+        source = self._loader(name)
+        if source is None:
+            raise ValueError(f"screen not found: {name}")
+        return Screen(name, source)
+
+    async def render(self, screen: Screen, data: dict | None = None) -> bool:
+        if not isinstance(screen, Screen):
+            raise TypeError("render: expected a screen")
+        if self._closed:
+            return False
+        data = data if data is not None else {}
+
+        def work():
+            ex = Expander.expand(screen.source, data, lambda n: self._loader(n), self._is_dark())
+            return self._session.prepare(FilledMarkup(ex.html, 1)), ex
+
+        loop = asyncio.get_running_loop()
+        prepared, expanded = await loop.run_in_executor(self._worker, work)
+        self._session.set_scope_items(expanded.items)
+        for w in expanded.warnings:
+            if not any(x.message == w.message and x.line == w.line for x in self._session.warnings):
+                self._session.warnings.append(w)
+        return await self._session.commit(prepared)
+
+    # ---- screen functions
+    def state(self, initial):
+        i = self._slot_index
+        self._slot_index += 1
+        if i == len(self._slots):
+            self._slots.append(initial() if callable(initial) else initial)
+        return self._slots[i]
+
+    def view(self, name: str, data: dict | None = None) -> Page:
+        scr = self._screens.get(name)
+        if scr is None:
+            scr = self._screens[name] = self.screen(name)
+        return ViewPage(scr, data if data is not None else {})
+
+    def go(self, next_: Callable[[], Page]) -> Page:
+        return GoPage(next_)
+
+    def go_root(self, next_: Callable[[], Page]) -> Page:
+        return GoPage(next_, root=True)
+
+    def go_back(self) -> Page:
+        return _BACK
+
+    def can_go_back(self) -> bool:
+        return bool(self._history)
+
+    def back(self) -> bool:
+        if self._fresh or not self._session.is_back():
+            return False
+        self._back_handled = True
+        return True
+
+    def press_back(self) -> None:
+        if not self._closed:
+            self._host.post_back()
+
+    async def run(self) -> None:
+        """Runs the program until the window closes. An error is shown in place of the screen."""
+        try:
+            if self._app is not None:
+                await self._run_app(self._app)
+            elif self._body is not None:
+                token = _current.set(self)
+                try:
+                    await self._body(self)
+                finally:
+                    _current.reset(token)
+        except Exception as error:
+            traceback.print_exc()
+            self._host.show_error(error.format() if isinstance(error, NativeLayoutError)
+                                  else (str(error) or repr(error)))
+
+    async def _run_app(self, app: Callable[[], Page]) -> None:
+        current = app
+        hops = 0
+        while not self._closed:
+            self._slot_index = 0
+            self._back_handled = False
+            token = _current.set(self)
+            try:
+                page = current()
+            finally:
+                _current.reset(token)
+            if not self._fresh and not self._back_handled and self._session.is_back():
+                if self._history:
+                    page = _BACK
+                elif self.on_exit is not None:
+                    self.on_exit()
+            if isinstance(page, BackPage) and not self._history:
+                # nothing to go back to: the screen stays as it is
+                if self.on_exit is not None:
+                    self.on_exit()
+                if self._last_shown is None:
+                    raise RuntimeError("goBack: there is no screen to return to")
+                page = self._last_shown
+            if isinstance(page, GoPage):
+                hops += 1
+                if hops > MAX_HOPS:
+                    raise RuntimeError("go: too many jumps without showing a screen")
+                if page.root:
+                    self._history.clear()
+                else:
+                    self._history.append(current)
+                current = page.next
+                self._last_shown = None
+                self._slots.clear()
+                self._fresh = True
+                self._session.reset()
+            elif isinstance(page, BackPage):
+                hops += 1
+                if hops > MAX_HOPS:
+                    raise RuntimeError("go: too many jumps without showing a screen")
+                current = self._history.pop()
+                self._last_shown = None
+                self._slots.clear()
+                self._fresh = True
+                self._session.reset()
+            elif isinstance(page, ViewPage):
+                hops = 0
+                self._last_shown = page
+                if not await self.render(page.screen, page.data):
+                    return
+                self._fresh = False
+            else:
+                raise TypeError("a screen function must return view(...), go(...) or go_back()")
+
+    # ---- taps and fields (after a jump there is no tap yet: they answer "nothing")
+    def click(self, target: str) -> bool:
+        return (not self._fresh) and self._session.click(target)
+
+    def click_index(self) -> int:
+        return -1 if self._fresh else self._session.click_index()
+
+    def clicked(self, name: str):
+        return None if self._fresh else self._session.clicked_item(name)
+
+    def value(self, id: str, *items) -> str:
+        if self._fresh:
+            return ""
+        r = self._session.field_text(id, list(items))
+        return r if r is not None else ""
+
+    def checked(self, id: str, *items) -> bool:
+        if self._fresh:
+            return False
+        r = self._session.field_checked(id, list(items))
+        return r if r is not None else False
+
+    def set_value(self, id: str, *args) -> None:
+        """`set_value(id, text)` or `set_value(id, item..., text)`: the last argument is the text."""
+        if not args or not isinstance(args[-1], str):
+            raise TypeError("set_value(id, item..., text): the last argument must be the text")
+        self._session.set_value(id, args[-1], list(args[:-1]))
+
+    def save(self, key: str, text: str) -> None:
+        self._session.save(key, text)
+
+    def load(self, key: str) -> str | None:
+        return self._session.load(key)
+
+    def exists(self, key: str) -> bool:
+        return self._session.exists(key)
+
+    def delete(self, key: str) -> None:
+        self._session.delete(key)
+
+    def close(self) -> None:
+        self._closed = True
+        self._worker.shutdown(wait=False)
+        self._host.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+        return False
+
+
+# ---- free verbs, bound to the NativeView that is calling the screen function
+def _ui() -> NativeViewBase:
+    ui = _current.get()
+    if ui is None:
+        raise RuntimeError("this verb can only be used inside a screen function")
+    return ui
+
+
+def screen(name): return _ui().screen(name)
+def state(initial): return _ui().state(initial)
+def view(name, data=None): return _ui().view(name, data)
+def go(next_): return _ui().go(next_)
+def go_root(next_): return _ui().go_root(next_)
+def go_back(): return _ui().go_back()
+def can_go_back(): return _ui().can_go_back()
+def back(): return _ui().back()
+def click(target): return _ui().click(target)
+def click_index(): return _ui().click_index()
+def clicked(name): return _ui().clicked(name)
+def value(id, *items): return _ui().value(id, *items)
+def checked(id, *items): return _ui().checked(id, *items)
+def set_value(id, *args): return _ui().set_value(id, *args)
+def save(key, text): return _ui().save(key, text)
+def load(key): return _ui().load(key)
+def exists(key): return _ui().exists(key)
+def delete(key): return _ui().delete(key)

nativelayout/core/scopes.py

@@ -0,0 +1,52 @@
+"""Identity of the repetitions of a `for` (port of Scopes.kt, section 5.7)."""
+from __future__ import annotations
+
+SEP = "~"
+_KEY_FIELDS = ("key", "id")
+_HEX = "0123456789ABCDEF"
+
+
+def key_of_item(item) -> str | None:
+    """Automatic key of an item: its field `key`, or else its field `id`. Only text and whole numbers."""
+    if not isinstance(item, dict):
+        return None
+    for field in _KEY_FIELDS:
+        v = item.get(field)
+        if isinstance(v, str):
+            t = v.strip()
+            if t:
+                return t
+        elif isinstance(v, int) and not isinstance(v, bool):
+            return str(v)
+    return None
+
+
+def encode(s: str) -> str:
+    """Letters, digits, `_`, `-` and `.` stay; the rest becomes %XX (`/`, `:` and `~` never appear)."""
+    out = []
+    for c in s.encode("utf-8"):
+        plain = (97 <= c <= 122) or (65 <= c <= 90) or (48 <= c <= 57) or c in (95, 45, 46)
+        out.append(chr(c) if plain else "%" + _HEX[c >> 4] + _HEX[c & 15])
+    return "".join(out)
+
+
+def token(key: str | None, index: int) -> str:
+    """Token of a repetition: its key, or `%p` + the position when there is no key."""
+    return encode(key) if key is not None else f"%p{index}"
+
+
+def variable_of(segment: str) -> str:
+    return segment.split(":", 1)[0]
+
+
+def token_of(segment: str) -> str:
+    return segment.split(":", 1)[1] if ":" in segment else segment
+
+
+def same_item(given, held, tok: str) -> bool:
+    if given is held or given == held:
+        return True
+    key = key_of_item(given)
+    if key is None:
+        return False
+    return encode(key) == tok