izana-pywebview 0.1.0__tar.gz

izana_pywebview-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+*.db
+uv.lock
+
+# Node
+node_modules/
+dist/
+package-lock.json
+
+# Rust — every crate's build dir, anywhere in the tree
+target/
+**/target/
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+examples/django-react-site/harness/test-results/
+
+# IDE
+.idea/
+.vscode/
+
+# Build artifacts
+protocol/izana-generate/bin/izana-generate-*
+
+# Env
+.env
+.env.*
+*.pem
+*.key

izana_pywebview-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: izana-pywebview
+Version: 0.1.0
+Summary: Izana PyWebView backend adapter — js_api RPC dispatch + context bundling, built on izana-core.
+License-Expression: Elastic-2.0
+Requires-Python: >=3.10
+Requires-Dist: izana-core>=0.2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

izana_pywebview-0.1.0/README.md

@@ -0,0 +1,144 @@
+# izana-pywebview
+
+PyWebView backend adapter for the Izana protocol. Desktop apps don't have a
+transport already listening on `127.0.0.1` — `window.pywebview.api` *is* the
+transport, so this adapter is the executor wired straight to it: two
+methods, `izana_call` and `izana_fetch`, both thin over `execute_call`/
+`execute_context`.
+
+## Scope
+
+Same dispatch/validation/invalidation/merge surface as izana-fastapi, minus
+HTTP: no status codes, no routes, no middleware. What's here instead:
+
+- **`izana_core.executor`** (not in this package) — `execute_function`, the
+  error taxonomy (`IzanaError`/`ErrorCode`), `compute_invalidation`,
+  `compute_merges`. Shared with izana-fastapi; the only thing HTTP adds is
+  the code→status table, and that lives in izana-fastapi's router.
+- **`bridge.py`** — `execute_call`/`execute_context` (the FastAPI adapter's
+  `POST /call/` and `GET /ctx/{name}/`, without the HTTP), `Bridge`, the
+  class a `pywebview.create_window(..., js_api=...)` call actually wants,
+  and `push`, the reverse channel (below).
+- **`discovery.py`** — `register_module(module_path)`. `@client` alone
+  doesn't register a function (see below); a pywebview app is one process
+  with one entry module, so this is the one-module version of the Django
+  adapter's app-walking discovery, without the Django dependency.
+- **`ir.py`** — `python -m izana_pywebview.ir <module>`, for codegen.
+
+## Install
+
+```bash
+uv add izana-pywebview
+```
+
+## Setup
+
+```python
+# host.py
+import webview
+
+from izana_pywebview import Bridge, register_module
+
+import myapp.clients  # noqa: F401 — not required for registration; see below
+
+register_module("myapp.clients")
+
+
+class Host:
+    def __init__(self):
+        self.state = ...  # whatever `request` should carry for your app
+        self._bridge = Bridge(request_factory=lambda: self.state)
+
+    def izana_call(self, fn, args=None):
+        return self._bridge.izana_call(fn, args)
+
+    def izana_fetch(self, context, params=None):
+        return self._bridge.izana_fetch(context, params)
+
+
+host = Host()
+window = webview.create_window("My App", "index.html", js_api=host)
+webview.start()
+```
+
+`Host` only needs to expose `izana_call`/`izana_fetch` on the object it
+hands to `js_api=`; everything else on `Host` is the app's own window
+plumbing (dialogs, `set_window`), never Izana's concern.
+
+## Why discovery is explicit
+
+```python
+from izana_core.client.function import client
+
+
+@client
+def echo(request, text: str) -> EchoOutput: ...
+```
+
+`@client` builds the `ServerFunction` subclass the registry wants, but
+*building* it isn't *registering* it — nothing calls `register()` as a side
+effect of decoration. izana-fastapi asks every project to call `register()`
+by hand (or from a startup hook); `register_module(module_path)` here does
+that walk for you: import the module, find every `ServerFunction` subclass
+among its members, register it under its function name. Call it once, before
+the window opens.
+
+## `@client` parameters
+
+Same as every adapter — see izana-fastapi's README for the full list
+(`context`, `affects`, `auth`, `rev`, …). This adapter reads `_meta` the
+same way; nothing here is pywebview-specific about the decorator itself.
+
+## Auth
+
+There's no HTTP session for `request.state.user` to ride in on. Whatever
+`request_factory` returns *is* `request` — if a verb needs `auth=`, populate
+`.state.user` on whatever object your `request_factory` builds, the same
+contract izana-fastapi's middleware fulfills for HTTP.
+
+## Error envelope
+
+A js_api call has no status line, so the envelope carries `code` alone:
+
+```json
+{"error": true, "code": "NOT_FOUND", "message": "..."}
+```
+
+This is the flat shape `IzanaError.fromEnvelope` (izana-base) already
+documents for a status-less perimeter (its own docstring calls it the
+"Django" shape) — the kernel's `IzanaError` on the frontend parses it
+without change.
+
+## Pushing from Python
+
+A mutation's `affects=` invalidates when the frontend calls it. A background
+job has no call to ride on, so it publishes itself:
+
+```python
+from izana_pywebview import push
+
+def on_job_finished(window):
+    push(window, "jobs")            # refetch every `context="jobs"` reader
+    push(window, "job", {"id": 7})  # or just the readers scoped to id=7
+```
+
+`push` evaluates `window.__izana_push__(context, params)` through
+`Window.evaluate_js`; `pywebviewTransport()` installs that handler and
+routes it into the kernel's `invalidate`.
+
+## Generate the frontend
+
+```bash
+python -m izana_pywebview.ir myapp.clients
+```
+
+Imports the module (triggering discovery — `register_module`, not a bare
+`importlib.import_module`, is what `ir.py` calls), then prints the Izana KDL
+IR to stdout, same as every other adapter's `ir.py`.
+
+## Running tests
+
+```bash
+uv sync --extra dev
+uv run pytest
+```

izana_pywebview-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "izana-pywebview"
+version = "0.1.0"
+license = "Elastic-2.0"
+description = "Izana PyWebView backend adapter — js_api RPC dispatch + context bundling, built on izana-core."
+requires-python = ">=3.10"
+dependencies = [
+    "izana-core>=0.2.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/izana_pywebview"]
+
+[tool.uv.sources]
+izana-core = { path = "../../cores/izana-python", editable = true }
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+python_classes = ["*Tests", "*Test", "Test*"]
+python_functions = ["test_*"]

izana_pywebview-0.1.0/src/izana_pywebview/__init__.py

@@ -0,0 +1,39 @@
+# The dispatch/auth/validate/serialize/invalidation/merge logic lives in
+# izana_core.executor — this adapter has no executor module of its own,
+# only the js_api-shaped transport (bridge.py) over the shared core.
+from izana_core.executor import (
+    ErrorCode,
+    IzanaError,
+    NotFound,
+    BadRequest,
+    ValidationFailed,
+    Unauthorized,
+    Forbidden,
+    NotImplementedYet,
+    InternalError,
+    compute_invalidation,
+    compute_merges,
+    execute_function,
+)
+from izana_pywebview.bridge import Bridge, execute_call, execute_context, push
+from izana_pywebview.discovery import register_module
+
+__all__ = [
+    "Bridge",
+    "execute_call",
+    "execute_context",
+    "push",
+    "register_module",
+    "execute_function",
+    "compute_invalidation",
+    "compute_merges",
+    "ErrorCode",
+    "IzanaError",
+    "NotFound",
+    "BadRequest",
+    "ValidationFailed",
+    "Unauthorized",
+    "Forbidden",
+    "NotImplementedYet",
+    "InternalError",
+]

izana_pywebview-0.1.0/src/izana_pywebview/bridge.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Callable
+
+from izana_core.executor import (
+    IzanaError,
+    NotFound,
+    compute_invalidation,
+    compute_merges,
+    execute_function,
+)
+from izana_core.registry import get_context_groups, get_function
+
+
+def _error_envelope(exc: IzanaError) -> dict[str, Any]:
+    # The flat, no-status shape: {"error": true, "code", "message", "details"}.
+    # izana-fastapi's router nests this under an "error" key because HTTP
+    # already carries the status line separately; a js_api bridge has no
+    # status line, so the envelope needs `error: true` to say "this is a
+    # failure" the way a status code otherwise would — the same shape
+    # izana-base's IzanaError already documents for a status-less perimeter.
+    body: dict[str, Any] = {
+        "error": True,
+        "code": exc.code.value,
+        "message": exc.message,
+    }
+    if exc.details:
+        body["details"] = exc.details
+    return body
+
+
+async def _call(request: Any, fn_name: str, args: dict[str, Any]) -> dict[str, Any]:
+    fn_class = get_function(fn_name)
+    result = await execute_function(request, fn_name, args)
+    invalidate = compute_invalidation(fn_class, args)
+    merges = compute_merges(fn_class, args, result)
+    envelope: dict[str, Any] = {"result": result, "invalidate": invalidate}
+    if merges:
+        envelope["merge"] = merges
+    return envelope
+
+
+def execute_call(request: Any, fn_name: str, args: dict[str, Any]) -> dict[str, Any]:
+    """`fn_name` dispatched, with its invalidation/merge envelope — or the
+    error envelope, since a js_api bridge has no exception-handler
+    middleware to catch `IzanaError` the way the FastAPI adapter's router
+    does; this function is that catch, done explicitly."""
+    try:
+        return asyncio.run(_call(request, fn_name, args))
+    except IzanaError as exc:
+        return _error_envelope(exc)
+
+
+async def _bundle(
+    request: Any, fn_names: list[str], params: dict[str, Any]
+) -> dict[str, Any]:
+    return {fn: await execute_function(request, fn, params) for fn in fn_names}
+
+
+def execute_context(
+    request: Any, context_name: str, params: dict[str, Any]
+) -> dict[str, Any]:
+    """Every function in `context_name`'s group, called and bundled by
+    name — the FastAPI adapter's `GET /ctx/{name}/` without the HTTP."""
+    fn_names = get_context_groups().get(context_name)
+    if not fn_names:
+        return _error_envelope(NotFound(f"context {context_name!r} not found"))
+    try:
+        return asyncio.run(_bundle(request, fn_names, params))
+    except IzanaError as exc:
+        return _error_envelope(exc)
+
+
+def push(window: Any, context: str, params: dict[str, Any] | None = None) -> None:
+    """The reverse channel: tell the frontend kernel that `context` changed
+    without waiting for it to ask. Evaluates `window.__izana_push__(...)`
+    — the handler `pywebviewTransport()` installs — through pywebview's
+    `Window.evaluate_js`, so a background job's own publish invalidates the
+    same way a mutation's `affects=` does."""
+    window.evaluate_js(
+        f"window.__izana_push__({json.dumps(context)}, {json.dumps(params)})"
+    )
+
+
+class Bridge:
+    """What pywebview gets as (part of) `js_api`: `izana_call`/`izana_fetch`,
+    thin over `execute_call`/`execute_context`. No verb name appears here —
+    dispatch is entirely registry-driven off `fn_name`/`context_name`.
+
+    `request_factory` is the one seam a consumer supplies: whatever
+    `request` means for that app is built fresh for every call, the same
+    way a WSGI/ASGI app builds a fresh `Request` per call — the executor
+    only ever reads `request` through `_enforce_auth`, so this adapter
+    itself carries no opinion about what `request` is.
+    """
+
+    def __init__(self, request_factory: Callable[[], Any]) -> None:
+        self._request_factory = request_factory
+
+    def izana_call(self, fn: str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+        return execute_call(self._request_factory(), fn, args or {})
+
+    def izana_fetch(
+        self, context: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return execute_context(self._request_factory(), context, params or {})

izana_pywebview-0.1.0/src/izana_pywebview/discovery.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import importlib
+import inspect
+from typing import Any
+
+from izana_core.client.function import ServerFunction
+from izana_core.registry import get_function, register
+
+
+def _members(module_path: str) -> list[tuple[str, Any]]:
+    module = importlib.import_module(module_path)
+    return [
+        (name, member)
+        for name, member in inspect.getmembers(module)
+        if not inspect.isclass(member) or member.__module__ == module.__name__
+    ]
+
+
+def register_module(module_path: str) -> None:
+    """Import `module_path` and register every `@client`-declared function it
+    defines.
+
+    `@client` alone builds the `ServerFunction` subclass but does not call
+    `register()` — every adapter's discovery does that separately (the
+    izana-django adapter's `izana_module` does the same walk this does, off
+    Django's own vendored member-lister; this is that walk without the
+    Django dependency, for the one-process, one-entry-module shape a
+    pywebview app actually has).
+
+    Idempotent: re-registering the same class under the same name (a second
+    `Host()` in a test, a stale re-import) is a no-op, mirroring
+    `register()`'s own idempotence for a same-name/same-class re-visit.
+    """
+    for name, member in _members(module_path):
+        if (
+            isinstance(member, type)
+            and issubclass(member, ServerFunction)
+            and member is not ServerFunction
+        ):
+            fn_name = getattr(member, "name", None) or member.__name__
+            if get_function(fn_name) is member:
+                continue
+            register(member, fn_name)

izana_pywebview-0.1.0/src/izana_pywebview/ir.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import sys
+
+from izana_core.ir import build_ir
+
+from izana_pywebview.discovery import register_module
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if len(args) != 1:
+        print("usage: python -m izana_pywebview.ir <module>", file=sys.stderr)
+        return 2
+
+    module_name = args[0]
+    try:
+        register_module(module_name)
+    except Exception as e:
+        print(f"failed to import {module_name!r}: {e}", file=sys.stderr)
+        return 1
+
+    sys.stdout.write(build_ir())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

izana_pywebview-0.1.0/tests/test_dispatch.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import sys
+
+import pytest
+from pydantic import BaseModel
+
+from izana_core.client.function import client
+from izana_core.registry import clear_registry, get_function, register
+
+from izana_pywebview import Bridge, execute_call, execute_context, push
+
+# ─── Fixtures ───────────────────────────────────────────────────────────────
+
+
+class EchoOutput(BaseModel):
+    message: str
+
+
+class SumOutput(BaseModel):
+    total: int
+
+
+class UserOutput(BaseModel):
+    email: str
+    authenticated: bool
+
+
+class ItemOutput(BaseModel):
+    id: int
+    name: str
+
+
+class NoRequest:
+    """An anonymous request: no `.state`, so `_user` degrades to `None`
+    through the same `getattr` chain a real bridge request hits when
+    nobody's logged in — a pywebview bridge has no auth middleware to
+    populate `.state.user`, so this is every un-authenticated call's actual
+    shape, not a test-only stand-in."""
+
+
+REQUEST = NoRequest()
+
+
+@pytest.fixture
+def registry():
+    clear_registry()
+
+    @client
+    def echo(request, text: str) -> EchoOutput:
+        return EchoOutput(message=f"echo: {text}")
+
+    @client
+    def add(request, a: int, b: int) -> SumOutput:
+        return SumOutput(total=a + b)
+
+    @client(context="user")
+    def current_user(request) -> UserOutput:
+        return UserOutput(email="anon@example.com", authenticated=False)
+
+    @client(context="user")
+    def user_count(request) -> SumOutput:
+        return SumOutput(total=42)
+
+    @client(affects="user")
+    def update_email(request, email: str) -> EchoOutput:
+        return EchoOutput(message=f"updated: {email}")
+
+    @client(auth=True)
+    def whoami(request) -> UserOutput:
+        return UserOutput(email="real@example.com", authenticated=True)
+
+    @client
+    def list_items(request) -> list[ItemOutput]:
+        return [ItemOutput(id=1, name="a"), ItemOutput(id=2, name="b")]
+
+    @client(merge="items")
+    def set_item_name(request, id: int, name: str) -> ItemOutput:
+        return ItemOutput(id=id, name=name)
+
+    @client(context="items")
+    def items_list(request) -> list[ItemOutput]:
+        return [ItemOutput(id=1, name="orig")]
+
+    register(echo, "echo")
+    register(add, "add")
+    register(current_user, "current_user")
+    register(user_count, "user_count")
+    register(update_email, "update_email")
+    register(whoami, "whoami")
+    register(list_items, "list_items")
+    register(set_item_name, "set_item_name")
+    register(items_list, "items_list")
+
+    yield None
+
+    clear_registry()
+
+
+# ─── RPC dispatch ───────────────────────────────────────────────────────────
+
+
+class FunctionCallTests:
+    def test_simple_call_returns_result(self, registry):
+        envelope = execute_call(REQUEST, "echo", {"text": "hi"})
+        assert envelope["result"]["message"] == "echo: hi"
+        assert envelope["invalidate"] == []
+
+    def test_call_with_typed_input(self, registry):
+        envelope = execute_call(REQUEST, "add", {"a": 2, "b": 3})
+        assert envelope["result"]["total"] == 5
+
+    def test_unknown_function_is_a_not_found_envelope(self, registry):
+        envelope = execute_call(REQUEST, "ghost", {})
+        assert envelope["error"] is True
+        assert envelope["code"] == "NOT_FOUND"
+
+    def test_validation_error_is_a_validation_envelope(self, registry):
+        envelope = execute_call(REQUEST, "add", {"a": "not-int", "b": 3})
+        assert envelope["error"] is True
+        assert envelope["code"] == "VALIDATION_ERROR"
+
+    def test_missing_required_input_is_a_validation_envelope(self, registry):
+        envelope = execute_call(REQUEST, "add", {})
+        assert envelope["code"] == "VALIDATION_ERROR"
+        assert "a" in envelope["details"]["fields"]
+
+
+# ─── Context bundling ───────────────────────────────────────────────────────
+
+
+class ContextFetchTests:
+    def test_context_returns_bundled_results(self, registry):
+        bundled = execute_context(REQUEST, "user", {})
+        assert bundled["current_user"]["email"] == "anon@example.com"
+        assert bundled["user_count"]["total"] == 42
+
+    def test_unknown_context_is_a_not_found_envelope(self, registry):
+        envelope = execute_context(REQUEST, "ghost", {})
+        assert envelope["error"] is True
+        assert envelope["code"] == "NOT_FOUND"
+
+
+# ─── Auth gating ────────────────────────────────────────────────────────────
+
+
+class AuthTests:
+    def test_anonymous_request_to_auth_required_is_unauthorized(self, registry):
+        envelope = execute_call(REQUEST, "whoami", {})
+        assert envelope["error"] is True
+        assert envelope["code"] == "UNAUTHORIZED"
+
+
+# ─── Invalidation ───────────────────────────────────────────────────────────
+
+
+class InvalidationTests:
+    def test_mutation_emits_invalidate_list(self, registry):
+        envelope = execute_call(REQUEST, "update_email", {"email": "new@example.com"})
+        assert "user" in envelope["invalidate"]
+
+
+# ─── Structured-output shapes ────────────────────────────────────────────────
+
+
+class StructuredOutputTests:
+    def test_list_of_basemodel_returns_bare_array(self, registry):
+        envelope = execute_call(REQUEST, "list_items", {})
+        assert envelope["result"] == [
+            {"id": 1, "name": "a"},
+            {"id": 2, "name": "b"},
+        ]
+
+
+# ─── Merge protocol ─────────────────────────────────────────────────────────
+
+
+class MergeTests:
+    def test_merge_target_emits_merge_entry(self, registry):
+        envelope = execute_call(REQUEST, "set_item_name", {"id": 42, "name": "renamed"})
+        assert envelope["merge"] == [
+            {
+                "context": "items",
+                "slot": "items_list",
+                "value": {"id": 42, "name": "renamed"},
+            }
+        ]
+        assert envelope["invalidate"] == []
+
+
+# ─── The js_api surface ──────────────────────────────────────────────────────
+
+
+class BridgeTests:
+    def test_bridge_delegates_izana_call_and_izana_fetch(self, registry):
+        bridge = Bridge(request_factory=lambda: REQUEST)
+        assert bridge.izana_call("echo", {"text": "via bridge"})["result"][
+            "message"
+        ] == ("echo: via bridge")
+        assert bridge.izana_fetch("user")["current_user"]["email"] == "anon@example.com"
+
+    def test_bridge_request_factory_is_called_fresh_per_call(self, registry):
+        seen: list[object] = []
+
+        @client
+        def note_request(request) -> EchoOutput:
+            seen.append(request)
+            return EchoOutput(message="noted")
+
+        register(note_request, "note_request")
+        bridge = Bridge(request_factory=lambda: object())
+        bridge.izana_call("note_request", {})
+        bridge.izana_call("note_request", {})
+        assert len(seen) == 2
+        assert seen[0] is not seen[1]
+
+
+# ─── Reverse channel ─────────────────────────────────────────────────────────
+
+
+class Window:
+    def __init__(self) -> None:
+        self.scripts: list[str] = []
+
+    def evaluate_js(self, script: str) -> None:
+        self.scripts.append(script)
+
+
+class PushTests:
+    def test_push_evaluates_the_kernel_handler_with_context_and_params(self):
+        window = Window()
+        push(window, "jobs")
+        push(window, "job", {"id": 7})
+        assert window.scripts == [
+            'window.__izana_push__("jobs", null)',
+            'window.__izana_push__("job", {"id": 7})',
+        ]
+
+
+# ─── Discovery ───────────────────────────────────────────────────────────────
+
+
+class DiscoveryTests:
+    def test_register_module_registers_every_client_function_in_it(
+        self, tmp_path, monkeypatch
+    ):
+        clear_registry()
+        monkeypatch.syspath_prepend(str(tmp_path))
+        (tmp_path / "sample_clients.py").write_text(
+            "from izana_core.client.function import client\n"
+            "from pydantic import BaseModel\n\n\n"
+            "class Out(BaseModel):\n"
+            "    value: int\n\n\n"
+            "@client\n"
+            "def sample(request) -> Out:\n"
+            "    return Out(value=1)\n"
+        )
+        from izana_pywebview import register_module
+
+        register_module("sample_clients")
+        assert get_function("sample") is not None
+
+        register_module("sample_clients")  # a re-visit is a no-op, not an error
+        assert get_function("sample") is not None
+
+        clear_registry()
+        del sys.modules["sample_clients"]