pyweb-stack 0.1.0__py3-none-any.whl

pyweb/bench.py

@@ -0,0 +1,101 @@
+"""Benchmark harness: measure what actually ships and how fast it renders.
+
+``python -m pyweb.bench`` compiles small reference apps and reports, per
+app: source lines, compile time, shipped JavaScript (minified and gzip,
+including the shared runtime only when the app ships any JS), HTML size
+and real per-request server render time. No theater: numbers come from
+the same code paths ``pyweb build`` and ``pyweb serve`` use.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import time
+
+APPS = {
+    "counter": (
+        'from pyweb import App\napp = App()\n@app.page("/")\n'
+        "def Home():\n    count = 0\n"
+        "    def increment():\n        count += 1\n"
+        "    <main>\n        <button onclick={increment}>\n"
+        "            Count: {count}\n        </button>\n    </main>\n"),
+    "todo": (
+        'from pyweb import App\napp = App()\n@app.page("/")\n'
+        "def Home():\n    text = ''\n    items = []\n    left = len(items)\n"
+        "    def add():\n        if text.strip():\n            items.append(text.strip())\n        text = ''\n"
+        "    def remove(item):\n        items.remove(item)\n"
+        "    <main>\n        <input bind={text} />\n"
+        "        <button onclick={add}>Add</button>\n        <p>{left} left</p>\n"
+        "        <ul>\n            for item in items:\n"
+        "                <li>{item} <button onclick={remove(item)}>x</button></li>\n        </ul>\n    </main>\n"),
+    "blog": (
+        'from pyweb import App\napp = App()\n@app.page("/posts/{slug}")\n'
+        "def Post(slug: str):\n    title = slug.replace('-', ' ').title()\n"
+        "    <article>\n        <h1>{title}</h1>\n"
+        "        <p>Static page: no JavaScript is shipped.</p>\n    </article>\n"),
+}
+
+
+def _gz(data: str) -> int:
+    return len(gzip.compress(data.encode(), 9))
+
+
+def runtime_sizes() -> dict:
+    """Minified and gzip size of the shared browser runtime."""
+    import os
+    from pyweb.build import minify_js
+    path = os.path.join(os.path.dirname(__file__), "runtime", "browser", "runtime.js")
+    with open(path, encoding="utf-8") as fh:
+        js = minify_js(fh.read())
+    return {"bytes": len(js.encode()), "gzip_bytes": _gz(js)}
+
+
+def bench_app(name: str, source: str, *, repeat: int = 50) -> dict:
+    from pyweb.app_loader import LoadedApp
+    from pyweb.build import minify_js
+    from pyweb.compiler import compile_source
+    t0 = time.perf_counter()
+    out = compile_source(source, filename=f"{name}.pyweb")
+    compile_ms = (time.perf_counter() - t0) * 1000
+    pages = out["pages"]
+    page_js = [minify_js(p["js"]) for p in pages.values() if p.get("js")]
+    rt = runtime_sizes() if page_js else {"bytes": 0, "gzip_bytes": 0}
+    app = LoadedApp(source=source, filename=f"{name}.pyweb")
+    page_name, page = next(iter(pages.items()))
+    params = {p: "hello-world" for p in page["params"]}
+    html = app.render(page_name, params)
+    t0 = time.perf_counter()
+    for _ in range(repeat):
+        app.render(page_name, params)
+    ssr_ms = (time.perf_counter() - t0) * 1000 / repeat
+    page_bytes = sum(len(j.encode()) for j in page_js)
+    page_gz = sum(_gz(j) for j in page_js)
+    return {"app": name, "source_lines": len(source.splitlines()),
+            "compile_ms": round(compile_ms, 2),
+            "page_js_bytes": page_bytes, "page_js_gzip": page_gz,
+            "runtime_js_bytes": rt["bytes"], "runtime_js_gzip": rt["gzip_bytes"],
+            "js_bytes": page_bytes + rt["bytes"], "js_gzip": page_gz + rt["gzip_bytes"],
+            "html_bytes": len(html.encode()),
+            "signals": sum(len(p.get("signals", ())) for p in pages.values()),
+            "ssr_ms": round(ssr_ms, 3),
+            "rpc": len(out.get("rpc", []))}
+
+
+def run(apps=None) -> dict:
+    apps = apps or APPS
+    return {name: bench_app(name, src) for name, src in apps.items()}
+
+
+def main():
+    results = run()
+    print(json.dumps(results, indent=2))
+    rt = runtime_sizes()
+    print(f"\nshared runtime: {rt['bytes']} B minified, {rt['gzip_bytes']} B gzip "
+          "(downloaded once, cached across pages)")
+    for r in results.values():
+        print(f"{r['app']:>8}: page JS {r['page_js_gzip']} B gzip, server render {r['ssr_ms']} ms")
+
+
+if __name__ == "__main__":
+    main()

pyweb/browser.py

@@ -0,0 +1,232 @@
+"""Typed browser APIs.
+
+Every capability exposes the same Python surface on the server (safe
+stub returning documented defaults) and in the browser (real binding).
+The compiler maps each stub to its JS implementation via
+:meth:`Api._js`; server execution never touches the DOM.
+
+Sensor/action APIs (camera, location, clipboard, notifications, share,
+filesystem, bluetooth) raise :class:`BrowserUnavailable` on the server
+instead of silently returning fake data — fake sensor data would be
+worse than an error. Query-style APIs (fetch, permissions, vibrate,
+IDB) return documented safe defaults so SSR code paths keep working.
+"""
+
+from __future__ import annotations
+
+
+class BrowserUnavailable(RuntimeError):
+    """Raised when a browser-only API is called outside the browser."""
+
+
+class Api:
+    _js = ""
+    _server_default = None
+
+    def _call(self, method, *args):
+        raise BrowserUnavailable(
+            f"{type(self).__name__}.{method}() needs a browser; "
+            "guard with `if platform.web:` or move it into an event handler")
+
+
+class _KeyValue(Api):
+    _js = "localStorage"
+    _server_default = None
+
+    def __init__(self):
+        self._d: dict = {}
+
+    def __getitem__(self, k):
+        return self._d.get(k)
+
+    def __setitem__(self, k, v):
+        self._d[k] = v
+
+    def __delitem__(self, k):
+        del self._d[k]
+
+    def get(self, k, default=None):
+        return self._d.get(k, default)
+
+
+class _SessionStorage(_KeyValue):
+    _js = "sessionStorage"
+
+
+storage = _KeyValue()
+session = _SessionStorage()
+
+
+class _Clipboard(Api):
+    _js = "navigator.clipboard"
+
+    async def write(self, text: str) -> bool:
+        self._call("write", text)
+        return False
+
+    async def read(self) -> str:
+        self._call("read")
+        return ""
+
+
+clipboard = _Clipboard()
+
+
+class _GeoPosition(dict):
+    pass
+
+
+class _Location(Api):
+    _js = "navigator.geolocation"
+
+    async def current(self, *, timeout_ms=10000) -> dict:
+        self._call("current")
+        return {}
+
+    def watch(self, callback, *, timeout_ms=10000):
+        """Subscribe to position updates; returns an unsubscribe callable."""
+        self._call("watch", callback)
+        return lambda: None
+
+
+location = _Location()
+
+
+class _Notifications(Api):
+    _js = "Notification"
+
+    async def request_permission(self) -> str:
+        self._call("request_permission")
+        return "denied"
+
+    async def send(self, title: str, body="", *, tag="") -> bool:
+        self._call("send", title)
+        return False
+
+
+notifications = _Notifications()
+
+
+class _Camera(Api):
+    _js = "navigator.mediaDevices.getUserMedia"
+
+    async def photo(self, *, facing="user") -> bytes:
+        self._call("photo")
+        return b""
+
+
+camera = _Camera()
+
+
+class IDB(Api):
+    """Typed IndexedDB key-value store (offline persistence)."""
+
+    _js = "indexedDB"
+
+    def __init__(self, db_name="pyweb", store="kv"):
+        self._db_name = db_name
+        self._store = store
+        self._d: dict = {}
+
+    async def get(self, key, default=None):
+        try:
+            self._call("get", key)
+        except BrowserUnavailable:
+            return self._d.get(key, default)
+
+    async def set(self, key, value):
+        try:
+            self._call("set", key, value)
+        except BrowserUnavailable:
+            self._d[key] = value
+
+    async def delete(self, key):
+        try:
+            self._call("delete", key)
+        except BrowserUnavailable:
+            self._d.pop(key, None)
+
+
+idb = IDB()
+
+
+class _Fetch(Api):
+    _js = "fetch"
+
+    async def get(self, url: str, *, headers=None, timeout_s=30) -> dict:
+        return {"status": 0, "body": ""}
+
+    async def post(self, url: str, body=None, *, headers=None,
+                   timeout_s=30) -> dict:
+        return {"status": 0, "body": ""}
+
+
+fetch = _Fetch()
+
+
+class _Permissions(Api):
+    _js = "navigator.permissions"
+
+    async def query(self, name: str) -> str:
+        """'granted' | 'denied' | 'prompt' — 'denied' on server."""
+        return "denied"
+
+
+permissions = _Permissions()
+
+
+class _Vibrate(Api):
+    _js = "navigator.vibrate"
+
+    def pulse(self, pattern=200) -> bool:
+        return False  # no-op on server; real haptics in browser
+
+
+vibrate = _Vibrate()
+
+
+class _Share(Api):
+    _js = "navigator.share"
+
+    async def text(self, title: str, text: str, *, url="") -> bool:
+        self._call("text", title)
+        return False
+
+
+share = _Share()
+
+
+class _Bluetooth(Api):
+    _js = "navigator.bluetooth"
+
+    async def request_device(self, *, accept_all=False,
+                             services=()) -> dict:
+        self._call("request_device")
+        return {}
+
+
+bluetooth = _Bluetooth()
+
+
+class _FileSystem(Api):
+    _js = "showOpenFilePicker"
+
+    async def pick_text(self, *, types=("text/plain",)) -> str:
+        self._call("pick_text")
+        return ""
+
+
+filesystem = _FileSystem()
+
+
+def bindings() -> dict:
+    """Name -> JS binding for every browser API (used by codegen)."""
+    import sys as _sys
+    mod = _sys.modules[__name__]
+    out = {}
+    for name in dir(mod):
+        obj = getattr(mod, name)
+        js = getattr(obj, "_js", "")
+        if isinstance(obj, Api) and js:
+            out[name] = js
+    return out

pyweb/build.py

@@ -0,0 +1,295 @@
+"""Build: a self-contained, deployable ``dist/`` directory.
+
+```text
+dist/
+  app.pyweb                the app source (server functions + page bodies)
+  manifest.json            routes, assets, RPC table, byte sizes
+  Dockerfile               `pyweb serve` image
+  static/
+    runtime.<hash>.js      shared browser runtime (cached across pages)
+    <page>.<hash>.js       per-page code (pages without interactivity ship none)
+    <page>.<hash>.js.map   handler/signal → .pyweb line mapping
+    ...                    your app's own static/ folder, copied as-is
+  server/
+    <page>.html            static prerender (literal state) for static hosting
+```
+
+Content hashes give immutable caching: a deploy only invalidates what
+changed. The built-in minifier is token-aware (strings, templates and
+regex literals are never touched); plug in esbuild via ``minifier=``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+
+__all__ = ["build", "minify_js", "content_hash", "write_dockerfile"]
+
+
+def content_hash(text) -> str:
+    if isinstance(text, str):
+        text = text.encode()
+    return hashlib.sha256(text).hexdigest()[:12]
+
+
+_REGEX_PREV = set("(,=:[!&|?{};+-*%<>~^") | {""}
+_REGEX_KEYWORDS = {"return", "typeof", "case", "do", "else", "in", "of", "void", "throw", "new", "delete"}
+_PUNCT = set("{}()[];,:=<>!&|?+-*/%^~.")
+
+
+def minify_js(js: str, *, minifier=None) -> str:
+    """Minify JS safely: strip comments and collapse whitespace.
+
+    Token-aware: string literals, template literals and regex literals are
+    copied verbatim, so ``"Count: "`` or ``"https://x"`` are never altered.
+    Newlines are kept where removing one could change meaning (ASI).
+    An external ``minifier`` callable (e.g. esbuild) wins if given.
+    """
+    if minifier is not None:
+        return minifier(js)
+    out = []
+    i, n = 0, len(js)
+    last = ""          # last significant token text
+    pending_space = False
+    pending_newline = False
+
+    def emit(tok):
+        nonlocal last, pending_space, pending_newline
+        if out:
+            prev = out[-1][-1]
+            if pending_newline and not (prev in "{(,;[" or tok[0] in "}),;]." or tok[0] in "=:?"):
+                out.append("\n")
+            elif pending_space and (prev.isalnum() or prev in "_$") and (tok[0].isalnum() or tok[0] in "_$"):
+                out.append(" ")
+            elif pending_space and prev in "+-" and tok[0] == prev:
+                out.append(" ")
+        out.append(tok)
+        last = tok
+        pending_space = pending_newline = False
+
+    while i < n:
+        c = js[i]
+        if c in " \t\r":
+            pending_space = True
+            i += 1
+            continue
+        if c == "\n":
+            pending_newline = True
+            i += 1
+            continue
+        if js.startswith("//", i):
+            j = js.find("\n", i)
+            i = n if j < 0 else j
+            continue
+        if js.startswith("/*", i):
+            j = js.find("*/", i + 2)
+            i = n if j < 0 else j + 2
+            pending_space = True
+            continue
+        if c in "\"'":
+            j = i + 1
+            while j < n and js[j] != c:
+                j += 2 if js[j] == "\\" else 1
+            emit(js[i:j + 1])
+            i = j + 1
+            continue
+        if c == "`":
+            j = i + 1
+            depth = 0
+            while j < n:
+                if js[j] == "\\":
+                    j += 2
+                    continue
+                if js.startswith("${", j):
+                    depth += 1
+                    j += 2
+                    continue
+                if js[j] == "}" and depth:
+                    depth -= 1
+                elif js[j] == "`" and not depth:
+                    break
+                j += 1
+            emit(js[i:j + 1])
+            i = j + 1
+            continue
+        if c == "/" and (last[-1:] in _REGEX_PREV or last in _REGEX_KEYWORDS):
+            j = i + 1
+            in_class = False
+            while j < n:
+                ch = js[j]
+                if ch == "\\":
+                    j += 2
+                    continue
+                if ch == "[":
+                    in_class = True
+                elif ch == "]":
+                    in_class = False
+                elif ch == "/" and not in_class:
+                    break
+                j += 1
+            j += 1
+            while j < n and (js[j].isalpha()):
+                j += 1
+            emit(js[i:j])
+            i = j
+            continue
+        if c.isalnum() or c in "_$":
+            j = i
+            while j < n and (js[j].isalnum() or js[j] in "_$"):
+                j += 1
+            emit(js[i:j])
+            i = j
+            continue
+        emit(c)
+        i += 1
+    return "".join(out).strip() + "\n"
+
+
+def _gzip_size(text) -> int:
+    import gzip
+    return len(gzip.compress(text.encode() if isinstance(text, str) else text, 9))
+
+
+def build(compiled: dict, out: str, *, minifier=None, extract_css=True,
+          source=None, app_dir=None, production=True) -> dict:
+    """Write a deployable ``dist/`` for ``compile_source`` output.
+
+    ``production=True`` minifies and content-hashes JS; otherwise files
+    keep plain names (``Home.js``) and pages reference ``?v=<hash>``.
+    ``source`` (the `.pyweb` text) is copied to ``dist/app.pyweb`` so
+    ``pyweb serve dist`` can run ``@server`` functions and render pages.
+    A ``static/`` folder next to the app (``app_dir``) is copied as-is.
+    """
+    import shutil
+    from pyweb.css import extract_styles
+    os.makedirs(f"{out}/static", exist_ok=True)
+    os.makedirs(f"{out}/server", exist_ok=True)
+
+    if app_dir and os.path.isdir(os.path.join(app_dir, "static")):
+        shutil.copytree(os.path.join(app_dir, "static"), f"{out}/static", dirs_exist_ok=True)
+
+    rt_path = os.path.join(os.path.dirname(__file__), "runtime", "browser", "runtime.js")
+    with open(rt_path, encoding="utf-8") as fh:
+        runtime_js = fh.read()
+    if production:
+        runtime_js = minify_js(runtime_js, minifier=minifier)
+        rt_name = f"runtime.{content_hash(runtime_js)}.js"
+    else:
+        rt_name = "runtime.js"
+    with open(f"{out}/static/{rt_name}", "w", encoding="utf-8") as fh:
+        fh.write(runtime_js)
+
+    manifest_pages = {}
+    for name, page in compiled["pages"].items():
+        js = page.get("js", "")
+        html = page.get("html", "")
+        js_name = ""
+        body = ""
+        if js:
+            body = js.replace('from "./runtime.js"', f'from "./{rt_name}"')
+            if production:
+                body = minify_js(body, minifier=minifier)
+                js_name = f"{name}.{content_hash(body)}.js"
+                url = f"/static/{js_name}"
+            else:
+                js_name = f"{name}.js"
+                url = f"/static/{js_name}?v={content_hash(body)[:10]}"
+            with open(f"{out}/static/{js_name}", "w", encoding="utf-8") as fh:
+                fh.write(body)
+            with open(f"{out}/static/{js_name}.map", "w", encoding="utf-8") as fh:
+                json.dump({"page": name, "mappings": page.get("sourcemap", [])}, fh)
+            html = re.sub(r'src="/static/' + re.escape(name) + r'\.js\?v=[0-9a-f]+"', f'src="{url}"', html)
+        css_text = ""
+        if extract_css:
+            html, css_text = extract_styles(html)
+        css_name = ""
+        if css_text.strip():
+            css_name = f"{name}.{content_hash(css_text)}.css"
+            with open(f"{out}/static/{css_name}", "w", encoding="utf-8") as fh:
+                fh.write(css_text + "\n")
+            html = html.replace("</head>", f'<link rel="stylesheet" href="/static/{css_name}"></head>')
+        with open(f"{out}/server/{name}.html", "w", encoding="utf-8") as fh:
+            fh.write(html)
+        manifest_pages[name] = {
+            "route": page.get("route"), "js": js_name, "css": css_name,
+            "runtime": rt_name if js else "", "bytes": len(body.encode()),
+            "gzip_bytes": _gzip_size(body) if body else 0,
+            "dynamic": bool(page.get("dynamic")),
+            "signals": page.get("signals", []),
+            "computeds": list(page.get("computeds", []))}
+
+    npm = detect_npm(compiled)
+    if npm:
+        importmap = {"imports": {
+            name: f"https://esm.sh/{name}@{ver}" for name, ver in npm.items()}}
+        for name in compiled["pages"]:
+            shell = f"{out}/server/{name}.html"
+            with open(shell, encoding="utf-8") as fh:
+                html = fh.read()
+            tag = ('<script type="importmap">' + json.dumps(importmap) + "</script></head>")
+            with open(shell, "w", encoding="utf-8") as fh:
+                fh.write(html.replace("</head>", tag))
+    if source is not None:
+        with open(f"{out}/app.pyweb", "w", encoding="utf-8") as fh:
+            fh.write(source)
+    try:
+        from pyweb import __version__ as pyweb_version
+    except ImportError:  # pragma: no cover
+        pyweb_version = "unknown"
+    manifest = {"pyweb": pyweb_version, "pages": manifest_pages,
+                "rpc": compiled.get("rpc", []), "ir": compiled.get("ir_text", ""),
+                "runtime": rt_name, "runtime_bytes": len(runtime_js.encode()),
+                "runtime_gzip_bytes": _gzip_size(runtime_js),
+                "app": "app.pyweb" if source is not None else None, "npm": npm}
+    with open(f"{out}/manifest.json", "w", encoding="utf-8") as fh:
+        json.dump(manifest, fh, indent=2)
+    write_dockerfile(f"{out}/Dockerfile", version=pyweb_version)
+    return manifest
+
+
+def detect_npm(compiled: dict) -> dict:
+    """Collect ``{package: version}`` from ``package(\"name[@ver]\")`` calls
+    and ``from npm[.x] import ...`` lines in page sources.
+
+    The mapping flows into the SSR importmap and ``manifest["npm"]`` so
+    deployments pin exactly what the browser loads (default: latest).
+    """
+    def split_spec(spec):
+        # "@scope/name@ver" keeps its scope; "name@ver" splits once.
+        if spec.startswith("@"):
+            head, _, tail = spec[1:].partition("@")
+            name = "@" + head
+            ver = tail
+        else:
+            name, _, ver = spec.partition("@")
+        return name or spec, ver or "latest"
+
+    found: dict[str, str] = {}
+    for page in compiled.get("pages", {}).values():
+        src = page.get("source") or ""
+        for m in re.finditer(r"""package\(\s*['"]([^'"]+)['"]""", src):
+            name, ver = split_spec(m.group(1))
+            found.setdefault(name, ver)
+        for m in re.finditer(r"""from\s+npm\.([\w-]+)\s+import""", src):
+            found.setdefault(m.group(1), "latest")
+    return found
+
+
+def write_dockerfile(path: str, version: str = "") -> None:
+    """A minimal image that serves this dist with ``pyweb serve``."""
+    pin = f"=={version}" if version and version[0].isdigit() and "+" not in version else ""
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(
+            "FROM python:3.12-slim\n"
+            "WORKDIR /app\n"
+            f"RUN pip install --no-cache-dir pyweb-stack{pin}\n"
+            "COPY . /app/\n"
+            "RUN if [ -f requirements.txt ]; then pip install --no-cache-dir -r requirements.txt; fi\n"
+            "ENV PYWEB_ENV=production\n"
+            "EXPOSE 8000\n"
+            "HEALTHCHECK CMD python -c \"import urllib.request; "
+            "urllib.request.urlopen('http://127.0.0.1:8000/healthz')\"\n"
+            'CMD ["pyweb", "serve", ".", "--host", "0.0.0.0", "--port", "8000"]\n')