frontage 0.16.1__py3-none-win_amd64.whl

frontage/__init__.py

@@ -0,0 +1,38 @@
+"""Frontage: a fine-grained reactive UI framework for Python in the browser.
+
+M5 of the rewrite (see project/design/architecture.md): the reactive core, the store, reactive views with the
+insert rules, templates (`h` and `html(t"…")`), control flow and boundaries, Resource and
+Action, the router, widgets, State, delegated events, and the DOM renderer.
+"""
+
+import sys
+
+from ._exports import EXPORTS
+from .version import __version__
+
+__all__ = sorted(EXPORTS) + ["__version__"]
+
+
+def __getattr__(name):
+    """`from frontage import Signal` loads `frontage.reactive` and nothing else.
+
+    The package used to import every module up front, so a counter shipped the router, the
+    store and the template parser. Resolving names on first use (PEP 562, which MicroPython
+    supports) is what lets `frontage build` pack only the modules a page reaches — the table
+    in `_exports.py` is what both this function and the build read.
+    """
+    module = EXPORTS.get(name)
+    if module is None:
+        # `from . import reactive` inside the package: CPython resolves a submodule itself when
+        # the attribute is missing, MicroPython asks here first. A name that is neither a
+        # public name nor a module is the usual AttributeError.
+        try:
+            __import__("frontage." + name)
+        except ImportError:
+            raise AttributeError("module 'frontage' has no attribute '%s'" % name) from None
+        return sys.modules["frontage." + name]
+    qualified = "frontage." + module
+    __import__(qualified)
+    value = getattr(sys.modules[qualified], name)
+    globals()[name] = value  # resolved once; the next access is a plain lookup
+    return value

frontage/__init__.pyi

@@ -0,0 +1,85 @@
+# Generated from _exports.py by `tools/exports.py`: the static view of the lazy package,
+# for editors and ty.
+
+from .aio import Action as Action
+from .aio import Resource as Resource
+from .aio import interval as interval
+from .aio import poll as poll
+from .errors import FrontageError as FrontageError
+from .errors import NotReady as NotReady
+from .errors import RenderError as RenderError
+from .errors import format_exception as format_exception
+from .flow import Dynamic as Dynamic
+from .flow import Errored as Errored
+from .flow import For as For
+from .flow import Loading as Loading
+from .flow import Match as Match
+from .flow import Portal as Portal
+from .flow import Show as Show
+from .flow import Switch as Switch
+from .head import Meta as Meta
+from .head import Title as Title
+from .island import island as island
+from .reactive import Context as Context
+from .reactive import Effect as Effect
+from .reactive import Memo as Memo
+from .reactive import Optimistic as Optimistic
+from .reactive import Owner as Owner
+from .reactive import RenderEffect as RenderEffect
+from .reactive import Signal as Signal
+from .reactive import Transition as Transition
+from .reactive import batch as batch
+from .reactive import get_owner as get_owner
+from .reactive import is_pending as is_pending
+from .reactive import latest as latest
+from .reactive import on as on
+from .reactive import on_cleanup as on_cleanup
+from .reactive import on_mount as on_mount
+from .reactive import provide as provide
+from .reactive import refresh as refresh
+from .reactive import run_with_owner as run_with_owner
+from .reactive import selector as selector
+from .reactive import spawn as spawn
+from .reactive import transition as transition
+from .reactive import tree as tree
+from .reactive import untrack as untrack
+from .reactive import use as use
+from .reactive import use_transition as use_transition
+from .renderer import HtmlRenderer as HtmlRenderer
+from .renderer import RecordingRenderer as RecordingRenderer
+from .renderer import Renderer as Renderer
+from .router import A as A
+from .router import ActionForm as ActionForm
+from .router import Navigate as Navigate
+from .router import Redirect as Redirect
+from .router import Route as Route
+from .router import Router as Router
+from .router import use_location as use_location
+from .router import use_navigate as use_navigate
+from .router import use_params as use_params
+from .router import use_query as use_query
+from .runtime import in_browser as in_browser
+from .runtime import platform as platform
+from .state import State as State
+from .state import computed as computed
+from .state import field as field
+from .store import Store as Store
+from .store import reconcile as reconcile
+from .store import snapshot as snapshot
+from .template import html as html
+from .version import __version__ as __version__
+from .view import Element as Element
+from .view import Mounted as Mounted
+from .view import NodeRef as NodeRef
+from .view import Text as Text
+from .view import build as build
+from .view import comment as comment
+from .view import component as component
+from .view import emit as emit
+from .view import h as h
+from .view import mount as mount
+from .view import render_to_string as render_to_string
+from .view import text as text
+from .view import unique_id as unique_id
+
+__all__: list[str]

frontage/__main__.py

@@ -0,0 +1,8 @@
+"""`python -m frontage`: the command line (build, prerender, serve, check, tailwind). Never imported
+in the browser."""
+
+import sys
+
+from frontage.cli import main
+
+sys.exit(main())

frontage/_exports.py

@@ -0,0 +1,87 @@
+# The public names of `frontage`, and the module each lives in. One table, two readers:
+# `frontage/__init__.py` resolves `from frontage import Signal` through it on first use
+# (PEP 562, so a page loads only the modules it reaches), and `frontage build`'s import
+# walk attributes the same name to the same module without importing anything. Keep it
+# sorted by module, then name; `__init__.pyi` is generated from it by `mk exports`.
+
+EXPORTS = {
+    "Action": "aio",
+    "Resource": "aio",
+    "interval": "aio",
+    "poll": "aio",
+    "FrontageError": "errors",
+    "NotReady": "errors",
+    "RenderError": "errors",
+    "format_exception": "errors",
+    "Dynamic": "flow",
+    "Errored": "flow",
+    "For": "flow",
+    "Loading": "flow",
+    "Match": "flow",
+    "Portal": "flow",
+    "Show": "flow",
+    "Switch": "flow",
+    "Meta": "head",
+    "Title": "head",
+    "island": "island",
+    "Context": "reactive",
+    "Effect": "reactive",
+    "Memo": "reactive",
+    "Optimistic": "reactive",
+    "Owner": "reactive",
+    "RenderEffect": "reactive",
+    "Signal": "reactive",
+    "Transition": "reactive",
+    "batch": "reactive",
+    "get_owner": "reactive",
+    "is_pending": "reactive",
+    "latest": "reactive",
+    "on": "reactive",
+    "on_cleanup": "reactive",
+    "on_mount": "reactive",
+    "provide": "reactive",
+    "refresh": "reactive",
+    "run_with_owner": "reactive",
+    "selector": "reactive",
+    "spawn": "reactive",
+    "transition": "reactive",
+    "tree": "reactive",
+    "untrack": "reactive",
+    "use": "reactive",
+    "use_transition": "reactive",
+    "HtmlRenderer": "renderer",
+    "RecordingRenderer": "renderer",
+    "Renderer": "renderer",
+    "A": "router",
+    "ActionForm": "router",
+    "Navigate": "router",
+    "Redirect": "router",
+    "Route": "router",
+    "Router": "router",
+    "use_location": "router",
+    "use_navigate": "router",
+    "use_params": "router",
+    "use_query": "router",
+    "in_browser": "runtime",
+    "platform": "runtime",
+    "State": "state",
+    "computed": "state",
+    "field": "state",
+    "Store": "store",
+    "reconcile": "store",
+    "snapshot": "store",
+    "html": "template",
+    "Element": "view",
+    "Mounted": "view",
+    "NodeRef": "view",
+    "Text": "view",
+    "build": "view",
+    "comment": "view",
+    "component": "view",
+    "emit": "view",
+    "h": "view",
+    "mount": "view",
+    "render_to_string": "view",
+    "text": "view",
+    "unique_id": "view",
+}

frontage/_runtime/boot.js

@@ -0,0 +1,127 @@
+// Boot a page on frontage's runtime: the wasm, the compiled modules named in
+// `manifest.json`, then the entry as `__main__`. The page declares what to run:
+//
+//     <script type="module" src="./_frontage/boot.js" data-fr-boot data-fr-entry="counter"></script>
+//
+// `data-fr-compiler` on the tag loads `frontage-compiler.wasm` instead, the same runtime with
+// the compiler in it, for a page that runs a program someone types (the playground).
+// Everything resolves from `import.meta.url`, so a page at any depth finds its runtime.
+
+import { load } from "./glue.js";
+
+const asset = (name) => new URL(name, import.meta.url).href;
+let rtAssets = "";
+
+async function bytes(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`frontage: ${response.status} fetching ${url}`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+const console_io = {
+  stdout: (s) => console.log(s.replace(/\n$/, "")),
+  stderr: (s) => console.error(s.replace(/\n$/, "")),
+};
+
+/**
+ * The runtime with the compiler in it and no application: for a page that holds its program
+ * in a URL fragment or a text box (the runner, the playground) and has nothing to fetch.
+ * `rt.runSource(code)` runs it as `__main__`. Deliberately touches nothing in the document.
+ */
+export async function startRuntime() {
+  const [rt, framework] = await Promise.all([
+    load(asset("frontage-compiler.wasm"), console_io),
+    fetch(asset("framework.json")).then((r) => r.json()),
+  ]);
+  await addModules(rt, framework.modules);
+  return rt;
+}
+
+// A built app's manifest names each module's content-hashed file; the dev server's does not.
+let files = {};
+const fileOf = (name) => files[name] || `${name}.fbc`;
+
+async function addModules(rt, names) {
+  const modules = await Promise.all(names.map(async (name) => [name, await bytes(asset(fileOf(name)))]));
+  for (const [name, fbc] of modules) rt.addModule(name, fbc);
+}
+
+/**
+ * The runtime, this page's modules, and the JavaScript libraries the tag declares. `run`
+ * picks, from the manifest, the file whose bytecode becomes `__main__` once everything is
+ * in: an app's entry, or — for a page of islands, which has no entry to run —
+ * `frontage.island`.
+ */
+async function start(tag, run) {
+  // A page that runs a typed program (`data-fr-compiler`) gets the whole framework, since
+  // the program may import any of it; a built app gets its entry's import closure.
+  const compiler = tag !== null && tag.dataset.frCompiler !== undefined;
+  const [manifest, framework] = await Promise.all([
+    fetch(asset("manifest.json")).then((r) => r.json()),
+    compiler ? fetch(asset("framework.json")).then((r) => r.json()) : { modules: [] },
+  ]);
+  files = manifest.files || {};
+  // What a chunk fetch needs later: where these files live, and which modules are in each.
+  rtAssets = asset("");
+  const rt = await load(asset(compiler ? "frontage-compiler.wasm" : manifest.wasm || "frontage.wasm"), console_io);
+  const names = [...new Set([...framework.modules, ...manifest.modules])];
+  await addModules(rt, names);
+  // JavaScript modules the app asked for (`data-fr-js="name=./lib.js, ./other.js"`): the
+  // glue around a C or Rust library compiled to WebAssembly. Named ones become Python
+  // modules. Resolved from `../` of this file, the app's own directory in every layout.
+  const appRoot = new URL("../", import.meta.url);
+  for (const item of ((tag && tag.dataset.frJs) || "").split(",")) {
+    const spec = item.trim();
+    if (!spec) continue;
+    const eq = spec.indexOf("=");
+    const name = eq > 0 ? spec.slice(0, eq).trim() : "";
+    const specifier = eq > 0 ? spec.slice(eq + 1).trim() : spec;
+    const namespace = await import(new URL(specifier, appRoot).href);
+    if (name) rt.registerJsModule(name, namespace);
+  }
+  const main = await bytes(asset(run(manifest)));
+  rt.assetBase = rtAssets;
+  rt.manifest = manifest;
+  window.frontage = rt;
+  const code = rt.run(main);
+  if (code === 1) console.error("frontage: the entry raised; see above");
+  return rt;
+}
+
+/**
+ * A static page whose islands have started asking for a runtime (`island.js`). There is no
+ * entry to run — the page's HTML was written at build time — so what runs is
+ * `frontage.island`, which mounts each queued wrapper over the markup already on screen.
+ * Called once per page, however many islands there are.
+ */
+export async function startIslands() {
+  const tag = document.querySelector("script[data-fr-islands]");
+  return start(tag, () => fileOf("frontage.island"));
+}
+
+async function boot() {
+  const tag = document.querySelector("script[data-fr-boot]");
+  if (!tag) {
+    // Not an error: a page may import this module for `startRuntime` or `startIslands` alone.
+    if (!document.querySelector("script[data-fr-islands]")) {
+      console.warn("frontage: no <script data-fr-boot> on the page, so nothing was mounted");
+    }
+    return null;
+  }
+  const entry = tag.dataset.frEntry || "app";
+  // `manifest.entry` is the built app's content-hashed entry file; the dev server's manifest
+  // has none, and the module is asked for by its plain name.
+  return start(tag, (manifest) => manifest.entry || `${entry}.fbc`);
+}
+
+const parsed =
+  document.readyState === "loading"
+    ? new Promise((done) => document.addEventListener("DOMContentLoaded", done, { once: true }))
+    : Promise.resolve();
+
+export const ready = parsed.then(boot);
+ready.catch((error) => {
+  setTimeout(() => {
+    throw error;
+  });
+});