hypereffect-ui 0.1.0__tar.gz

hypereffect_ui-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+/rust/target/
+/site/demo/wasm/
+/site/demo/lib/
+node_modules/
+/ts/dist/
+/python/dist/
+__pycache__/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

hypereffect_ui-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: hypereffect-ui
+Version: 0.1.0
+Summary: Types and helpers for writing hypereffect servers: messages, line framing, signals and components, an App/Server session driver, and a renderer client with a loopback for tests.
+Project-URL: Homepage, https://hypereffect.dev
+Project-URL: Repository, https://github.com/hypereffect/hypereffect
+Project-URL: Issues, https://github.com/hypereffect/hypereffect/issues
+License-Expression: MIT
+Keywords: cel,gui,hypermedia,server-driven-ui,ui
+Requires-Python: >=3.11
+Requires-Dist: cel-python<0.6,>=0.5
+Description-Content-Type: text/markdown
+
+# hypereffect (Python)
+
+Types and helpers for writing [hypereffect](https://hypereffect.dev) servers in
+Python, ported from the [Rust crate](https://github.com/hypereffect/hypereffect/tree/master/rust):
+elements, handlers and messages with their line framing, signals, the
+components and their nesting rules, an `App`/`Server` session driver, and a
+renderer client with a loopback for testing apps without a renderer.
+
+```
+pip install hypereffect-ui
+```
+
+The distribution is `hypereffect-ui`; the package is imported as
+`hypereffect`. It needs Python 3.11 or later.
+
+## Servers
+
+```python
+from hypereffect import Action, App, Handler, Outbox, cel, ui
+
+
+class Counter(App):
+    def __init__(self) -> None:
+        self.count = 0
+
+    def hello(self, out: Outbox, params: dict[str, str]) -> None:
+        out.signal({"count": 0})
+        out.element(ui.column("main"))
+        out.element(ui.text("value").parent("main").text(cel("'Count: ' + string(s.count)")))
+        out.element(ui.button("inc").parent("main").label("+").on_press(Handler(action="add")))
+
+    def action(self, out: Outbox, action: Action) -> None:
+        if action.name == "add":
+            self.count += 1
+            out.signal({"count": self.count})
+```
+
+- `ui.text("id")` and the other constructors return an `Element` with setters
+  for every attribute (`label`, `variant`, `disabled`, …, or `set` for any
+  other); each takes a literal or `cel("...")`. `bind` sets a signal path, and
+  `on_press`, `on_change`, `on_submit` and `on_dismiss` take a `Handler`,
+  built with keywords: `Handler(action="save", payload=7, indicator="_busy")`,
+  `Handler(patch={"_open": True})` or `Handler(open="https://…")`.
+- `parse_server_message`, `parse_renderer_message` and each message's
+  `to_line` convert to and from lines; `LineBuffer` splits a stream of bytes
+  or text into lines.
+- `hypereffect.signals` has merge patch, local-signal stripping and signal
+  paths.
+- `Server` drives an `App` from what a renderer sends, creating a new app on
+  every hello. An app that overrides `tick_interval` gets `tick` calls.
+
+The library does not open connections. Any transport that carries lines
+works: pass what arrives to `server.receive`, then send
+`server.output.take()`. Over stdio:
+
+```python
+import sys
+
+server = Server(Counter)
+for chunk in iter(sys.stdin.buffer.readline, b""):
+    server.receive(chunk)
+    sys.stdout.write(server.output.take())
+    sys.stdout.flush()
+```
+
+## Testing
+
+`hypereffect.client` is the renderer side without drawing, on top of
+[cel-python](https://github.com/cloud-custodian/cel-python).
+`Loopback` connects it to a `Server` in one process:
+
+```python
+from hypereffect.client import Loopback
+
+
+def test_counter() -> None:
+    l = Loopback(Counter)               # sends hello
+    assert l.trigger("inc", "onPress")  # True if an action was sent
+    assert l.client.attr("value", "text") == "Count: 1"
+    assert l.client.take_diagnostics() == []  # rejected elements or failed expressions
+```
+
+`l.write(path, value)` writes a bound signal as a control does,
+`l.tick(now_ms)` runs the timer, `l.client.value(path)` reads a signal and
+`l.client.take_opens()` returns the URLs buttons asked to open.
+`examples/todos.py` is the task list demo; `tests/test_todos.py` tests it.
+
+cel-python lacks parts of the CEL environment the spec requires, so
+`hypereffect._cel` adds them: comparison of ints and doubles by value, the
+strings, math and lists extensions (following cel-go), the `sortBy` macro,
+and the `math.`, `strings.` and `lists.` namespaces. It relies on
+cel-python's evaluator internals, so the dependency is pinned to 0.5.x.
+
+There is no WebAssembly export like the Rust `wasm_app!`.
+
+## Tests
+
+```
+uv run pytest
+uv run mypy
+```
+
+The tests include the shared renderer fixtures in the repository's
+[`fixtures/`](https://github.com/hypereffect/hypereffect/tree/master/fixtures).

hypereffect_ui-0.1.0/README.md

@@ -0,0 +1,104 @@
+# hypereffect (Python)
+
+Types and helpers for writing [hypereffect](https://hypereffect.dev) servers in
+Python, ported from the [Rust crate](https://github.com/hypereffect/hypereffect/tree/master/rust):
+elements, handlers and messages with their line framing, signals, the
+components and their nesting rules, an `App`/`Server` session driver, and a
+renderer client with a loopback for testing apps without a renderer.
+
+```
+pip install hypereffect-ui
+```
+
+The distribution is `hypereffect-ui`; the package is imported as
+`hypereffect`. It needs Python 3.11 or later.
+
+## Servers
+
+```python
+from hypereffect import Action, App, Handler, Outbox, cel, ui
+
+
+class Counter(App):
+    def __init__(self) -> None:
+        self.count = 0
+
+    def hello(self, out: Outbox, params: dict[str, str]) -> None:
+        out.signal({"count": 0})
+        out.element(ui.column("main"))
+        out.element(ui.text("value").parent("main").text(cel("'Count: ' + string(s.count)")))
+        out.element(ui.button("inc").parent("main").label("+").on_press(Handler(action="add")))
+
+    def action(self, out: Outbox, action: Action) -> None:
+        if action.name == "add":
+            self.count += 1
+            out.signal({"count": self.count})
+```
+
+- `ui.text("id")` and the other constructors return an `Element` with setters
+  for every attribute (`label`, `variant`, `disabled`, …, or `set` for any
+  other); each takes a literal or `cel("...")`. `bind` sets a signal path, and
+  `on_press`, `on_change`, `on_submit` and `on_dismiss` take a `Handler`,
+  built with keywords: `Handler(action="save", payload=7, indicator="_busy")`,
+  `Handler(patch={"_open": True})` or `Handler(open="https://…")`.
+- `parse_server_message`, `parse_renderer_message` and each message's
+  `to_line` convert to and from lines; `LineBuffer` splits a stream of bytes
+  or text into lines.
+- `hypereffect.signals` has merge patch, local-signal stripping and signal
+  paths.
+- `Server` drives an `App` from what a renderer sends, creating a new app on
+  every hello. An app that overrides `tick_interval` gets `tick` calls.
+
+The library does not open connections. Any transport that carries lines
+works: pass what arrives to `server.receive`, then send
+`server.output.take()`. Over stdio:
+
+```python
+import sys
+
+server = Server(Counter)
+for chunk in iter(sys.stdin.buffer.readline, b""):
+    server.receive(chunk)
+    sys.stdout.write(server.output.take())
+    sys.stdout.flush()
+```
+
+## Testing
+
+`hypereffect.client` is the renderer side without drawing, on top of
+[cel-python](https://github.com/cloud-custodian/cel-python).
+`Loopback` connects it to a `Server` in one process:
+
+```python
+from hypereffect.client import Loopback
+
+
+def test_counter() -> None:
+    l = Loopback(Counter)               # sends hello
+    assert l.trigger("inc", "onPress")  # True if an action was sent
+    assert l.client.attr("value", "text") == "Count: 1"
+    assert l.client.take_diagnostics() == []  # rejected elements or failed expressions
+```
+
+`l.write(path, value)` writes a bound signal as a control does,
+`l.tick(now_ms)` runs the timer, `l.client.value(path)` reads a signal and
+`l.client.take_opens()` returns the URLs buttons asked to open.
+`examples/todos.py` is the task list demo; `tests/test_todos.py` tests it.
+
+cel-python lacks parts of the CEL environment the spec requires, so
+`hypereffect._cel` adds them: comparison of ints and doubles by value, the
+strings, math and lists extensions (following cel-go), the `sortBy` macro,
+and the `math.`, `strings.` and `lists.` namespaces. It relies on
+cel-python's evaluator internals, so the dependency is pinned to 0.5.x.
+
+There is no WebAssembly export like the Rust `wasm_app!`.
+
+## Tests
+
+```
+uv run pytest
+uv run mypy
+```
+
+The tests include the shared renderer fixtures in the repository's
+[`fixtures/`](https://github.com/hypereffect/hypereffect/tree/master/fixtures).

hypereffect_ui-0.1.0/examples/todos.py

@@ -0,0 +1,168 @@
+"""A task list: adding, checking off and deleting tasks, a local filter, and
+a confirmation dialog. The Python port of the demo on hypereffect.dev."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hypereffect import Action, App, Element, Handler, Json, Outbox, cel, ui
+
+
+@dataclass
+class Task:
+    id: str
+    title: str
+    done: bool
+
+
+class Todos(App):
+    def __init__(self) -> None:
+        self.next = 1
+        self.tasks = [
+            Task(self.new_id(), title, done)
+            for title, done in [("Water the plants", True), ("Call the bank", False), ("Read the spec", False)]
+        ]
+
+    def new_id(self) -> str:
+        id = f"t{self.next}"
+        self.next += 1
+        return id
+
+    def row(self, task: Task) -> list[Element]:
+        id = task.id
+        done = f"s.done.{id}"
+        return [
+            ui.row(id)
+            .parent("items")
+            .justify("between")
+            .visible(cel(f"s._filter == 'all' || (s._filter == 'done') == {done}")),
+            ui.checkbox(f"{id}-check")
+            .parent(id)
+            .label(task.title)
+            .bind(f"done.{id}")
+            .on_change(Handler(action="toggle", payload=id)),
+            ui.button(f"{id}-del")
+            .parent(id)
+            .label("Delete")
+            .variant("plain")
+            .on_press(Handler(action="delete", payload=id)),
+        ]
+
+    def hello(self, out: Outbox, params: dict[str, str]) -> None:
+        out.signal({
+            "new": "",
+            "done": {t.id: t.done for t in self.tasks},
+            "_filter": "all",
+            "_adding": False,
+            "_confirm": False,
+            "_clearing": False,
+        })
+        out.element(ui.card("todos").title("Tasks"))
+        out.element(ui.row("add-row").parent("todos"))
+        out.element(
+            ui.input("new")
+            .parent("add-row")
+            .placeholder("New task")
+            .bind("new")
+            .error(cel("size(s.new) > 80 ? 'Keep it under 80 characters.' : ''"))
+            .on_submit(Handler(action="add", indicator="_adding"))
+        )
+        out.element(
+            ui.button("add")
+            .parent("add-row")
+            .variant("primary")
+            .label(cel("s._adding ? 'Adding…' : 'Add'"))
+            .disabled(cel("s._adding || s.new.trim() == '' || size(s.new) > 80"))
+            .on_press(Handler(action="add", indicator="_adding"))
+        )
+        out.element(
+            ui.select("filter")
+            .parent("todos")
+            .variant("segmented")
+            .bind("_filter")
+            .options([
+                {"value": "all", "label": "All"},
+                {"value": "open", "label": "Open"},
+                {"value": "done", "label": "Done"},
+            ])
+        )
+        out.element(ui.list("items").parent("todos").empty("Nothing here."))
+        for t in self.tasks:
+            for e in self.row(t):
+                out.element(e)
+        out.element(ui.row("footer").parent("todos").justify("between"))
+        out.element(ui.text("left").parent("footer").variant("caption").text(cel(
+            "string(s.done.filter(k, !s.done[k]).size()) + ' of ' + string(size(s.done)) + ' left'"
+        )))
+        out.element(
+            ui.button("clear")
+            .parent("footer")
+            .variant("failure")
+            .label("Clear completed…")
+            .disabled(cel("!s.done.exists(k, s.done[k]) || s._clearing"))
+            .on_press(Handler(patch={"_confirm": True}))
+        )
+        out.element(
+            ui.dialog("confirm")
+            .title("Clear completed tasks?")
+            .open(cel("s._confirm"))
+            .on_dismiss(Handler(patch={"_confirm": False}))
+        )
+        out.element(ui.text("confirm-text").parent("confirm").text(cel(
+            "string(s.done.filter(k, s.done[k]).size()) + ' tasks will be deleted.'"
+        )))
+        out.element(ui.row("confirm-row").parent("confirm").justify("end"))
+        out.element(
+            ui.button("confirm-no")
+            .parent("confirm-row")
+            .label("Cancel")
+            .on_press(Handler(patch={"_confirm": False}))
+        )
+        out.element(
+            ui.button("confirm-yes")
+            .parent("confirm-row")
+            .variant("failure")
+            .label("Delete")
+            .on_press(Handler(action="clear", patch={"_confirm": False}, indicator="_clearing"))
+        )
+
+    def find(self, id: Json) -> Task | None:
+        return next((t for t in self.tasks if t.id == id), None)
+
+    def action(self, out: Outbox, action: Action) -> None:
+        if action.name == "add":
+            raw = action.signal("new")
+            title = raw.strip() if isinstance(raw, str) else ""
+            if not title or len(title) > 80:
+                out.signal({"_adding": False})
+                return
+            task = Task(self.new_id(), title, False)
+            # New tasks go at the top.
+            first = self.tasks[0].id if self.tasks else None
+            # The signal comes first so that the row's expressions can read
+            # done.<id> as soon as it arrives.
+            out.signal({"new": "", "done": {task.id: False}, "_adding": False})
+            for i, e in enumerate(self.row(task)):
+                out.element(e.before(first) if i == 0 and first else e)
+            self.tasks.insert(0, task)
+        elif action.name == "toggle":
+            task = self.find(action.payload)
+            if task is None:
+                return
+            done = action.signal(f"done.{task.id}")
+            if isinstance(done, bool):
+                task.done = done
+            out.signal({"done": {task.id: task.done}})
+        elif action.name == "delete":
+            task = self.find(action.payload)
+            if task is None:
+                return
+            self.tasks.remove(task)
+            out.remove(task.id)
+            out.signal({"done": {task.id: None}})
+        elif action.name == "clear":
+            for t in self.tasks:
+                if t.done:
+                    out.remove(t.id)
+            out.signal({"done": {t.id: None for t in self.tasks if t.done}, "_clearing": False})
+            self.tasks = [t for t in self.tasks if not t.done]

hypereffect_ui-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "hypereffect-ui"
+version = "0.1.0"
+description = "Types and helpers for writing hypereffect servers: messages, line framing, signals and components, an App/Server session driver, and a renderer client with a loopback for tests."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["cel-python>=0.5,<0.6"]
+keywords = ["hypermedia", "gui", "ui", "server-driven-ui", "cel"]
+
+[project.urls]
+Homepage = "https://hypereffect.dev"
+Repository = "https://github.com/hypereffect/hypereffect"
+Issues = "https://github.com/hypereffect/hypereffect/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "mypy>=1.10"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.mypy]
+strict = true
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = ["celpy", "celpy.*", "lark", "lark.*"]
+ignore_missing_imports = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hypereffect"]

hypereffect_ui-0.1.0/src/hypereffect/__init__.py

@@ -0,0 +1,45 @@
+"""Types and helpers for `hypereffect <https://hypereffect.dev>`_, a small
+hypermedia protocol for server-driven UI.
+
+- Elements, handlers, server and renderer messages, and the line framing.
+  Building an interface looks like
+  ``ui.text("title").parent("main").variant("h1").text("Inbox")``.
+- :mod:`hypereffect.signals`: merge patch, local signals and signal paths.
+- The components, their attributes and nesting rules.
+- An :class:`App` base class for per-session logic, and a :class:`Server`
+  that drives one from any transport.
+- :mod:`hypereffect.client`: the renderer side without drawing, and a
+  ``Loopback`` that connects it to a Server for tests.
+"""
+
+from . import signals, ui
+from .components import Attr, AttrType, Component, accepts
+from .message import (
+    Action,
+    Element,
+    Handler,
+    Hello,
+    Json,
+    LineBuffer,
+    Metadata,
+    ParseError,
+    ParseErrorKind,
+    RendererMessage,
+    Remove,
+    ServerMessage,
+    Signal,
+    cel,
+    encode_line,
+    is_cel,
+    parse_line,
+    parse_renderer_message,
+    parse_server_message,
+)
+from .server import App, Outbox, Server
+
+__all__ = [
+    "Action", "App", "Attr", "AttrType", "Component", "Element", "Handler", "Hello", "Json",
+    "LineBuffer", "Metadata", "Outbox", "ParseError", "ParseErrorKind", "RendererMessage",
+    "Remove", "Server", "ServerMessage", "Signal", "accepts", "cel", "encode_line", "is_cel",
+    "parse_line", "parse_renderer_message", "parse_server_message", "signals", "ui",
+]