pyweb-stack 0.3.0__tar.gz → 0.4.0__tar.gz

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 MaanavKrishna and Claude
+Copyright (c) 2026 MaanavKrishna
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pyweb-stack
-Version: 0.3.0
+Version: 0.4.0
 Summary: Full-stack web apps in one Python file: server-rendered pages, reactive browser UI, typed RPC.
-Author-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>, Claude <noreply@anthropic.com>
+Author-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
 Maintainer-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
 License: MIT
 Project-URL: Homepage, https://maanavkrishna.github.io/PyWeb/
@@ -123,11 +123,20 @@ pyweb dev app.pyweb        # http://localhost:8000
 - **Boundaries are checked.** Database handles, imports and secrets can't
   leak into browser code: it's a compile error with a line number.
   `pyweb inspect` explains where every name runs and why.
+- **Pages that keep up.** `live(db, "select ...")` keeps page data in
+  step with the database in every open window; `@server` functions that
+  `yield` stream to the browser (AI replies included, with a Stop
+  button that really stops).
+- **Real multi-page apps.** Shared layouts that keep their state, links
+  that load without a full reload, typed query parameters, per-page
+  titles and social tags, error pages written in `.pyweb`.
+- **npm without Node.** `pyweb add chart.js/auto` vendors a package for
+  browser code; no `node_modules`, no bundler.
 - **Stateless servers.** Signed-cookie sessions and plain HTTP RPC scale
   horizontally behind any load balancer. Deploy with `pyweb serve`,
   uvicorn/gunicorn (ASGI) or the generated Dockerfile.
 
-A typical interactive page ships under 1 KB of page code plus a ~10 KB
+A typical interactive page ships under 1 KB of page code plus a ~14 KB
 (gzip) runtime that's cached across pages. Pages without interactivity
 ship no JavaScript.
 
@@ -137,9 +146,9 @@ ship no JavaScript.
 small SaaS products and content sites with interactive parts, built by
 people who'd rather stay in Python.
 
-**Not a fit:** large client-heavy single-page apps that need the npm
-ecosystem (use React/Svelte/Vue), or running scientific Python in the
-browser (use Pyodide/PyScript). See the
+**Not a fit:** large client-heavy single-page apps built around a
+JavaScript component framework (use React/Svelte/Vue), or running
+scientific Python in the browser (use Pyodide/PyScript). See the
 [comparison](https://maanavkrishna.github.io/PyWeb/introduction.html)
 and [current limitations](docs/16-limitations-roadmap.md).
 
@@ -168,10 +177,10 @@ See [AI assistants & MCP](docs/17-ai-assistants.md).
 | | |
 |---|---|
 | Start | [Introduction](docs/01-introduction.md) · [Quickstart](docs/02-quickstart.md) · [Tutorial](docs/03-tutorial.md) · [AI assistants & MCP](docs/17-ai-assistants.md) |
-| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) |
-| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Data](docs/09-data.md) · [Auth](docs/10-auth.md) |
+| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) · [npm packages](docs/18-npm-packages.md) |
+| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Layouts & navigation](docs/19-layouts-navigation.md) · [Data](docs/09-data.md) · [Live data](docs/21-live-data.md) · [Building AI apps](docs/20-ai-apps.md) · [Auth](docs/10-auth.md) |
 | Ship | [Testing](docs/11-testing.md) · [Deployment](docs/12-deployment.md) · [Security](docs/13-security.md) · [CLI](docs/14-cli.md) |
-| Reference | [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
+| Reference | [Recipe: wallets & web3](docs/22-recipe-web3.md) · [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
 
 The same docs are published at
 **[maanavkrishna.github.io/PyWeb](https://maanavkrishna.github.io/PyWeb/)**,
@@ -190,11 +199,15 @@ a real browser by the test suite.
 | [`auth`](examples/auth/app.pyweb) | registration, password hashing, sessions, protected pages |
 | [`chat`](examples/chat/app.pyweb) | route params, shared server state, live updates with `publish`/`subscribe` |
 | [`showcase`](examples/showcase/app.pyweb) | everything on one page, with a stylesheet |
+| [`site`](examples/site/app.pyweb) | a layout, client-side navigation, query parameters, page titles, a 404 page |
+| [`dashboard`](examples/dashboard/app.pyweb) | live queries and a Chart.js chart from npm, in every open window |
+| [`ai-chat`](examples/ai-chat/app.pyweb) | streaming AI replies with Stop and Markdown (Anthropic, OpenAI-compatible or a demo model) |
 
 ## Command line
 
 ```bash
-pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat)
+pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat|ai-chat)
+pyweb add chart.js/auto                          # an npm package for browser code (no Node.js)
 pyweb dev app.pyweb                              # dev server: live reload + error overlay
 pyweb inspect app.pyweb                          # where each name runs, and why
 pyweb check app.pyweb                            # compile + security checks for CI
@@ -218,9 +231,12 @@ and changes to them are announced in the [changelog](CHANGELOG.md) (see
 
 | Version | Highlights |
 |---|---|
+| 0.4 | npm packages without Node, layouts and client-side navigation, streaming server functions and `<Markdown>` for AI apps, live queries, page head tags, `.pyweb` error pages |
 | 0.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |
 | 0.2 | MCP server for AI assistants, AI guide, project templates, `AGENTS.md`/`CLAUDE.md`, `llms.txt` |
-| 0.1 | First public release: compiler, reactive runtime, server rendering, typed RPC, sessions, databases, CLI | The test suite covers the
+| 0.1 | First public release: compiler, reactive runtime, server rendering, typed RPC, sessions, databases, CLI |
+
+The test suite covers the
 parser, the Python→JavaScript translation (differentially, against
 CPython), the reactive runtime, server rendering, RPC, sessions, every
 example app in Chromium, and the database/Redis layers against real
@@ -228,7 +244,7 @@ Postgres, MySQL and Redis servers, on Python 3.10–3.13.
 
 ## Authors
 
-Built by [MaanavKrishna](https://github.com/MaanavKrishna) and Claude.
+Built by [MaanavKrishna](https://github.com/MaanavKrishna).
 
 ## Contributing
 

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/README.md

@@ -69,11 +69,20 @@ pyweb dev app.pyweb        # http://localhost:8000
 - **Boundaries are checked.** Database handles, imports and secrets can't
   leak into browser code: it's a compile error with a line number.
   `pyweb inspect` explains where every name runs and why.
+- **Pages that keep up.** `live(db, "select ...")` keeps page data in
+  step with the database in every open window; `@server` functions that
+  `yield` stream to the browser (AI replies included, with a Stop
+  button that really stops).
+- **Real multi-page apps.** Shared layouts that keep their state, links
+  that load without a full reload, typed query parameters, per-page
+  titles and social tags, error pages written in `.pyweb`.
+- **npm without Node.** `pyweb add chart.js/auto` vendors a package for
+  browser code; no `node_modules`, no bundler.
 - **Stateless servers.** Signed-cookie sessions and plain HTTP RPC scale
   horizontally behind any load balancer. Deploy with `pyweb serve`,
   uvicorn/gunicorn (ASGI) or the generated Dockerfile.
 
-A typical interactive page ships under 1 KB of page code plus a ~10 KB
+A typical interactive page ships under 1 KB of page code plus a ~14 KB
 (gzip) runtime that's cached across pages. Pages without interactivity
 ship no JavaScript.
 
@@ -83,9 +92,9 @@ ship no JavaScript.
 small SaaS products and content sites with interactive parts, built by
 people who'd rather stay in Python.
 
-**Not a fit:** large client-heavy single-page apps that need the npm
-ecosystem (use React/Svelte/Vue), or running scientific Python in the
-browser (use Pyodide/PyScript). See the
+**Not a fit:** large client-heavy single-page apps built around a
+JavaScript component framework (use React/Svelte/Vue), or running
+scientific Python in the browser (use Pyodide/PyScript). See the
 [comparison](https://maanavkrishna.github.io/PyWeb/introduction.html)
 and [current limitations](docs/16-limitations-roadmap.md).
 
@@ -114,10 +123,10 @@ See [AI assistants & MCP](docs/17-ai-assistants.md).
 | | |
 |---|---|
 | Start | [Introduction](docs/01-introduction.md) · [Quickstart](docs/02-quickstart.md) · [Tutorial](docs/03-tutorial.md) · [AI assistants & MCP](docs/17-ai-assistants.md) |
-| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) |
-| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Data](docs/09-data.md) · [Auth](docs/10-auth.md) |
+| Language | [`.pyweb` files](docs/04-pyweb-files.md) · [State & reactivity](docs/05-reactivity.md) · [Python in the browser](docs/07-browser-python.md) · [npm packages](docs/18-npm-packages.md) |
+| Server | [Server functions & RPC](docs/06-server-functions.md) · [Pages & routing](docs/08-pages-routing-assets.md) · [Layouts & navigation](docs/19-layouts-navigation.md) · [Data](docs/09-data.md) · [Live data](docs/21-live-data.md) · [Building AI apps](docs/20-ai-apps.md) · [Auth](docs/10-auth.md) |
 | Ship | [Testing](docs/11-testing.md) · [Deployment](docs/12-deployment.md) · [Security](docs/13-security.md) · [CLI](docs/14-cli.md) |
-| Reference | [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
+| Reference | [Recipe: wallets & web3](docs/22-recipe-web3.md) · [Toolkit & stability](docs/15-toolkit.md) · [Limitations & roadmap](docs/16-limitations-roadmap.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md) |
 
 The same docs are published at
 **[maanavkrishna.github.io/PyWeb](https://maanavkrishna.github.io/PyWeb/)**,
@@ -136,11 +145,15 @@ a real browser by the test suite.
 | [`auth`](examples/auth/app.pyweb) | registration, password hashing, sessions, protected pages |
 | [`chat`](examples/chat/app.pyweb) | route params, shared server state, live updates with `publish`/`subscribe` |
 | [`showcase`](examples/showcase/app.pyweb) | everything on one page, with a stylesheet |
+| [`site`](examples/site/app.pyweb) | a layout, client-side navigation, query parameters, page titles, a 404 page |
+| [`dashboard`](examples/dashboard/app.pyweb) | live queries and a Chart.js chart from npm, in every open window |
+| [`ai-chat`](examples/ai-chat/app.pyweb) | streaming AI replies with Stop and Markdown (Anthropic, OpenAI-compatible or a demo model) |
 
 ## Command line
 
 ```bash
-pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat)
+pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat|ai-chat)
+pyweb add chart.js/auto                          # an npm package for browser code (no Node.js)
 pyweb dev app.pyweb                              # dev server: live reload + error overlay
 pyweb inspect app.pyweb                          # where each name runs, and why
 pyweb check app.pyweb                            # compile + security checks for CI
@@ -164,9 +177,12 @@ and changes to them are announced in the [changelog](CHANGELOG.md) (see
 
 | Version | Highlights |
 |---|---|
+| 0.4 | npm packages without Node, layouts and client-side navigation, streaming server functions and `<Markdown>` for AI apps, live queries, page head tags, `.pyweb` error pages |
 | 0.3 | Hydration, live updates (SSE), multi-file apps, language server + VS Code extension, browser playground, faster rendering, screenshot/test MCP tools |
 | 0.2 | MCP server for AI assistants, AI guide, project templates, `AGENTS.md`/`CLAUDE.md`, `llms.txt` |
-| 0.1 | First public release: compiler, reactive runtime, server rendering, typed RPC, sessions, databases, CLI | The test suite covers the
+| 0.1 | First public release: compiler, reactive runtime, server rendering, typed RPC, sessions, databases, CLI |
+
+The test suite covers the
 parser, the Python→JavaScript translation (differentially, against
 CPython), the reactive runtime, server rendering, RPC, sessions, every
 example app in Chromium, and the database/Redis layers against real
@@ -174,7 +190,7 @@ Postgres, MySQL and Redis servers, on Python 3.10–3.13.
 
 ## Authors
 
-Built by [MaanavKrishna](https://github.com/MaanavKrishna) and Claude.
+Built by [MaanavKrishna](https://github.com/MaanavKrishna).
 
 ## Contributing
 

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyweb-stack"
-version = "0.3.0"
+version = "0.4.0"
 description = "Full-stack web apps in one Python file: server-rendered pages, reactive browser UI, typed RPC."
 readme = "README.md"
 license = { text = "MIT" }
@@ -12,7 +12,6 @@ requires-python = ">=3.10"
 dependencies = []
 authors = [
     { name = "MaanavKrishna", email = "67054795+MaanavKrishna@users.noreply.github.com" },
-    { name = "Claude", email = "noreply@anthropic.com" },
 ]
 maintainers = [{ name = "MaanavKrishna", email = "67054795+MaanavKrishna@users.noreply.github.com" }]
 keywords = ["web", "framework", "full-stack", "reactive", "rpc", "ssr", "compiler"]

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/pyweb/__init__.py

@@ -3,20 +3,24 @@
 from .app import App
 from .models import Email, Model
 from . import auth, cache, jobs, realtime, security, observability, forms, testing
-from . import sync, deploy, uploads, lsp, live
+from . import sync, deploy, uploads, lsp, livetable
 from . import browser as browser_api
 from . import build, css, plugins, platform
 from .jobs import task
-from .context import NotFound, redirect, request, session
+from .context import NotFound, head, redirect, request, session
 from .rpc import RPCError
 from .decorators import component, edge, server, worker
 from .realtime import channel, publish, subscribe
+from .packages import npm
+from .markdown import Markdown
+from .livedata import live
 
 __all__ = [
     "App",
     "request",
     "session",
     "redirect",
+    "head",
     "NotFound",
     "RPCError",
     "component",
@@ -26,6 +30,9 @@ __all__ = [
     "channel",
     "publish",
     "subscribe",
+    "npm",
+    "Markdown",
+    "live",
     "Email",
     "Model",
     "task",
@@ -38,7 +45,7 @@ __all__ = [
     "forms",
     "testing",
     "sync",
-    "live",
+    "livetable",
     "deploy",
     "uploads",
     "lsp",

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/pyweb/ai/guide.md

@@ -171,8 +171,36 @@ def Item(item_id: int):
 - Database: `from pyweb.db import connect; db = connect("sqlite:///app.db")`;
   `db.execute("select ... where id = ?", (x,)).dicts()`; always use `?`
   parameters; `with db.transaction(): ...`.
-- In handlers, navigate with `window.location.href = "/path"`.
-- Run code after load with a handler named `on_mount`.
+- Query parameters: page params not in the route come from the query
+  string, typed by annotation: `def Search(q: str = "", page: int = 1)`.
+  Missing required / bad values -> 400.
+- Layouts: `@app.layout` (or `@app.layout("/admin")`) on a function with
+  markup containing `{children}` once wraps every page under the prefix;
+  `@app.page(..., layout=None)` opts out. Links between pages load without
+  a full reload and keep the layout's state; mark nothing yourself: links
+  to the current page get `aria-current="page"` automatically.
+- In handlers, navigate with `navigate("/path")` (`from pyweb.browser import navigate`).
+- Head tags: `@app.page("/", title=..., description=..., image=...)`, or
+  `head(title=..., description=...)` in the page body (server). `App(base_url=...)`
+  adds canonical URLs.
+- Error pages: `@app.error(404)` on a page function taking `path` (and/or
+  `status`, `message`, `request_id`).
+- Run code after load with a handler named `on_mount`; stop timers in
+  `on_unmount` (runs when the user navigates away). React to a value
+  changing with `watch(lambda: value, handler)` in `on_mount`
+  (`from pyweb.browser import watch`).
+- Live data: `rows = live(db, "select ... where x = ?", (x,))` in a page
+  (`from pyweb import live`) renders the rows and keeps them current in
+  every open page when the tables are written through `pyweb.db`. No
+  publish/subscribe needed. Use `db.notify("table")` after writes made
+  outside `pyweb.db`. Keep live queries small (`LIMIT`).
+- Streaming (AI replies, progress): a `@server` function that `yield`s;
+  in an `async def` handler `stream = fn(...)` then
+  `async for piece in stream: ...`; `stream.cancel()` stops it (closes the
+  generator on the server). Show model output with `<Markdown text={reply} />`
+  (`from pyweb import Markdown`): safe, renders as it streams. Template:
+  `pyweb new NAME --template ai-chat`. Keep API keys in server code
+  (`os.environ`), never in page variables.
 - Live updates: in a server function `publish("room:1", data)`; in the
   page `feed = channel("room:1")` (runs on the server); in `on_mount`
   `subscribe(feed, handler)`, where `handler(message)` assigns page
@@ -192,7 +220,16 @@ JS globals are available directly: `window`, `document`, `localStorage`,
 
 Not supported in browser code: classes, imports, `with`, generators,
 walrus, `*args/**kwargs` parameters, slice assignment, keyword arguments to
-JS functions, server-only names. Move such code into `@server` functions.
+browser globals, server-only names. Move such code into `@server` functions.
+
+npm packages (no Node.js needed): run `pyweb add chart.js/auto` in the app
+folder (writes `pyweb.lock` and `static/vendor/`; commit both), then bind at
+module level with literal strings: `Chart = npm("chart.js/auto")`,
+`Gauge = npm("pkg", "Gauge")` (named export), `lib = npm("pkg", "*")` (whole
+module). Calling a class constructs it (`new`); keyword arguments become one
+options object. npm names work only in browser code (handlers, `on_mount`,
+lambdas), never directly in markup. Give libraries an element with
+`ref={el}` (declare `el = None`; it is set before `on_mount`).
 
 ## 8. Errors and fixes
 
@@ -207,11 +244,16 @@ JS functions, server-only names. Move such code into `@server` functions.
 | `unknown component <X>` | Define `def X(...)` with markup (capitalized) in this file, or import it: `from widgets import X`. |
 | `mismatched </tag>` / `is never closed` | Close every tag; void tags (`input`, `img`, `br`) need no close (`<input ... />`). |
 | `... is not supported in browser code` | Rewrite with supported constructs or move it to `@server`. |
+| `npm package 'x' isn't installed` | Run `pyweb add x` in the app folder (the folder with `pyweb.lock`). |
+| `uses X from npm(...), which only exists in the browser` | Use the package in a handler or `on_mount` and store the result in a page variable that markup shows. |
+| `layout ... has no {children}` | Put `{children}` exactly once in the layout's markup where pages go. |
+| `isn't a valid int` / `missing ?name=` (400) | Give the query parameter a default, or link with a valid value. |
+| `pyweb add`: `is CommonJS` / `imports the Node.js module` | Pick an ES-module browser package (e.g. `lodash-es`), or do the work in an `@server` function. |
 
 ## 9. Workflow for agents
 
 1. Start from a template: `pyweb new NAME --template todo` (or the
-   `pyweb_new_app` MCP tool). Templates: blank, counter, todo, blog, auth, chat.
+   `pyweb_new_app` MCP tool). Templates: blank, counter, todo, blog, auth, chat, ai-chat.
 2. Edit `app.pyweb`. After every edit run `pyweb check app.pyweb`
    (MCP: `pyweb_check`) and fix errors by line number.
 3. Use `pyweb inspect` (MCP: `pyweb_inspect`) to confirm what runs in the

pyweb_stack-0.4.0/pyweb/app.py

@@ -0,0 +1,78 @@
+"""Application object: page registry and configuration."""
+
+from __future__ import annotations
+
+
+class App:
+    """The app: its pages, layouts, error pages and site-wide settings.
+
+    ``base_url`` (e.g. ``"https://example.com"``) gives every page a
+    canonical URL and absolute social-card links; ``description`` and
+    ``image`` are the defaults for pages that don't set their own.
+    ``client_nav=False`` makes links do full page loads.
+    """
+
+    def __init__(self, database=None, cache=None, auth=None, plugins=(), *,
+                 title="PyWeb", stylesheets=(), lang="en", base_url=None, description=None,
+                 image=None, client_nav=True):
+        self.title = title
+        self.stylesheets = list(stylesheets)
+        self.lang = lang
+        self.base_url = base_url.rstrip("/") if base_url else None
+        self.description = description
+        self.image = image
+        self.client_nav = client_nav
+        self.database = database
+        self.cache = cache
+        self.auth = auth
+        self.pages: list[tuple[str, str, dict]] = []
+        self.layouts: list[tuple[str, str]] = []
+        self.errors: dict[int, str] = {}
+        from pyweb.plugins import Registry
+        self.plugins = Registry()
+        for plugin in plugins:
+            self.use(plugin)
+
+    def page(self, route, *, title=None, render="server", description=None, image=None, canonical=None,
+             noindex=False, layout=...):
+        """Register a page at ``route``. ``{name}`` segments and other parameters of the
+        function (from the query string) become its arguments."""
+        def deco(fn):
+            self.pages.append((route, fn.__name__, {"render": render, "title": title}))
+            fn.__pyweb_route__ = route
+            fn.__pyweb_title__ = title
+            fn.__pyweb_render__ = render
+            return fn
+
+        return deco
+
+    def layout(self, prefix="/"):
+        """Wrap every page under ``prefix`` in this function's markup (``{children}`` is the page).
+
+        Use as ``@app.layout`` or ``@app.layout("/admin")``.
+        """
+        if callable(prefix):
+            self.layouts.append(("/", prefix.__name__))
+            return prefix
+
+        def deco(fn):
+            self.layouts.append((prefix, fn.__name__))
+            return fn
+
+        return deco
+
+    def error(self, status, *, title=None, layout=...):
+        """Render this page for HTTP ``status`` (404, 500, ...) instead of the built-in one."""
+        def deco(fn):
+            self.errors[status] = fn.__name__
+            return fn
+
+        return deco
+
+    def use(self, plugin):
+        """Attach a :class:`pyweb.plugins.Plugin`; merges its routes."""
+        self.plugins.add(plugin)
+        for route, fn in plugin.routes:
+            self.pages.append((route, fn.__name__, {"render": "server",
+                                                   "plugin": plugin.name}))
+        return plugin

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/pyweb/app_loader.py

@@ -13,11 +13,12 @@ import inspect
 import os
 import sys
 import types
+import typing
 
 from .compiler import compile_source
 from .compiler import parser as P
 from .compiler.lower import is_ui_stmt
-from .context import NotFound, Redirect
+from .context import BadRequest, NotFound, Redirect, _page_head
 from .ssr import NS_KEY, Renderer, page_html
 
 STATE_PREFIX = "__pyweb_state_"
@@ -66,6 +67,7 @@ class LoadedApp:
         self.files += [lib.path for lib in self.libraries]
         infos = [p["info"] for p in self.compiled["pages"].values()]
         infos += list(self.compiled["components"].values())
+        infos += [lay["info"] for lay in self.compiled.get("layouts", {}).values()]
         self.module = self._exec(source, self.filename, infos)
         self.rpc = {}
         for spec in self.compiled["rpc"]:
@@ -80,6 +82,9 @@ class LoadedApp:
         app_obj = next((v for v in self.module.__dict__.values()
                         if type(v).__name__ == "App" and type(v).__module__.startswith("pyweb")), None)
         self.app = app_obj
+        if self.ctx.live_names or any(lib.ctx.live_names for lib in self.libraries):
+            from . import livedata
+            livedata.enable()            # announce table writes from this process, even before a live() call
         self.title = getattr(app_obj, "title", None) or "PyWeb"
         self.stylesheets = list(getattr(app_obj, "stylesheets", []) or []) + self.extra_stylesheets
         self.lang = getattr(app_obj, "lang", "en") or "en"
@@ -123,48 +128,152 @@ class LoadedApp:
         env[NS_KEY] = ctx
         return info.ui, env
 
-    def renderer(self):
-        return Renderer(self.module.__dict__, component_state=self._component_state, strict=True)
+    def renderer(self, path=None):
+        return Renderer(self.module.__dict__, component_state=self._component_state, strict=True, path=path)
 
-    def coerce_params(self, page_name, raw):
+    def coerce_params(self, page_name, raw, query=None):
+        """Arguments for page ``page_name``: route segments from ``raw`` (bad values are a 404) and,
+        when ``query`` (``{name: [values]}``) is given, the other parameters from the query string
+        (missing or bad values are a 400)."""
         fn = self.module.__dict__[STATE_PREFIX + page_name]
         out = {}
         for pname, param in inspect.signature(fn).parameters.items():
-            if pname not in raw:
-                continue
             ann = param.annotation
-            value = raw[pname]
-            try:
-                if ann in (int, "int"):
-                    value = int(value)
-                elif ann in (float, "float"):
-                    value = float(value)
-            except ValueError:
-                raise NotFound(f"{pname}={value!r}") from None
-            out[pname] = value
+            if pname in raw:
+                try:
+                    out[pname] = _convert(raw[pname], ann)
+                except ValueError:
+                    raise NotFound(f"{pname}={raw[pname]!r}") from None
+            elif query is not None and pname in query:
+                values = query[pname]
+                try:
+                    out[pname] = [_convert(v, _item_type(ann)) for v in values] if _is_list(ann) \
+                        else _convert(values[-1], ann)
+                except ValueError:
+                    raise BadRequest(f"?{pname}={values[-1]!r} isn't a valid {_type_name(ann)}") from None
+            elif query is not None and param.default is inspect.Parameter.empty:
+                raise BadRequest(f"missing ?{pname}=")
         return out
 
-    def render(self, page_name, params=None):
-        """Return ``html`` (str) or a :class:`~pyweb.context.Redirect`."""
-        page = self.compiled["pages"][page_name]
-        info = page["info"]
-        fn = self.module.__dict__[STATE_PREFIX + page_name]
-        args = self.coerce_params(page_name, params or {})
-        result = fn(**args)
+    def _layout(self, name, renderer):
+        """Run layout ``name``; returns its page_html entry or a Redirect."""
+        lay = self.compiled["layouts"][name]
+        fn = self.module.__dict__[STATE_PREFIX + name]
+        result = fn(**({"children": None} if "children" in inspect.signature(fn).parameters else {}))
         if isinstance(result, Redirect):
             return result
-        if not isinstance(result, dict):
-            raise TypeError(f"page {page_name}() returned {type(result).__name__}; pages may only "
-                            "return redirect(...)")
         env = dict(result)
-        body = self.renderer().render(info.ui, env)
-        state = {k: env.get(k) for k in info.sent}
+        js_url = (self.asset_urls.get(name) or lay["js_url"]) if lay["js"] else None
+        return {"name": name, "body": renderer.render(lay["info"].ui, env), "js_url": js_url,
+                "state": _state(lay["info"], env), "version": lay["version"]}
+
+    def render(self, page_name, params=None, *, query=None, path=None, extra=None):
+        """Return ``html`` (str) or a :class:`~pyweb.context.Redirect`.
+
+        ``params`` are route segments, ``query`` the parsed query string
+        (``{name: [values]}``), ``path`` the request path (for canonical URLs
+        and marking current links), ``extra`` values offered to parameters of
+        the same name without conversion (error pages get ``status``, ``path``,
+        ``message``).
+        """
+        page = self.compiled["pages"][page_name]
+        info = page["info"]
+        fn = self.module.__dict__[STATE_PREFIX + page_name]
+        token = _page_head.set({})
+        try:
+            args = self.coerce_params(page_name, params or {}, query)
+            if extra:
+                wanted = inspect.signature(fn).parameters
+                args.update({k: v for k, v in extra.items() if k in wanted and k not in args})
+            renderer = self.renderer(path)
+            layouts = []
+            for name in page.get("layouts") or ():
+                entry = self._layout(name, renderer)
+                if isinstance(entry, Redirect):
+                    return entry
+                layouts.append(entry)
+            result = fn(**args)
+            if isinstance(result, Redirect):
+                return result
+            if not isinstance(result, dict):
+                raise TypeError(f"page {page_name}() returned {type(result).__name__}; pages may only "
+                                "return redirect(...)")
+            env = dict(result)
+            body = renderer.render(info.ui, env)
+            dynamic = _page_head.get()
+        finally:
+            _page_head.reset(token)
+        state = _state(info, env)
         js_url = self.asset_urls.get(page_name)
         if js_url is None and page["js"]:
             js_url = page["js_url"]
         title = info.title or self.title
         if callable(getattr(self.app, "title_for", None)):
             title = self.app.title_for(page_name) or title
+        title = dynamic.pop("title", None) or title
+        importmap = dict(page.get("importmap") or {})
         return page_html(name=page_name, title=title, body=body, state=state,
                          js_url=js_url if page["js"] else None, css_urls=self.stylesheets,
-                         lang=self.lang)
+                         lang=self.lang, importmap=importmap, layouts=layouts,
+                         head=self.head_for(page, dynamic, path),
+                         nav=getattr(self.app, "client_nav", True) is not False)
+
+    def head_for(self, page, dynamic, path):
+        """Description, image and canonical URL: the page's own, then ``head()`` values, then the app's."""
+        app = self.app
+        base = getattr(app, "base_url", None)
+        out = {"description": getattr(app, "description", None), "image": getattr(app, "image", None)}
+        out.update(page.get("head") or {})
+        out.update(dynamic)
+        canonical = out.get("canonical")
+        if canonical is None and base and path and not page.get("error_status"):
+            canonical = path
+        if canonical is False:
+            canonical = None
+        for key, value in (("canonical", canonical), ("image", out.get("image"))):
+            if isinstance(value, str) and value.startswith("/") and base:
+                value = base + value
+            out[key] = value
+        return {k: v for k, v in out.items() if v not in (None, False, "")}
+
+
+def _state(info, env):
+    """What the browser gets for a page or layout: its sent variables, plus how to follow live queries."""
+    state = {k: env.get(k) for k in info.sent}
+    for k in info.sent:
+        meta = getattr(env.get(k), "live", None)
+        if isinstance(meta, dict):
+            state["$live:" + k] = meta
+    return state
+
+
+def _is_list(ann):
+    return ann is list or typing.get_origin(ann) is list or (isinstance(ann, str) and ann.startswith("list"))
+
+
+def _item_type(ann):
+    if isinstance(ann, str):
+        inner = ann[5:-1] if ann.startswith("list[") else "str"
+        return inner
+    args = typing.get_args(ann)
+    return args[0] if args else str
+
+
+def _type_name(ann):
+    return ann if isinstance(ann, str) else getattr(ann, "__name__", str(ann))
+
+
+def _convert(value, ann):
+    """A route or query-string value as the parameter's annotated type (ValueError if it isn't one)."""
+    if ann in (int, "int"):
+        return int(value)
+    if ann in (float, "float"):
+        return float(value)
+    if ann in (bool, "bool"):
+        low = str(value).strip().lower()
+        if low in ("1", "true", "yes", "on", ""):
+            return True
+        if low in ("0", "false", "no", "off"):
+            return False
+        raise ValueError(value)
+    return value

{pyweb_stack-0.3.0 → pyweb_stack-0.4.0}/pyweb/asgi.py

@@ -83,7 +83,7 @@ def create_app(target="app.pyweb", *, debug=False, max_body=1_048_576, **server_
             status, hdrs, body = await asyncio.to_thread(
                 site.respond, scope.get("method", "GET"), path, headers, b"".join(chunks))
         raw_headers = [(k.lower().encode("latin-1"), v.encode("latin-1")) for k, v in hdrs]
-        if hasattr(body, "aiter"):  # Server-Sent Events
+        if hasattr(body, "aiter"):  # Server-Sent Events, streamed RPC results
             await send({"type": "http.response.start", "status": status, "headers": raw_headers})
             await _stream(body, receive, send)
             return