pyweb-stack 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyweb/_templates.py +15 -0
- pyweb/ai/docs/01-introduction.md +4 -0
- pyweb/ai/docs/02-quickstart.md +13 -1
- pyweb/ai/docs/14-cli.md +46 -7
- pyweb/ai/docs/16-limitations-roadmap.md +12 -4
- pyweb/ai/docs/17-ai-assistants.md +22 -1
- pyweb/ai/docs/27-upgrading.md +1 -0
- pyweb/ai/docs/29-performance.md +11 -1
- pyweb/ai/docs/35-dev-loop.md +151 -0
- pyweb/ai/docs/THREAT_MODEL.md +15 -0
- pyweb/app_loader.py +53 -9
- pyweb/assist.py +394 -0
- pyweb/bench.py +68 -1
- pyweb/cli/__init__.py +354 -45
- pyweb/compiler/diskcache.py +72 -0
- pyweb/compiler/errors.py +195 -1
- pyweb/compiler/lower.py +12 -3
- pyweb/compiler/parser.py +56 -0
- pyweb/compiler/pipeline.py +64 -2
- pyweb/compiler/pyjs.py +17 -3
- pyweb/devlink.py +37 -3
- pyweb/devopen.py +92 -0
- pyweb/doctor.py +303 -0
- pyweb/hosting.py +4 -3
- pyweb/lsp_ui.py +19 -2
- pyweb/mcp.py +92 -49
- pyweb/mcp_tools.py +22 -0
- pyweb/qr.py +273 -0
- pyweb/runtime/browser/dev/assist.js +156 -0
- pyweb/runtime/browser/dev/inspect.js +138 -0
- pyweb/runtime/browser/dev/reload.js +180 -0
- pyweb/runtime/browser/dev/timeline.js +144 -0
- pyweb/runtime/browser/dev/welcome.js +46 -0
- pyweb/runtime/browser/runtime.js +6 -4
- pyweb/runtime/server/__init__.py +4 -2
- pyweb/share.py +172 -0
- pyweb/telemetry/devtools.py +4 -1
- pyweb/ui/extending.py +7 -0
- pyweb/upgrade.py +12 -1
- {pyweb_stack-0.6.0.dist-info → pyweb_stack-0.6.2.dist-info}/METADATA +15 -4
- {pyweb_stack-0.6.0.dist-info → pyweb_stack-0.6.2.dist-info}/RECORD +45 -33
- {pyweb_stack-0.6.0.dist-info → pyweb_stack-0.6.2.dist-info}/WHEEL +0 -0
- {pyweb_stack-0.6.0.dist-info → pyweb_stack-0.6.2.dist-info}/entry_points.txt +0 -0
- {pyweb_stack-0.6.0.dist-info → pyweb_stack-0.6.2.dist-info}/licenses/LICENSE +0 -0
- {pyweb_stack-0.6.0.dist-info → pyweb_stack-0.6.2.dist-info}/top_level.txt +0 -0
pyweb/_templates.py
CHANGED
|
@@ -1,3 +1,18 @@
|
|
|
1
1
|
"""The `pyweb new` template names (kept apart so the CLI can list them without loading the MCP server)."""
|
|
2
2
|
|
|
3
3
|
TEMPLATES = ("blank", "counter", "todo", "blog", "saas", "auth", "chat", "ai-chat", "desktop")
|
|
4
|
+
|
|
5
|
+
# The colour presets `pyweb new --theme` offers (pyweb.ui.theme.PRESETS has their values; a test keeps the two in step).
|
|
6
|
+
THEME_PRESETS = ("indigo", "zinc", "slate", "rose", "ocean", "violet", "emerald", "amber")
|
|
7
|
+
|
|
8
|
+
DESCRIPTIONS = {
|
|
9
|
+
"blank": "one empty page",
|
|
10
|
+
"counter": "a page with a button: the smallest app with state",
|
|
11
|
+
"todo": "a list you add to and tick off, with the UI kit",
|
|
12
|
+
"blog": "pages with routes, a database and server functions",
|
|
13
|
+
"saas": "teams, sign-in, data, background jobs and an admin",
|
|
14
|
+
"auth": "accounts: sign up, sign in, passkeys",
|
|
15
|
+
"chat": "a live chat room (realtime)",
|
|
16
|
+
"ai-chat": "a streaming chat with an AI model",
|
|
17
|
+
"desktop": "a notes app in its own window",
|
|
18
|
+
}
|
pyweb/ai/docs/01-introduction.md
CHANGED
|
@@ -43,6 +43,10 @@ Around that core, PyWeb has what a product needs, in the same file:
|
|
|
43
43
|
([Installable apps](31-pwa-push.md), [Desktop apps](32-desktop.md))
|
|
44
44
|
- **Webhooks and files**: signed webhooks in and out, and unused uploads
|
|
45
45
|
cleaned up. ([Webhooks & files](33-webhooks-files.md))
|
|
46
|
+
- **A dev loop that keeps up**: saves update the open page in place with
|
|
47
|
+
its state kept; Alt-click opens any element's source; Fix with AI and
|
|
48
|
+
Edit with AI; a time-travel timeline; `pyweb dev --share`.
|
|
49
|
+
([The dev loop](35-dev-loop.md))
|
|
46
50
|
- **Shipping**: `pyweb deploy` writes Docker, Compose, Kubernetes, Fly,
|
|
47
51
|
Render or Railway files; logs, metrics and traces come built in.
|
|
48
52
|
([Scaling & deploying](25-scaling.md))
|
pyweb/ai/docs/02-quickstart.md
CHANGED
|
@@ -20,9 +20,14 @@ pip install "pyweb-stack[all]" # optional: Postgres, MySQL, Redis, argon2, O
|
|
|
20
20
|
```bash
|
|
21
21
|
pyweb new hello
|
|
22
22
|
cd hello
|
|
23
|
-
pyweb dev app.pyweb # http://localhost:8000
|
|
23
|
+
pyweb dev app.pyweb # opens http://localhost:8000; saves update the page in place
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
+
(`pyweb new` with no name asks for one, a starter and colours.) Save a
|
|
27
|
+
change and the open page updates without losing its state; hold Alt and
|
|
28
|
+
click anything to open its line in your editor. [The dev loop](35-dev-loop.md)
|
|
29
|
+
has the rest: Fix with AI, time travel and sharing with `--share`.
|
|
30
|
+
|
|
26
31
|
`pyweb new` writes `app.pyweb`, a starter test (`test_app.py`) and
|
|
27
32
|
`AGENTS.md`/`CLAUDE.md` (instructions for AI coding agents). Add
|
|
28
33
|
`--template saas` for a small product with teams, accounts, a database,
|
|
@@ -88,6 +93,12 @@ pyweb serve dist # production server with /healthz
|
|
|
88
93
|
`dist/` contains your app source, static assets and a `Dockerfile`; see
|
|
89
94
|
[Deployment](12-deployment.md).
|
|
90
95
|
|
|
96
|
+
If something doesn't work and the error isn't clear, `pyweb doctor`
|
|
97
|
+
checks the project and your machine (Python, the app, optional packages,
|
|
98
|
+
the database and migrations, the port, your editor) and prints a fix for
|
|
99
|
+
each problem; `pyweb doctor --production` also checks the production
|
|
100
|
+
settings.
|
|
101
|
+
|
|
91
102
|
## Next
|
|
92
103
|
|
|
93
104
|
The [tutorial](03-tutorial.md) builds a notes app with a database,
|
|
@@ -101,6 +112,7 @@ ships it. Then, depending on what you're building:
|
|
|
101
112
|
- work that runs later or on a schedule: [Background jobs](24-jobs.md);
|
|
102
113
|
- teams that share data: [Teams & organizations](30-teams.md);
|
|
103
114
|
- components, a theme and animation: [UI kit & motion](34-ui-and-motion.md);
|
|
115
|
+
- everything `pyweb dev` does for you: [The dev loop](35-dev-loop.md);
|
|
104
116
|
- an app people install, or a desktop app: [Installable apps & push](31-pwa-push.md),
|
|
105
117
|
[Desktop apps](32-desktop.md);
|
|
106
118
|
- several pages with a shared header: [Layouts & navigation](19-layouts-navigation.md);
|
pyweb/ai/docs/14-cli.md
CHANGED
|
@@ -1,17 +1,30 @@
|
|
|
1
1
|
# Command line
|
|
2
2
|
|
|
3
3
|
```text
|
|
4
|
-
pyweb new NAME [--template T]
|
|
4
|
+
pyweb new [NAME] [--template T] [--theme PRESET]
|
|
5
|
+
create NAME/ with app.pyweb, test_app.py, AGENTS.md, CLAUDE.md, static/;
|
|
5
6
|
T = blank | counter (default) | todo | blog | saas | auth | chat | ai-chat | desktop
|
|
6
|
-
(apps with a database also get migrations/0001_initial.py and a README)
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
(apps with a database also get migrations/0001_initial.py and a README);
|
|
8
|
+
PRESET = indigo | zinc | slate | rose | ocean | violet | emerald | amber
|
|
9
|
+
(written into App(theme=...)); with no NAME, in a terminal, it asks
|
|
10
|
+
pyweb dev FILE [--port 8000] [--host 127.0.0.1] [--no-reload] [--no-open] [--share]
|
|
11
|
+
development server (see The dev loop): saves update the open page
|
|
12
|
+
in place, keeping page and component state (?fresh starts over);
|
|
13
|
+
Alt-click opens an element's line in your editor, Alt+Shift-click
|
|
14
|
+
changes it with AI, error pages have Fix with AI; the dev toolbar
|
|
15
|
+
(requests, SQL, jobs, emails, theme, motion, a time-travel timeline);
|
|
16
|
+
background jobs in the same process; opens the browser (not in CI,
|
|
17
|
+
over SSH or with --no-open); --host 0.0.0.0 prints the network URL
|
|
18
|
+
with a QR code; --share prints a temporary public link; writes
|
|
11
19
|
.pyweb/dev.json so `pyweb mcp` can see its errors and logs
|
|
12
20
|
pyweb check FILE [--production] [--strict]
|
|
13
21
|
compile, security and accessibility checks; --production also checks
|
|
14
22
|
the environment; --strict fails on warnings too
|
|
23
|
+
pyweb doctor [FILE] [--production] [--json] [--port 8000]
|
|
24
|
+
is the project ready? Python, the app compiles, optional packages,
|
|
25
|
+
database and migrations, Redis, secrets in the source, upgrade
|
|
26
|
+
changes, a stale dev server link, tests, the port, the editor; a fix
|
|
27
|
+
for each problem (exit 1 on any failure; --json for CI)
|
|
15
28
|
pyweb upgrade [FILE] [--fix] what to change for this PyWeb version (file and line); --fix applies
|
|
16
29
|
the safe rewrites
|
|
17
30
|
pyweb inspect FILE [--security] where every name runs and why; RPC table; findings
|
|
@@ -66,13 +79,39 @@ pyweb dts FILE.d.ts Python dataclasses from TypeScript declarat
|
|
|
66
79
|
pyweb mcp MCP server over stdio for AI assistants (see AI assistants & MCP)
|
|
67
80
|
pyweb mcp --http [--port 8765] [--token T] the same over Streamable HTTP (127.0.0.1 only without a token)
|
|
68
81
|
pyweb lsp language server over stdio for editors (see below)
|
|
69
|
-
pyweb test [PATH] run pytest
|
|
82
|
+
pyweb test [PATH] run pytest on PATH (a test file, a folder or app.pyweb's folder;
|
|
83
|
+
default: the current folder, where new apps keep test_app.py)
|
|
70
84
|
pyweb fmt [PATH] / pyweb lint [PATH] run ruff format / ruff check (if installed)
|
|
71
85
|
pyweb --version
|
|
72
86
|
```
|
|
73
87
|
|
|
74
88
|
`python -m pyweb.cli ...` is equivalent to `pyweb ...`.
|
|
75
89
|
|
|
90
|
+
## Error messages
|
|
91
|
+
|
|
92
|
+
A compile error names the file and line, shows the line with a caret under
|
|
93
|
+
the problem, suggests the name you probably meant, and links the docs page
|
|
94
|
+
that explains it:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
error: app.pyweb:17: <Greeting> has no prop 'nme'; did you mean 'name'?
|
|
98
|
+
|
|
99
|
+
16 | <h1>{count}</h1>
|
|
100
|
+
> 17 | <Greeting nme="x" />
|
|
101
|
+
| ^
|
|
102
|
+
18 | </main>
|
|
103
|
+
|
|
104
|
+
hint: Use one of the component's parameter names as the attribute.
|
|
105
|
+
docs: https://maanavkrishna.github.io/PyWeb/language.html
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The first line keeps the `file:line: message` shape, so editors and CI
|
|
109
|
+
logs can jump to it. `pyweb check` also warns about kit props and motion
|
|
110
|
+
values that won't work (`<Button variant="outlin">`). The `pyweb dev`
|
|
111
|
+
overlay shows the same, and when page code raises, its error page starts
|
|
112
|
+
with the frames in your own files and their source lines, before the full
|
|
113
|
+
traceback.
|
|
114
|
+
|
|
76
115
|
## Exit codes
|
|
77
116
|
|
|
78
117
|
`check` and `build` exit `1` on compile or security errors and `2` on
|
|
@@ -11,8 +11,9 @@ can decide up front whether they matter for your app.
|
|
|
11
11
|
- **npm packages must ship ES modules.** CommonJS-only packages and
|
|
12
12
|
packages built on Node.js modules can't run in the browser; see
|
|
13
13
|
[npm packages](18-npm-packages.md).
|
|
14
|
-
- **
|
|
15
|
-
|
|
14
|
+
- **Time travel moves the page's state only.** The dev timeline puts the
|
|
15
|
+
page's and components' variables back; data on the server isn't
|
|
16
|
+
rolled back.
|
|
16
17
|
- **SQLite is for one machine.** Several processes on one host share it
|
|
17
18
|
fine, but more than one server needs Postgres or MySQL;
|
|
18
19
|
`pyweb check --production` and `pyweb deploy` say so.
|
|
@@ -33,7 +34,13 @@ can decide up front whether they matter for your app.
|
|
|
33
34
|
with Web Push, desktop windows and installers, a UI kit with themes and
|
|
34
35
|
motion, Trusted Types, encrypted fields and a threat model, about 2.5×
|
|
35
36
|
faster serving, Python 3.15 and free-threaded builds, and a much richer
|
|
36
|
-
MCP server.
|
|
37
|
+
MCP server. 0.6.1 added error messages with code frames and
|
|
38
|
+
suggestions, `pyweb doctor`, dev reloads that keep page state, and 4×
|
|
39
|
+
faster reloads and tests. 0.6.2 made the [dev loop](35-dev-loop.md):
|
|
40
|
+
saves update the page in place with component state kept, Alt-click
|
|
41
|
+
opens any element's source, Fix with AI and Edit with AI, a
|
|
42
|
+
time-travel timeline, `pyweb dev --share`, a faster first start and a
|
|
43
|
+
guided `pyweb new`.
|
|
37
44
|
- **0.5**: production apps. Models with relations and migrations, forms
|
|
38
45
|
checked in the browser and on the server, an auth kit (passwords,
|
|
39
46
|
passkeys, emailed links, OAuth, two-step sign-in, an admin), row-level
|
|
@@ -64,7 +71,8 @@ Planned, roughly in order. Nothing here is promised for a date.
|
|
|
64
71
|
1. **1.0**: the API, RPC protocol and CLI frozen under semantic versioning,
|
|
65
72
|
after 0.6 has been used in production for a while.
|
|
66
73
|
2. **File uploads from the playground and the admin.**
|
|
67
|
-
3. **
|
|
74
|
+
3. **Fix with AI in the editor**, from the same proposals the dev page
|
|
75
|
+
shows (diff, apply, undo), through the VS Code extension.
|
|
68
76
|
|
|
69
77
|
Ideas, bug reports and pull requests are welcome; see
|
|
70
78
|
[CONTRIBUTING.md](https://github.com/MaanavKrishna/PyWeb/blob/main/CONTRIBUTING.md).
|
|
@@ -70,7 +70,7 @@ tool runs. Slow tools (tests, screenshots, profiling) report progress.
|
|
|
70
70
|
| `pyweb_guide` | The rules for writing `.pyweb` apps (or one section): what runs where, state, markup, components, server functions, the browser Python subset, and every common error with its fix. |
|
|
71
71
|
| `pyweb_docs` | Searches the documentation (every page, the guide and the threat model) and returns the matching sections, or one whole page. For any "how do I..." question. |
|
|
72
72
|
| `pyweb_new_app` | Creates an app from a template (`blank`, `counter`, `todo`, `blog`, `saas`, `auth`, `chat`, `ai-chat`, `desktop`) with `AGENTS.md`, `CLAUDE.md`, tests and a stylesheet; apps with a database also get their first migration. `saas` (teams, accounts, tenant Models, forms, live pages, jobs, webhooks, admin) is the best start for a product; `desktop` is a notes app for `pyweb desktop`. |
|
|
73
|
-
| `pyweb_check` | Compiles the app and runs the security and accessibility checks. Returns `ok`, errors with `line`, `message
|
|
73
|
+
| `pyweb_check` | Compiles the app and runs the security and accessibility checks. Returns `ok`, errors with `line`, `message`, a fix `hint`, a code `frame` and a `docs` link, plus pages (with their layouts, live-data variables and npm packages), signals, what's sent to the browser, JS size and the server functions. |
|
|
74
74
|
| `pyweb_explain` | What your editor shows for a line: for each name, where it runs and why (or its signature or npm type), the problems on that line and, with `complete`, the completions at a column. |
|
|
75
75
|
| `pyweb_inspect` | For every name: does it run in the browser or on the server, and why. |
|
|
76
76
|
| `pyweb_compiled` | The JavaScript generated for a page, and its server-rendered HTML. |
|
|
@@ -106,7 +106,9 @@ tool runs. Slow tools (tests, screenshots, profiling) report progress.
|
|
|
106
106
|
| Tool | What it does |
|
|
107
107
|
|---|---|
|
|
108
108
|
| `pyweb_dev` | Whether `pyweb dev` is running for this app: its URL, whether the app compiles right now (with the error and traceback), its pages and recent 500 errors. |
|
|
109
|
+
| `pyweb_doctor` | Project health, as `pyweb doctor`: each check with `status` (ok, warn, fail), `detail` and a `fix`; `production=true` adds the production settings. |
|
|
109
110
|
| `pyweb_logs` | The dev server's log lines (warnings, errors with tracebacks, slow queries, job failures); `since` returns only newer ones. |
|
|
111
|
+
| `pyweb_assist_requests` | What the developer asked for from the page (Fix with AI on an error page, Alt+Shift-click → Edit with AI) while no AI was set up to answer: the file, the error or the element's line, and the instruction. |
|
|
110
112
|
|
|
111
113
|
When `pyweb dev` starts, it writes `.pyweb/dev.json` next to the app: its
|
|
112
114
|
address and a random token, readable only by you (the folder has its own
|
|
@@ -148,6 +150,7 @@ Prompts are step-by-step workflows that name the tools to use:
|
|
|
148
150
|
| `design_pass` | Kit components, a theme and motion, reviewed in light, dark and on a phone. |
|
|
149
151
|
| `fix_failing_test` | Reproduce, find the cause in the app, fix, re-run. |
|
|
150
152
|
| `debug_page` | Errors, logs, requests and a profile for one page. |
|
|
153
|
+
| `fix_errors` | Check, fix and test in a loop until the app compiles cleanly and the tests pass; first does what was asked from the page. |
|
|
151
154
|
|
|
152
155
|
### What a session looks like
|
|
153
156
|
|
|
@@ -171,6 +174,24 @@ Prompts are step-by-step workflows that name the tools to use:
|
|
|
171
174
|
click around, the assistant reads the error with `pyweb_dev` and
|
|
172
175
|
`pyweb_logs` and fixes it.
|
|
173
176
|
|
|
177
|
+
### Fix with AI from the page (sampling)
|
|
178
|
+
|
|
179
|
+
`pyweb dev` puts a **Fix with AI** button on error pages, and
|
|
180
|
+
Alt+Shift-click asks for a change to any element (see
|
|
181
|
+
[The dev loop](35-dev-loop.md#fix-with-ai-and-edit-with-ai)). When your
|
|
182
|
+
assistant's app supports MCP **sampling** (the client lets a server ask
|
|
183
|
+
its model a question, after you approve), `pyweb mcp` answers those
|
|
184
|
+
requests with your assistant's own model: it notices the client offers
|
|
185
|
+
sampling when it connects, finds the running `pyweb dev` through
|
|
186
|
+
`.pyweb/dev.json`, and hands each request over. The page shows the
|
|
187
|
+
answer as a diff to apply or discard. This works over stdio (`pyweb
|
|
188
|
+
mcp`); set `PYWEB_APP` when the app file isn't `app.pyweb` in the folder
|
|
189
|
+
the assistant starts in.
|
|
190
|
+
|
|
191
|
+
Assistants without sampling see the same requests with
|
|
192
|
+
`pyweb_assist_requests` and can do them with their own file tools; the
|
|
193
|
+
`fix_errors` prompt starts there.
|
|
194
|
+
|
|
174
195
|
`pyweb_render`, `pyweb_call`, `pyweb_screenshot`, `pyweb_review`,
|
|
175
196
|
`pyweb_profile`, `pyweb_webhook_send`, `pyweb_jobs` and `pyweb_test` run
|
|
176
197
|
your app's code, as `pyweb dev` or `pytest` would; `pyweb_packages`
|
pyweb/ai/docs/27-upgrading.md
CHANGED
pyweb/ai/docs/29-performance.md
CHANGED
|
@@ -107,12 +107,22 @@ you use it in a browser.
|
|
|
107
107
|
Profile against a copy of your real data. A page that's fast with ten
|
|
108
108
|
rows can be slow with ten thousand.
|
|
109
109
|
|
|
110
|
+
## Fast reloads and tests
|
|
111
|
+
|
|
112
|
+
The UI kit is compiled once per process, and each `.pyweb` file's Python
|
|
113
|
+
code is reused until the file changes. On the saas example that took a
|
|
114
|
+
reload in `pyweb dev` from about 255 to 60 ms and creating a
|
|
115
|
+
`TestClient` from about 255 to 55 ms; the dev server also notices a save
|
|
116
|
+
within a tenth of a second. Compiled output is byte-for-byte what a fresh
|
|
117
|
+
compile gives, and a test checks that.
|
|
118
|
+
|
|
110
119
|
## Benchmarks in CI
|
|
111
120
|
|
|
112
121
|
`python -m pyweb.bench` reports compile time, shipped JavaScript and
|
|
113
122
|
render time per page. `--system` measures the whole stack: requests per
|
|
114
123
|
second over real sockets, a signed-in page with a database, start-up
|
|
115
|
-
time,
|
|
124
|
+
time, live query hashing, and how long loading an app again takes (what
|
|
125
|
+
`pyweb dev` does after a save, and what each `TestClient` does).
|
|
116
126
|
|
|
117
127
|
PyWeb's CI runs `--compare` on every push and pull request. It checks out
|
|
118
128
|
the commit before the change next to the new one and runs both five
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# The dev loop
|
|
2
|
+
|
|
3
|
+
`pyweb dev app.pyweb` is where you spend your day, so it does a lot for
|
|
4
|
+
you: saves show up in the open page without a reload, any element opens
|
|
5
|
+
its own line in your editor, errors come with a "Fix with AI" button, you
|
|
6
|
+
can step back through what the page did, and a link lets someone else
|
|
7
|
+
try what you're building. Everything on this page exists only under
|
|
8
|
+
`pyweb dev`: production builds, `pyweb serve` and `TestClient` are
|
|
9
|
+
unchanged.
|
|
10
|
+
|
|
11
|
+
## Your first run
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pyweb new # in a terminal: asks for a name, a starter and colours
|
|
15
|
+
cd my-app
|
|
16
|
+
pyweb dev app.pyweb # opens the browser
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`pyweb new` with no name asks three questions: the folder name, a
|
|
20
|
+
starter (each with a line saying what it is) and a colour preset, which
|
|
21
|
+
it writes into `App(theme=Theme(...))`. `pyweb new shop --template todo
|
|
22
|
+
--theme rose` does the same without asking.
|
|
23
|
+
|
|
24
|
+
`pyweb dev` opens your browser (not in CI, over SSH, or with
|
|
25
|
+
`--no-open`) and, the first time a project runs, shows a short Welcome
|
|
26
|
+
panel: what to try, and the snippet that connects your AI assistant.
|
|
27
|
+
**Got it** hides it for good (`PYWEB_WELCOME=0` turns it off).
|
|
28
|
+
|
|
29
|
+
## Saves update the page in place
|
|
30
|
+
|
|
31
|
+
Change some markup, a style or a function and save. The open page
|
|
32
|
+
updates in about a tenth of a second, without a reload and without a
|
|
33
|
+
flash:
|
|
34
|
+
|
|
35
|
+
- **page and component state stays.** Every page variable and every
|
|
36
|
+
component's variables keep their values; two `<Counter />`s keep their
|
|
37
|
+
own counts. A variable you renamed, or whose type changed (a number
|
|
38
|
+
that is now a string), starts over.
|
|
39
|
+
- **form fields, scroll position, focus and the text selection stay**,
|
|
40
|
+
for fields that have an `id` or a `name`.
|
|
41
|
+
- **a stylesheet-only save** swaps that stylesheet and nothing else.
|
|
42
|
+
|
|
43
|
+
When the page's structure changed too much to swap in place (a new
|
|
44
|
+
layout, different npm packages), it reloads, and the same state comes
|
|
45
|
+
back. After a compile error the browser shows the error; fix it, save,
|
|
46
|
+
and you're back where you were, state included. Add `?fresh` to the URL
|
|
47
|
+
to start over every time.
|
|
48
|
+
|
|
49
|
+
The first start is fast too: parse results and compiled code are kept in
|
|
50
|
+
`~/.cache/pyweb` (`PYWEB_CACHE_DIR` to move it, `PYWEB_CACHE=0` to turn
|
|
51
|
+
it off), keyed by each file's contents and the PyWeb and Python versions.
|
|
52
|
+
|
|
53
|
+
## Alt-click to open the source
|
|
54
|
+
|
|
55
|
+
Hold **Alt** (Option on a Mac) and point at anything: it is outlined,
|
|
56
|
+
with the components it sits in and its file and line. **Alt-click** it
|
|
57
|
+
to open that line in your editor. It also opens the **inspector**: the
|
|
58
|
+
chain of components around the element, each with its live variables.
|
|
59
|
+
Type a new value (JSON: `3`, `"hi"`, `[1, 2]`) and the page follows.
|
|
60
|
+
|
|
61
|
+
The editor is `$PYWEB_EDITOR` when you set it, a command with `{file}`
|
|
62
|
+
and `{line}` in it:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
export PYWEB_EDITOR='code -g {file}:{line}' # VS Code
|
|
66
|
+
export PYWEB_EDITOR='idea --line {line} {file}' # JetBrains
|
|
67
|
+
export PYWEB_EDITOR='nvim +{line} {file}' # in a terminal editor, use a new window
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Otherwise the first of VS Code (`code`), Cursor, Windsurf, Zed and
|
|
71
|
+
Sublime Text found on your `PATH`; with none of them, the inspector shows
|
|
72
|
+
a `vscode://` link. Elements that come from the UI kit open the line in
|
|
73
|
+
your app that uses them.
|
|
74
|
+
|
|
75
|
+
## Fix with AI, and Edit with AI
|
|
76
|
+
|
|
77
|
+
When the app doesn't compile, or a page fails with an exception, the
|
|
78
|
+
error page has a **Fix with AI** button. **Alt+Shift-click** any element
|
|
79
|
+
to say what should change ("make this a card with a delete button").
|
|
80
|
+
|
|
81
|
+
Either way you get a **diff** of one file in your app, already compiled:
|
|
82
|
+
a change that doesn't compile is shown but can't be applied. **Apply**
|
|
83
|
+
writes it (only if the file hasn't changed since), the page updates in
|
|
84
|
+
place, and **Undo** puts the old version back (every replaced version is
|
|
85
|
+
also kept in `.pyweb/history/`).
|
|
86
|
+
|
|
87
|
+
Who answers, in this order:
|
|
88
|
+
|
|
89
|
+
1. **Your assistant, through `pyweb mcp`.** If the assistant's app
|
|
90
|
+
supports MCP *sampling*, `pyweb mcp` hands the request to it: its own
|
|
91
|
+
model does the work, and the app asks you before each request.
|
|
92
|
+
2. **An API key** in the environment `pyweb dev` runs in:
|
|
93
|
+
`ANTHROPIC_API_KEY`, or `OPENAI_API_KEY` / `OPENAI_BASE_URL` (any
|
|
94
|
+
OpenAI-compatible server, Ollama included), with `AI_MODEL` to choose
|
|
95
|
+
the model.
|
|
96
|
+
3. **Nobody yet.** The page gives you the prompt to copy into any
|
|
97
|
+
assistant, and a connected assistant can pick the request up with the
|
|
98
|
+
`pyweb_assist_requests` tool (the `fix_errors` prompt starts there).
|
|
99
|
+
|
|
100
|
+
What's sent is the file and the error (or your instruction). Credentials
|
|
101
|
+
in them, in the formats `pyweb check` knows and random-looking values in
|
|
102
|
+
secret-named variables, are replaced by placeholders before sending and
|
|
103
|
+
put back in the answer.
|
|
104
|
+
|
|
105
|
+
## Time travel
|
|
106
|
+
|
|
107
|
+
The toolbar's **Timeline** tab (the ⚡ badge, bottom left) records every
|
|
108
|
+
change to the page's variables with what caused it: a click on which
|
|
109
|
+
button, typing in which field, Enter, a server function call. Each event
|
|
110
|
+
is one step. Drag the slider, press **Step back** or click a step and
|
|
111
|
+
every variable goes back to its value then; the page is paused while you
|
|
112
|
+
look (clicks and typing are held back). **Resume** puts the latest values
|
|
113
|
+
back. Only the page's own state moves: data on the server isn't rolled
|
|
114
|
+
back. The last 500 changes are kept.
|
|
115
|
+
|
|
116
|
+
## On your phone, and with someone else
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
pyweb dev app.pyweb --host 0.0.0.0 # prints the network URL and a QR code
|
|
120
|
+
pyweb dev app.pyweb --share # a temporary public link (and a QR code)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`--host 0.0.0.0` listens on your network: scan the QR code with a phone
|
|
124
|
+
on the same Wi-Fi.
|
|
125
|
+
|
|
126
|
+
`--share` starts a tunnel, with `cloudflared` when it's installed or
|
|
127
|
+
`ssh` to localhost.run otherwise, and prints a link like
|
|
128
|
+
`https://quiet-fox-12.trycloudflare.com/__pyweb/share?t=…`. Anyone with
|
|
129
|
+
the link can use the app and sees your saves live. Nobody gets in with
|
|
130
|
+
the address alone: the link's token sets a cookie, and every other
|
|
131
|
+
request through the tunnel is refused. The link works until you stop
|
|
132
|
+
`pyweb dev`.
|
|
133
|
+
|
|
134
|
+
People on the network or coming through a share link get the app and
|
|
135
|
+
hot reload, never your tools: no toolbar (it shows SQL and request
|
|
136
|
+
data), inspector, AI help, editor opening or theme saving. Those
|
|
137
|
+
answer only requests from your machine to `localhost`.
|
|
138
|
+
|
|
139
|
+
## Security limits
|
|
140
|
+
|
|
141
|
+
| Feature | Who can use it |
|
|
142
|
+
|---|---|
|
|
143
|
+
| Hot reload, the error page | Everyone who can open the page |
|
|
144
|
+
| Toolbar, timeline, inspector, Alt-click, Fix/Edit with AI, theme saving, Welcome | You: a request from this machine, to a loopback address, from the page itself |
|
|
145
|
+
| Files AI may change | `.pyweb` files inside the app folder; only after Apply; never if the file changed since |
|
|
146
|
+
| Files Alt-click may open | `.pyweb` files in the app folder or in PyWeb's UI kit |
|
|
147
|
+
| `--share` guests | The app, with the link's cookie; nothing under `/__pyweb/dev/` but change polling |
|
|
148
|
+
| `pyweb mcp`'s view of the dev server | With the token in `.pyweb/dev.json` (readable by you only), from this machine |
|
|
149
|
+
|
|
150
|
+
The [threat model](https://github.com/MaanavKrishna/PyWeb/blob/main/THREAT_MODEL.md) lists each of these with the tests
|
|
151
|
+
that prove it.
|
pyweb/ai/docs/THREAT_MODEL.md
CHANGED
|
@@ -177,6 +177,21 @@ websites in the user's browser.
|
|
|
177
177
|
| T | An assistant's "read-only" SQL changing data | One statement, write keywords refused (even in a CTE), a read-only transaction that is rolled back; secrets redacted | `test_dx_v5.py::test_mcp_data_tools` |
|
|
178
178
|
| T | Malformed tool arguments reaching app code | Arguments are checked against each tool's schema before it runs | `test_mcp_v6.py::test_arguments_are_checked_before_the_tool_runs` |
|
|
179
179
|
|
|
180
|
+
## 7d. The dev loop: sharing, AI help, open in editor
|
|
181
|
+
|
|
182
|
+
`pyweb dev` only. Its tools change files, open programs and show request data, so they are for the
|
|
183
|
+
person running it, on that machine: a request must come from a loopback address and name a loopback
|
|
184
|
+
`Host` (a tunnel's or the LAN's requests don't), and writes must be same-origin.
|
|
185
|
+
|
|
186
|
+
| | Threat | Mitigation | Proof |
|
|
187
|
+
|---|---|---|---|
|
|
188
|
+
| S | Someone who learns the `--share` address (or guesses the tunnel name) using the app | Every request through the tunnel needs a cookie (`HttpOnly`, `Secure`, `SameSite=Lax`) set by the printed link's random token; forged cookies are refused | `test_share.py::test_the_link_sets_a_cookie_and_nothing_else_gets_in`, `test_share.py::test_pyweb_dev_share_end_to_end` |
|
|
189
|
+
| E/I | A share-link guest (or someone on the LAN) using the developer's tools: the toolbar's SQL and requests, the agent endpoints, AI fixes, opening files, saving the theme | Guests get the app and hot reload only; every `/__pyweb/dev/` endpoint but change polling answers 403 to them, and their pages carry no toolbar or tool scripts | `test_share.py::test_guests_get_the_app_and_hot_reload_only`, `test_share.py::test_you_still_get_everything_and_the_lan_gets_hot_reload`, `test_share.py::test_a_compile_error_page_for_guests_has_no_tools` |
|
|
190
|
+
| T | A web page making "Fix with AI" or "Edit with AI" write to the app | Same-origin, loopback-only POSTs; the answer is compiled first, applied only on Apply, only to `.pyweb` files in the app, refused if the file changed since; the old version is kept for Undo | `test_assist.py::test_endpoints_refuse_other_sites_and_other_machines`, `test_assist.py::test_a_change_that_does_not_compile_is_refused`, `test_assist.py::test_apply_refuses_when_the_file_changed_since`, `test_assist.py::test_only_app_files_are_targets` |
|
|
191
|
+
| I | Credentials in the app's source sent to a model | Known key formats and random-looking secret values are replaced by placeholders before sending and put back in the answer | `test_assist.py::test_secrets_are_replaced_before_sending_and_put_back`, `test_assist.py::test_the_connected_assistant_answers_through_mcp_sampling` |
|
|
192
|
+
| E | Alt-click "open in editor" used to open arbitrary files or run commands | Only `.pyweb` files inside the app folder or the UI kit; the editor gets an argument list, never a shell; same-origin and loopback only | `test_devopen.py::test_only_app_and_kit_files_resolve`, `e2e/test_dev_inspect_browser.py::test_open_refuses_cross_site_and_outside_files` |
|
|
193
|
+
| I | Dev-only markers or scripts in production pages | `data-pw-src` markers come from dev compiles only; the dev scripts are added by the dev server only | `test_devopen.py::test_other_builds_have_no_marks`, `test_trusted_types.py::test_dev_scripts_never_ship_in_built_pages` |
|
|
194
|
+
|
|
180
195
|
## 8. The release
|
|
181
196
|
|
|
182
197
|
| | Threat | Mitigation | Proof |
|
pyweb/app_loader.py
CHANGED
|
@@ -30,10 +30,10 @@ def _state_function(fn):
|
|
|
30
30
|
Markup placeholders are dropped; an explicit ``return`` (e.g.
|
|
31
31
|
``return redirect("/login")``) still returns early.
|
|
32
32
|
"""
|
|
33
|
-
new = copy.
|
|
33
|
+
new = copy.copy(fn) # only the kept statements need copies, not the markup
|
|
34
34
|
new.name = STATE_PREFIX + fn.name
|
|
35
35
|
new.decorator_list = []
|
|
36
|
-
body = [s for s in
|
|
36
|
+
body = [copy.deepcopy(s) for s in fn.body if not is_ui_stmt(s)]
|
|
37
37
|
ret = ast.Return(value=ast.Call(func=ast.Name(id="locals", ctx=ast.Load()), args=[], keywords=[]))
|
|
38
38
|
body.append(ret)
|
|
39
39
|
new.body = body
|
|
@@ -41,6 +41,53 @@ def _state_function(fn):
|
|
|
41
41
|
return new
|
|
42
42
|
|
|
43
43
|
|
|
44
|
+
_CODE: dict = {} # (file, source hash, page/component names) -> code object
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _module_code(source, filename, infos):
|
|
48
|
+
"""The Python code for a ``.pyweb`` module: its Python part plus a state function per page and
|
|
49
|
+
component. Cached by source, so reloading an app (or loading it again in tests) skips re-parsing
|
|
50
|
+
the files that didn't change, the UI kit's above all."""
|
|
51
|
+
import hashlib
|
|
52
|
+
key = (filename, hashlib.sha256(source.encode()).hexdigest(), tuple(getattr(i, "name", "") for i in infos))
|
|
53
|
+
code = _CODE.get(key)
|
|
54
|
+
if code is None:
|
|
55
|
+
code = _disk_code(key)
|
|
56
|
+
if code is None:
|
|
57
|
+
py_source, _ui = P.split_sources(source)
|
|
58
|
+
tree = ast.parse(py_source, filename=filename)
|
|
59
|
+
for info in infos:
|
|
60
|
+
tree.body.append(_state_function(info.node))
|
|
61
|
+
code = compile(tree, filename, "exec")
|
|
62
|
+
if len(_CODE) > 256:
|
|
63
|
+
_CODE.clear()
|
|
64
|
+
_CODE[key] = code
|
|
65
|
+
_disk_code(key, code)
|
|
66
|
+
elif key not in _CODE:
|
|
67
|
+
_CODE[key] = code
|
|
68
|
+
return code
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _disk_code(key, code=None):
|
|
72
|
+
"""Read (or with ``code``, write) a module's code object in the on-disk cache."""
|
|
73
|
+
import marshal
|
|
74
|
+
|
|
75
|
+
from .compiler import diskcache
|
|
76
|
+
if not diskcache.enabled():
|
|
77
|
+
return None
|
|
78
|
+
k = diskcache.key("code", key[0], key[1], *key[2])
|
|
79
|
+
if code is not None:
|
|
80
|
+
diskcache.put("code", k, marshal.dumps(code))
|
|
81
|
+
return code
|
|
82
|
+
data = diskcache.get("code", k)
|
|
83
|
+
if data is None:
|
|
84
|
+
return None
|
|
85
|
+
try:
|
|
86
|
+
return marshal.loads(data)
|
|
87
|
+
except Exception: # noqa: BLE001 - a corrupt entry: compile again
|
|
88
|
+
return None
|
|
89
|
+
|
|
90
|
+
|
|
44
91
|
def _kit_markup(path):
|
|
45
92
|
"""Whether a component file is kit markup (a component copied with ``pyweb ui add``)."""
|
|
46
93
|
try:
|
|
@@ -53,7 +100,7 @@ def _kit_markup(path):
|
|
|
53
100
|
|
|
54
101
|
class LoadedApp:
|
|
55
102
|
def __init__(self, path=None, *, source=None, filename=None, asset_urls=None,
|
|
56
|
-
stylesheets=None):
|
|
103
|
+
stylesheets=None, dev=False):
|
|
57
104
|
if source is None:
|
|
58
105
|
with open(path, encoding="utf-8") as fh:
|
|
59
106
|
source = fh.read()
|
|
@@ -62,7 +109,7 @@ class LoadedApp:
|
|
|
62
109
|
self.source = source
|
|
63
110
|
self.asset_urls = dict(asset_urls or {})
|
|
64
111
|
self.extra_stylesheets = list(stylesheets or [])
|
|
65
|
-
self.compiled = compile_source(source, filename=self.filename)
|
|
112
|
+
self.compiled = compile_source(source, filename=self.filename, dev=dev)
|
|
66
113
|
self.ctx = self.compiled["context"]
|
|
67
114
|
# Other .pyweb files the app imports run as real modules, registered
|
|
68
115
|
# under their import name so `from widgets import Card` works.
|
|
@@ -169,10 +216,7 @@ class LoadedApp:
|
|
|
169
216
|
|
|
170
217
|
# ----------------------------------------------------------- module
|
|
171
218
|
def _exec(self, source, filename, infos, module_name=None):
|
|
172
|
-
|
|
173
|
-
tree = ast.parse(py_source, filename=filename)
|
|
174
|
-
for info in infos:
|
|
175
|
-
tree.body.append(_state_function(info.node))
|
|
219
|
+
code = _module_code(source, filename, infos)
|
|
176
220
|
stem = os.path.splitext(os.path.basename(filename))[0] or "app"
|
|
177
221
|
mod = types.ModuleType(module_name or f"pyweb_app_{stem}")
|
|
178
222
|
mod.__file__ = os.path.abspath(filename) if self.path else filename
|
|
@@ -191,7 +235,7 @@ class LoadedApp:
|
|
|
191
235
|
if app_dir and app_dir not in sys.path:
|
|
192
236
|
sys.path.insert(0, app_dir)
|
|
193
237
|
sys.modules[mod.__name__] = mod
|
|
194
|
-
exec(
|
|
238
|
+
exec(code, mod.__dict__) # noqa: S102 - the app itself
|
|
195
239
|
return mod
|
|
196
240
|
|
|
197
241
|
# -------------------------------------------------------- rendering
|