webapp-shell 0.1__py3-none-any.whl

webapp_shell/contract/guard.py

@@ -0,0 +1,106 @@
+"""Access control for a Starlette or FastAPI backend: the launch token, from a header or a cookie.
+
+    app.add_middleware(TokenGuard, validator=TokenValidator(token, wire), wire=wire)
+
+and for a WebSocket route, which middleware does not cover:
+
+    guard = WebSocketGuard(validator, wire)
+
+    @app.websocket("/api/events")
+    async def events(socket: WebSocket):
+        if not await guard.accept(socket):
+            return
+        ...
+
+Needs `starlette` (`pip install "webapp-shell[backend]"`).
+"""
+
+from dataclasses import dataclass, field
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse, Response
+from starlette.types import ASGIApp
+from starlette.websockets import WebSocket
+
+__all__ = ["GuardResponses", "TokenGuard", "WebSocketGuard"]
+
+from ..protocol import WireProtocol
+from .tokens import OriginPolicy, TokenValidator
+
+ORIGIN_HEADER = "origin"
+HOST_HEADER = "host"
+
+
+@dataclass(frozen=True)
+class GuardResponses:
+    """What a refused request gets back. A project with its own error format replaces them."""
+
+    unauthorized: dict[str, str] = field(default_factory=lambda: {"code": "UNAUTHORIZED"})
+    foreign_origin: dict[str, str] = field(default_factory=lambda: {"code": "FOREIGN_ORIGIN"})
+
+
+class TokenGuard(BaseHTTPMiddleware):
+    """Protects the API with the launch token.
+
+    Opening the app with `/?token=...` turns the token into a cookie and redirects to the clean URL,
+    so a launcher only has to open one URL and needs no cookie code of its own.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        validator: TokenValidator,
+        wire: WireProtocol,
+        origins: OriginPolicy | None = None,
+        responses: GuardResponses | None = None,
+    ):
+        super().__init__(app)
+        self._validator = validator
+        self._wire = wire
+        self._origins = origins or OriginPolicy()
+        self._responses = responses or GuardResponses()
+
+    def _bearer(self, request: Request) -> str | None:
+        return request.headers.get(self._wire.token_header) or request.cookies.get(self._wire.token_cookie)
+
+    def _bootstrap_session(self, request: Request) -> RedirectResponse:
+        response = RedirectResponse(str(request.url.remove_query_params(self._wire.token_query)))
+        response.set_cookie(self._wire.token_cookie, self._validator.token, httponly=True, samesite="strict")
+        return response
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        wire = self._wire
+        path = request.url.path
+        in_api = path.startswith(wire.api_prefix)
+        if self._validator.is_valid(request.query_params.get(wire.token_query)) and not in_api:
+            return self._bootstrap_session(request)
+        if in_api and not self._origins.allows(request.headers.get(ORIGIN_HEADER), request.headers.get(HOST_HEADER)):
+            return JSONResponse(self._responses.foreign_origin, status_code=403)
+        if in_api and path != wire.health_path and not self._validator.is_valid(self._bearer(request)):
+            return JSONResponse(self._responses.unauthorized, status_code=401)
+        return await call_next(request)
+
+
+class WebSocketGuard:
+    """The same rules for a socket as `TokenGuard` has for a request: the token (header, cookie or query string) and
+    the origin. A refused socket is closed with `wire.ws_close_unauthorized` before it is accepted."""
+
+    def __init__(self, validator: TokenValidator, wire: WireProtocol, origins: OriginPolicy | None = None):
+        self._validator = validator
+        self._wire = wire
+        self._origins = origins or OriginPolicy()
+
+    def allows(self, socket: WebSocket) -> bool:
+        from_own_page = self._origins.allows(socket.headers.get(ORIGIN_HEADER), socket.headers.get(HOST_HEADER))
+        return from_own_page and self._validator.is_valid_connection(
+            socket.headers, socket.cookies, socket.query_params
+        )
+
+    async def accept(self, socket: WebSocket) -> bool:
+        """Accepts the socket and returns True, or closes it and returns False: the route then just returns."""
+        if not self.allows(socket):
+            await socket.close(code=self._wire.ws_close_unauthorized)
+            return False
+        await socket.accept()
+        return True

webapp_shell/contract/launch.py

@@ -0,0 +1,49 @@
+"""The command line the shell starts a backend with, read by the backend: the port, the compiled frontend, the
+preferences file and the token. The argument names come from the same `BackendSpec` the shell builds the command from,
+so the two cannot drift."""
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..backend import BackendSpec
+from ..protocol import WireProtocol
+
+
+@dataclass(frozen=True)
+class LaunchArguments:
+    port: int
+    token: str
+    frontend: Path | None
+    preferences_file: Path | None
+    host: str
+
+
+def add_launch_arguments(parser: argparse.ArgumentParser, backend: BackendSpec) -> None:
+    """Adds the standard arguments to a backend's parser. Read them back with `LaunchArguments.of(args, ...)`."""
+    wire = backend.wire
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument(backend.port_argument, dest="port", type=int, required=True)
+    parser.add_argument(
+        "--token",
+        default=wire.token_from_environment(),
+        help=f"the launch token; {wire.token_env} in the environment is safer, a command line is visible to other users",
+    )
+    parser.add_argument(backend.frontend_argument, dest="frontend", type=Path, default=None)
+    if backend.preferences_argument:
+        parser.add_argument(backend.preferences_argument, dest="preferences_file", type=Path, default=None)
+
+
+def read_launch_arguments(
+    parser: argparse.ArgumentParser, args: argparse.Namespace, wire: WireProtocol
+) -> LaunchArguments:
+    """Checks the token is there (the parser reports the error) and gathers the standard arguments."""
+    if not args.token:
+        parser.error(f"a token is needed: --token or {wire.token_env}")
+    return LaunchArguments(
+        port=args.port,
+        token=args.token,
+        frontend=args.frontend,
+        preferences_file=getattr(args, "preferences_file", None),
+        host=args.host,
+    )

webapp_shell/contract/tokens.py

@@ -0,0 +1,41 @@
+"""Decides whether a candidate is the launch token, and whether a request comes from the app's own page. No HTTP
+framework code here."""
+
+import hmac
+from collections.abc import Mapping
+from urllib.parse import urlsplit
+
+from ..protocol import WireProtocol
+
+
+class TokenValidator:
+    def __init__(self, token: str, wire: WireProtocol):
+        self._token = token
+        self._wire = wire
+
+    @property
+    def token(self) -> str:
+        return self._token
+
+    def is_valid(self, candidate: str | None) -> bool:
+        # Compared as bytes: `compare_digest` refuses text with non-ASCII characters, which a caller controls.
+        return bool(candidate) and hmac.compare_digest(candidate.encode(), self._token.encode())
+
+    def is_valid_connection(
+        self, headers: Mapping[str, str], cookies: Mapping[str, str], query: Mapping[str, str]
+    ) -> bool:
+        """A socket can carry the token in a header (tools), the cookie (the browser) or the query string."""
+        wire = self._wire
+        candidate = headers.get(wire.token_header) or cookies.get(wire.token_cookie) or query.get(wire.token_query)
+        return self.is_valid(candidate)
+
+
+class OriginPolicy:
+    """A browser tells which page made a request in `Origin`. Cookies are shared by every port of a host, so another
+    program's page on 127.0.0.1 would otherwise be allowed to call this one: only the app's own page is."""
+
+    def allows(self, origin: str | None, host: str | None) -> bool:
+        """True when the request names no origin (a tool, not a page) or the origin is the host being called."""
+        if origin is None:
+            return True
+        return bool(host) and urlsplit(origin).netloc == host

webapp_shell/enums.py

@@ -0,0 +1,20 @@
+from enum import StrEnum
+
+
+class ShellKind(StrEnum):
+    """The desktop shells. The value is what the command line and the run scripts use."""
+
+    QT = "qt"
+    WEBVIEW = "webview"
+
+
+class NativeMethod(StrEnum):
+    """The native functions a page may call (02-architecture.md). The value is the name on the wire, in both shells."""
+
+    PICK_FOLDER = "pickFolder"
+    PICK_FILE = "pickFile"
+    SAVE_AS = "saveAs"
+    REVEAL = "reveal"
+    OPEN_URL = "openUrl"
+    SET_BOOT_COLORS = "setBootColors"
+    SET_ZOOM = "setZoom"

webapp_shell/freezing/__init__.py

@@ -0,0 +1,10 @@
+"""Freezing a program into one folder with PyInstaller: the project writes a `FreezePlan`, the library does the rest.
+
+    python -m webapp_shell freeze acme_freeze:PLAN --path . qt webview
+
+Needs `pyinstaller` (`pip install "webapp-shell[freeze]"`); only `webapp_shell.freezing.spec` imports it.
+"""
+
+from .plan import DataFolder, FreezePlan
+
+__all__ = ["DataFolder", "FreezePlan"]

webapp_shell/freezing/app.spec

@@ -0,0 +1,5 @@
+# -*- mode: python ; coding: utf-8 -*-
+# The one PyInstaller spec of webapp_shell: the plan and the shell come from the environment (see builder.py).
+from webapp_shell.freezing.spec import freeze
+
+freeze()

webapp_shell/freezing/builder.py

@@ -0,0 +1,82 @@
+"""Freezes the program for each shell and checks the result: `python -m webapp_shell freeze PLAN [qt] [webview]`.
+
+Each shell is built into `<output>/<shell>/<product>/`: the other shell's libraries must not be in it, the files the
+plan requires must be, and the frozen program's own `--check-libraries` must pass. Nothing here makes an installer.
+"""
+
+import argparse
+import importlib.util
+import os
+import subprocess
+import sys
+from importlib import resources
+from pathlib import Path
+
+from ..enums import ShellKind
+from ..installation import Installation
+from .plan import FreezePlan
+from .profile import PROFILES
+from .verify import BuildVerifier, Finding
+
+PLAN_VARIABLE = "WEBAPP_SHELL_FREEZE_PLAN"  # how the spec learns what to freeze: the plan's reference ...
+KIND_VARIABLE = "WEBAPP_SHELL_FREEZE_KIND"  # ... and the shell
+
+
+class Builder:
+    def __init__(self, plan: FreezePlan, reference: str, paths: tuple[Path, ...], output: Path, work: Path):
+        self.plan, self.reference, self.paths = plan, reference, paths
+        self.output, self.work = output, work
+
+    def folder(self, kind: ShellKind) -> Path:
+        return self.output / kind.value / self.plan.product
+
+    def _program(self, kind: ShellKind) -> Path:
+        program = self.folder(kind) / self.plan.product
+        return program.with_suffix(".exe") if sys.platform == "win32" else program
+
+    def _library_problems(self, kind: ShellKind) -> str:
+        """Runs the frozen program's own check: every library the program loads on first use must be in it."""
+        done = subprocess.run([str(self._program(kind)), Installation.CHECK_LIBRARIES], capture_output=True, text=True)
+        return "" if done.returncode == 0 else (done.stdout + done.stderr).strip()
+
+    def _environment(self, kind: ShellKind) -> dict[str, str]:
+        roots = [str(path.resolve()) for path in self.paths]
+        python_path = os.pathsep.join([*roots, *filter(None, [os.environ.get("PYTHONPATH")])])
+        return {**os.environ, "PYTHONPATH": python_path, PLAN_VARIABLE: self.reference, KIND_VARIABLE: kind.value}
+
+    def build(self, kind: ShellKind) -> int:
+        if importlib.util.find_spec("PyInstaller") is None:
+            print('PyInstaller is not installed: pip install "webapp-shell[freeze]"')
+            return 1
+        spec = resources.files("webapp_shell.freezing") / "app.spec"
+        with resources.as_file(spec) as spec_path:
+            command = [
+                sys.executable, "-m", "PyInstaller", str(spec_path), "--noconfirm", "--clean",
+                "--distpath", str(self.output / kind.value), "--workpath", str(self.work / kind.value),
+            ]  # fmt: skip
+            done = subprocess.run(command, env=self._environment(kind))
+        if done.returncode:
+            return done.returncode
+        findings = BuildVerifier(self.folder(kind), PROFILES[kind], self.plan).findings()
+        if not findings and (problem := self._library_problems(kind)):
+            findings = [Finding("libraries", problem)]
+        for finding in findings:
+            print(f"{kind.value}: {finding.path}: {finding.problem}")
+        print(f"{kind.value}: {self.folder(kind)} " + ("is not right" if findings else "checked"))
+        return 1 if findings else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m webapp_shell freeze", description=(__doc__ or "").splitlines()[0])
+    parser.add_argument("plan", help="module:attribute of the project's FreezePlan")
+    parser.add_argument("shells", nargs="*", type=ShellKind, default=list(PROFILES), help="default: every shell")
+    parser.add_argument(
+        "--path", type=Path, action="append", default=[], help="a folder to import the project from (repeatable)"
+    )
+    parser.add_argument("--output", type=Path, default=Path("dist"))
+    parser.add_argument("--work", type=Path, default=Path("build"))
+    args = parser.parse_args(argv)
+    for path in args.path:
+        sys.path.insert(0, str(path.resolve()))
+    builder = Builder(FreezePlan.load(args.plan), args.plan, tuple(args.path), args.output, args.work)
+    return max(builder.build(kind) for kind in args.shells)

webapp_shell/freezing/entry.py

@@ -0,0 +1,24 @@
+"""The entry point of a frozen program: a file written for each build."""
+
+from ..enums import ShellKind
+from .plan import FreezePlan
+
+ENTRY_SOURCE = '''"""Entry point of the frozen {shell} build (generated by webapp_shell.freezing)."""
+
+import multiprocessing
+import sys
+
+from webapp_shell import Installation, run
+from {module} import {attribute} as target
+
+if __name__ == "__main__":
+    multiprocessing.freeze_support()  # a child process of the program is the same executable
+    config = target() if callable(target) else target
+    args = sys.argv[1:]
+    sys.exit(run(config, args if args[:1] and args[0] in Installation.COMMANDS else ["{shell}", *args]))
+'''
+
+
+def entry_source(plan: FreezePlan, kind: ShellKind) -> str:
+    module, _, attribute = plan.config.partition(":")
+    return ENTRY_SOURCE.format(shell=kind.value, module=module, attribute=attribute)

webapp_shell/freezing/plan.py

@@ -0,0 +1,38 @@
+"""What a project says about its frozen build. The rest (the entry file, what each shell leaves out, the checks of the
+finished folder) belongs to the library."""
+
+import importlib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class DataFolder:
+    """A folder of the project that goes into the build as data (the compiled frontend, files the backend reads)."""
+
+    source: Path
+    target: str  # the folder inside the build, e.g. "frontend/dist"
+
+
+@dataclass(frozen=True)
+class FreezePlan:
+    product: str  # the name of the folder and of the executable
+    config: str  # "module:attribute": the `ShellConfig` (or a function returning one) the program runs with
+    packages: tuple[str, ...]  # whose submodules are all collected: the project's own, and any that load by name
+    data_folders: tuple[DataFolder, ...] = ()
+    required: tuple[
+        str, ...
+    ] = ()  # files that must be in the finished build, relative to its data, e.g. "frontend/dist/index.html"
+    collect_all: tuple[str, ...] = ()  # third-party packages with data files or native libraries
+    runtime_hooks: tuple[Path, ...] = ()  # scripts that run before anything else in the frozen program
+    excludes: tuple[str, ...] = ()  # more libraries to keep out, besides the developer tools the library leaves out
+    icon: Path | None = None  # `.ico`, used for the Windows executable
+
+    @classmethod
+    def load(cls, reference: str) -> "FreezePlan":
+        """The plan named `module:attribute`; the module must be importable (`--path`)."""
+        module, _, name = reference.partition(":")
+        plan = getattr(importlib.import_module(module), name)
+        if not isinstance(plan, cls):
+            raise TypeError(f"{reference} is not a FreezePlan")
+        return plan

webapp_shell/freezing/profile.py

@@ -0,0 +1,49 @@
+"""What each shell brings and what it must leave out, so a build carries one window toolkit and not the other."""
+
+from dataclasses import dataclass
+
+from ..enums import ShellKind
+
+
+@dataclass(frozen=True)
+class ShellProfile:
+    """One shell, with the libraries of the other kept out of its build."""
+
+    kind: ShellKind
+    modules: tuple[str, ...]  # webapp_shell modules that belong to this shell only
+    forbidden: tuple[str, ...]  # top-level names that must not be in the finished build
+
+    @property
+    def other_modules(self) -> tuple[str, ...]:
+        return tuple(m for p in PROFILES.values() if p.kind is not self.kind for m in p.modules)
+
+    @property
+    def excludes(self) -> list[str]:
+        """Libraries the freezer must leave out even if something imports them."""
+        return [*COMMON_EXCLUDES, *self.forbidden, *self.other_modules]
+
+    def wanted_module(self, name: str) -> bool:
+        return not any(name == m or name.startswith(f"{m}.") for m in self.other_modules)
+
+
+PROFILES: dict[ShellKind, ShellProfile] = {
+    ShellKind.QT: ShellProfile(
+        ShellKind.QT,
+        modules=("webapp_shell.qt_shell", "webapp_shell.native.qt_bridge", "webapp_shell.native.qt_window"),
+        forbidden=("webview", "pythonnet", "clr_loader", "proxy_tools", "bottle"),
+    ),
+    ShellKind.WEBVIEW: ShellProfile(
+        ShellKind.WEBVIEW,
+        modules=(
+            "webapp_shell.webview_shell",
+            "webapp_shell.native.webview_bridge",
+            "webapp_shell.native.webview_background",
+            "webapp_shell.native.webview_window",
+            "webapp_shell.native.zoom",
+        ),
+        forbidden=("PySide6", "shiboken6", "PyQt5", "PyQt6", "qtpy"),
+    ),
+}
+
+# Tools of the developer, never of the user.
+COMMON_EXCLUDES = ["tkinter", "pytest", "ruff", "pip", "IPython", "notebook"]  # not setuptools: pkg_resources needs it

webapp_shell/freezing/spec.py

@@ -0,0 +1,68 @@
+# pyright: basic
+"""The only module that imports PyInstaller: runs inside a PyInstaller build and describes it from the `FreezePlan`."""
+
+import os
+import sys
+from pathlib import Path
+from typing import cast
+
+from PyInstaller.building.api import COLLECT, EXE, PYZ
+from PyInstaller.building.build_main import Analysis
+from PyInstaller.config import CONF
+from PyInstaller.utils.hooks import collect_all, collect_submodules
+
+from ..enums import ShellKind
+from .builder import KIND_VARIABLE, PLAN_VARIABLE
+from .entry import entry_source
+from .plan import FreezePlan
+from .profile import PROFILES
+
+LIBRARY_PACKAGES = ("webapp_shell",)  # the registry loads its shells by name, so every submodule of this shell is in
+
+
+def freeze() -> None:
+    plan = FreezePlan.load(os.environ[PLAN_VARIABLE])
+    kind = ShellKind(os.environ[KIND_VARIABLE])
+    profile = PROFILES[kind]
+
+    workpath = Path(cast(str, CONF["workpath"]))  # PyInstaller types CONF loosely; it is a path
+    entry = workpath / f"entry_{kind.value}.py"
+    entry.parent.mkdir(parents=True, exist_ok=True)
+    entry.write_text(entry_source(plan, kind), encoding="utf-8")
+
+    datas = [(str(folder.source), folder.target) for folder in plan.data_folders]
+    binaries = []
+    hiddenimports = []
+    for package in plan.collect_all:
+        found = collect_all(package)
+        datas += found[0]
+        binaries += found[1]
+        hiddenimports += found[2]
+    for package in (*LIBRARY_PACKAGES, *plan.packages):
+        hiddenimports += collect_submodules(package, filter=profile.wanted_module)
+
+    analysis = Analysis(
+        [str(entry)],
+        pathex=[],
+        binaries=binaries,
+        datas=datas,
+        hiddenimports=hiddenimports,
+        hookspath=[],
+        runtime_hooks=[str(hook) for hook in plan.runtime_hooks],
+        excludes=[*profile.excludes, *plan.excludes],
+        noarchive=False,
+    )
+    pyz = PYZ(analysis.pure)
+    exe = EXE(
+        pyz,
+        analysis.scripts,
+        [],
+        exclude_binaries=True,
+        name=plan.product,
+        debug=False,
+        strip=False,
+        upx=False,
+        console=False,
+        icon=str(plan.icon) if plan.icon and sys.platform == "win32" else None,
+    )
+    COLLECT(exe, analysis.binaries, analysis.datas, strip=False, upx=False, name=plan.product)

webapp_shell/freezing/verify.py

@@ -0,0 +1,43 @@
+"""Looks inside a finished build and fails when it holds something it must not, or lacks something it needs."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .plan import FreezePlan
+from .profile import ShellProfile
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: str
+    problem: str
+
+
+class BuildVerifier:
+    """`folder` is the program's folder (the one that is handed over for installing)."""
+
+    def __init__(self, folder: Path, profile: ShellProfile, plan: FreezePlan):
+        self.folder, self.profile, self.plan = Path(folder), profile, plan
+
+    def findings(self) -> list[Finding]:
+        return [*self._missing(), *self._forbidden()]
+
+    def _inside(self) -> Path:
+        """PyInstaller puts the bundled files in `_internal` from version 6, beside the executable before."""
+        internal = self.folder / "_internal"
+        return internal if internal.is_dir() else self.folder
+
+    def _missing(self) -> list[Finding]:
+        found = [Finding(name, "missing") for name in self.plan.required if not (self._inside() / name).exists()]
+        if not any((self.folder / f"{self.plan.product}{suffix}").exists() for suffix in ("", ".exe")):
+            found.append(Finding(self.plan.product, "the executable is missing"))
+        return found
+
+    def _forbidden(self) -> list[Finding]:
+        names = {name.lower() for name in self.profile.forbidden}
+        found: list[Finding] = []
+        for path in self.folder.rglob("*"):
+            parts = {part.lower().split(".")[0] for part in path.relative_to(self.folder).parts}
+            if parts & names:
+                found.append(Finding(path.relative_to(self.folder).as_posix(), "belongs to the other shell"))
+        return found

webapp_shell/identity.py

@@ -0,0 +1,48 @@
+"""Who the program is: the one place a project says its name, where it keeps things and how its opening looks."""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .preferences import BootColors
+
+_SLUG = re.compile(r"[a-z][a-z0-9]*")
+
+
+@dataclass(frozen=True)
+class AppIdentity:
+    """What the shell shows and stores for one program. Nothing else in the library names the program."""
+
+    name: str  # shown in the window title, the splash and the messages: "Acme Notes"
+    slug: str  # lowercase letters and digits: names the page's native object, the Qt script, the default wire names
+    storage_dir: Path  # the program's own folder for what the shell remembers: "~/.acme"
+    boot_colors: BootColors  # the opening screen's colours until the page reports the user's own
+    icon_png: Path | None = None  # window icon (macOS, Linux) and the splash mark
+    icon_ico: Path | None = None  # window icon on Windows, which draws only `.ico` files
+    window_size: tuple[int, int] = field(default=(1280, 800))
+
+    def __post_init__(self) -> None:
+        if not _SLUG.fullmatch(self.slug):
+            raise ValueError(f"slug must be lowercase letters and digits, starting with a letter: {self.slug!r}")
+        if not self.name.strip():
+            raise ValueError("name must not be empty")
+
+    @property
+    def native_global(self) -> str:
+        """The name of the object the Qt shell puts on the page: `window.<slug>Native`."""
+        return f"{self.slug}Native"
+
+    @property
+    def native_ready_event(self) -> str:
+        """The event the page waits for before using `native_global`."""
+        return f"{self.slug}nativeready"
+
+    @property
+    def shell_preferences_path(self) -> Path:
+        """What the shell itself needs before the app exists (the opening colours)."""
+        return self.storage_dir / "shell.json"
+
+    @property
+    def app_preferences_path(self) -> Path:
+        """The program's own preferences, one file for every shell, owned by the backend."""
+        return self.storage_dir / "preferences.json"

webapp_shell/installation.py

@@ -0,0 +1,41 @@
+"""Where the program lives and how its backend is started: from the source tree, or frozen into one folder."""
+
+import os
+import sys
+from pathlib import Path
+
+from .backend import BackendSpec
+
+
+class Installation:
+    """A frozen program (PyInstaller) has one executable and no `python -m`: it starts its own backend by running
+    itself with `RUN_BACKEND`. From the source tree the backend is `python -m <module>`, as always."""
+
+    RUN_BACKEND = "--run-backend"
+    CHECK_LIBRARIES = "--check-libraries"  # imports every required library; a build runs it on the frozen program
+    COMMANDS = (RUN_BACKEND, CHECK_LIBRARIES)  # what a frozen program does instead of opening a window
+
+    def __init__(self, source_root: Path, frozen: bool | None = None, bundle: Path | None = None):
+        self.frozen = bool(getattr(sys, "frozen", False)) if frozen is None else frozen
+        self._bundle = bundle if bundle is not None else Path(getattr(sys, "_MEIPASS", source_root))
+        self._source_root = source_root
+
+    @property
+    def root(self) -> Path:
+        """The folder that holds the compiled frontend (and whatever else the program ships)."""
+        return self._bundle if self.frozen else self._source_root
+
+    def package_dirs(self, backend: BackendSpec) -> tuple[Path, ...]:
+        """Import roots to add by hand. A frozen program carries its packages inside."""
+        return () if self.frozen else backend.package_dirs
+
+    def backend_command(self, backend: BackendSpec) -> list[str]:
+        return [sys.executable, self.RUN_BACKEND] if self.frozen else [sys.executable, "-m", backend.module]
+
+
+def ensure_standard_streams() -> None:
+    """A windowed program has no console: `sys.stdout` and `sys.stderr` are None, and libraries that ask a stream
+    whether it is a terminal (the backend's web server does) fail. They get a stream that discards its text."""
+    for name in ("stdout", "stderr"):
+        if getattr(sys, name) is None:
+            setattr(sys, name, open(os.devnull, "w", encoding="utf-8"))  # noqa: SIM115 - kept open for the whole run

webapp_shell/json_types.py

@@ -0,0 +1,4 @@
+"""What JSON can carry. Everything that crosses between the page and Python is one of these, never a bare `dict`."""
+
+type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None
+type JsonObject = dict[str, JsonValue]