glimpse-applet-sdk 0.1.0__tar.gz

glimpse_applet_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Oleshkevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

glimpse_applet_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: glimpse-applet-sdk
+Version: 0.1.0
+Summary: Typed async framework for Glimpse exec applets
+Keywords: glimpse,applet,panel,desktop,sdk
+Author: Alex Oleshkevich
+Author-email: Alex Oleshkevich <alex.oleshkevich@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Homepage, https://alex-oleshkevich.github.io/glimpse/
+Project-URL: Documentation, https://alex-oleshkevich.github.io/glimpse/applets/exec-sdk
+Project-URL: Repository, https://github.com/alex-oleshkevich/glimpse
+Project-URL: Issues, https://github.com/alex-oleshkevich/glimpse/issues
+Description-Content-Type: text/markdown
+
+# Glimpse Applet Python SDK
+
+Small async framework for building Glimpse `exec` applets without touching stdio or raw JSON.
+
+## Goals
+
+- typed protocol models
+- typed widget builders
+- async runtime
+- decorator-based callbacks
+- state-driven rendering via `await self.set_state(...)`
+
+## Example
+
+```python
+from dataclasses import dataclass, field
+
+from glimpse_sdk import (
+    Applet,
+    AppletState,
+    Box,
+    Button,
+    Hero,
+    Icon,
+    InputEvent,
+    Label,
+    RenderResult,
+    StatusItem,
+    click,
+    input,
+)
+
+
+@dataclass
+class DeployState(AppletState):
+    version: str = "2026.04.07"
+    status: str = "Ready"
+
+
+class DeployApplet(Applet[DeployState]):
+    def initial_state(self) -> DeployState:
+        return DeployState()
+
+    async def render(self) -> RenderResult:
+        return RenderResult(
+            status=[
+                StatusItem(
+                    id="deploy",
+                    icon=Icon.name("software-update-available-symbolic"),
+                    label=self.state.status,
+                )
+            ],
+            hero=Hero(
+                icon=Icon.name("software-update-available-symbolic"),
+                title="Deploy",
+                subtitle=self.state.version,
+            ),
+            tree=Box.vertical(
+                [
+                    Label("Version"),
+                    Button(id="deploy_now", label="Deploy now"),
+                ]
+            ),
+        )
+
+    @click("deploy_now")
+    async def on_deploy(self, _event) -> None:
+        await self.set_state(status="Deploying")
+
+
+if __name__ == "__main__":
+    DeployApplet().run()
+```

glimpse_applet_sdk-0.1.0/README.md

@@ -0,0 +1,73 @@
+# Glimpse Applet Python SDK
+
+Small async framework for building Glimpse `exec` applets without touching stdio or raw JSON.
+
+## Goals
+
+- typed protocol models
+- typed widget builders
+- async runtime
+- decorator-based callbacks
+- state-driven rendering via `await self.set_state(...)`
+
+## Example
+
+```python
+from dataclasses import dataclass, field
+
+from glimpse_sdk import (
+    Applet,
+    AppletState,
+    Box,
+    Button,
+    Hero,
+    Icon,
+    InputEvent,
+    Label,
+    RenderResult,
+    StatusItem,
+    click,
+    input,
+)
+
+
+@dataclass
+class DeployState(AppletState):
+    version: str = "2026.04.07"
+    status: str = "Ready"
+
+
+class DeployApplet(Applet[DeployState]):
+    def initial_state(self) -> DeployState:
+        return DeployState()
+
+    async def render(self) -> RenderResult:
+        return RenderResult(
+            status=[
+                StatusItem(
+                    id="deploy",
+                    icon=Icon.name("software-update-available-symbolic"),
+                    label=self.state.status,
+                )
+            ],
+            hero=Hero(
+                icon=Icon.name("software-update-available-symbolic"),
+                title="Deploy",
+                subtitle=self.state.version,
+            ),
+            tree=Box.vertical(
+                [
+                    Label("Version"),
+                    Button(id="deploy_now", label="Deploy now"),
+                ]
+            ),
+        )
+
+    @click("deploy_now")
+    async def on_deploy(self, _event) -> None:
+        await self.set_state(status="Deploying")
+
+
+if __name__ == "__main__":
+    DeployApplet().run()
+```

glimpse_applet_sdk-0.1.0/glimpse_sdk/__init__.py

@@ -0,0 +1,120 @@
+from .app import Applet, AppletState, RenderResult
+from .decorators import change, click, event, input, scroll, toggle
+from .events import (
+    CallbackEvent,
+    ChangeEvent,
+    ClickEvent,
+    InitEvent,
+    InputEvent,
+    PopoverEvent,
+    ScrollEvent,
+    ToggleEvent,
+)
+from .protocol import Icon, MenuItem, StatusItem
+from .widgets import (
+    ActionMenu,
+    ActionMenuItem,
+    ActionRow,
+    Align,
+    Badge,
+    Box,
+    Button,
+    Card,
+    Checkbox,
+    Collapsible,
+    CollapsibleItem,
+    Column,
+    Copyable,
+    DetailGrid,
+    DetailGridItem,
+    Dropdown,
+    DropdownItem,
+    EmptyState,
+    Grid,
+    GridChild,
+    Header,
+    Hero,
+    IconWidget,
+    Image,
+    Item,
+    Label,
+    Meter,
+    Orientation,
+    Progress,
+    Row,
+    Scale,
+    Scroll,
+    Section,
+    Separator,
+    Spinner,
+    StatusDot,
+    Switch,
+    Toast,
+    ToastAction,
+    TreeNode,
+    Variant,
+)
+
+__all__ = [
+    "ActionMenu",
+    "ActionMenuItem",
+    "ActionRow",
+    "Align",
+    "Applet",
+    "AppletState",
+    "Badge",
+    "Box",
+    "Button",
+    "CallbackEvent",
+    "Card",
+    "ChangeEvent",
+    "Checkbox",
+    "ClickEvent",
+    "Collapsible",
+    "CollapsibleItem",
+    "Column",
+    "Copyable",
+    "DetailGrid",
+    "DetailGridItem",
+    "Dropdown",
+    "DropdownItem",
+    "EmptyState",
+    "Grid",
+    "GridChild",
+    "Header",
+    "Hero",
+    "Icon",
+    "IconWidget",
+    "Image",
+    "InitEvent",
+    "InputEvent",
+    "Item",
+    "Label",
+    "Meter",
+    "Orientation",
+    "PopoverEvent",
+    "Progress",
+    "RenderResult",
+    "Row",
+    "Scale",
+    "Scroll",
+    "ScrollEvent",
+    "Section",
+    "Separator",
+    "Spinner",
+    "StatusItem",
+    "MenuItem",
+    "StatusDot",
+    "Switch",
+    "Toast",
+    "ToastAction",
+    "ToggleEvent",
+    "TreeNode",
+    "Variant",
+    "change",
+    "click",
+    "event",
+    "input",
+    "scroll",
+    "toggle",
+]

glimpse_applet_sdk-0.1.0/glimpse_sdk/app.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from dataclasses import dataclass, is_dataclass
+from typing import Any, Generic, TypeVar
+
+from .events import CallbackEvent, InitEvent, PopoverEvent, parse_callback_event, parse_init_event
+from .protocol import StatusItem
+from .widgets import TreeNode
+
+StateT = TypeVar("StateT", bound="AppletState")
+
+
+@dataclass(slots=True)
+class AppletState:
+    pass
+
+
+@dataclass(slots=True)
+class RenderResult:
+    status: list[StatusItem] | None = None
+    tree: TreeNode | None = None
+
+    def __post_init__(self) -> None:
+        if self.status is None:
+            self.status = []
+
+
+class Applet(Generic[StateT]):
+    def __init__(self) -> None:
+        self.state: StateT = self.initial_state()
+        self._incoming: asyncio.Queue[InitEvent | CallbackEvent] = asyncio.Queue()
+        self._outgoing: asyncio.Queue[tuple[str, dict[str, Any]]] = asyncio.Queue()
+        self._handler_map = self._collect_handlers()
+        self._render_task: asyncio.Task[None] | None = None
+        self._render_requested = False
+        self._last_status: list[dict[str, Any]] | None = None
+        self._last_tree: dict[str, Any] | None = None
+        self._popover_open = False
+
+    def initial_state(self) -> StateT:
+        raise NotImplementedError
+
+    async def on_start(self) -> None:
+        return None
+
+    async def on_init(self, _event: InitEvent) -> None:
+        return None
+
+    async def on_callback(self, _event: CallbackEvent) -> None:
+        return None
+
+    async def render(self) -> RenderResult:
+        return RenderResult()
+
+    async def set_state(self, **kwargs: Any) -> None:
+        for key, value in kwargs.items():
+            if not hasattr(self.state, key):
+                raise AttributeError(f"Unknown state field: {key}")
+            setattr(self.state, key, value)
+        self._schedule_render()
+        await asyncio.sleep(0)
+
+    def is_popover_open(self) -> bool:
+        return self._popover_open
+
+    def _schedule_render(self) -> None:
+        self._render_requested = True
+        if self._render_task is None or self._render_task.done():
+            self._render_task = asyncio.create_task(self._flush_render())
+            self._render_task.add_done_callback(_log_render_exception)
+
+    async def _flush_render(self) -> None:
+        await asyncio.sleep(0)
+        while self._render_requested:
+            self._render_requested = False
+            rendered = await self.render()
+            status = [item.to_protocol() for item in rendered.status]
+            content = None if rendered.tree is None else rendered.tree.to_protocol()
+            tree = {"root": content}
+
+            if status != self._last_status:
+                self._last_status = status
+                await self._outgoing.put(("status", {"items": status}))
+            publish_popover = self._popover_open or self._last_tree is None or content is None
+            if publish_popover and tree != self._last_tree:
+                self._last_tree = tree
+                await self._outgoing.put(("popover", tree))
+
+    def _collect_handlers(self) -> dict[tuple[str, str], Any]:
+        handlers: dict[tuple[str, str], Any] = {}
+        for name in dir(self):
+            value = getattr(self, name)
+            handler_meta = getattr(value, "__glimpse_handler__", None)
+            if handler_meta is not None:
+                handlers[handler_meta] = value
+        return handlers
+
+    async def _dispatch_callback(self, event: CallbackEvent) -> None:
+        handler = self._handler_map.get((event.event, event.id))
+        if handler is not None:
+            await handler(event)
+        else:
+            await self.on_callback(event)
+
+    async def _reader_loop(self, eof: asyncio.Event) -> None:
+        try:
+            while True:
+                line = await asyncio.to_thread(sys.stdin.readline)
+                if line == "":
+                    break
+                try:
+                    parsed = _parse_line(line)
+                except (ValueError, json.JSONDecodeError) as exc:
+                    print(f"glimpse-sdk: ignoring malformed input: {exc}", file=sys.stderr)
+                    continue
+                if parsed is None:
+                    continue
+                message_type, data = parsed
+                try:
+                    if message_type == "init":
+                        await self._incoming.put(parse_init_event(data))
+                    elif message_type == "event":
+                        await self._incoming.put(parse_callback_event(data))
+                except Exception as exc:
+                    print(f"glimpse-sdk: ignoring malformed event: {exc}", file=sys.stderr)
+                    continue
+        finally:
+            eof.set()
+
+    async def _writer_loop(self) -> None:
+        while True:
+            command, payload = await self._outgoing.get()
+            try:
+                sys.stdout.write(f"{command} {json.dumps(payload, separators=(',', ':'))}\n")
+                sys.stdout.flush()
+            except (BrokenPipeError, OSError):
+                return
+
+    async def _event_loop(self, eof: asyncio.Event) -> None:
+        await self.on_start()
+        self._schedule_render()
+        get_task: asyncio.Task[InitEvent | CallbackEvent] | None = None
+        eof_task = asyncio.create_task(eof.wait())
+        try:
+            while True:
+                if get_task is None:
+                    get_task = asyncio.create_task(self._incoming.get())
+                done, _ = await asyncio.wait(
+                    {get_task, eof_task}, return_when=asyncio.FIRST_COMPLETED
+                )
+                if eof_task in done and get_task not in done:
+                    get_task.cancel()
+                    return
+                event = get_task.result()
+                get_task = None
+                if isinstance(event, InitEvent):
+                    await self.on_init(event)
+                    self._schedule_render()
+                else:
+                    if isinstance(event, PopoverEvent):
+                        self._popover_open = event.open
+                    await self._dispatch_callback(event)
+                    self._schedule_render()
+                if self._render_task is not None and self._render_task.done():
+                    exc = self._render_task.exception()
+                    if exc is not None:
+                        raise exc
+                await asyncio.sleep(0)
+        finally:
+            if get_task is not None:
+                get_task.cancel()
+            eof_task.cancel()
+
+    async def _run(self) -> None:
+        if not is_dataclass(self.state):
+            raise TypeError("Applet state must be a dataclass instance")
+        eof = asyncio.Event()
+        writer = asyncio.create_task(self._writer_loop())
+        reader = asyncio.create_task(self._reader_loop(eof))
+        try:
+            await self._event_loop(eof)
+        finally:
+            reader.cancel()
+            writer.cancel()
+            if self._render_task is not None and not self._render_task.done():
+                self._render_task.cancel()
+
+    def run(self) -> None:
+        asyncio.run(self._run())
+
+
+def _log_render_exception(task: "asyncio.Task[None]") -> None:
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is None:
+        return
+    import traceback
+
+    print("glimpse-sdk: render error:", file=sys.stderr)
+    traceback.print_exception(type(exc), exc, exc.__traceback__, file=sys.stderr)
+
+
+def _parse_line(line: str) -> tuple[str, dict[str, Any]] | None:
+    stripped = line.strip()
+    if not stripped:
+        return None
+    command, _, payload = stripped.partition(" ")
+    if not payload:
+        raise ValueError("missing command payload")
+    data = json.loads(payload)
+    if not isinstance(data, dict):
+        raise ValueError("command payload must be an object")
+    return command, data

glimpse_applet_sdk-0.1.0/glimpse_sdk/decorators.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+def event(event_type: str, target_id: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(func, "__glimpse_handler__", (event_type, target_id))
+        return func
+
+    return decorator
+
+
+def click(target_id: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    return event("click", target_id)
+
+
+def input(target_id: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    return event("input", target_id)
+
+
+def change(target_id: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    return event("change", target_id)
+
+
+def toggle(target_id: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    return event("toggle", target_id)
+
+
+def scroll(target_id: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    return event("scroll", target_id)

glimpse_applet_sdk-0.1.0/glimpse_sdk/events.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class InitEvent:
+    instance: str
+    options: dict[str, Any]
+
+
+@dataclass(slots=True)
+class CallbackEvent:
+    id: str
+    event: str
+
+
+@dataclass(slots=True)
+class ClickEvent(CallbackEvent):
+    button: str | None = None
+
+
+@dataclass(slots=True)
+class ScrollEvent(CallbackEvent):
+    delta_y: float | None = None
+
+
+@dataclass(slots=True)
+class InputEvent(CallbackEvent):
+    text: str = ""
+
+
+@dataclass(slots=True)
+class ChangeEvent(CallbackEvent):
+    value: Any = None
+
+
+@dataclass(slots=True)
+class ToggleEvent(CallbackEvent):
+    value: bool = False
+
+
+@dataclass(slots=True)
+class PopoverEvent(CallbackEvent):
+    open: bool = False
+
+
+def parse_init_event(payload: dict[str, Any]) -> InitEvent:
+    return InitEvent(
+        instance=str(payload.get("instance", "")),
+        options=payload.get("options") or {},
+    )
+
+
+def parse_callback_event(payload: dict[str, Any]) -> CallbackEvent:
+    event_type = str(payload.get("type", payload.get("event", "")))
+    callback_id = str(payload.get("id", ""))
+    if event_type == "click":
+        return ClickEvent(id=callback_id, event=event_type, button=payload.get("button"))
+    if event_type == "scroll":
+        return ScrollEvent(id=callback_id, event=event_type, delta_y=payload.get("delta_y"))
+    if event_type == "input":
+        return InputEvent(id=callback_id, event=event_type, text=str(payload.get("text", "")))
+    if event_type == "toggle":
+        active = payload.get("active")
+        value = payload.get("value")
+        if isinstance(active, bool):
+            toggled = active
+        elif isinstance(value, bool):
+            toggled = value
+        else:
+            toggled = False
+        return ToggleEvent(id=callback_id, event=event_type, value=toggled)
+    if event_type in {"open", "close"}:
+        return PopoverEvent(id=callback_id, event=event_type, open=event_type == "open")
+    return ChangeEvent(id=callback_id, event=event_type, value=payload.get("value"))

glimpse_applet_sdk-0.1.0/glimpse_sdk/protocol.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class Icon:
+    kind: str
+    value: str
+
+    @classmethod
+    def name(cls, value: str) -> "Icon":
+        return cls(kind="name", value=value)
+
+    @classmethod
+    def path(cls, value: str) -> "Icon":
+        return cls(kind="path", value=value)
+
+    def to_protocol(self) -> dict[str, str]:
+        return {self.kind: self.value}
+
+
+@dataclass(slots=True)
+class MenuItem:
+    id: str
+    label: str
+    visible: bool | None = None
+    enabled: bool | None = None
+
+    def to_protocol(self) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "id": self.id,
+            "label": self.label,
+        }
+        if self.visible is not None:
+            payload["visible"] = self.visible
+        if self.enabled is not None:
+            payload["enabled"] = self.enabled
+        return payload
+
+
+@dataclass(slots=True)
+class StatusItem:
+    id: str | None = None
+    icon: Icon | None = None
+    label: str | None = None
+    tooltip: str | None = None
+
+    def to_protocol(self) -> dict[str, object]:
+        payload: dict[str, object] = {}
+        if self.id is not None:
+            payload["id"] = self.id
+        if self.icon is not None:
+            payload["icon"] = self.icon.to_protocol()
+        if self.label is not None:
+            payload["label"] = self.label
+        if self.tooltip is not None:
+            payload["tooltip"] = self.tooltip
+        return payload