PyWeave

PyWeave is a Textual-inspired, server-driven web UI framework for Python.

It brings a component model, event system, reactivity, workers, and SSE updates to the web while keeping the application logic in Python.

Highlights

• Widget, Page, App core model
• reactive(...) state
• @on(...) event handlers with selector support
• @work(...) background workers with progress events
• @route(...) page-local HTTP handlers
• SSE runtime for real-time UI updates
• htmx + Alpine CDN integration by default
• component kit in pyweave.components

Requirements

• Python >=3.13
• uv (recommended)

Install

uv sync

Quick Start

from pyweave import App, Page, on, reactive
from pyweave.components import Button, Form, Input, List, ListItem
from pyweave.events import Submit


class TodoPage(Page):
    tasks = reactive(list, default_factory=list)

    def compose(self):
        yield Form(
            Input(type="text", name="task"),
            Button("Add", type="submit"),
            id="todo-form",
        )
        yield List(id="todo-list")

    @on(Submit, "#todo-form")
    async def on_submit(self, event: Submit) -> None:
        task = str(event.form_data.get("task", "")).strip()
        if not task:
            return
        self.tasks.append(task)
        todo_list = self.query_one("#todo-list")
        todo_list.clear_children()
        for item in self.tasks:
            todo_list.add_child(ListItem(item))
        self.refresh()


app = App(TodoPage, title="Todos")
app.run()

Example App

The complete demo lives in:

• examples/todo_app/app.py

Run it:

uv run examples/todo_app/app.py

The demo includes:

• add/toggle/remove tasks
• total/completed/pending counters
• worker progress status updates
• SSE-driven front-end refresh

Public API Surface

Main imports:

from pyweave import App, Page, Widget, reactive, on, work, route

Event payload helpers (for browser events):

action = event.data("action")
task_id = event.data_int("task-id")
match = event.id_match(r"^delete-(\d+)$")

Development

Task runner commands:

task lint
task typecheck
task test
task check

Direct commands:

uv run ruff check src tests
uv run mypy src
uv run pytest

Project Structure

• src/pyweave/app.py: ASGI runtime and route wiring
• src/pyweave/message.py, src/pyweave/message_pump.py: event/message bus
• src/pyweave/reactive.py: reactive descriptor system
• src/pyweave/dom/: virtual DOM tree and selector engine
• src/pyweave/runtime/: SSE, session, broker adapters
• src/pyweave/workers/: worker execution and progress events
• src/pyweave/static/pyweave-client.js: browser bridge
• tests/: unit and integration coverage

Optional Dependencies

• Redis broker support: install extra redis
• E2E support: install extra e2e (Playwright)

With uv:

uv sync --extra redis --extra e2e

Todo: Demo App Improvements

Pending improvements for examples/todo_app/app.py:

• Persist tasks in a real store (SQLite/Postgres/Redis) instead of in-memory session state.
• Add task edit/rename flow.
• Add filters (all, pending, done) and simple search.
• Add pagination or virtualization for large task lists.
• Add keyboard shortcuts (Enter add, Esc clear input, quick toggle).
• Add i18n-ready labels/messages.
• Extract inline style strings to reusable theme tokens or CSS classes.
• Improve accessibility (aria-*, focus states, semantic landmarks).
• Add optimistic UI mode with rollback on worker failure.
• Add richer error/status feedback for worker failures and network issues.

Security Reviews

Recommended security review checklist for PyWeave and demo apps:

• Input validation and normalization for all form/event payload fields.
• Output safety: ensure escaped HTML by default, and audit any raw HTML usage.
• CSRF strategy for state-changing endpoints (/__pyweave/event and custom @route POST endpoints).
• Session hardening: secure cookie flags, rotation policy, expiration strategy.
• Authorization boundaries for multi-user contexts (avoid cross-session data leaks).
• SSE channel isolation and access control validation.
• Rate-limiting/throttling on event endpoint and SSE connections.
• Abuse protection for worker spawning (limits by session/user/group).
• Dependency scanning and update policy (FastAPI/Uvicorn/JS CDN dependencies).
• Logging review: avoid sensitive data in logs and event payload traces.
• Security headers/CSP policy review for production deployments.
• Add automated security tests for common abuse cases (payload fuzzing, injection attempts, endpoint flooding).

Operational recommendation:

• Run a lightweight security review before each release and a deeper review on major API/runtime changes.