wesktop 0.1.1__py3-none-any.whl

wesktop/__init__.py

@@ -0,0 +1,86 @@
+"""wesktop — A Python framework for building web-based desktop applications."""
+
+from __future__ import annotations
+
+import importlib.metadata
+from pathlib import Path
+
+from wesktop.entries import create_entry, remove_entry
+from wesktop.asgi import (
+    Router,
+    Request,
+    JSONResponse,
+    TextResponse,
+    HTMLResponse,
+    BytesResponse,
+    StreamResponse,
+    create_app,
+    add_ws_route,
+)
+from wesktop.sse import Broadcaster, sse_route
+
+__version__ = importlib.metadata.version("wesktop")
+
+__all__ = [
+    # asgi
+    "Router",
+    "Request",
+    "JSONResponse",
+    "TextResponse",
+    "HTMLResponse",
+    "BytesResponse",
+    "StreamResponse",
+    "create_app",
+    "add_ws_route",
+    # sse
+    "Broadcaster",
+    "sse_route",
+    # entries
+    "create_entry",
+    "remove_entry",
+    # top-level
+    "run",
+    "serve",
+    # metadata
+    "__version__",
+]
+
+
+def run(
+    target: str,
+    *,
+    title: str = "wesktop",
+    width: int = 1280,
+    height: int = 800,
+    icon: str | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    pid_path: Path | None = None,
+) -> None:
+    """Start server + native desktop window."""
+    from wesktop.desktop import run as _run
+
+    _run(
+        target,
+        title=title,
+        width=width,
+        height=height,
+        icon=icon,
+        host=host,
+        port=port,
+        pid_path=pid_path,
+    )
+
+
+def serve(
+    target: str,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    pid_path: Path | None = None,
+    name: str = "wesktop",
+) -> None:
+    """Start server in blocking/headless mode."""
+    from wesktop.server import start_server
+
+    start_server(target, host, port, pid_path=pid_path, name=name)

wesktop/asgi.py

@@ -0,0 +1,404 @@
+"""
+Minimal ASGI micro-framework with zero external dependencies (stdlib + msgspec).
+Provides routing, static file serving, SPA fallback, middleware, and lifespan support.
+"""
+
+from __future__ import annotations
+
+import logging
+import mimetypes
+from pathlib import Path
+from typing import Any, AsyncGenerator, Callable
+from urllib.parse import parse_qs
+
+import msgspec
+
+
+# ---------------------------------------------------------------------------
+# Response types
+# ---------------------------------------------------------------------------
+
+class JSONResponse:
+    """JSON response with optional status code."""
+
+    def __init__(self, data: Any, status: int = 200):
+        self.data = data
+        self.status = status
+
+
+class TextResponse:
+    """Plain text or CSS response.
+
+    ``headers`` (optional) is merged with the framework's default response
+    headers; values must already be plain strings.
+    """
+
+    def __init__(
+        self,
+        text: str,
+        content_type: str = "text/plain",
+        status: int = 200,
+        headers: dict[str, str] | None = None,
+    ):
+        self.text = text
+        self.content_type = content_type
+        self.status = status
+        self.headers = headers or {}
+
+
+class HTMLResponse:
+    """HTML response."""
+
+    def __init__(self, html: str, status: int = 200):
+        self.html = html
+        self.status = status
+
+
+class BytesResponse:
+    """Raw bytes response with an explicit content type."""
+
+    def __init__(self, data: bytes, content_type: str = "application/octet-stream", status: int = 200):
+        self.data = data
+        self.content_type = content_type
+        self.status = status
+
+
+class StreamResponse:
+    """Streaming response (for SSE)."""
+
+    def __init__(
+        self,
+        generator: AsyncGenerator,
+        content_type: str,
+        headers: dict[str, str] | None = None,
+    ):
+        self.generator = generator
+        self.content_type = content_type
+        self.headers = headers or {}
+
+
+# ---------------------------------------------------------------------------
+# Request wrapper
+# ---------------------------------------------------------------------------
+
+class Request:
+    """Wraps ASGI scope with parsed body and params."""
+
+    __slots__ = ("scope", "path_params", "json", "_body")
+
+    def __init__(self, scope: dict, path_params: dict, body: bytes | None):
+        self.scope = scope
+        self.path_params = path_params
+        self._body = body
+        try:
+            self.json: dict | list | None = (
+                msgspec.json.decode(body) if body else None
+            )
+        except (msgspec.DecodeError, ValueError):
+            self.json = None
+
+    @property
+    def body(self) -> bytes | None:
+        """Raw request body bytes."""
+        return self._body
+
+    def query(self, name: str, default: Any = None, type_: type = str) -> Any:
+        """Get a query parameter by name, with optional type conversion."""
+        qs = parse_qs(self.scope.get("query_string", b"").decode())
+        values = qs.get(name)
+        if not values:
+            return default
+        try:
+            return type_(values[0])
+        except (ValueError, TypeError):
+            return default
+
+    def header(self, name: str, default: str | None = None) -> str | None:
+        """Return a request header by name (case-insensitive).
+
+        ASGI headers arrive as a list of ``(bytes, bytes)`` tuples. This
+        helper decodes both to ``str`` and looks the name up
+        case-insensitively, matching HTTP semantics.
+        """
+        target = name.lower().encode()
+        for k, v in self.scope.get("headers", []):
+            if k.lower() == target:
+                return v.decode("latin-1")
+        return default
+
+    @property
+    def body_size(self) -> int:
+        """Length in bytes of the raw request body (0 if no body)."""
+        return len(self._body) if self._body is not None else 0
+
+
+# ---------------------------------------------------------------------------
+# Router
+# ---------------------------------------------------------------------------
+
+class Router:
+    """Simple path-based HTTP router using {param} placeholders."""
+
+    def __init__(self) -> None:
+        # List of (method, pattern_segments, handler)
+        self._routes: list[tuple[str, list[str], Callable]] = []
+
+    def get(self, path: str) -> Callable:
+        """Decorator to register a GET handler."""
+        def decorator(fn: Callable) -> Callable:
+            self.add_route("GET", path, fn)
+            return fn
+        return decorator
+
+    def post(self, path: str) -> Callable:
+        """Decorator to register a POST handler."""
+        def decorator(fn: Callable) -> Callable:
+            self.add_route("POST", path, fn)
+            return fn
+        return decorator
+
+    def delete(self, path: str) -> Callable:
+        """Decorator to register a DELETE handler."""
+        def decorator(fn: Callable) -> Callable:
+            self.add_route("DELETE", path, fn)
+            return fn
+        return decorator
+
+    def add_route(self, method: str, path: str, handler: Callable) -> None:
+        """Programmatic route registration."""
+        segments = path.strip("/").split("/")
+        self._routes.append((method, segments, handler))
+
+    def match(self, method: str, path: str) -> tuple[Callable, dict[str, str]] | None:
+        """Return (handler, path_params) or None if no route matches."""
+        segments = path.strip("/").split("/")
+        for route_method, pattern, handler in self._routes:
+            if route_method != method or len(pattern) != len(segments):
+                continue
+            params: dict[str, str] = {}
+            matched = True
+            for pat_seg, req_seg in zip(pattern, segments):
+                if pat_seg.startswith("{") and pat_seg.endswith("}"):
+                    params[pat_seg[1:-1]] = req_seg
+                elif pat_seg != req_seg:
+                    matched = False
+                    break
+            if matched:
+                return handler, params
+        return None
+
+
+# ---------------------------------------------------------------------------
+# ASGI send helpers
+# ---------------------------------------------------------------------------
+
+async def _send_response(
+    send: Callable,
+    status: int,
+    body: bytes,
+    content_type: str,
+    extra_headers: dict[str, str] | None = None,
+) -> None:
+    """Send a complete HTTP response (headers + body)."""
+    headers: list[list[bytes]] = [
+        [b"content-type", content_type.encode()],
+        [b"content-length", str(len(body)).encode()],
+    ]
+    if extra_headers:
+        for k, v in extra_headers.items():
+            headers.append([k.encode(), v.encode()])
+    await send({
+        "type": "http.response.start",
+        "status": status,
+        "headers": headers,
+    })
+    await send({"type": "http.response.body", "body": body})
+
+
+async def _send_stream(send: Callable, resp: StreamResponse) -> None:
+    """Send a streaming HTTP response, iterating the async generator."""
+    headers = [
+        [b"content-type", resp.content_type.encode()],
+    ]
+    for key, value in resp.headers.items():
+        headers.append([key.encode(), value.encode()])
+    await send({"type": "http.response.start", "status": 200, "headers": headers})
+    async for chunk in resp.generator:
+        payload = chunk.encode() if isinstance(chunk, str) else chunk
+        await send({"type": "http.response.body", "body": payload, "more_body": True})
+    await send({"type": "http.response.body", "body": b"", "more_body": False})
+
+
+async def _send_result(send: Callable, result: Any) -> None:
+    """Dispatch a handler return value to the appropriate sender."""
+    # Auto-wrap plain dicts/lists as JSON responses
+    if isinstance(result, (dict, list)):
+        result = JSONResponse(result)
+
+    if isinstance(result, JSONResponse):
+        await _send_response(send, result.status, msgspec.json.encode(result.data), "application/json")
+    elif isinstance(result, TextResponse):
+        await _send_response(
+            send, result.status, result.text.encode(),
+            result.content_type, extra_headers=result.headers,
+        )
+    elif isinstance(result, HTMLResponse):
+        await _send_response(send, result.status, result.html.encode(), "text/html")
+    elif isinstance(result, BytesResponse):
+        await _send_response(send, result.status, result.data, result.content_type)
+    elif isinstance(result, StreamResponse):
+        await _send_stream(send, result)
+    else:
+        # Fallback: try JSON-encoding anything else
+        await _send_response(send, 200, msgspec.json.encode(result), "application/json")
+
+
+# ---------------------------------------------------------------------------
+# Static file + SPA helpers
+# ---------------------------------------------------------------------------
+
+async def _serve_static(send: Callable, static_dir: Path, rel_path: str) -> bool:
+    """Serve a static file. Returns True if served, False if not found."""
+    file_path = (static_dir / rel_path).resolve()
+    # Prevent path traversal
+    if not str(file_path).startswith(str(static_dir.resolve())):
+        return False
+    if not file_path.is_file():
+        return False
+    mime, _ = mimetypes.guess_type(str(file_path))
+    body = file_path.read_bytes()
+    await _send_response(send, 200, body, mime or "application/octet-stream")
+    return True
+
+
+async def _serve_spa_fallback(send: Callable, spa_fallback: Path) -> None:
+    """Serve the SPA fallback file (typically index.html)."""
+    if spa_fallback.is_file():
+        body = spa_fallback.read_bytes()
+        await _send_response(send, 200, body, "text/html")
+    else:
+        await _send_response(send, 404, msgspec.json.encode({"error": "not found"}), "application/json")
+
+
+# ---------------------------------------------------------------------------
+# WebSocket route registry
+# ---------------------------------------------------------------------------
+
+# Maps exact paths (e.g. "/ws/echo") to raw ASGI WebSocket handlers
+# with signature (scope, receive, send) -> None.
+_ws_routes: dict[str, Callable] = {}
+
+
+def add_ws_route(path: str, handler: Callable) -> None:
+    """Register a WebSocket handler for an exact path."""
+    _ws_routes[path] = handler
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+def create_app(
+    router: Router,
+    middleware: list[type] | None = None,
+    static_dir: Path | None = None,
+    static_path: str = "/assets",
+    spa_fallback: Path | None = None,
+    lifespan: Callable | None = None,
+    name: str | None = None,
+) -> Callable:
+    """Create an ASGI application callable."""
+
+    log = logging.getLogger(name or "wesktop.asgi")
+
+    async def app(scope: dict, receive: Callable, send: Callable) -> None:
+        # -- Lifespan protocol --
+        if scope["type"] == "lifespan":
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                if lifespan is not None:
+                    # Enter the context manager; it stays open until shutdown
+                    ctx = lifespan(app)
+                    await ctx.__aenter__()
+                    await send({"type": "lifespan.startup.complete"})
+                    await receive()  # blocks until lifespan.shutdown
+                    await ctx.__aexit__(None, None, None)
+                else:
+                    await send({"type": "lifespan.startup.complete"})
+                    await receive()
+                await send({"type": "lifespan.shutdown.complete"})
+            return
+
+        # -- WebSocket routing --
+        if scope["type"] == "websocket":
+            path = scope.get("path", "")
+            handler = _ws_routes.get(path)
+            if handler:
+                await handler(scope, receive, send)
+            else:
+                # Reject unknown WebSocket paths
+                await receive()  # consume websocket.connect per ASGI spec
+                await send({"type": "websocket.close", "code": 4004})
+            return
+
+        if scope["type"] != "http":
+            return
+
+        method = scope["method"]
+        path = scope["path"]
+
+        # -- Route matching --
+        match = router.match(method, path)
+        if match:
+            handler, path_params = match
+            try:
+                # Read body for POST, skip for GET/DELETE
+                body = None
+                if method == "POST":
+                    body = b""
+                    while True:
+                        msg = await receive()
+                        body += msg.get("body", b"")
+                        if not msg.get("more_body", False):
+                            break
+
+                request = Request(scope, path_params, body)
+                result = await handler(request)
+                await _send_result(send, result)
+            except Exception as exc:
+                log.exception("Handler error on %s %s", method, path)
+                await _send_response(
+                    send, 500,
+                    msgspec.json.encode({"error": str(exc)}),
+                    "application/json",
+                )
+            return
+
+        # -- Static files --
+        if static_dir and path.startswith(static_path + "/"):
+            rel = path[len(static_path) + 1:]
+            if await _serve_static(send, static_dir, rel):
+                return
+
+        # -- SPA fallback (GET only) --
+        if spa_fallback and method == "GET":
+            # Before returning index.html, check if the path maps to an
+            # actual file under the static root (spa_fallback's parent dir).
+            # This lets sub-directories be served without registering each
+            # one as a separate static_path prefix.
+            static_root = spa_fallback.parent
+            candidate = path.lstrip("/")
+            if candidate and await _serve_static(send, static_root, candidate):
+                return
+            await _serve_spa_fallback(send, spa_fallback)
+            return
+
+        # -- 404 --
+        await _send_response(send, 404, msgspec.json.encode({"error": "not found"}), "application/json")
+
+    # -- Apply middleware in reverse so the first in the list is outermost --
+    wrapped = app
+    for mw in reversed(middleware or []):
+        wrapped = mw(wrapped)
+
+    return wrapped

wesktop/desktop.py

@@ -0,0 +1,39 @@
+"""Native desktop window via pywebview, backed by a Granian server in a daemon thread."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def run(
+    target: str,
+    *,
+    title: str = "wesktop",
+    width: int = 1280,
+    height: int = 800,
+    icon: str | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    pid_path: Path | None = None,
+) -> None:
+    """Start server + open native desktop window. Blocks until window closes."""
+    from wesktop.server import start_server_in_background
+
+    url = start_server_in_background(target, host, port, pid_path=pid_path)
+
+    # Late import so headless mode (serve) has no pywebview dependency
+    import webview
+
+    window = webview.create_window(
+        title=title,
+        url=url,
+        width=width,
+        height=height,
+    )
+    if icon:
+        # pywebview supports icon parameter on some platforms
+        pass
+
+    webview.start()
+    # When webview.start() returns, the window was closed.
+    # Daemon thread (server) auto-exits with main thread.

wesktop/entries.py

@@ -0,0 +1,297 @@
+"""Cross-platform desktop entry creation and removal."""
+
+from __future__ import annotations
+
+import logging
+import platform
+import shutil
+import subprocess
+import textwrap
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+
+def create_entry(
+    name: str,
+    command: str,
+    *,
+    icon: str | Path | None = None,
+    comment: str = "",
+    categories: str = "Utility;",
+) -> Path:
+    """Create a platform-native desktop entry. Returns the path of the created entry."""
+    system = platform.system()
+    if system == "Linux":
+        return _create_linux(name, command, icon=icon, comment=comment, categories=categories)
+    elif system == "Darwin":
+        return _create_macos(name, command, icon=icon, comment=comment)
+    elif system == "Windows":
+        return _create_windows(name, command, icon=icon, comment=comment)
+    else:
+        raise OSError(f"Unsupported platform: {system}")
+
+
+def remove_entry(name: str) -> bool:
+    """Remove a desktop entry. Returns True if something was removed."""
+    system = platform.system()
+    if system == "Linux":
+        return _remove_linux(name)
+    elif system == "Darwin":
+        return _remove_macos(name)
+    elif system == "Windows":
+        return _remove_windows(name)
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Linux
+# ---------------------------------------------------------------------------
+
+def _linux_apps_dir() -> Path:
+    return Path.home() / ".local" / "share" / "applications"
+
+
+def _linux_icons_dir() -> Path:
+    return Path.home() / ".local" / "share" / "icons" / "hicolor" / "256x256" / "apps"
+
+
+def _create_linux(
+    name: str,
+    command: str,
+    *,
+    icon: str | Path | None = None,
+    comment: str = "",
+    categories: str = "Utility;",
+) -> Path:
+    apps_dir = _linux_apps_dir()
+    apps_dir.mkdir(parents=True, exist_ok=True)
+
+    icon_value = ""
+    if icon is not None:
+        icon_path = Path(icon)
+        if icon_path.is_file():
+            icons_dir = _linux_icons_dir()
+            icons_dir.mkdir(parents=True, exist_ok=True)
+            dest = icons_dir / f"{name}.png"
+            shutil.copy2(icon_path, dest)
+            icon_value = str(dest)
+        else:
+            # Treat as a theme icon name
+            icon_value = str(icon)
+
+    desktop_path = apps_dir / f"{name}.desktop"
+    desktop_path.write_text(
+        textwrap.dedent(f"""\
+            [Desktop Entry]
+            Type=Application
+            Name={name}
+            Exec={command}
+            Icon={icon_value}
+            Comment={comment}
+            Categories={categories}
+            Terminal=false
+        """)
+    )
+
+    # Validate if tool is available
+    if shutil.which("desktop-file-validate"):
+        result = subprocess.run(
+            ["desktop-file-validate", str(desktop_path)],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            log.warning("desktop-file-validate: %s", result.stderr.strip() or result.stdout.strip())
+
+    # Update database if tool is available
+    if shutil.which("update-desktop-database"):
+        subprocess.run(
+            ["update-desktop-database", str(apps_dir)],
+            capture_output=True,
+        )
+
+    return desktop_path
+
+
+def _remove_linux(name: str) -> bool:
+    removed = False
+    desktop_path = _linux_apps_dir() / f"{name}.desktop"
+    if desktop_path.exists():
+        desktop_path.unlink()
+        removed = True
+    icon_path = _linux_icons_dir() / f"{name}.png"
+    if icon_path.exists():
+        icon_path.unlink()
+        removed = True
+    return removed
+
+
+# ---------------------------------------------------------------------------
+# macOS
+# ---------------------------------------------------------------------------
+
+def _macos_apps_dir() -> Path:
+    return Path.home() / "Applications"
+
+
+def _create_macos(
+    name: str,
+    command: str,
+    *,
+    icon: str | Path | None = None,
+    comment: str = "",
+) -> Path:
+    bundle_id = "com.wesktop." + name.lower().replace(" ", "-")
+    app_dir = _macos_apps_dir() / f"{name}.app"
+    contents = app_dir / "Contents"
+    macos_dir = contents / "MacOS"
+    resources_dir = contents / "Resources"
+
+    macos_dir.mkdir(parents=True, exist_ok=True)
+    resources_dir.mkdir(parents=True, exist_ok=True)
+
+    # Info.plist
+    icon_filename = ""
+    if icon is not None:
+        icon_path = Path(icon)
+        if icon_path.is_file():
+            dest = resources_dir / "icon.icns"
+            shutil.copy2(icon_path, dest)
+            icon_filename = "icon"
+
+    plist = textwrap.dedent(f"""\
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+          "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+            <key>CFBundleExecutable</key>
+            <string>launcher</string>
+            <key>CFBundleName</key>
+            <string>{name}</string>
+            <key>CFBundleIdentifier</key>
+            <string>{bundle_id}</string>
+            <key>CFBundleVersion</key>
+            <string>1.0</string>
+            <key>CFBundlePackageType</key>
+            <string>APPL</string>
+            <key>CFBundleIconFile</key>
+            <string>{icon_filename}</string>
+            <key>NSHighResolutionCapable</key>
+            <true/>
+        </dict>
+        </plist>
+    """)
+    (contents / "Info.plist").write_text(plist)
+
+    # Launcher script
+    launcher = macos_dir / "launcher"
+    launcher.write_text(f"#!/bin/bash\nexec {command}\n")
+    launcher.chmod(0o755)
+
+    return app_dir
+
+
+def _remove_macos(name: str) -> bool:
+    app_dir = _macos_apps_dir() / f"{name}.app"
+    if app_dir.exists():
+        shutil.rmtree(app_dir)
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Windows
+# ---------------------------------------------------------------------------
+
+def _windows_start_menu_dir() -> Path:
+    import os
+
+    appdata = os.environ.get("APPDATA", "")
+    if not appdata:
+        raise OSError("APPDATA environment variable not set")
+    return Path(appdata) / "Microsoft" / "Windows" / "Start Menu" / "Programs"
+
+
+def _create_windows(
+    name: str,
+    command: str,
+    *,
+    icon: str | Path | None = None,
+    comment: str = "",
+) -> Path:
+    start_menu = _windows_start_menu_dir()
+    start_menu.mkdir(parents=True, exist_ok=True)
+    lnk_path = start_menu / f"{name}.lnk"
+
+    # Split command into target and arguments
+    parts = command.split(None, 1)
+    target = parts[0]
+    arguments = parts[1] if len(parts) > 1 else ""
+
+    icon_location = str(icon) if icon else ""
+
+    try:
+        return _create_windows_com(lnk_path, target, arguments, icon_location, comment)
+    except Exception:
+        log.debug("win32com unavailable, falling back to PowerShell")
+        return _create_windows_powershell(lnk_path, target, arguments, icon_location, comment)
+
+
+def _create_windows_com(
+    lnk_path: Path,
+    target: str,
+    arguments: str,
+    icon_location: str,
+    comment: str,
+) -> Path:
+    import win32com.client  # type: ignore[import-untyped]
+
+    shell = win32com.client.Dispatch("WScript.Shell")
+    shortcut = shell.CreateShortCut(str(lnk_path))
+    shortcut.TargetPath = target
+    shortcut.Arguments = arguments
+    shortcut.Description = comment
+    if icon_location:
+        shortcut.IconLocation = icon_location
+    shortcut.save()
+    return lnk_path
+
+
+def _create_windows_powershell(
+    lnk_path: Path,
+    target: str,
+    arguments: str,
+    icon_location: str,
+    comment: str,
+) -> Path:
+    # Escape single quotes for PowerShell strings
+    def ps_escape(s: str) -> str:
+        return s.replace("'", "''")
+
+    script = (
+        "$ws = New-Object -ComObject WScript.Shell; "
+        f"$s = $ws.CreateShortcut('{ps_escape(str(lnk_path))}'); "
+        f"$s.TargetPath = '{ps_escape(target)}'; "
+        f"$s.Arguments = '{ps_escape(arguments)}'; "
+        f"$s.Description = '{ps_escape(comment)}'; "
+    )
+    if icon_location:
+        script += f"$s.IconLocation = '{ps_escape(icon_location)}'; "
+    script += "$s.Save()"
+
+    subprocess.run(
+        ["powershell", "-NoProfile", "-Command", script],
+        check=True,
+        capture_output=True,
+    )
+    return lnk_path
+
+
+def _remove_windows(name: str) -> bool:
+    lnk_path = _windows_start_menu_dir() / f"{name}.lnk"
+    if lnk_path.exists():
+        lnk_path.unlink()
+        return True
+    return False

wesktop/server.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+"""Granian ASGI server lifecycle -- PID file management, port checks, start/stop."""
+
+import atexit
+import logging
+import os
+import signal
+import socket
+import sys
+import threading
+from pathlib import Path
+
+from granian import Granian
+
+log = logging.getLogger(__name__)
+
+
+def _write_pid(pid_path: Path) -> None:
+    """Write the current PID to disk, become process group leader, and register cleanup handlers.
+
+    Becoming a process group leader (via os.setpgid(0, 0)) lets the 'stop'
+    subcommand signal our entire process group with os.killpg, so granian
+    worker subprocesses die with us instead of being orphaned.
+    """
+    try:
+        os.setpgid(0, 0)  # 0,0 = current process becomes its own group leader
+    except OSError:
+        # Already a group leader, or not permitted in this context (e.g. some
+        # supervised contexts) -- not fatal.
+        pass
+    pid_path.write_text(str(os.getpid()))
+    atexit.register(_remove_pid, pid_path)
+    # Clean up PID file on SIGTERM and SIGINT (Ctrl+C).
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        signal.signal(sig, lambda signum, _frame: _signal_handler(signum, _frame, pid_path))
+
+
+def _remove_pid(pid_path: Path) -> None:
+    """Remove the PID file if it exists."""
+    try:
+        pid_path.unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def _signal_handler(signum: int, _frame: object, pid_path: Path) -> None:
+    """Handle SIGTERM/SIGINT: forward to our process group, clean up, exit."""
+    # Restore default disposition so the forwarded signal doesn't recurse into us.
+    signal.signal(signum, signal.SIG_DFL)
+    try:
+        os.killpg(os.getpgrp(), signum)
+    except (ProcessLookupError, PermissionError):
+        pass
+    _remove_pid(pid_path)
+    sys.exit(0)
+
+
+def check_already_running(pid_path: Path, name: str = "server") -> None:
+    """Exit if another instance is already running (based on the PID file)."""
+    if not pid_path.exists():
+        return
+    try:
+        pid = int(pid_path.read_text().strip())
+    except (ValueError, OSError):
+        # Corrupt or unreadable PID file -- treat as stale.
+        _remove_pid(pid_path)
+        return
+    try:
+        os.kill(pid, 0)  # probe whether the process is alive
+    except ProcessLookupError:
+        # Process is dead; stale PID file.
+        _remove_pid(pid_path)
+        return
+    except PermissionError:
+        # Process exists but we can't signal it -- still running.
+        pass
+    log.error(
+        "%s is already running (PID %d). Stop it before starting another.",
+        name,
+        pid,
+    )
+    sys.exit(1)
+
+
+def ensure_port_available(host: str, port: int) -> int:
+    """Check that *port* on *host* is available; exit with a diagnostic error if not.
+
+    Returns *port* on success.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        # SO_REUSEADDR matches Granian's behavior so our probe doesn't spuriously
+        # fail during the kernel's brief TIME_WAIT after a recent stop. Without
+        # this the bind raises EADDRINUSE while no process is actually listening.
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind((host, port))
+            return port
+        except OSError:
+            log.error(
+                "Port %d on %s is already in use. Use a different port "
+                "or stop the process holding it.",
+                port,
+                host,
+            )
+            sys.exit(1)
+
+
+def _make_server(target: str, host: str, port: int) -> Granian:
+    """Create a Granian instance bound to *host* on *port*.
+
+    *target* is an ASGI module path, e.g. ``"myapp:app"``.
+    """
+    return Granian(
+        target=target,
+        address=host,
+        port=port,
+        interface="asgi",
+    )
+
+
+def start_server(
+    target: str,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    pid_path: Path | None = None,
+    name: str = "server",
+) -> None:
+    """Start Granian serving the ASGI app (blocks the calling thread).
+
+    If *pid_path* is given, PID file management is enabled: an existing
+    running instance is detected, the PID is written, and cleanup handlers
+    are registered.
+    """
+    if pid_path is not None:
+        check_already_running(pid_path, name)
+    ensure_port_available(host, port)
+    if pid_path is not None:
+        _write_pid(pid_path)
+    server = _make_server(target, host, port)
+    log.info("Starting %s on http://%s:%d", name, host, port)
+    server.serve()
+
+
+def start_server_in_background(
+    target: str,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    pid_path: Path | None = None,
+    name: str = "server",
+) -> str:
+    """Start Granian in a daemon thread and return the URL it listens on.
+
+    The daemon thread dies automatically when the main thread exits.
+    If *pid_path* is given, PID file management is enabled.
+    """
+    if pid_path is not None:
+        check_already_running(pid_path, name)
+    ensure_port_available(host, port)
+    if pid_path is not None:
+        _write_pid(pid_path)
+    server = _make_server(target, host, port)
+    url = f"http://{host}:{port}"
+    thread = threading.Thread(target=server.serve, daemon=True)
+    thread.start()
+    log.info("%s started in background on %s", name, url)
+    return url

wesktop/sse.py

@@ -0,0 +1,119 @@
+"""SSE (Server-Sent Events) broadcaster with typed event registration."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from wesktop.asgi import Request, StreamResponse
+
+log = logging.getLogger(__name__)
+
+
+class Broadcaster:
+    """Manages SSE client connections and broadcasts typed events.
+
+    Event types must be registered via ``register_event`` before they can be
+    broadcast.  In strict mode (the default), broadcasting an unregistered
+    event raises ``ValueError``.  Pass ``strict=False`` to skip validation.
+    """
+
+    def __init__(self, buffer_size: int = 256, *, strict: bool = True):
+        self._clients: list[asyncio.Queue[str]] = []
+        self._buffer_size = buffer_size
+        self._event_types: set[str] = set()
+        self._strict = strict
+
+    # -- Event type registry --------------------------------------------------
+
+    def register_event(self, name: str) -> None:
+        """Declare an allowed event type."""
+        self._event_types.add(name)
+
+    @property
+    def event_types(self) -> frozenset[str]:
+        """Currently registered event types."""
+        return frozenset(self._event_types)
+
+    # -- Broadcasting ---------------------------------------------------------
+
+    def _format_sse(self, event: str, data: dict[str, Any] | str) -> str:
+        """Format a payload as an SSE wire message."""
+        payload = json.dumps(data) if isinstance(data, dict) else data
+        return f"event: {event}\ndata: {payload}\n\n"
+
+    def broadcast(self, event: str, data: dict[str, Any] | str) -> None:
+        """Send an event to all connected clients.
+
+        Prunes clients whose queues are full (they fell behind and are
+        presumed disconnected or stuck).
+
+        Raises ``ValueError`` if *event* was not previously registered and
+        the broadcaster is in strict mode.
+        """
+        if self._strict and event not in self._event_types:
+            raise ValueError(
+                f"unregistered event type {event!r}; "
+                f"call register_event({event!r}) first "
+                f"(registered: {sorted(self._event_types)})"
+            )
+        message = self._format_sse(event, data)
+        disconnected: list[asyncio.Queue[str]] = []
+        for q in self._clients:
+            try:
+                q.put_nowait(message)
+            except asyncio.QueueFull:
+                disconnected.append(q)
+        for q in disconnected:
+            self._clients.remove(q)
+            log.debug("pruned full SSE client queue (%d remain)", len(self._clients))
+
+    # -- Client streaming -----------------------------------------------------
+
+    async def _event_generator(self, queue: asyncio.Queue[str]) -> AsyncGenerator[str, None]:
+        """Yield SSE messages from a per-client queue."""
+        try:
+            while True:
+                msg = await queue.get()
+                yield msg
+        except asyncio.CancelledError:
+            return
+        finally:
+            if queue in self._clients:
+                self._clients.remove(queue)
+
+    async def stream(self, request: Request) -> StreamResponse:
+        """Return a ``StreamResponse`` for an SSE endpoint.
+
+        Creates a per-client queue, registers it, and wraps the async
+        generator in the framework's streaming response type.
+        """
+        queue: asyncio.Queue[str] = asyncio.Queue(maxsize=self._buffer_size)
+        self._clients.append(queue)
+        return StreamResponse(
+            self._event_generator(queue),
+            content_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+        )
+
+    # -- Introspection --------------------------------------------------------
+
+    @property
+    def client_count(self) -> int:
+        """Number of currently connected SSE clients."""
+        return len(self._clients)
+
+
+# -- Convenience --------------------------------------------------------------
+
+
+def sse_route(broadcaster: Broadcaster):
+    """Return an async handler suitable for ``router.add_route("GET", "/events", handler)``."""
+
+    async def handler(request: Request) -> StreamResponse:
+        return await broadcaster.stream(request)
+
+    return handler

wesktop-0.1.1.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: wesktop
+Version: 0.1.1
+Summary: A Python framework for building web-based desktop applications
+Author-email: smm-h <smmh72@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,desktop,granian,gui,pywebview,rlsbl,web
+Requires-Python: >=3.11
+Requires-Dist: granian>=2.7.4
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: pywebview>=6.2.1

wesktop-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+wesktop/__init__.py,sha256=LsxctXitK3J83UefEcTA_Y3HdbslkKo79UboXck2CnE,1707
+wesktop/asgi.py,sha256=QqfVeR04Lk9_4Og0isBWO1Z027EBo3fZ3X71IDS0OVo,14453
+wesktop/desktop.py,sha256=NaviiqbLXlup07KBJwNTDoCcXYJcDaWQWyPlcVRErIk,1044
+wesktop/entries.py,sha256=CRMLQgIXRDckv3la_BzQtwW_4Iv5BihSic09kYQZbn8,8521
+wesktop/server.py,sha256=nUPt-l8_ngld0Kq_JBUFRs2Oyc-oo3w9lrmsxCI08VA,5314
+wesktop/sse.py,sha256=1_bOj-_k0o4BTGMOeQ1qTZgXVcXIgxMYZ6KSeyr60hk,4290
+wesktop-0.1.1.dist-info/METADATA,sha256=EEf1RTk_mM6Z-9W76g_Npsl02_jg7yUL0iLjgn6gRgg,380
+wesktop-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+wesktop-0.1.1.dist-info/licenses/LICENSE,sha256=6ViJKrwd1dmR_KbVKOaV0zXyV3PTc9Lgvl9KlQfY-NU,1062
+wesktop-0.1.1.dist-info/RECORD,,

wesktop-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

wesktop-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smm-h
+
+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.