carterkit 0.2.0__tar.gz → 0.3.0__tar.gz

{carterkit-0.2.0 → carterkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT
@@ -51,25 +51,30 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-Use **typed builders** (`build.<control>`) and **binding helpers** (`bind`) — both
-generated from / shaped by the bundled docs, so unknown control types and bad enum
-values raise instead of silently shipping a broken layout:
+The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
+**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
+unknown control types and bad enum values raise instead of silently shipping a broken
+layout:
 
 ```python
-import carterkit
-from carterkit import LayoutBuffer, build, bind, validate_layout
+from carterkit import Layout, build, bind
 
-b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
-b.add_control(build.gauge(id="cpu", label="CPU", min=0, max=100,
-                          sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
-              default_span=[2, 2])
-b.add_control(build.button(id="refresh", label="Refresh",
-                           action=bind.action("refresh")))
+lay = (Layout("Dashboard", columns=4, rows=4)
+       .connect("ws://192.168.1.50:8765", channel="home")
+       .tab("Main", icon="gauge")
+       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
+                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
+            default_span=[2, 2])
+       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
 
-print(carterkit.format_findings(validate_layout(b.layout)))   # schema + grid lint
+print(lay.findings())    # schema + grid + binding lint against the bundled catalog
 help(build.gauge)        # ← prints the gauge documentation, straight from the docs
+layout = lay.layout      # the composed dict, ready to push/save
 ```
 
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
 `infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
 `codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
@@ -92,13 +97,12 @@ import asyncio
 from carterkit import CarterClient
 
 async def main():
-    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
-                     channel="home", role="device", name="my-hub")
-    c.on("toggle", lambda d: {"ok": True, **d})
-    await c.connect()
-    await c.broadcast("reading", {"temp_c": 21.4})
-    await asyncio.sleep(60)
-    await c.close()
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
 
 asyncio.run(main())
 ```

{carterkit-0.2.0 → carterkit-0.3.0}/README.md

@@ -28,25 +28,30 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-Use **typed builders** (`build.<control>`) and **binding helpers** (`bind`) — both
-generated from / shaped by the bundled docs, so unknown control types and bad enum
-values raise instead of silently shipping a broken layout:
+The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
+**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
+unknown control types and bad enum values raise instead of silently shipping a broken
+layout:
 
 ```python
-import carterkit
-from carterkit import LayoutBuffer, build, bind, validate_layout
+from carterkit import Layout, build, bind
 
-b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
-b.add_control(build.gauge(id="cpu", label="CPU", min=0, max=100,
-                          sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
-              default_span=[2, 2])
-b.add_control(build.button(id="refresh", label="Refresh",
-                           action=bind.action("refresh")))
+lay = (Layout("Dashboard", columns=4, rows=4)
+       .connect("ws://192.168.1.50:8765", channel="home")
+       .tab("Main", icon="gauge")
+       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
+                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
+            default_span=[2, 2])
+       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
 
-print(carterkit.format_findings(validate_layout(b.layout)))   # schema + grid lint
+print(lay.findings())    # schema + grid + binding lint against the bundled catalog
 help(build.gauge)        # ← prints the gauge documentation, straight from the docs
+layout = lay.layout      # the composed dict, ready to push/save
 ```
 
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
 `infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
 `codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
@@ -69,13 +74,12 @@ import asyncio
 from carterkit import CarterClient
 
 async def main():
-    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
-                     channel="home", role="device", name="my-hub")
-    c.on("toggle", lambda d: {"ok": True, **d})
-    await c.connect()
-    await c.broadcast("reading", {"temp_c": 21.4})
-    await asyncio.sleep(60)
-    await c.close()
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
 
 asyncio.run(main())
 ```

{carterkit-0.2.0 → carterkit-0.3.0}/carterkit/__init__.py

@@ -21,6 +21,7 @@ from .validate import validate_layout as _validate_layout, format_findings
 from .client import CarterClient, notify_http, CarterNotifyError
 from . import bind
 from .controls import build, control
+from .layout import Layout
 
 __version__ = "0.2.0"
 
@@ -67,6 +68,6 @@ __all__ = [
     "LayoutBuffer", "BufferError",
     "controls", "doc", "doc_markdown", "examples", "validate_layout",
     "format_findings", "controldocs_dir",
-    "build", "control", "bind",
+    "build", "control", "bind", "Layout",
     "catalog", "grid", "codegen", "infer", "theming", "tune",
 ]

{carterkit-0.2.0 → carterkit-0.3.0}/carterkit/client.py

@@ -136,3 +136,11 @@ class CarterClient:
 
     async def close(self):
         await self._sock.stop()
+
+    async def __aenter__(self):
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+        return False

carterkit-0.3.0/carterkit/layout.py

@@ -0,0 +1,87 @@
+"""A fluent layout builder — the ergonomic front door over LayoutBuffer.
+
+    from carterkit import Layout, build, bind
+
+    layout = (Layout("Dashboard", columns=4, rows=4)
+              .connect("ws://192.168.1.50:8765", channel="home")
+              .tab("Main", icon="gauge")
+              .add(build.gauge(id="cpu", min=0, max=100,
+                               sync=[bind.listen("cpu")]), default_span=[2, 2])
+              .add(build.button(id="refresh", action=bind.action("refresh")))
+              .layout)
+
+Auto-placement, id de-duplication, and grid bookkeeping come from LayoutBuffer;
+`.validate()` lints against the bundled catalog. Chainable: every mutator returns self.
+"""
+from __future__ import annotations
+
+import json
+
+from . import bind as _bind
+from . import validate as _validate
+from .buffer import LayoutBuffer
+
+
+class Layout:
+    def __init__(self, name: str = "Layout", *, columns: int = 4, rows: int = 6,
+                 accent: str = "#667eea"):
+        self._buf = LayoutBuffer.blank(name=name, columns=columns, rows=rows, accent=accent)
+        self._tab = 0
+        self._first_tab_used = False
+
+    def connect(self, url: str, **identity) -> "Layout":
+        """Attach a `connection` block (see bind.connection for the identity kwargs)."""
+        self._buf.layout["connection"] = _bind.connection(url, **identity)
+        return self
+
+    def tab(self, title: str, *, icon: str = "square.grid.2x2",
+            columns: int = 4, rows: int = 6) -> "Layout":
+        """Start a tab and make it current. The first call configures the default tab;
+        later calls append new tabs."""
+        if not self._first_tab_used:
+            t = self._buf.tabs[0]
+            t["title"], t["icon"] = title, icon
+            t["grid"] = {"columns": columns, "rows": rows}
+            self._tab = 0
+            self._first_tab_used = True
+        else:
+            self._tab = self._buf.add_tab(title, icon=icon, columns=columns, rows=rows)
+        return self
+
+    def add(self, control: dict, *, position=None, span=None, default_span=None) -> "Layout":
+        """Add a control to the current tab (auto-placed unless `position` is given)."""
+        self._buf.add_control(control, tab_index=self._tab, position=position,
+                              default_span=default_span or span)
+        return self
+
+    def group(self, group: dict, *, position=None) -> "Layout":
+        """Add a group container to the current tab."""
+        self._buf.add_group(group, tab_index=self._tab, position=position)
+        return self
+
+    @property
+    def layout(self) -> dict:
+        """The composed layout dict (ready to push/save)."""
+        return self._buf.layout
+
+    @property
+    def buffer(self) -> LayoutBuffer:
+        """The underlying LayoutBuffer, for advanced ops (update/move/remove)."""
+        return self._buf
+
+    def validate(self) -> list:
+        """Lint against the bundled control catalog."""
+        import carterkit
+        return carterkit.validate_layout(self.layout)
+
+    def findings(self) -> str:
+        """Human-readable lint report."""
+        return _validate.format_findings(self.validate())
+
+    def json(self, indent: int = 2) -> str:
+        return json.dumps(self.layout, indent=indent)
+
+    def __repr__(self) -> str:
+        n = sum(len(t.get("children", [])) for t in self._buf.tabs)
+        return (f"<Layout {self.layout.get('name')!r}: "
+                f"{len(self._buf.tabs)} tab(s), {n} control(s)>")

{carterkit-0.2.0 → carterkit-0.3.0}/carterkit/validate.py

@@ -116,6 +116,26 @@ def _validate_child(ch, catalog, where, findings, seen_ids):
             if v not in fd["values"]:
                 findings.append(_f("error", "bad_enum", spot,
                                    f"{ctype}.{k} = '{v}' is not one of {fd['values']}"))
+    _validate_bindings(ch, ctype, spot, findings)
+
+
+def _validate_bindings(ch, ctype, spot, findings):
+    """Shape-check the data bindings: every `sync` entry needs a `valuePath`, and
+    `action`/`longPressAction` need an `event` (else they silently do nothing)."""
+    sync = ch.get("sync")
+    if sync is not None:
+        if not isinstance(sync, list):
+            findings.append(_f("warn", "bad_sync", spot, f"{ctype}.sync should be a list"))
+        else:
+            for i, s in enumerate(sync):
+                if not isinstance(s, dict) or not s.get("valuePath"):
+                    findings.append(_f("warn", "bad_sync", spot,
+                                       f"{ctype}.sync[{i}] is missing a 'valuePath'"))
+    for akey in ("action", "longPressAction"):
+        a = ch.get(akey)
+        if a is not None and (not isinstance(a, dict) or not a.get("event")):
+            findings.append(_f("error", "bad_action", spot,
+                               f"{ctype}.{akey} is missing an 'event'"))
 
 
 def format_findings(findings: list[dict]) -> str:

{carterkit-0.2.0 → carterkit-0.3.0}/carterkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT
@@ -51,25 +51,30 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-Use **typed builders** (`build.<control>`) and **binding helpers** (`bind`) — both
-generated from / shaped by the bundled docs, so unknown control types and bad enum
-values raise instead of silently shipping a broken layout:
+The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
+**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
+unknown control types and bad enum values raise instead of silently shipping a broken
+layout:
 
 ```python
-import carterkit
-from carterkit import LayoutBuffer, build, bind, validate_layout
+from carterkit import Layout, build, bind
 
-b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
-b.add_control(build.gauge(id="cpu", label="CPU", min=0, max=100,
-                          sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
-              default_span=[2, 2])
-b.add_control(build.button(id="refresh", label="Refresh",
-                           action=bind.action("refresh")))
+lay = (Layout("Dashboard", columns=4, rows=4)
+       .connect("ws://192.168.1.50:8765", channel="home")
+       .tab("Main", icon="gauge")
+       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
+                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
+            default_span=[2, 2])
+       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
 
-print(carterkit.format_findings(validate_layout(b.layout)))   # schema + grid lint
+print(lay.findings())    # schema + grid + binding lint against the bundled catalog
 help(build.gauge)        # ← prints the gauge documentation, straight from the docs
+layout = lay.layout      # the composed dict, ready to push/save
 ```
 
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
 `infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
 `codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
@@ -92,13 +97,12 @@ import asyncio
 from carterkit import CarterClient
 
 async def main():
-    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
-                     channel="home", role="device", name="my-hub")
-    c.on("toggle", lambda d: {"ok": True, **d})
-    await c.connect()
-    await c.broadcast("reading", {"temp_c": 21.4})
-    await asyncio.sleep(60)
-    await c.close()
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
 
 asyncio.run(main())
 ```

{carterkit-0.2.0 → carterkit-0.3.0}/carterkit.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ carterkit/controls.py
 carterkit/e2ee.py
 carterkit/grid.py
 carterkit/infer.py
+carterkit/layout.py
 carterkit/py.typed
 carterkit/theming.py
 carterkit/tune.py
@@ -71,11 +72,14 @@ tests/test_bind.py
 tests/test_buffer.py
 tests/test_catalog.py
 tests/test_cli.py
+tests/test_client.py
 tests/test_codegen.py
 tests/test_controls.py
 tests/test_e2ee.py
 tests/test_grid.py
 tests/test_infer.py
+tests/test_layout.py
 tests/test_theming.py
 tests/test_tune.py
-tests/test_validate.py
+tests/test_validate.py
+tests/test_validate_bindings.py

{carterkit-0.2.0 → carterkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "carterkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Build and drive CAR-TER layouts from Python — the control docs are the library."
 readme = "README.md"
 requires-python = ">=3.10"

carterkit-0.3.0/tests/test_client.py

@@ -0,0 +1,32 @@
+"""Test the CarterClient async context manager (no network — fake socket)."""
+
+import asyncio
+
+from carterkit import CarterClient
+
+
+class _FakeSock:
+    def __init__(self):
+        self.events = []
+
+    async def start(self):
+        self.events.append("start")
+
+    async def wait_until_ready(self):
+        self.events.append("ready")
+
+    async def stop(self):
+        self.events.append("stop")
+
+
+def test_async_context_manager_connects_and_closes():
+    c = CarterClient(gateway_url="ws://x", token="t", channel="home")
+    fake = _FakeSock()
+    c._sock = fake  # swap the real MeshSocket for a recorder
+
+    async def run():
+        async with c as ctx:
+            assert ctx is c
+        return fake.events
+
+    assert asyncio.run(run()) == ["start", "ready", "stop"]

carterkit-0.3.0/tests/test_layout.py

@@ -0,0 +1,40 @@
+"""Tests for the fluent Layout builder."""
+
+from carterkit import Layout, build, bind
+
+
+def test_fluent_compose():
+    lay = (Layout("Dash", columns=4, rows=4)
+           .connect("ws://h:8765", channel="home")
+           .tab("Main", icon="gauge")
+           .add(build.gauge(id="cpu", min=0, max=100, sync=[bind.listen("cpu")]),
+                default_span=[2, 2])
+           .add(build.button(id="go", action=bind.action("go"))))
+    layout = lay.layout
+    assert layout["name"] == "Dash"
+    assert layout["connection"]["url"] == "ws://h:8765"
+    tab0 = layout["tabs"][0]
+    assert tab0["title"] == "Main" and tab0["icon"] == "gauge"
+    assert {c["id"] for c in tab0["children"]} == {"cpu", "go"}
+    g = next(c for c in tab0["children"] if c["id"] == "cpu")
+    assert g["span"] == [2, 2] and g["position"] == [0, 0]
+
+
+def test_first_tab_renames_then_appends():
+    lay = (Layout("X")
+           .tab("One").add(build.button(id="a"))
+           .tab("Two").add(build.button(id="b")))
+    assert [t["title"] for t in lay.layout["tabs"]] == ["One", "Two"]
+    assert lay.layout["tabs"][1]["children"][0]["id"] == "b"
+
+
+def test_validate_and_findings_clean():
+    lay = Layout("X").add(
+        build.gauge(id="g", min=0, max=100, sync=[bind.listen("g")]), default_span=[2, 2])
+    assert [f for f in lay.validate() if f["severity"] == "error"] == []
+    assert "No issues" in lay.findings()
+
+
+def test_repr_counts_controls():
+    lay = Layout("X").add(build.button(id="a")).add(build.button(id="b"))
+    assert "2 control" in repr(lay)

carterkit-0.3.0/tests/test_validate_bindings.py

@@ -0,0 +1,40 @@
+"""Tests for the richer sync/action binding validation."""
+
+import carterkit
+from carterkit import validate, build, bind
+
+CAT = carterkit.controls(include_theme=True)
+
+
+def _layout(children):
+    return {"name": "T", "version": 1,
+            "tabs": [{"title": "Main", "icon": "house.fill",
+                      "grid": {"columns": 4, "rows": 4}, "children": children}]}
+
+
+def _kinds(findings):
+    return {f["kind"] for f in findings}
+
+
+def test_action_missing_event_is_error():
+    lay = _layout([{"type": "button", "id": "b", "position": [0, 0],
+                    "action": {"method": "meshsocket", "mode": "broadcast"}}])
+    findings = validate.validate_layout(lay, CAT)
+    assert "bad_action" in _kinds(findings)
+    assert any(f["severity"] == "error" for f in findings if f["kind"] == "bad_action")
+
+
+def test_sync_missing_valuepath_is_warning():
+    lay = _layout([{"type": "gauge", "id": "g", "position": [0, 0], "min": 0, "max": 100,
+                    "sync": [{"method": "meshsocket", "type": "listen", "event": "broadcast"}]}])
+    bs = [f for f in validate.validate_layout(lay, CAT) if f["kind"] == "bad_sync"]
+    assert bs and bs[0]["severity"] == "warn"
+
+
+def test_helper_built_bindings_are_clean():
+    lay = _layout([
+        build.button(id="b", position=[0, 0], action=bind.action("go")),
+        build.gauge(id="g", position=[0, 1], min=0, max=100, sync=[bind.listen("g")]),
+    ])
+    kinds = _kinds(validate.validate_layout(lay, CAT))
+    assert "bad_action" not in kinds and "bad_sync" not in kinds