webapp-shell 0.1__py3-none-any.whl

webapp_shell/__init__.py

@@ -0,0 +1,50 @@
+"""webapp_shell: a desktop window for a web app made of a Python backend and a compiled frontend.
+
+A project describes itself with a `ShellConfig` and calls `run(config)`; the library starts the backend, waits until it
+is healthy, opens the frontend in a window (pywebview by default, Qt on request) and gives the page a small set of
+native functions.
+"""
+
+from .backend import BackendSpec, CliFlag
+from .cli import build_parser, run
+from .config import ShellConfig
+from .enums import NativeMethod, ShellKind
+from .identity import AppIdentity
+from .installation import Installation
+from .json_types import JsonObject, JsonValue
+from .library_check import LibraryProblem
+from .messages import MessageKey, ShellMessages
+from .native.errors import NativeError
+from .native.filters import FileFilter
+from .native.registry import NativeCallable, NativeFunction, NoArguments
+from .native.standard import standard_functions
+from .native.window import NativeContext, NativeWindow
+from .preferences import BootColors
+from .protocol import WireProtocol
+
+__all__ = [
+    "AppIdentity",
+    "BackendSpec",
+    "BootColors",
+    "CliFlag",
+    "FileFilter",
+    "Installation",
+    "JsonObject",
+    "JsonValue",
+    "LibraryProblem",
+    "MessageKey",
+    "NativeCallable",
+    "NativeContext",
+    "NativeError",
+    "NativeFunction",
+    "NativeMethod",
+    "NativeWindow",
+    "NoArguments",
+    "ShellConfig",
+    "ShellKind",
+    "ShellMessages",
+    "WireProtocol",
+    "build_parser",
+    "run",
+    "standard_functions",
+]

webapp_shell/__main__.py

@@ -0,0 +1,53 @@
+"""`python -m webapp_shell bridge --out DIR` copies the page-side bridge (one `.js` file and its `.d.ts`) into a frontend;
+`messages` prints the shell's sentences as JSON; `freeze PLAN` freezes a program with PyInstaller."""
+
+import argparse
+import json
+import shutil
+import sys
+from importlib import resources
+from pathlib import Path
+
+from .messages import ShellMessages
+
+BRIDGE_FILES = ("webapp-shell-bridge.js", "webapp-shell-bridge.d.ts")
+
+
+def copy_bridge(out: Path) -> list[Path]:
+    """Copies the bridge files into `out` (created if needed) and returns where they went."""
+    out.mkdir(parents=True, exist_ok=True)
+    source = resources.files("webapp_shell") / "bridge"
+    copied: list[Path] = []
+    for name in BRIDGE_FILES:
+        target = out / name
+        with resources.as_file(source / name) as path:
+            shutil.copyfile(path, target)
+        copied.append(target)
+    return copied
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m webapp_shell", description="webapp-shell tools")
+    commands = parser.add_subparsers(dest="command", required=True)
+    bridge = commands.add_parser("bridge", help="copy the page-side bridge into a frontend")
+    bridge.add_argument("--out", type=Path, required=True, help="the folder to copy into, e.g. frontend/src")
+    commands.add_parser(
+        "messages", help="print the sentences the shell shows, as JSON, for a frontend's translation files"
+    )
+    commands.add_parser("freeze", help="freeze a program with PyInstaller (webapp_shell.freezing); see freeze --help")
+    arguments = sys.argv[1:] if argv is None else argv
+    if arguments[:1] == ["freeze"]:  # its own arguments: the plan, the shells, the folders
+        from .freezing.builder import main as freeze
+
+        return freeze(arguments[1:])
+    args = parser.parse_args(arguments)
+    if args.command == "bridge":
+        for path in copy_bridge(args.out):
+            print(path)
+    if args.command == "messages":
+        print(json.dumps(ShellMessages().catalogue(), indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

webapp_shell/backend.py

@@ -0,0 +1,30 @@
+"""How a project's backend is started: a Python module run as `python -m <module>` (or, in a frozen program, by the
+program running itself)."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .protocol import WireProtocol
+
+
+@dataclass(frozen=True)
+class CliFlag:
+    """A command-line switch the project adds to its program (`--sandbox`). When given, the backend gets `passes`."""
+
+    name: str
+    help: str
+    passes: tuple[str, ...]  # what the backend is started with when the switch is on
+
+
+@dataclass(frozen=True)
+class BackendSpec:
+    module: str  # the backend's package: started as `python -m <module>`; its `__main__.main(argv)` runs when frozen
+    wire: WireProtocol
+    frontend_dist: Path = Path("frontend/dist")  # the compiled frontend, relative to the program's root
+    frontend_argument: str = "--frontend"  # how the backend is told where the compiled frontend is
+    port_argument: str = "--port"
+    preferences_argument: str | None = "--preferences-file"  # None when the backend keeps no preferences file
+    arguments: tuple[str, ...] = ()  # always passed
+    source_only_arguments: tuple[str, ...] = ()  # passed only when running from the source, not when frozen
+    flags: tuple[CliFlag, ...] = ()  # the project's own command-line switches
+    package_dirs: tuple[Path, ...] = ()  # import roots to add by hand when running from the source

webapp_shell/backend_process.py

@@ -0,0 +1,136 @@
+"""Owns the backend child process: start it, wait until it is healthy, ask it things, stop it."""
+
+import os
+import secrets
+import socket
+import subprocess
+import time
+
+import httpx
+
+from .backend import CliFlag
+from .json_types import JsonObject, JsonValue
+from .messages import MessageKey
+from .settings import Settings
+
+
+class BackendError(RuntimeError):
+    """The backend could not be started or reached."""
+
+
+class BackendProcess:
+    def __init__(self, settings: Settings, keeps_preferences: bool = True, flags: tuple[CliFlag, ...] = ()):
+        self._settings = settings
+        self._wire = settings.config.backend.wire
+        self._keeps_preferences = keeps_preferences
+        self._flags = flags  # the project's switches that are on
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._port = 0
+        self.token = secrets.token_urlsafe(24)
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self._settings.host}:{self._port}"
+
+    @property
+    def launch_url(self) -> str:
+        """The URL a shell opens: it carries the token once; the backend turns it into a cookie."""
+        return f"{self.base_url}/?{self._wire.token_query}={self.token}"
+
+    def __enter__(self) -> "BackendProcess":
+        self.start()
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.stop()
+
+    def start(self) -> None:
+        if not (self._settings.frontend_dist / "index.html").is_file():
+            raise BackendError(self._say(MessageKey.FRONTEND_MISSING, path=str(self._settings.frontend_dist)))
+        self._port = self._port or self._free_port()  # a restart keeps the address the open page knows
+        self._proc = subprocess.Popen(self._command(), env=self._environment())
+        self._wait_until_healthy()
+
+    @property
+    def died(self) -> bool:
+        """True when the process ended without `stop()` having been asked."""
+        return self._proc is not None and self._proc.poll() is not None
+
+    def restart(self) -> None:
+        """Start the engine again on the same address and with the same token, so the page that is open reconnects
+        by itself. What was open in it is closed (the person opens the database again); what was saved is safe."""
+        self.stop()
+        self.start()
+
+    def stop(self) -> None:
+        if self._proc is None:
+            return
+        self._proc.terminate()
+        try:
+            self._proc.wait(5)
+        except subprocess.TimeoutExpired:
+            self._proc.kill()
+        self._proc = None
+
+    def version(self) -> JsonObject:
+        """What the backend says about itself, or nothing when the project has no version path."""
+        if self._wire.version_path is None:
+            return {}
+        response = httpx.get(f"{self.base_url}{self._wire.version_path}", headers={self._wire.token_header: self.token})
+        response.raise_for_status()
+        body: JsonValue = response.json()
+        if not isinstance(body, dict):
+            raise BackendError(self._say(MessageKey.VERSION_NOT_OBJECT))
+        return body
+
+    def _say(self, key: MessageKey, **values: str) -> str:
+        return self._settings.config.messages.text(key, **values)
+
+    def _command(self) -> list[str]:
+        backend = self._settings.config.backend
+        installation = self._settings.installation
+        return [
+            *installation.backend_command(backend),
+            backend.port_argument, str(self._port),
+            backend.frontend_argument, str(self._settings.frontend_dist),
+            *self._preferences_arguments(),
+            *backend.arguments,
+            *([] if installation.frozen else backend.source_only_arguments),
+            *(argument for flag in self._flags for argument in flag.passes),
+        ]  # fmt: skip
+
+    def _preferences_arguments(self) -> list[str]:
+        """A headless check keeps its preferences in memory, so it never touches the user's file."""
+        argument = self._settings.config.backend.preferences_argument
+        if argument is None or not self._keeps_preferences:
+            return []
+        return [argument, str(self._settings.identity.app_preferences_path)]
+
+    def _environment(self) -> dict[str, str]:
+        paths = [str(p) for p in self._settings.package_dirs] + [os.environ.get("PYTHONPATH", "")]
+        return {**os.environ, "PYTHONPATH": os.pathsep.join(paths), self._wire.token_env: self.token}
+
+    def _free_port(self) -> int:
+        with socket.socket() as s:
+            s.bind((self._settings.host, 0))
+            return s.getsockname()[1]
+
+    def _wait_until_healthy(self) -> None:
+        deadline = time.time() + self._settings.startup_timeout
+        while time.time() < deadline and self._proc is not None and self._proc.poll() is None:
+            try:
+                if httpx.get(f"{self.base_url}{self._wire.health_path}", timeout=1).status_code == 200:
+                    return
+            except httpx.HTTPError:
+                time.sleep(0.2)
+        code = self._proc.poll() if self._proc is not None else None
+        self.stop()
+        if code is not None:
+            raise BackendError(self._say(MessageKey.BACKEND_EXITED, code=str(code)))
+        raise BackendError(
+            self._say(
+                MessageKey.BACKEND_NOT_STARTED,
+                path=self._wire.health_path,
+                seconds=f"{self._settings.startup_timeout:g}",
+            )
+        )

webapp_shell/bridge/webapp-shell-bridge.d.ts

@@ -0,0 +1,48 @@
+export declare const STANDARD_METHODS: readonly string[]
+
+export declare const BridgeKind: Readonly<{ Qt: 'qt'; Pywebview: 'pywebview'; Browser: 'browser' }>
+export type BridgeKind = (typeof BridgeKind)[keyof typeof BridgeKind]
+
+export interface FileFilter {
+  name: string
+  extensions: string[]
+}
+
+/** The colours of the opening screen, `#rrggbb` each. */
+export interface BootColors {
+  base: string
+  glowA: string
+  glowB: string
+}
+
+/** An error answered by the shell. */
+export declare class NativeCallError extends Error {}
+
+export interface Bridge {
+  readonly kind: BridgeKind
+  /** True inside a desktop shell, where the user can pick real absolute paths. */
+  readonly canPickPaths: boolean
+  readonly canZoom: boolean
+  /** Calls any native function, standard or the project's own. Rejects with NativeCallError. */
+  call<T = unknown>(name: string, ...args: unknown[]): Promise<T>
+  /** `start` is the path the field holds now: the dialog opens there, or at the nearest folder that exists. */
+  pickFolder(start?: string): Promise<string | null>
+  pickFile(filters?: FileFilter[], start?: string): Promise<string | null>
+  saveAs(defaultName?: string, start?: string): Promise<string | null>
+  reveal(path: string): Promise<boolean>
+  openUrl(url: string): Promise<boolean>
+  setBootColors(colors: BootColors): Promise<boolean>
+  setZoom(factor: number): Promise<boolean>
+}
+
+export interface BridgeOptions {
+  /** The Qt shell's object on the window: `<slug>Native`. */
+  nativeGlobal: string
+  /** How long to wait for a shell before assuming a plain browser (default 1500). */
+  waitMs?: number
+  /** The project's own functions for a plain browser, by name. */
+  fallbacks?: Record<string, (...args: unknown[]) => unknown>
+}
+
+export declare function getBridge(options: BridgeOptions): Promise<Bridge>
+export declare function resetBridge(): void

webapp_shell/bridge/webapp-shell-bridge.js

@@ -0,0 +1,146 @@
+/**
+ * webapp-shell bridge: how a page calls the native functions of its desktop shell.
+ *
+ *   import { getBridge } from './webapp-shell-bridge.js'
+ *   const bridge = await getBridge({ nativeGlobal: 'acmeNative' })
+ *   const path = await bridge.pickFile([{ name: 'Excel', extensions: ['xlsx'] }])
+ *
+ * One file, no dependencies. Copy it into the frontend with `python -m webapp_shell bridge --out src/`.
+ */
+
+/** The standard native functions, by their names on the wire (a test keeps this list equal to the Python one). */
+export const STANDARD_METHODS = [
+  'pickFolder',
+  'pickFile',
+  'saveAs',
+  'reveal',
+  'openUrl',
+  'setBootColors',
+  'setZoom',
+]
+
+export const BridgeKind = Object.freeze({ Qt: 'qt', Pywebview: 'pywebview', Browser: 'browser' })
+
+const DEFAULT_WAIT_MS = 1500
+
+/** An error answered by the shell (`{ ok: false, error }`). */
+export class NativeCallError extends Error {}
+
+/** Runs one call on a shell's raw api object and unwraps the envelope. */
+async function callApi(api, name, args) {
+  if (typeof api[name] !== 'function') throw new NativeCallError(`the shell has no native function "${name}"`)
+  const answer = await api[name](...args)
+  if (!answer || typeof answer !== 'object' || !('ok' in answer)) return answer
+  if (!answer.ok) throw new NativeCallError(answer.error)
+  return answer.value
+}
+
+const pathOrNull = (value) => (value ? value : null)
+
+class Bridge {
+  /**
+   * @param kind one of BridgeKind
+   * @param api the shell's raw object, or null in a plain browser
+   * @param fallbacks functions used instead of a missing shell, by name
+   */
+  constructor(kind, api, fallbacks = {}) {
+    this.kind = kind
+    this.canPickPaths = kind !== BridgeKind.Browser
+    this.canZoom = kind !== BridgeKind.Browser
+    this._api = api
+    this._fallbacks = fallbacks
+  }
+
+  /** Calls any native function, standard or the project's own. */
+  call(name, ...args) {
+    if (this._api) return callApi(this._api, name, args)
+    const fallback = this._fallbacks[name]
+    if (fallback) return Promise.resolve(fallback(...args))
+    return Promise.reject(new NativeCallError(`"${name}" is not available in a plain browser`))
+  }
+
+  pickFolder(start = '') {
+    return this.call('pickFolder', start).then(pathOrNull)
+  }
+  pickFile(filters = [], start = '') {
+    return this.call('pickFile', filters, start).then(pathOrNull)
+  }
+  saveAs(defaultName = '', start = '') {
+    return this.call('saveAs', defaultName, start).then(pathOrNull)
+  }
+  reveal(path) {
+    return this.call('reveal', path)
+  }
+  openUrl(url) {
+    return this.call('openUrl', url)
+  }
+  setBootColors(colors) {
+    return this.call('setBootColors', colors)
+  }
+  setZoom(factor) {
+    return this.call('setZoom', factor)
+  }
+}
+
+/** What a plain browser does instead of the shell: nothing for paths, a new tab for links. */
+const BROWSER_FALLBACKS = {
+  pickFolder: async () => null,
+  pickFile: async () => null,
+  saveAs: async () => null,
+  reveal: async () => false,
+  setBootColors: async () => false,
+  setZoom: async () => false,
+  openUrl: async (url) => {
+    window.open(url, '_blank', 'noopener')
+    return true
+  },
+}
+
+function found(nativeGlobal) {
+  if (window[nativeGlobal]) return new Bridge(BridgeKind.Qt, window[nativeGlobal])
+  if (window.pywebview && window.pywebview.api) return new Bridge(BridgeKind.Pywebview, window.pywebview.api)
+  return null
+}
+
+/** The shells inject their object after the page starts, so wait for their ready events before giving up. */
+function waitForShell(nativeGlobal, readyEvent, waitMs, fallbacks) {
+  return new Promise((resolve) => {
+    const events = ['pywebviewready', readyEvent]
+    const settle = () => {
+      const bridge = found(nativeGlobal)
+      if (!bridge) return
+      cleanup()
+      resolve(bridge)
+    }
+    const timer = setTimeout(() => {
+      cleanup()
+      resolve(new Bridge(BridgeKind.Browser, null, fallbacks))
+    }, waitMs)
+    const cleanup = () => {
+      clearTimeout(timer)
+      events.forEach((event) => window.removeEventListener(event, settle))
+    }
+    events.forEach((event) => window.addEventListener(event, settle))
+  })
+}
+
+let cached = null
+
+/**
+ * The bridge of the shell that hosts the page, resolved once and shared.
+ * @param options.nativeGlobal the Qt shell's object: `<slug>Native` (the slug of the project's AppIdentity)
+ * @param options.waitMs how long to wait for a shell before assuming a plain browser
+ * @param options.fallbacks the project's own functions for a plain browser, by name
+ */
+export function getBridge({ nativeGlobal, waitMs = DEFAULT_WAIT_MS, fallbacks = {} }) {
+  cached ??= Promise.resolve(
+    found(nativeGlobal) ??
+      waitForShell(nativeGlobal, nativeGlobal.toLowerCase() + 'ready', waitMs, { ...BROWSER_FALLBACKS, ...fallbacks }),
+  )
+  return cached
+}
+
+/** For tests: forget the shared bridge. */
+export function resetBridge() {
+  cached = null
+}

webapp_shell/cli.py

@@ -0,0 +1,76 @@
+"""The command line every project gets: `<program> [webview|qt] [--smoke] [--splash-seconds N] [project switches]`."""
+
+import argparse
+import importlib
+import sys
+
+from . import registry
+from .backend_process import BackendProcess
+from .config import ShellConfig
+from .enums import ShellKind
+from .installation import Installation, ensure_standard_streams
+from .library_check import LibraryCheck
+from .messages import MessageKey
+from .preferences import ShellPreferences
+from .settings import Settings
+from .webview2 import Webview2Check, show_message_box
+
+
+def build_parser(config: ShellConfig) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=f"Open {config.identity.name} in one of the desktop shells.")
+    parser.add_argument(
+        "shell", type=ShellKind, choices=registry.kinds(), nargs="?", default=ShellKind.WEBVIEW,
+        help="the window toolkit (default: webview)",
+    )  # fmt: skip
+    parser.add_argument("--smoke", action="store_true", help="headless check: load the page, print the result, exit")
+    parser.add_argument(
+        "--splash-seconds",
+        type=float,
+        default=None,
+        help="how long the splash stays at least (default: the setting; 0 with --smoke)",
+    )
+    for flag in config.backend.flags:
+        parser.add_argument(flag.name, action="store_true", help=flag.help)
+    return parser
+
+
+def run_backend(config: ShellConfig, argv: list[str]) -> int:
+    """A frozen program starts its backend by running itself with `Installation.RUN_BACKEND`."""
+    importlib.import_module(f"{config.backend.module}.__main__").main(argv)
+    return 0
+
+
+def check_libraries(config: ShellConfig) -> int:
+    problems = LibraryCheck(config.required_libraries).problems()
+    problems += [problem for check in config.library_checks for problem in check()]
+    print("\n".join(map(str, problems)) or config.messages.text(MessageKey.LIBRARIES_PRESENT))
+    return 1 if problems else 0
+
+
+def run(config: ShellConfig, argv: list[str] | None = None, installation: Installation | None = None) -> int:
+    """The entry point of a project's program: its launcher builds a `ShellConfig` and calls this."""
+    ensure_standard_streams()
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == [Installation.RUN_BACKEND]:
+        return run_backend(config, argv[1:])
+    if argv[:1] == [Installation.CHECK_LIBRARIES]:
+        return check_libraries(config)
+    args = build_parser(config).parse_args(argv)
+    if args.shell is ShellKind.WEBVIEW and not args.smoke:
+        problem = Webview2Check().problem(config.identity.name, config.messages)
+        if problem:
+            show_message_box(config.identity.name, problem)
+            return 1
+
+    # a headless check never reads or writes the user's own preferences file
+    preferences = ShellPreferences(None if args.smoke else config.identity.shell_preferences_path)
+    splash = 0.0 if args.smoke and args.splash_seconds is None else args.splash_seconds
+    settings = Settings.of(config, preferences, installation, splash_seconds=splash)
+    flags = tuple(flag for flag in config.backend.flags if getattr(args, flag.name.lstrip("-").replace("-", "_")))
+    shell = registry.shell_class(args.shell)(
+        settings,
+        BackendProcess(settings, keeps_preferences=not args.smoke, flags=flags),
+        preferences=preferences,
+        smoke=args.smoke,
+    )
+    return shell.run()

webapp_shell/config.py

@@ -0,0 +1,27 @@
+"""The one object a project gives the library."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .backend import BackendSpec
+from .identity import AppIdentity
+from .library_check import LibraryProblem
+from .messages import ENGLISH, ShellMessages
+from .native.registry import NativeCallable
+
+
+@dataclass(frozen=True)
+class ShellConfig:
+    identity: AppIdentity
+    backend: BackendSpec
+    source_root: Path  # running from the source: the folder that holds the compiled frontend (`frontend/dist`)
+    host: str = "127.0.0.1"
+    startup_timeout: float = 20.0  # seconds to wait for the backend to answer its health path
+    # The splash stays at least this long, so the opening always reads as a deliberate, steady start.
+    splash_seconds: float = 0.0
+    native_functions: tuple[NativeCallable, ...] = ()  # the project's own, added to the standard ones
+    required_libraries: tuple[str, ...] = ()  # imported by `--check-libraries` on a frozen program
+    # Checks of the project's own, run by `--check-libraries` after the imports (a codec, a data file): problems found.
+    library_checks: tuple[Callable[[], list[LibraryProblem]], ...] = ()
+    messages: ShellMessages = ENGLISH  # the shell's own sentences, in the project's language

webapp_shell/contract/__init__.py

@@ -0,0 +1,10 @@
+"""The backend's side of the contract with the shell.
+
+The core (`tokens`, `launch`) needs no web framework. `guard` is a ready-made Starlette middleware (FastAPI apps are
+Starlette apps) and is imported on its own: `from webapp_shell.contract.guard import TokenGuard`.
+"""
+
+from .launch import LaunchArguments, add_launch_arguments, read_launch_arguments
+from .tokens import OriginPolicy, TokenValidator
+
+__all__ = ["LaunchArguments", "OriginPolicy", "TokenValidator", "add_launch_arguments", "read_launch_arguments"]