Metadata-Version: 2.4
Name: pyweb-stack
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>
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

# PyWeb

**Full-stack web apps in one Python file.** Server-rendered pages,
reactive browser UI compiled from Python, and typed calls to server
functions, without a JavaScript toolchain.

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

**[Try it in your browser](https://maanavkrishna.github.io/PyWeb/playground.html)**: the playground runs
the real PyWeb, server functions included, on Python compiled to WebAssembly.

```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
```

## Why PyWeb

- **Interactions run in the browser.** Handlers and expressions are
  compiled to small JavaScript modules; the server is only contacted when
  your code calls a `@server` function. No WebSocket per user, no
  multi-megabyte Python runtime in the browser.
- **Every page is server-rendered.** Complete HTML on first paint, real
  data from your database, good for SEO and slow devices.
- **You never write an API layer.** `@server` functions get endpoints,
  argument validation, typed errors and generated browser calls.
- **Plain variables are state.** The compiler sees which variables your
  handlers change and makes exactly those reactive; updates touch only
  the DOM nodes that read them.
- **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 ~14 KB
(gzip) runtime that's cached across pages. Pages without interactivity
ship no JavaScript.

## Is it for you?

**Good fit:** internal tools, admin panels, dashboards, CRUD apps,
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/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).

## Build it with AI

PyWeb ships an MCP server so AI assistants can scaffold, check, inspect,
render, screenshot and test your app, with errors that come back as line
numbers and 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 and other MCP clients).
`pyweb new myapp --template todo` also writes `AGENTS.md` and `CLAUDE.md`
so coding agents follow PyWeb's rules, and the docs site publishes
[`llms-full.txt`](https://maanavkrishna.github.io/PyWeb/llms-full.txt).
See [AI assistants & MCP](docs/17-ai-assistants.md).

## 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.

## Examples

Each runs with `pyweb dev examples/<name>/app.pyweb` and is exercised 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 params, 404s, validation errors |
| [`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|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
pyweb build app.pyweb --out dist --production    # self-contained, hashed, minified dist/
pyweb serve dist                                 # production server (/healthz, CSP, graceful shutdown)
pyweb mcp                                        # MCP server for AI assistants (stdio)
pyweb lsp                                        # language server for editors (stdio)
```

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

## Status

PyWeb is in beta (0.x; see the PyPI badge above for the latest version).
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.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, sessions, every
example app in Chromium, and the database/Redis layers against real
Postgres, MySQL and Redis servers, on Python 3.10–3.13.

## Authors

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports:
[SECURITY.md](SECURITY.md). License: MIT.
