webapp-shell

A desktop window for a web app made of a Python backend and a compiled frontend. Your project describes itself in one config object; the library starts the backend, waits until it is healthy, opens the frontend in a native window (pywebview, or Qt on request) and gives the page a small set of native functions (file and folder dialogs, reveal in the file manager, open a link, zoom).

Documentation: https://prmpsmart.github.io/webapp_shell. The same site is what examples/site opens in the library's own window, where each feature's demonstration button does the real thing.

By Miracle Apata (@prmpsmart). MIT licence.

from pathlib import Path

from webapp_shell import AppIdentity, BackendSpec, BootColors, ShellConfig, WireProtocol, run

ROOT = Path(__file__).resolve().parent

config = ShellConfig(
    identity=AppIdentity(
        name="Acme Notes",
        slug="acme",
        storage_dir=Path.home() / ".acme",
        boot_colors=BootColors(base="#102030", glow_a="#204060", glow_b="#4060a0"),
    ),
    backend=BackendSpec(module="acme_backend", wire=WireProtocol.for_slug("acme"), package_dirs=(ROOT / "backend",)),
    source_root=ROOT,  # holds frontend/dist, the compiled frontend
)

if __name__ == "__main__":
    raise SystemExit(run(config))

The backend reads the same contract with the library's helpers (Starlette or FastAPI):

import argparse

from starlette.applications import Starlette
from webapp_shell.contract import TokenValidator, add_launch_arguments, read_launch_arguments
from webapp_shell.contract.guard import TokenGuard

wire = config.backend.wire  # the same names the shell uses

parser = argparse.ArgumentParser()
add_launch_arguments(parser, config.backend)  # --port, --frontend, --preferences-file, --token
launch = read_launch_arguments(parser, parser.parse_args(), wire)

app = Starlette(...)
app.add_middleware(TokenGuard, validator=TokenValidator(launch.token, wire), wire=wire)

Native functions: the standard set (file and folder dialogs, save as, reveal, open a link, zoom, boot colours) is always there; a project adds its own and the page calls them by name.

from dataclasses import dataclass
from webapp_shell import JsonValue, NativeContext, NativeFunction


@dataclass(frozen=True)
class Greeting:  # the page's arguments, in order; each is type-checked before your code runs
    who: str


def greet(context: NativeContext, arguments: Greeting) -> JsonValue:  # context.window, .preferences, .actions
    return f"hello {arguments.who}"


config = ShellConfig(..., native_functions=(NativeFunction("greet", Greeting, greet),))

// copy the bridge into the frontend once: python -m webapp_shell bridge --out src/
import { getBridge } from "./webapp-shell-bridge.js";

const bridge = await getBridge({ nativeGlobal: "acmeNative" });
const path = await bridge.pickFile([{ name: "Excel", extensions: ["xlsx"] }]);
const hello = await bridge.call("greet", "Ada");

Install: pip install webapp-shell (pywebview is included); the extras are qt (the Qt window), backend (Starlette, for the token guard) and freeze (PyInstaller, for the next step), for example pip install "webapp-shell[qt,backend]".

Freezing: describe the program in a FreezePlan and run python -m webapp_shell freeze plan:PLAN qt webview. The library writes the entry file and the PyInstaller spec, keeps the other window toolkit out of each build and checks the finished folder (see freezing).

On Windows the pywebview window needs the WebView2 runtime (present on Windows 11); pythonnet is installed by pywebview.

A runnable minimal program is in examples/minimal/, and examples/site/ is the documentation website, opened by the library's own shell, with a live demonstration of every feature.

Guides (docs/): the contract, configuration, native functions, freezing with PyInstaller, translating, troubleshooting, and the generated API listing (the public API: nothing that is not listed there is promised). The same guides are pages of the documentation site. To work on the library, read CONTRIBUTING.md.