webapp-shell 0.1__py3-none-any.whl

webapp_shell/native/webview_icon.py

@@ -0,0 +1,32 @@
+"""The application icon in the Dock. pywebview applies its `icon` option on Qt and GTK only, so on macOS the Dock
+shows a generic icon until it is set here. A packaged program has its icon from the bundle; this serves a run
+from the source tree. Always safe: a platform it does not know is left alone."""
+
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownLambdaType=false
+# pyright: reportUnknownArgumentType=false, reportMissingTypeStubs=false, reportMissingImports=false
+# pyright: reportAttributeAccessIssue=false
+# The lines below talk to AppKit (PyObjC), .NET and GTK, which publish no type stubs. Their inside is untyped by
+# necessity; the signatures of this module are typed.
+
+import sys
+from pathlib import Path
+
+
+class WebviewIcon:
+    def __init__(self, path: Path | None):
+        self.path = path
+
+    def apply(self) -> bool:
+        if sys.platform != "darwin" or self.path is None:
+            return False
+        try:
+            import AppKit
+            from PyObjCTools import AppHelper
+
+            image = AppKit.NSImage.alloc().initWithContentsOfFile_(str(self.path))
+            if image is None:
+                return False
+            AppHelper.callAfter(lambda: AppKit.NSApplication.sharedApplication().setApplicationIconImage_(image))
+            return True
+        except Exception:  # cosmetic only: never stop the app for an icon
+            return False

webapp_shell/native/webview_window.py

@@ -0,0 +1,54 @@
+"""`NativeWindow` for the pywebview shell. The window is attached after pywebview creates it."""
+
+from collections.abc import Sequence
+
+import webview
+
+from .filters import FileFilter
+from .start_location import StartLocation
+from .window import NativeWindow
+from .zoom import WebviewZoom
+
+
+class WebviewWindow(NativeWindow):
+    def __init__(self, zoom: WebviewZoom | None = None):
+        self._window: webview.Window | None = None
+        self._zoom = zoom or WebviewZoom()
+
+    def bind(self, window: webview.Window) -> None:
+        self._window = window
+
+    @property
+    def window(self) -> webview.Window:
+        if self._window is None:
+            raise RuntimeError("the window is not attached yet")
+        return self._window
+
+    def pick_folder(self, start: str) -> str | None:
+        location = StartLocation.of(start)
+        return self._first(self.window.create_file_dialog(webview.FileDialog.FOLDER, directory=location.directory))
+
+    def pick_file(self, filters: list[FileFilter], start: str) -> str | None:
+        location = StartLocation.of(start)
+        types = tuple(f.to_webview() for f in filters)
+        return self._first(
+            self.window.create_file_dialog(webview.FileDialog.OPEN, directory=location.directory, file_types=types)
+        )
+
+    def save_as(self, name: str, start: str) -> str | None:
+        location = StartLocation.of(start)
+        return self._first(
+            self.window.create_file_dialog(
+                webview.FileDialog.SAVE, directory=location.directory, save_filename=location.filename or name
+            )
+        )
+
+    def set_zoom(self, factor: float) -> bool:
+        return self._zoom.apply(self.window, factor)
+
+    @staticmethod
+    def _first(result: Sequence[str] | str | None) -> str | None:
+        """pywebview returns a path, a list of paths, or nothing when cancelled."""
+        if not result:
+            return None
+        return result if isinstance(result, str) else result[0]

webapp_shell/native/window.py

@@ -0,0 +1,34 @@
+"""What a native function can use: the window it opens dialogs on, the shell's preferences and the OS actions. Each
+toolkit implements `NativeWindow`; the functions are written once, against it."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from ..preferences import ShellPreferences
+from .filters import FileFilter
+from .os_actions import OsActions
+
+
+class NativeWindow(ABC):
+    """The window of one toolkit. A dialog returns the chosen path, or None when the person cancelled."""
+
+    @abstractmethod
+    def pick_folder(self, start: str) -> str | None: ...
+
+    @abstractmethod
+    def pick_file(self, filters: list[FileFilter], start: str) -> str | None: ...
+
+    @abstractmethod
+    def save_as(self, name: str, start: str) -> str | None: ...
+
+    @abstractmethod
+    def set_zoom(self, factor: float) -> bool: ...
+
+
+@dataclass(frozen=True)
+class NativeContext:
+    """Handed to every native function as its first argument."""
+
+    window: NativeWindow
+    preferences: ShellPreferences
+    actions: OsActions

webapp_shell/native/zoom.py

@@ -0,0 +1,104 @@
+"""Page zoom (Cmd/Ctrl +, -, 0). The page decides the factor and keeps it as an app preference; each shell only
+applies it to its web view. Qt has `setZoomFactor`; pywebview has no zoom call, so each system's own web view is
+reached here, one small class per system."""
+
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownLambdaType=false
+# pyright: reportUnknownArgumentType=false, reportMissingTypeStubs=false, reportMissingImports=false
+# pyright: reportAttributeAccessIssue=false
+# The lines below talk to AppKit (PyObjC), .NET and GTK, which publish no type stubs. Their inside is untyped by
+# necessity; the signatures of this module are typed.
+
+import sys
+import threading
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+import webview
+
+MAIN_THREAD_WAIT = 2.0  # seconds to wait for the system's UI thread
+
+
+class ZoomSurface(ABC):
+    """How to set the page zoom of a pywebview window on one system. `apply` says whether it was applied."""
+
+    @abstractmethod
+    def apply(self, window: webview.Window, factor: float) -> bool: ...
+
+
+class MacZoom(ZoomSurface):
+    """The window's content view is the WKWebView; its `pageZoom` reflows the page like a browser's zoom does.
+    Cocoa views are touched on the main thread only, and the call waits so a failure is reported."""
+
+    def __init__(self, on_main: Callable[[Callable[[], None]], None] | None = None):
+        self._on_main = on_main or self._app_helper
+
+    def apply(self, window: webview.Window, factor: float) -> bool:
+        done = threading.Event()
+        result: list[bool] = []
+
+        def zoom() -> None:
+            try:
+                window.native.contentView().setPageZoom_(factor)
+                result.append(True)
+            except Exception:  # cosmetic only: never stop the app for a zoom
+                result.append(False)
+            finally:
+                done.set()
+
+        try:
+            self._on_main(zoom)
+        except Exception:
+            return False
+        return done.wait(MAIN_THREAD_WAIT) and bool(result and result[0])
+
+    @staticmethod
+    def _app_helper(call: Callable[[], None]) -> None:
+        from PyObjCTools import AppHelper
+
+        AppHelper.callAfter(call)
+
+
+class WindowsZoom(ZoomSurface):
+    """WebView2's `ZoomFactor`. The browser's own Ctrl +/- are off in a released program, the page's shortcuts do it."""
+
+    def apply(self, window: webview.Window, factor: float) -> bool:
+        try:
+            from System import Func, Type
+
+            form = window.native
+
+            def zoom() -> None:
+                form.webview.ZoomFactor = factor
+
+            form.Invoke(Func[Type](zoom))  # waits for the form's thread
+            return True
+        except Exception:
+            return False
+
+
+class GtkZoom(ZoomSurface):
+    """WebKitGTK's `set_zoom_level`, called on the GTK main loop."""
+
+    def apply(self, window: webview.Window, factor: float) -> bool:
+        try:
+            from gi.repository import GLib
+
+            view = window.native.webview
+            GLib.idle_add(lambda: view.set_zoom_level(factor) and False)
+            return True
+        except Exception:
+            return False
+
+
+class WebviewZoom:
+    def __init__(self, surface: ZoomSurface | None = None):
+        self._surface = surface or self._for_this_system()
+
+    @staticmethod
+    def _for_this_system() -> ZoomSurface:
+        if sys.platform == "darwin":
+            return MacZoom()
+        return WindowsZoom() if sys.platform == "win32" else GtkZoom()
+
+    def apply(self, window: webview.Window, factor: float) -> bool:
+        return self._surface.apply(window, factor)

webapp_shell/native/zoom_range.py

@@ -0,0 +1,9 @@
+"""The range of the page zoom, for every shell (no toolkit is imported here, so a Qt-only build can read it)."""
+
+MIN_ZOOM = 0.5
+MAX_ZOOM = 3.0
+
+
+def clamp(value: float) -> float:
+    """A usable zoom factor: the value, kept between the smallest and the largest the shells allow."""
+    return min(MAX_ZOOM, max(MIN_ZOOM, value))

webapp_shell/preferences.py

@@ -0,0 +1,84 @@
+"""What the shell itself remembers between launches: the colours of the app's opening screen, so the window and
+the splash start in the colours of the theme the user chose (the shell cannot read the web page's storage before
+the page loads)."""
+
+import json
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .json_types import JsonObject, JsonValue
+
+_HEX_COLOUR = re.compile(r"#[0-9a-fA-F]{6}")
+
+
+def is_colour(value: object) -> bool:
+    """Only `#rrggbb` is accepted: these values are later written into HTML and CSS."""
+    return isinstance(value, str) and _HEX_COLOUR.fullmatch(value) is not None
+
+
+@dataclass(frozen=True)
+class BootColors:
+    """The three colours of the navy gradient (frontend tokens `--nav`, `--hero-a`, `--hero-b`)."""
+
+    base: str
+    glow_a: str
+    glow_b: str
+
+    @classmethod
+    def from_values(cls, base: JsonValue, glow_a: JsonValue, glow_b: JsonValue) -> "BootColors | None":
+        """From three stored values. None when one is not text or the three are not `#rrggbb` colours."""
+        if not (isinstance(base, str) and isinstance(glow_a, str) and isinstance(glow_b, str)):
+            return None
+        colors = cls(base, glow_a, glow_b)
+        return colors if colors.is_valid else None
+
+    @property
+    def is_valid(self) -> bool:
+        return all(is_colour(c) for c in (self.base, self.glow_a, self.glow_b))
+
+    def normalised(self) -> "BootColors":
+        return BootColors(self.base.lower(), self.glow_a.lower(), self.glow_b.lower())
+
+
+class ShellPreferences:
+    """A tiny JSON file. With `path=None` it lives in memory only (headless checks must not touch the user's file)."""
+
+    BOOT_KEY = "bootColors"
+
+    def __init__(self, path: Path | None):
+        self._path = path
+        self._values: JsonObject = self._read()
+
+    @property
+    def boot_colors(self) -> BootColors | None:
+        stored = self._values.get(self.BOOT_KEY)
+        if not isinstance(stored, dict):
+            return None
+        return BootColors.from_values(stored.get("base"), stored.get("glow_a"), stored.get("glow_b"))
+
+    def save_boot_colors(self, colors: BootColors) -> bool:
+        if not colors.is_valid:
+            return False
+        self._values[self.BOOT_KEY] = asdict(colors.normalised())
+        self._write()
+        return True
+
+    # storage -----------------------------------------------------------------------------------
+    def _read(self) -> JsonObject:
+        if self._path is None or not self._path.is_file():
+            return {}
+        try:
+            data: JsonValue = json.loads(self._path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _write(self) -> None:
+        if self._path is None:
+            return
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._path.write_text(json.dumps(self._values, indent=2), encoding="utf-8")
+        except OSError:  # colours are not worth failing for
+            pass

webapp_shell/protocol.py

@@ -0,0 +1,34 @@
+"""The names the shell and a backend must agree on. The backend reads the same names; the library never invents them
+silently: `for_slug` gives a consistent default set and a project may write its own."""
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class WireProtocol:
+    token_header: str  # how an API call proves it comes from this launch
+    token_cookie: str  # what the backend turns the first token into
+    token_query: str  # where the launch URL carries the token once
+    token_env: str  # how the shell hands the token over (a command line is visible to other users)
+    api_prefix: str  # everything below it needs the token, except the health path
+    health_path: str  # answers 200 when the backend is ready
+    version_path: str | None  # answers JSON with a "version"; None when the backend has none
+    ws_close_unauthorized: int = 4401  # the close code of a socket that came without a valid token
+
+    @classmethod
+    def for_slug(cls, slug: str) -> "WireProtocol":
+        return cls(
+            token_header=f"x-{slug}-token",
+            token_cookie=f"{slug}_token",
+            token_query="token",
+            token_env=f"{slug.upper()}_TOKEN",
+            api_prefix="/api",
+            health_path="/api/health",
+            version_path="/api/version",
+        )
+
+    def token_from_environment(self, environ: Mapping[str, str] | None = None) -> str | None:
+        """The token the shell handed over, read by the backend."""
+        return (os.environ if environ is None else environ).get(self.token_env)

webapp_shell/qt_shell.py

@@ -0,0 +1,126 @@
+"""Shell 1: Qt WebEngine (bundled Chromium)."""
+
+import os
+import sys
+import threading
+from collections.abc import Callable
+
+from PySide6.QtCore import QObject, QTimer, QUrl, Signal
+from PySide6.QtGui import QColor, QIcon
+from PySide6.QtWebChannel import QWebChannel
+from PySide6.QtWebEngineCore import QWebEngineScript
+from PySide6.QtWebEngineWidgets import QWebEngineView
+from PySide6.QtWidgets import QApplication
+
+from .backend_process import BackendProcess
+from .enums import ShellKind
+from .native.os_actions import OsActions
+from .native.qt_bridge import CHANNEL_OBJECT, QtBridge
+from .native.qt_window import QtWindow
+from .native.window import NativeContext
+from .preferences import ShellPreferences
+from .settings import Settings
+from .shell import Shell
+from .smoke import SETTLE_SECONDS, page_probe_js
+
+
+class _Dispatcher(QObject):
+    """Lets the worker thread ask the GUI thread to act (Qt widgets must only be touched there)."""
+
+    navigate = Signal(str)
+    show_page = Signal(str)
+    set_title = Signal(str)
+    quit = Signal()
+
+
+class QtShell(Shell):
+    name = ShellKind.QT
+
+    def __init__(
+        self,
+        settings: Settings,
+        backend: BackendProcess,
+        preferences: ShellPreferences | None = None,
+        smoke: bool = False,
+    ):
+        super().__init__(settings, backend, preferences, smoke)
+        if self.smoke:
+            os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+        self._app = QApplication(sys.argv)
+        self._view = QWebEngineView()
+        self._apply_icon()
+        self._apply_background()
+        self._dispatcher = _Dispatcher()
+        self._wire_dispatcher()
+        self._install_native_bridge()
+
+    def event_loop(self, boot: Callable[[], None]) -> None:
+        self._view.setWindowTitle(self.settings.identity.name)
+        self._view.resize(*self.settings.window_size)
+        self._view.setHtml(self.splash.loading())
+        if self.smoke:  # headless: never show the window (offscreen GPU rendering is unreliable)
+            self._view.loadFinished.connect(self._on_load_finished)
+            QTimer.singleShot(30_000, self._app.quit)  # pyright: ignore[reportUnknownMemberType]  # PySide6 leaves the callable open
+        else:
+            self._view.show()
+        QTimer.singleShot(0, lambda: threading.Thread(target=boot, daemon=True).start())  # pyright: ignore[reportUnknownMemberType]  # PySide6 leaves the callable open
+        self._app.exec()
+
+    def navigate(self, url: str) -> None:
+        self._dispatcher.navigate.emit(url)
+
+    def show_page(self, html: str) -> None:
+        self._dispatcher.show_page.emit(html)
+
+    def set_title(self, title: str) -> None:
+        self._dispatcher.set_title.emit(title)
+
+    def quit(self) -> None:
+        self._dispatcher.quit.emit()
+
+    def _apply_icon(self) -> None:
+        if self.settings.icon_png:
+            icon = QIcon(str(self.settings.icon_png))
+            self._app.setWindowIcon(icon)
+            self._view.setWindowIcon(icon)
+
+    def _apply_background(self) -> None:
+        """The page and the widget behind it start in the app's colour, so nothing flashes white."""
+        colour = self.settings.background_color
+        self._view.page().setBackgroundColor(QColor(colour))
+        self._view.setStyleSheet(f"background:{colour}")
+
+    def _wire_dispatcher(self) -> None:
+        d = self._dispatcher
+        d.navigate.connect(self._load)
+        d.show_page.connect(self._view.setHtml)
+        d.set_title.connect(self._view.setWindowTitle)
+        d.quit.connect(self._app.quit)
+
+    def _load(self, url: str) -> None:
+        self._view.load(QUrl(url))
+
+    def _install_native_bridge(self) -> None:
+        self._channel = QWebChannel(self._view.page())
+        context = NativeContext(QtWindow(self._view), self.preferences, OsActions())
+        self._channel.registerObject(CHANNEL_OBJECT, QtBridge(self.native, context, self._view))
+        self._view.page().setWebChannel(self._channel)
+        script = QWebEngineScript()
+        script.setName(f"{self.settings.identity.slug}-native")
+        script.setInjectionPoint(QWebEngineScript.InjectionPoint.DocumentReady)
+        script.setWorldId(QWebEngineScript.ScriptWorldId.MainWorld)
+        script.setSourceCode(QtBridge.page_script_source(self.settings.identity, self.native))
+        self._view.page().scripts().insert(script)  # pyright: ignore[reportUnknownMemberType]  # overload with an open list type
+
+    def _on_load_finished(self, _ok: bool) -> None:
+        if self._view.url().scheme() == "http":  # the frontend, not the splash
+            QTimer.singleShot(int(SETTLE_SECONDS * 1000), self._probe)  # pyright: ignore[reportUnknownMemberType]  # PySide6 leaves the callable open
+
+    def _probe(self) -> None:
+        self._view.page().runJavaScript(  # pyright: ignore[reportUnknownMemberType]  # the result callback type is open
+            page_probe_js(self.settings.identity.native_global), self._on_probe
+        )
+
+    def _on_probe(self, page: str) -> None:
+        self.finish_smoke(page)
+        self._app.quit()

webapp_shell/registry.py

@@ -0,0 +1,20 @@
+"""Available shells, imported lazily so choosing one never requires the other's dependencies."""
+
+import importlib
+
+from .enums import ShellKind
+from .shell import Shell
+
+_SHELLS = {
+    ShellKind.QT: ("webapp_shell.qt_shell", "QtShell"),
+    ShellKind.WEBVIEW: ("webapp_shell.webview_shell", "WebviewShell"),
+}
+
+
+def kinds() -> list[ShellKind]:
+    return list(_SHELLS)
+
+
+def shell_class(kind: ShellKind) -> type[Shell]:
+    module, cls = _SHELLS[kind]
+    return getattr(importlib.import_module(module), cls)

webapp_shell/settings.py

@@ -0,0 +1,78 @@
+"""Where things are and how the shell behaves, in one place: the project's config on this installation."""
+
+import sys
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from .config import ShellConfig
+from .installation import Installation
+from .preferences import BootColors, ShellPreferences
+
+
+@dataclass(frozen=True)
+class Settings:
+    config: ShellConfig
+    installation: Installation
+    boot_colors: BootColors  # the opening colours: the identity's, or the ones the user's theme left behind
+
+    @classmethod
+    def of(
+        cls,
+        config: ShellConfig,
+        preferences: ShellPreferences | None = None,
+        installation: Installation | None = None,
+        splash_seconds: float | None = None,
+    ) -> "Settings":
+        """The config on this installation, with the opening colours the user's theme left behind last time."""
+        installation = installation or Installation(config.source_root)
+        remembered = preferences.boot_colors if preferences else None
+        if splash_seconds is not None:
+            config = replace(config, splash_seconds=splash_seconds)
+        return cls(config, installation, remembered or config.identity.boot_colors)
+
+    @property
+    def identity(self):
+        return self.config.identity
+
+    @property
+    def host(self) -> str:
+        return self.config.host
+
+    @property
+    def startup_timeout(self) -> float:
+        return self.config.startup_timeout
+
+    @property
+    def splash_seconds(self) -> float:
+        return self.config.splash_seconds
+
+    @property
+    def window_size(self) -> tuple[int, int]:
+        return self.identity.window_size
+
+    @property
+    def background_color(self) -> str:
+        """The solid colour behind everything (the gradient's base), used for the window and the web view."""
+        return self.boot_colors.base
+
+    @property
+    def package_dirs(self) -> tuple[Path, ...]:
+        return self.installation.package_dirs(self.config.backend)
+
+    @property
+    def frontend_dist(self) -> Path:
+        return self.installation.root / self.config.backend.frontend_dist
+
+    @property
+    def icon_png(self) -> Path | None:
+        return self._existing(self.identity.icon_png)
+
+    @property
+    def window_icon(self) -> Path | None:
+        """The icon for the window frame. Windows draws it with `System.Drawing.Icon`, which reads only `.ico` files;
+        the other systems take the PNG."""
+        return self._existing(self.identity.icon_ico if sys.platform == "win32" else self.identity.icon_png)
+
+    @staticmethod
+    def _existing(path: Path | None) -> Path | None:
+        return path if path is not None and path.is_file() else None