webapp-shell 0.1__py3-none-any.whl

webapp_shell/library_check.py

@@ -0,0 +1,28 @@
+"""Imports every third-party library a project lists. Heavy libraries load lazily, so a frozen program that lacks
+one would only fail when the person reaches the feature; this finds it when the program is built."""
+
+import importlib
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LibraryProblem:
+    name: str
+    detail: str
+
+    def __str__(self) -> str:
+        return f"{self.name}: {self.detail}"
+
+
+class LibraryCheck:
+    def __init__(self, libraries: tuple[str, ...]):
+        self._libraries = libraries
+
+    def problems(self) -> list[LibraryProblem]:
+        found: list[LibraryProblem] = []
+        for name in self._libraries:
+            try:
+                importlib.import_module(name)
+            except Exception as error:
+                found.append(LibraryProblem(name, f"{type(error).__name__}: {error}"))
+        return found

webapp_shell/messages.py

@@ -0,0 +1,58 @@
+"""The few sentences the shell shows itself (in the splash page's error, and in what it prints), as one catalogue.
+
+A project that translates its program gives its own `ShellMessages` (in the language it chose) to `ShellConfig`; the
+frontend can read the same catalogue as JSON (`python -m webapp_shell messages`) to put the keys in its translation
+files. The user interface itself belongs to the frontend; these are only the sentences that appear when there is no
+frontend yet or any more.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from .json_types import JsonObject
+
+
+class MessageKey(StrEnum):
+    """The name of each sentence. The member name, lower-cased, is the field of `ShellMessages`; the value is the key in
+    the JSON catalogue."""
+
+    FRONTEND_MISSING = "frontendMissing"
+    BACKEND_NOT_STARTED = "backendNotStarted"
+    BACKEND_EXITED = "backendExited"
+    VERSION_NOT_OBJECT = "versionNotObject"
+    BACKEND_GAVE_UP = "backendGaveUp"
+    LIBRARIES_PRESENT = "librariesPresent"
+    WEBVIEW2_MISSING = "webview2Missing"
+
+
+@dataclass(frozen=True)
+class ShellMessages:
+    """Every sentence, with its English default. `{name}` and `{path}` are filled in when the sentence is shown."""
+
+    frontend_missing: str = "the compiled frontend is missing: {path}"
+    backend_not_started: str = (
+        "the backend did not answer {path} within {seconds} seconds; start it by hand to read what it says"
+    )
+    backend_exited: str = "the backend stopped while starting (exit code {code}); start it by hand to read what it says"
+    version_not_object: str = "the version path did not answer with an object"
+    backend_gave_up: str = "The backend stopped several times in a row. Close {name} and open it again."
+    libraries_present: str = "all libraries are present"
+    webview2_missing: str = (
+        "{name} needs the Microsoft WebView2 runtime, which is not installed. "
+        "Install it from {url} and open {name} again."
+    )
+
+    def text(self, key: MessageKey, **values: str) -> str:
+        """The sentence for `key` with its placeholders filled."""
+        return self.sentences()[key].format(**values)
+
+    def sentences(self) -> dict[MessageKey, str]:
+        """Each key with its sentence, in the order of `MessageKey`."""
+        return {key: getattr(self, key.name.lower()) for key in MessageKey}
+
+    def catalogue(self) -> JsonObject:
+        """The JSON object a frontend reads: key → sentence, placeholders left as `{name}`."""
+        return {str(key): sentence for key, sentence in self.sentences().items()}
+
+
+ENGLISH = ShellMessages()

webapp_shell/native/__init__.py

@@ -0,0 +1,4 @@
+"""The native bridge: what a web page cannot do itself (real-path dialogs, reveal in file manager, open URL).
+
+`os_actions` and `filters` are shared; each shell adds only its own dialog implementation.
+"""

webapp_shell/native/arguments.py

@@ -0,0 +1,131 @@
+"""Turns the list of JSON values a page sent into the typed arguments of a native function.
+
+A function declares its arguments as a dataclass; the page's positional arguments fill the fields in order, and a
+field with a default may be left out. Supported field types: `str`, `int`, `float` (an integer is accepted),
+`bool`, `X | None`, `list[X]`, `tuple[X, ...]` and another dataclass (sent as an object with camelCase keys, so the
+field `glow_a` is `glowA` on the wire). Nothing is converted silently: a number where text is expected is refused.
+"""
+
+import dataclasses
+import types
+from collections.abc import Callable
+from typing import Union, get_args, get_origin, get_type_hints
+
+from ..json_types import JsonValue
+from .errors import NativeError
+
+
+def wire_name(field_name: str) -> str:
+    """`glow_a` -> `glowA`: the name a field has on the wire."""
+    head, *rest = field_name.split("_")
+    return head + "".join(part.capitalize() for part in rest)
+
+
+def _has_default(field: dataclasses.Field[object]) -> bool:
+    return field.default is not dataclasses.MISSING or field.default_factory is not dataclasses.MISSING
+
+
+def _is_union(hint: object) -> bool:
+    return get_origin(hint) in (Union, types.UnionType)
+
+
+def _check_supported(hint: object, where: str) -> None:
+    """Fails when a function is declared, not when a page first calls it."""
+    if hint is str or hint is int or hint is float or hint is bool:
+        return
+    if _is_union(hint):
+        members = [member for member in get_args(hint) if member is not type(None)]
+        if len(members) != 1:
+            raise TypeError(f"{where}: only `X | None` unions are supported")
+        return _check_supported(members[0], where)
+    origin = get_origin(hint)
+    if origin is list:
+        return _check_supported(get_args(hint)[0], where)
+    if origin is tuple:
+        item, ellipsis = get_args(hint)
+        if ellipsis is not Ellipsis:
+            raise TypeError(f"{where}: only `tuple[X, ...]` is supported")
+        return _check_supported(item, where)
+    if isinstance(hint, type) and dataclasses.is_dataclass(hint):
+        for field_name, field_hint in get_type_hints(hint).items():
+            _check_supported(field_hint, f"{where}.{field_name}")
+        return
+    raise TypeError(f"{where}: the type {hint!r} cannot be an argument of a native function")
+
+
+def _convert(value: JsonValue, hint: object, label: str) -> object:
+    if _is_union(hint):
+        if value is None:
+            return None
+        (member,) = (member for member in get_args(hint) if member is not type(None))
+        return _convert(value, member, label)
+    if hint is str:
+        if isinstance(value, str):
+            return value
+        raise NativeError(f'"{label}" must be text')
+    if hint is bool:
+        if isinstance(value, bool):
+            return value
+        raise NativeError(f'"{label}" must be true or false')
+    if hint is int:
+        if isinstance(value, int) and not isinstance(value, bool):
+            return value
+        raise NativeError(f'"{label}" must be a whole number')
+    if hint is float:
+        if isinstance(value, int | float) and not isinstance(value, bool):
+            return float(value)
+        raise NativeError(f'"{label}" must be a number')
+    origin = get_origin(hint)
+    if origin in (list, tuple):
+        if not isinstance(value, list):
+            raise NativeError(f'"{label}" must be a list')
+        item = get_args(hint)[0]
+        items = [_convert(entry, item, f"{label}[{index}]") for index, entry in enumerate(value)]
+        return items if origin is list else tuple(items)
+    if isinstance(hint, type) and dataclasses.is_dataclass(hint):
+        return _convert_object(value, hint, label)
+    raise AssertionError(f"unsupported type {hint!r}")  # _check_supported refused it at declaration
+
+
+def _convert_object(value: JsonValue, shape: type, label: str) -> object:
+    if not isinstance(value, dict):
+        raise NativeError(f'"{label}" must be an object')
+    hints = get_type_hints(shape)
+    fields = {wire_name(field.name): field for field in dataclasses.fields(shape)}
+    unknown = sorted(set(value) - set(fields))
+    if unknown:
+        raise NativeError(f'"{label}" has no field "{unknown[0]}"')
+    values: dict[str, object] = {}
+    for name, field in fields.items():
+        if name in value:
+            values[field.name] = _convert(value[name], hints[field.name], f"{label}.{name}")
+        elif not _has_default(field):
+            raise NativeError(f'"{label}" needs the field "{name}"')
+    build: Callable[..., object] = shape
+    return build(**values)
+
+
+class Arguments[A]:
+    """The arguments of one native function, declared as a dataclass."""
+
+    def __init__(self, shape: type[A]):
+        if not dataclasses.is_dataclass(shape):
+            raise TypeError(f"the arguments of a native function are a dataclass, not {shape!r}")
+        self._shape = shape
+        self._hints = get_type_hints(shape)
+        self._fields = dataclasses.fields(shape)
+        for field in self._fields:
+            _check_supported(self._hints[field.name], f"{shape.__name__}.{field.name}")
+
+    def parse(self, values: list[JsonValue]) -> A:
+        if len(values) > len(self._fields):
+            raise NativeError("too many arguments")
+        parsed: dict[str, object] = {}
+        for index, field in enumerate(self._fields):
+            label = wire_name(field.name)
+            if index < len(values):
+                parsed[field.name] = _convert(values[index], self._hints[field.name], label)
+            elif not _has_default(field):
+                raise NativeError(f'missing argument "{label}"')
+        build: Callable[..., A] = self._shape
+        return build(**parsed)

webapp_shell/native/errors.py

@@ -0,0 +1,5 @@
+"""The error a native function raises to refuse a call in words the page may show."""
+
+
+class NativeError(Exception):
+    """Raised by a handler to refuse a call in words the page may show."""

webapp_shell/native/filters.py

@@ -0,0 +1,24 @@
+"""File-type filters in the one shape the frontend sends, converted for each toolkit."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FileFilter:
+    """`{name: 'Excel', extensions: ['xlsx', 'xls']}` from the page. An extension may be written `xlsx` or `*.xlsx`."""
+
+    name: str
+    extensions: tuple[str, ...]
+
+    @property
+    def is_usable(self) -> bool:
+        return bool(self.name) and bool(self.extensions)
+
+    def _patterns(self) -> list[str]:
+        return ["*." + extension.lstrip("*.") for extension in self.extensions]
+
+    def to_qt(self) -> str:
+        return f"{self.name} ({' '.join(self._patterns())})"
+
+    def to_webview(self) -> str:
+        return f"{self.name} ({';'.join(self._patterns())})"

webapp_shell/native/os_actions.py

@@ -0,0 +1,33 @@
+"""Operating-system actions both shells offer to the page. Inputs come from a web page, so they are validated."""
+
+import subprocess
+import sys
+import webbrowser
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+class OsActions:
+    ALLOWED_URL_SCHEMES = frozenset({"http", "https", "mailto"})
+
+    def reveal(self, path: str) -> bool:
+        """Show a file or folder in the file manager."""
+        target = Path(path)
+        if not target.exists():
+            return False
+        subprocess.Popen(self._reveal_command(target))
+        return True
+
+    def open_url(self, url: str) -> bool:
+        """Open a web link in the default browser; other schemes (file:, javascript:, ...) are refused."""
+        if urlparse(url).scheme.lower() not in self.ALLOWED_URL_SCHEMES:
+            return False
+        return webbrowser.open(url)
+
+    @staticmethod
+    def _reveal_command(target: Path) -> list[str]:
+        if sys.platform == "darwin":
+            return ["open", "-R", str(target)]
+        if sys.platform == "win32":
+            return ["explorer", f"/select,{target}"]
+        return ["xdg-open", str(target if target.is_dir() else target.parent)]

webapp_shell/native/qt_bridge.py

@@ -0,0 +1,62 @@
+"""The native bridge of the Qt shell: a QObject published to the page through QWebChannel.
+
+The page does not load `qwebchannel.js` itself. The shell injects it, from Qt's own resources, together with a small
+script that exposes the same promise API (`window.<slug>Native.<name>(...)`) the page sees in every shell. One slot,
+`call`, carries every native function: the name and the arguments as JSON text in, the envelope as JSON text out.
+"""
+
+import json
+
+from PySide6.QtCore import QFile, QIODevice, QObject, Slot
+
+from ..identity import AppIdentity
+from ..json_types import JsonValue
+from .registry import NativeRegistry
+from .window import NativeContext
+
+CHANNEL_OBJECT = "bridge"
+
+_GLUE_JS = """
+new QWebChannel(qt.webChannelTransport, function (channel) {
+  var b = channel.objects.%(object)s;
+  var api = {};
+  %(names)s.forEach(function (name) {
+    api[name] = function () {
+      var args = JSON.stringify(Array.prototype.slice.call(arguments));
+      return new Promise(function (resolve) {
+        b.call(name, args, function (answer) { resolve(JSON.parse(answer)); });
+      });
+    };
+  });
+  window.%(global)s = api;
+  window.dispatchEvent(new Event('%(ready)s'));
+});
+"""
+
+
+class QtBridge(QObject):
+    def __init__(self, registry: NativeRegistry, context: NativeContext, parent: QObject | None = None):
+        super().__init__(parent)
+        self._registry = registry
+        self._context = context
+
+    @Slot(str, str, result=str)
+    def call(self, name: str, arguments_json: str) -> str:
+        try:
+            arguments: JsonValue = json.loads(arguments_json or "[]")
+        except ValueError:
+            arguments = None
+        return json.dumps(self._registry.call(self._context, name, arguments))
+
+    @staticmethod
+    def page_script_source(identity: AppIdentity, registry: NativeRegistry) -> str:
+        """qwebchannel.js (from Qt's resources) followed by the glue that defines the page's native object."""
+        resource = QFile(":/qtwebchannel/qwebchannel.js")
+        if not resource.open(QIODevice.OpenModeFlag.ReadOnly):
+            raise RuntimeError("qwebchannel.js is not available in this Qt installation")
+        return bytes(resource.readAll().data()).decode("utf-8") + _GLUE_JS % {
+            "object": CHANNEL_OBJECT,
+            "names": json.dumps(registry.names),
+            "global": identity.native_global,
+            "ready": identity.native_ready_event,
+        }

webapp_shell/native/qt_window.py

@@ -0,0 +1,34 @@
+"""`NativeWindow` for the Qt shell: the dialogs of `QFileDialog` and the page zoom of the web view."""
+
+from pathlib import Path
+
+from PySide6.QtWebEngineWidgets import QWebEngineView
+from PySide6.QtWidgets import QFileDialog
+
+from .filters import FileFilter
+from .start_location import StartLocation
+from .window import NativeWindow
+
+
+class QtWindow(NativeWindow):
+    def __init__(self, view: QWebEngineView):
+        self._view = view
+
+    def pick_folder(self, start: str) -> str | None:
+        return QFileDialog.getExistingDirectory(self._view, dir=StartLocation.of(start).qt_path()) or None
+
+    def pick_file(self, filters: list[FileFilter], start: str) -> str | None:
+        patterns = ";;".join(f.to_qt() for f in filters)
+        location = StartLocation.of(start).qt_path()
+        return QFileDialog.getOpenFileName(self._view, dir=location, filter=patterns)[0] or None
+
+    def save_as(self, name: str, start: str) -> str | None:
+        """Opens at the folder of the current choice (or the one it was in), proposing `name` unless a file is set."""
+        location = StartLocation.of(start)
+        proposed = location.filename or name
+        where = str(Path(location.directory, proposed)) if location.directory else name
+        return QFileDialog.getSaveFileName(self._view, dir=where)[0] or None
+
+    def set_zoom(self, factor: float) -> bool:
+        self._view.setZoomFactor(factor)
+        return True

webapp_shell/native/registry.py

@@ -0,0 +1,91 @@
+"""The native functions a page may call: a name, typed arguments, a handler, and one place that runs them for both
+toolkits.
+
+The page is untrusted, so a call is checked here: the name must be registered, the arguments must fit the declared
+types, an error never leaks more than a plain message, and every result travels in the same envelope:
+`{"ok": true, "value": ...}` or `{"ok": false, "error": "..."}`.
+"""
+
+import logging
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+from ..json_types import JsonObject, JsonValue
+from .arguments import Arguments
+from .errors import NativeError
+from .window import NativeContext
+
+__all__ = ["NativeCallable", "NativeError", "NativeFunction", "NativeRegistry", "NoArguments"]
+
+_NAME = re.compile(r"[a-z][A-Za-z0-9]*")
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class NoArguments:
+    """The arguments of a function that takes none."""
+
+
+class NativeCallable(Protocol):
+    """What the registry stores: any `NativeFunction`, whatever its arguments are."""
+
+    @property
+    def name(self) -> str: ...
+
+    def run(self, context: NativeContext, values: list[JsonValue]) -> JsonValue: ...
+
+
+class NativeFunction[A]:
+    """A function the page can call by `name`. `arguments` is a dataclass (see `native.arguments`); the handler is
+    called as `handler(context, arguments)` and returns anything JSON can carry."""
+
+    def __init__(self, name: str, arguments: type[A], handler: Callable[[NativeContext, A], JsonValue]):
+        if not _NAME.fullmatch(name):
+            raise ValueError(f"a native function name is camelCase letters and digits: {name!r}")
+        self._name = name
+        self._arguments = Arguments(arguments)
+        self._handler = handler
+
+    @property
+    def name(self) -> str:  # camelCase, starts with a lowercase letter: it is the name on the wire and in the page
+        return self._name
+
+    def run(self, context: NativeContext, values: list[JsonValue]) -> JsonValue:
+        return self._handler(context, self._arguments.parse(values))
+
+
+class NativeRegistry:
+    def __init__(self, functions: tuple[NativeCallable, ...] = ()):
+        self._functions: dict[str, NativeCallable] = {}
+        for function in functions:
+            self.add(function)
+
+    def add(self, function: NativeCallable) -> None:
+        if function.name in self._functions:
+            raise ValueError(f"a native function named {function.name!r} is already registered")
+        self._functions[function.name] = function
+
+    @property
+    def names(self) -> list[str]:
+        return list(self._functions)
+
+    def call(self, context: NativeContext, name: str, arguments: JsonValue) -> JsonObject:
+        """Runs one call from the page and returns the envelope."""
+        function = self._functions.get(name)
+        if function is None:
+            return self._failed("unknown native function")
+        if not isinstance(arguments, list):
+            return self._failed("the arguments must be a list")
+        try:
+            return {"ok": True, "value": function.run(context, arguments)}
+        except NativeError as error:
+            return self._failed(str(error))
+        except Exception:
+            _log.exception("native function %s failed", name)
+            return self._failed("the native function failed")
+
+    @staticmethod
+    def _failed(message: str) -> JsonObject:
+        return {"ok": False, "error": message}

webapp_shell/native/standard.py

@@ -0,0 +1,89 @@
+"""The native functions every project gets. Written once, against `NativeContext`; the page sees them under the names
+of `NativeMethod`. Each declares its arguments as a dataclass."""
+
+from dataclasses import dataclass, field
+
+from ..enums import NativeMethod
+from ..preferences import BootColors
+from .filters import FileFilter
+from .registry import NativeCallable, NativeFunction
+from .window import NativeContext
+from .zoom_range import clamp
+
+
+@dataclass(frozen=True)
+class PickFolderArguments:
+    start: str = ""
+
+
+@dataclass(frozen=True)
+class PickFileArguments:
+    filters: list[FileFilter] = field(default_factory=list[FileFilter])
+    start: str = ""
+
+
+@dataclass(frozen=True)
+class SaveAsArguments:
+    name: str = ""
+    start: str = ""
+
+
+@dataclass(frozen=True)
+class RevealArguments:
+    path: str
+
+
+@dataclass(frozen=True)
+class OpenUrlArguments:
+    url: str
+
+
+@dataclass(frozen=True)
+class BootColorsArguments:
+    colors: BootColors
+
+
+@dataclass(frozen=True)
+class ZoomArguments:
+    factor: float
+
+
+def pick_folder(context: NativeContext, arguments: PickFolderArguments) -> str | None:
+    return context.window.pick_folder(arguments.start)
+
+
+def pick_file(context: NativeContext, arguments: PickFileArguments) -> str | None:
+    usable = [item for item in arguments.filters if item.is_usable]
+    return context.window.pick_file(usable, arguments.start)
+
+
+def save_as(context: NativeContext, arguments: SaveAsArguments) -> str | None:
+    return context.window.save_as(arguments.name, arguments.start)
+
+
+def reveal(context: NativeContext, arguments: RevealArguments) -> bool:
+    return context.actions.reveal(arguments.path)
+
+
+def open_url(context: NativeContext, arguments: OpenUrlArguments) -> bool:
+    return context.actions.open_url(arguments.url)
+
+
+def set_boot_colors(context: NativeContext, arguments: BootColorsArguments) -> bool:
+    return context.preferences.save_boot_colors(arguments.colors)
+
+
+def set_zoom(context: NativeContext, arguments: ZoomArguments) -> bool:
+    return context.window.set_zoom(clamp(arguments.factor))
+
+
+def standard_functions() -> tuple[NativeCallable, ...]:
+    return (
+        NativeFunction(NativeMethod.PICK_FOLDER.value, PickFolderArguments, pick_folder),
+        NativeFunction(NativeMethod.PICK_FILE.value, PickFileArguments, pick_file),
+        NativeFunction(NativeMethod.SAVE_AS.value, SaveAsArguments, save_as),
+        NativeFunction(NativeMethod.REVEAL.value, RevealArguments, reveal),
+        NativeFunction(NativeMethod.OPEN_URL.value, OpenUrlArguments, open_url),
+        NativeFunction(NativeMethod.SET_BOOT_COLORS.value, BootColorsArguments, set_boot_colors),
+        NativeFunction(NativeMethod.SET_ZOOM.value, ZoomArguments, set_zoom),
+    )

webapp_shell/native/start_location.py

@@ -0,0 +1,28 @@
+"""Where a native dialog opens: the path the field already holds, or the nearest folder that still exists."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class StartLocation:
+    directory: str = ""
+    filename: str = ""
+
+    @classmethod
+    def of(cls, path: str | None) -> "StartLocation":
+        """A folder opens itself; a file opens its folder with the name preselected; a missing path falls back
+        to the closest parent that exists; anything else leaves the choice to the toolkit."""
+        if not path:
+            return cls()
+        target = Path(path).expanduser()
+        if target.is_dir():
+            return cls(str(target))
+        for parent in target.parents:
+            if parent.is_dir():
+                return cls(str(parent), target.name if parent == target.parent and target.suffix else "")
+        return cls()
+
+    def qt_path(self) -> str:
+        """Qt takes one `dir` argument: a folder, or a folder plus the name to preselect."""
+        return str(Path(self.directory, self.filename)) if self.directory else ""

webapp_shell/native/webview_background.py

@@ -0,0 +1,39 @@
+"""Makes the web view itself paint the app's background before a page loads, so no white shows between the
+splash and the frontend. Platform specific, and 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
+
+import webview
+
+
+class WebviewBackground:
+    def __init__(self, color: str):
+        self.color = color
+
+    def apply(self, window: webview.Window) -> None:
+        if sys.platform == "darwin":
+            self._apply_macos(window)
+
+    def _apply_macos(self, window: webview.Window) -> None:
+        """WKWebView paints white under a page until told otherwise (`underPageBackgroundColor`, macOS 12+)."""
+        try:
+            import AppKit
+            from PyObjCTools import AppHelper
+
+            red, green, blue = (int(self.color.lstrip("#")[i : i + 2], 16) / 255 for i in (0, 2, 4))
+            colour = AppKit.NSColor.colorWithSRGBRed_green_blue_alpha_(red, green, blue, 1.0)
+
+            def paint() -> None:  # Cocoa views are touched on the main thread only
+                webview = window.native.webview
+                if webview.respondsToSelector_("setUnderPageBackgroundColor:"):
+                    webview.setUnderPageBackgroundColor_(colour)
+
+            AppHelper.callAfter(paint)
+        except Exception:  # cosmetic only: never stop the app for a colour
+            pass

webapp_shell/native/webview_bridge.py

@@ -0,0 +1,25 @@
+"""The native bridge of the pywebview shell. pywebview turns every public callable of this object into
+`window.pywebview.api.<name>()`; the registered native functions are attached by name, each answering in the envelope."""
+
+from collections.abc import Callable
+
+from ..json_types import JsonObject, JsonValue
+from .registry import NativeRegistry
+from .window import NativeContext
+
+
+class WebviewBridge:
+    def __init__(self, registry: NativeRegistry, context: NativeContext):
+        # Private on purpose: pywebview walks every public attribute of the API object (and went into the .NET window
+        # when the window was public, which failed on Windows with thread and recursion errors).
+        self._registry = registry
+        self._context = context
+        for name in registry.names:
+            setattr(self, name, self._function(name))
+
+    def _function(self, name: str) -> Callable[..., JsonObject]:
+        def call(*arguments: JsonValue) -> JsonObject:
+            return self._registry.call(self._context, name, list(arguments))
+
+        call.__name__ = name
+        return call