Metadata-Version: 2.4
Name: pyweb-stack
Version: 0.4.1
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>
Maintainer-email: MaanavKrishna <67054795+MaanavKrishna@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://maanavkrishna.github.io/PyWeb/
Project-URL: Documentation, https://maanavkrishna.github.io/PyWeb/guide.html
Project-URL: Source, https://github.com/MaanavKrishna/PyWeb
Project-URL: Changelog, https://github.com/MaanavKrishna/PyWeb/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/MaanavKrishna/PyWeb/issues
Keywords: web,framework,full-stack,reactive,rpc,ssr,compiler
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: mysql
Requires-Dist: PyMySQL>=1.1; extra == "mysql"
Provides-Extra: redis
Requires-Dist: redis>=5; extra == "redis"
Provides-Extra: crypto
Requires-Dist: cryptography>=42; extra == "crypto"
Provides-Extra: asgi
Requires-Dist: uvicorn>=0.30; extra == "asgi"
Provides-Extra: all
Requires-Dist: psycopg[binary]>=3.1; extra == "all"
Requires-Dist: PyMySQL>=1.1; extra == "all"
Requires-Dist: redis>=5; extra == "all"
Requires-Dist: cryptography>=42; extra == "all"
Requires-Dist: uvicorn>=0.30; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: playwright>=1.45; extra == "test"
Requires-Dist: mcp>=1.2; extra == "test"
Dynamic: license-file

<div align="center">

# PyWeb

**Full-stack web apps in one Python file.**

Server-rendered pages, a reactive UI compiled from Python, typed calls to
your server, live data and streaming AI, with no JavaScript toolchain.

[![CI](https://github.com/MaanavKrishna/PyWeb/actions/workflows/ci.yml/badge.svg)](https://github.com/MaanavKrishna/PyWeb/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pyweb-stack)](https://pypi.org/project/pyweb-stack/)
![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-3776ab)
[![Docs](https://img.shields.io/badge/docs-maanavkrishna.github.io%2FPyWeb-0d9488)](https://maanavkrishna.github.io/PyWeb/)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

**[Documentation](https://maanavkrishna.github.io/PyWeb/)** ·
**[Try it in your browser](https://maanavkrishna.github.io/PyWeb/playground.html)** ·
**[Examples](#examples)** ·
**[Changelog](CHANGELOG.md)**

</div>

```pyweb
from pyweb import App, server

app = App(title="Guestbook")
ENTRIES = []


@server
def sign(name: str) -> list:
    ENTRIES.append(name.strip() or "anonymous")
    return ENTRIES


@app.page("/")
def Home():
    entries = list(ENTRIES)     # computed on the server per request
    name = ""                   # bound to the input: browser state

    def submit():               # compiled to JavaScript
        entries = sign(name)    # typed RPC to the server
        name = ""

    <main>
        <h1>Guestbook ({len(entries)})</h1>
        <form onsubmit={submit}>
            <input bind={name} placeholder="Your name" />
            <button>Sign</button>
        </form>
        <ul>
            for entry in entries:
                <li>{entry}</li>
        </ul>
    </main>
```

```bash
pip install pyweb-stack      # imported as `pyweb`
pyweb dev app.pyweb          # http://localhost:8000, with live reload
```

That's the whole app. The page is rendered on the server with real data,
the handler becomes a few hundred bytes of JavaScript, and `sign()` becomes
a validated JSON endpoint the browser calls for you.

## What you get

### Python on both sides, split by the compiler

You write one file. The compiler decides, line by line, what runs in the
browser and what stays on the server, and tells you why
(`pyweb inspect`). Variables your handlers change become reactive state;
everything else is computed on the server. Database handles, imports and
secrets can't leak into browser code: that's a compile error with a line
number, not a production incident.

### Pages that follow the database

```pyweb
from pyweb import App, live
from pyweb.db import connect

app = App()
db = connect("sqlite:///shop.db")


@app.page("/orders")
def Orders():
    orders = live(db, "select item, status from orders order by id desc limit 20")

    <ul>
        for o in orders:
            <li>{o["item"]}: {o["status"]}</li>
    </ul>
```

Any write through `pyweb.db` updates every open window. Identical queries
run once for all viewers, and it works across processes with Redis.
[Live data →](docs/21-live-data.md)

### AI features that stream

```pyweb
from pyweb import App, Markdown, server

app = App()


@server
def answer(question: str):
    for piece in ("**Streaming**", " from", " the", " server."):   # your model's tokens
        yield piece


@app.page("/")
def Ask():
    question = ""
    reply = ""
    stream = None

    async def ask():
        reply = ""
        stream = answer(question)
        async for piece in stream:
            reply += piece

    def stop():
        if stream:
            stream.cancel()

    <input bind={question} />
    <button onclick={ask}>Ask</button>
    <button onclick={stop}>Stop</button>
    <Markdown text={reply} />
```

`yield` on the server, `async for` in the browser. Stop really stops:
the generator on the server is closed, so the model call ends too.
`<Markdown>` is safe on model output. Start from
`pyweb new mychat --template ai-chat` (Anthropic, any OpenAI-compatible
server, or a built-in demo model). [Building AI apps →](docs/20-ai-apps.md)

### Real multi-page apps

```pyweb
from pyweb import App

app = App(title="Plant shop")


@app.layout
def Shell(children):
    cart = 0

    def add():
        cart += 1

    <nav><a href="/">Home</a> <a href="/plants">Plants</a> <button onclick={add}>Cart {cart}</button></nav>
    {children}


@app.page("/plants", description="Every plant we sell")
def Plants(light: str = "", max_price: int = 0):    # typed query parameters
    <h1>Plants</h1>
```

Layouts keep their state while links load without a full page reload
(with prefetching and scroll restore). Links to the current page are
marked automatically, every page gets its own title, description and
social tags, and 404/500 pages are written in `.pyweb` too.
[Layouts & navigation →](docs/19-layouts-navigation.md)

### npm packages, without Node.js

```bash
pyweb add chart.js/auto
```

```python
Chart = npm("chart.js/auto")
```

PyWeb downloads the package from the npm registry, checks its checksum,
keeps only the files the browser loads and pins them in `pyweb.lock`.
There's no `node_modules` and no bundler, and pages that don't use a
package don't load it. [npm packages →](docs/18-npm-packages.md)

### Small, fast and boring to run

- **Every page is server-rendered**: complete HTML on first paint, then
  hydrated in place. Pages without interactivity ship no JavaScript.
- **Small**: a typical interactive page is under 1 KB of code plus a
  ~15 KB (gzip) runtime that's cached across pages.
- **Stateless servers**: signed-cookie sessions and plain JSON over HTTP
  scale behind any load balancer. Run `pyweb serve`, uvicorn/gunicorn
  (ASGI) or the generated Dockerfile.
- **Secure defaults**: escaped output, a strict Content Security Policy,
  CSRF and origin checks on RPC, rate limits and request size limits.

## See it

| [Live dashboard](examples/dashboard/app.pyweb) | [Streaming AI chat](examples/ai-chat/app.pyweb) | [Multi-page site](examples/site/app.pyweb) |
|---|---|---|
| ![Sales dashboard: totals and a Chart.js bar chart that update live](https://raw.githubusercontent.com/MaanavKrishna/PyWeb/main/docs/images/dashboard.png) | ![AI chat with a streamed Markdown reply](https://raw.githubusercontent.com/MaanavKrishna/PyWeb/main/docs/images/ai-chat.png) | ![Plant shop with a navigation layout and a cart](https://raw.githubusercontent.com/MaanavKrishna/PyWeb/main/docs/images/site.png) |
| `live()` queries + Chart.js from npm | `yield` + Stop + `<Markdown>` | layout, query parameters, 404 page |

Or open the **[playground](https://maanavkrishna.github.io/PyWeb/playground.html)**:
it runs the real PyWeb, server functions included, in your browser.

## Quick start

```bash
pip install pyweb-stack
pyweb new myapp --template todo      # blank | counter | todo | blog | auth | chat | ai-chat
cd myapp
pyweb dev app.pyweb                  # edit app.pyweb; the page reloads on save
```

Then:

```bash
pyweb check app.pyweb                # compile + security checks (CI-friendly exit codes)
pytest                               # new apps come with test_app.py
pyweb build app.pyweb --production   # hashed, minified, self-contained dist/
pyweb serve dist                     # production server
```

The [quickstart](docs/02-quickstart.md) and [tutorial](docs/03-tutorial.md)
take it from there.

## How it works

```text
                      app.pyweb
                          │
                  ┌───────┴────────┐  compiler: parses Python + markup, decides
                  ▼                ▼  where each name runs, checks the boundary
       ┌─────────────────┐  ┌─────────────────────────┐
       │  browser module │  │  server                 │
       │  signals, DOM   │  │  page bodies, @server   │
       │  updates, your  │  │  functions, database,   │
       │  handlers in JS │  │  sessions, secrets      │
       └────────┬────────┘  └────────────┬────────────┘
                └──── typed JSON RPC ────┘
                     (streams and live updates over the same HTTP)
```

The [architecture overview](ARCHITECTURE.md) goes through each stage.

## Build it with AI

PyWeb ships an MCP server so AI assistants can scaffold, check, inspect,
render, screenshot and test your app, add npm packages, and map its
routes. Errors come back as line numbers with fix hints:

```bash
claude mcp add pyweb -- pyweb mcp                                    # Claude Code
```

```json
{ "mcpServers": { "pyweb": { "command": "pyweb", "args": ["mcp"] } } }
```

(the JSON is for Cursor, Claude Desktop, VS Code, Windsurf and other MCP
clients). New projects include `AGENTS.md` and `CLAUDE.md`, and the docs
site publishes [`llms-full.txt`](https://maanavkrishna.github.io/PyWeb/llms-full.txt).
[AI assistants & MCP →](docs/17-ai-assistants.md)

## Editor support

The **[VS Code extension](editors/vscode)** adds highlighting, errors as
you type, hover that shows where code runs (and the signatures of npm
packages), completion and go to definition. Any other LSP editor can run
`pyweb lsp` ([setup](docs/14-cli.md#editor-support)).

## Examples

Each runs with `pyweb dev examples/<name>/app.pyweb` and is tested in a
real browser by the test suite.

| Example | Shows |
|---|---|
| [`counter`](examples/counter/app.pyweb) | signals, computed values, binding a number input |
| [`todo`](examples/todo/app.pyweb) | components, list mutation, filters, keyed lists |
| [`blog`](examples/blog/app.pyweb) | SQL database, server functions, route parameters, 404s, validation errors |
| [`auth`](examples/auth/app.pyweb) | registration, password hashing, sessions, protected pages |
| [`chat`](examples/chat/app.pyweb) | route parameters, 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) |

## Documentation

| | |
|---|---|
| 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) · [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 | [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/)**,
with compiler output shown next to each example.

## Is it for you?

**Good fit:** internal tools, admin panels, dashboards, CRUD apps, AI
features, 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 built around a
JavaScript component framework (use React, Svelte or Vue), or running
scientific Python in the browser (use Pyodide or PyScript). See the
[introduction](docs/01-introduction.md) and the
[current limitations](docs/16-limitations-roadmap.md).

## Status

PyWeb is in beta (0.x). The language, server API, RPC protocol and CLI
are documented and tested, and changes to them are announced in the
[changelog](CHANGELOG.md) (see [stability](docs/15-toolkit.md#stability)).
Upgrade with `pip install -U pyweb-stack`.

| 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.4.1: richer MCP tools |
| 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 parser, the Python→JavaScript translation
(differentially, against CPython), the reactive runtime, server
rendering, RPC, streaming, live queries, client-side navigation, every
example app in Chromium, the playground on Pyodide, and the
database/Redis layers against real Postgres, MySQL and Redis servers, on
Python 3.10–3.13.

## Contributing

Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
Security reports: [SECURITY.md](SECURITY.md).

Built by [MaanavKrishna](https://github.com/MaanavKrishna). MIT licensed.
