tempestweb

📚 Documentation: Português (Brasil) · English (US) — bilingual docs site (PT-BR default + EN-US), deployed to GitHub Pages.

Build web apps in typed Python. One declarative widget tree, a DOM renderer, and three execution modes that share 100% of the application code: Mode A (WASM) runs your Python in the browser via Pyodide; Mode B (server) runs it on the server (FastAPI) and talks to a thin JS client over WebSocket or SSE; Mode C (transpile) transcribes your Python to native JavaScript — zero Python runtime, static hosting, great first-paint/SEO. Installable PWA, offline-first (service worker + IndexedDB), and WebPush are first-class — parity with tempest-react-sdk.

Sister project to tempestroid — same "one tree, multiple renderers" architecture. The renderer-agnostic engine (IR, reconciler, state, style, widgets) is shared; tempestweb adds a DOM leaf renderer (pure JavaScript, no framework, no build step, no TypeScript) and two patch transports.

Status

Published on PyPI and functional across all three modes — a working counter runs live under WASM, server, and transpile; the full test gate is green and every example builds. The transpile mode (C) is now a mature, first-class mode — 100% of tempest_core widgets, a wide typed-Python subset, and a full PWA story (installable, offline, WebPush). Only a handful of advanced constructs sit outside its subset, and the compiler fails early with file:line when you hit one. Design docs:

Want runnable apps? Browse the Example Gallery (PT-BR) — 50+ single-concept demos (stopwatch, forms, data table/grid, kanban, chat, theming, i18n, canvas charts, app shells, native capabilities, observability, PWA/WebPush, a Mode C tour, and a server-mode walkthrough), each running unchanged across the execution modes.

Building something real? Read the App architecture & best practices guide (EN) — the ideal layered structure (routes · pages · components · styles · controllers · services · storages · schemas · utils · core), mirroring tempest-fastapi-sdk, so your app doesn't rot into garbage code.

How it works

   view(app) ──build──▶ Node tree (IR) ──diff──▶ [ Patch ]   ← shared core (tempest-core)
                                                    │          insert/remove/update/reorder/replace
              ╭─────────────────┬───────────────────┤
       Mode A transport   Mode B transport     Mode C: transpile view() → native JS;
       (pyodide.ffi)      (WebSocket | SSE)     the core runs IN JS, patches in-process
              ╰─────────────────┴───────────────────╯
                  client/ (pure JS): apply patches to the DOM
                  + Style→CSS + event capture          ← same client code in every mode

The application's view() never names a transport — the same examples/counter/app.py runs under --mode wasm, --mode server and --mode transpile unchanged. Capabilities (native/: http, audio, share, geolocation, clipboard, storage, camera, install, offline, notifications) are typed awaitables with the same Python API in every mode — Mode A calls the Web API in-process, Mode B proxies it over a round-trip, Mode C routes to the same JS glue via an in-process facade (see docs/contract.md).

Static SSR — render_to_html

Another render target, alongside the interactive modes: the same typed tree renders to a static HTML string on the server — no JavaScript, no DOM, no runtime. HTML is just another leaf renderer.

from tempest_core import Column, Text, Button, Style
from tempest_core.style import Edge
from tempestweb.html import render_to_html, render_document

tree: Column = Column(
    style=Style(gap=8.0, padding=Edge.all(16)),
    children=[Text(content="Hello"), Button(label="Click")],
)

fragment: str = render_to_html(tree)                 # an HTML fragment
page: str = render_document(tree, title="Home", htmx=True)  # a full document

The CSS is byte-identical to what the DOM client emits (the style_to_css port mirrors client/style.js), and the new tempest-core 0.9.0 Widget.tag / Widget.attrs fields let you emit semantic, htmx-ready markup (Container(tag="nav", attrs={"hx-get": "/x"})). All text/attributes are escaped. See the Static SSR guide (EN).

Mode C — transpile to native JS 🚀

The "TypeScript story" for Python: you write the typed-Python app; a compiler transcribes the app layer (state, view(), handlers) to native JavaScript, reusing the whole shared JS renderer. Zero Python runtime in the browser — static hosting, small bundle, great first-paint/SEO.

# examples/counter/app.py  (unchanged from Modes A/B)
@dataclass
class CounterState:
    value: int = 0

def view(app: App[CounterState]) -> Widget:
    def increment() -> None:
        app.set_state(lambda s: setattr(s, "value", s.value + 1))
    return Column(children=[
        Text(content=f"Count: {app.state.value}", key="label"),
        Button(label="+", on_click=increment, key="inc"),
    ])

from tempestweb.transpile import transpile_file

js: str = transpile_file("examples/counter/app.py")  # -> native ES module

The generated module runs on the native runtime (client/transpile/runtime.js) with a JS diff locked against a core-derived golden. Coverage is now 100% of tempest_core: all ~64 widgets, MD3 styling, state-with-methods, navigation (routes + URL), i18n, theme + responsiveness, native capabilities (http/storage/ cookies/…), field validators and both declarative and imperative animation. The tempestweb build/dev --mode transpile CLI emits a static, CDN-servable bundle that is a first-class PWA — installable and offline out of the box (manifest

  • cache-first service worker precaching the whole shell; customize via [pwa] in tempestweb.toml).

See the canonical examples/transpile-tour — one app exercising the whole surface — and the guide (PT · EN). It is a first-class mode: only a handful of advanced constructs sit outside the typed subset (out-of-subset constructs fail loud with file:line).

Scaffold a PWA

tempestweb new myapp --template pwa    # Mode C: installable, offline PWA
tempestweb build --mode transpile --path myapp

The pwa template pre-configures mode = "transpile" + a [pwa] manifest block and ships a counter with an Install button. Omit --template for the plain counter starter that runs unchanged in all three modes.

WebPush (end-to-end)

Push works client-to-server out of the box. Generate VAPID keys, mount the router, subscribe from the client:

tempestweb vapid --env        # -> VAPID_PUBLIC_KEY=… / VAPID_PRIVATE_KEY=…

from fastapi import FastAPI
from tempestweb.server import VapidConfig, WebPushService, webpush_router

service = WebPushService(VapidConfig.from_env())
app = FastAPI()
app.include_router(webpush_router(service))   # /webpush/{subscribe,unsubscribe,send}

The client subscribes with native.notifications.subscribe(public_key) and POSTs the subscription to /webpush/subscribe; POST /webpush/send pushes to it. See the runnable examples/webpush-server.

Deploy (server mode)

tempestweb deploy --server-name app.example.com --tls    # -> deploy/
cd deploy && docker compose up --build

Generates a tailored nginx.conf (WebSocket upgrade, streaming timeouts, sticky ip_hash, optional TLS), a Dockerfile, docker-compose.yml and a DEPLOY.md. Harden the app with a SecurityConfig (auth, CORS, limits, rate limiting, headers) — see the Security and Deploy guides. Static modes (A/C) need no server — publish the build to any CDN.

Develop

uv venv && uv pip install -e ".[dev,server,cli]"
make check          # ruff + mypy + pytest + JS (jsdom) tests

Layout

Path What
tempest-core (dependency) Renderer-agnostic engine — IR/reconciler/state/style/widgets (import tempest_core), extracted from tempestroid.
tempestweb/components/ Native fields + forms (EmailField, PasswordField, LoginForm, …) plus the re-exported tempest-core library — 54 Material 3 components (Card, DataTable, Tabs, Drawer, Alert, BarChart/LineChart, …).
tempestweb/transports/ The one seam between modes (base.py Protocol, wasm.py, websocket.py, sse.py).
tempestweb/html/ Static SSR leaf renderer — render_to_html / render_document / style_to_css (Python port of client/style.js).
tempestweb/transpile/ Mode C: ast-based Python→JS compiler for the app layer. Paired with the native runtime in client/transpile/ (diff.js · widgets.js · runtime.js).
tempestweb/server/ FastAPI + WebSocket/SSE host (Mode B).
tempestweb/native/ Web API capability adapters — http, audio, share, geo, clipboard, storage, camera (Track N).
tempestweb/observability/ Telemetry, logger, error boundary, feature flags, auth — adapter pattern (Track O).
tempestweb/pwa/ Web App Manifest + icon emitter (Track P).
tempestweb/cli/ tempestweb new/dev/build/run/sync.
client/ Pure-JS DOM renderer (incl. Canvas draw-command execution for charts), Style→CSS, event capture; pwa/ sw/ offline/ push/ native/ subdirs.
tests/fixtures/ Golden wire-format fixtures derived from the core.

Conventions

Python: double quotes, full typing (mypy --strict), Google docstrings in English, async-first. Client: plain JavaScript only — no TypeScript, no framework, no build step. See CLAUDE.md.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.121.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mauriciorocha70 from gravatar.com mauriciorocha70

Credits

Author: Mauricio Benjamin

License

MIT

Requires

Python >=3.11

Provides Extra

cli dev docs server webpush

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tempestweb-0.48.0.tar.gz (317.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

tempestweb-0.48.0-py3-none-any.whl (336.3 kB view details)

Uploaded Python 3

File details

Details for the file tempestweb-0.48.0.tar.gz.

File metadata

  • Download URL: tempestweb-0.48.0.tar.gz
  • Upload date:
  • Size: 317.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for tempestweb-0.48.0.tar.gz
Algorithm Hash digest
SHA256 226ec680923c0897ecc46cc82a36734b9cd3f02b5bc263dc282745f63ba4c02e
MD5 d81595fa1a158a55a69ac2048e511ff0
BLAKE2b-256 a1833e3453cc4c7398fc4a466e5d3035af00c4477250cc47ab3df680f0e6e2f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for tempestweb-0.48.0.tar.gz:

Publisher: publish.yml on mauriciobenjamin700/tempestweb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tempestweb-0.48.0-py3-none-any.whl.

File metadata

  • Download URL: tempestweb-0.48.0-py3-none-any.whl
  • Upload date:
  • Size: 336.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for tempestweb-0.48.0-py3-none-any.whl
Algorithm Hash digest
SHA256 eb9e37fd30f826469af80bb062f8a1bb227b8c33a0fae0f561b32e23919657a2
MD5 5684e3bf54ea5f54cbbbd8ee20e8fd68
BLAKE2b-256 a0ea6ead606efdea81ab7fecc72cac3c186467c772af37ea4aa5dc9f8d9663aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for tempestweb-0.48.0-py3-none-any.whl:

Publisher: publish.yml on mauriciobenjamin700/tempestweb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.121.0

2 files

0.120.0

2 files

0.113.0

2 files

0.111.0

2 files

0.108.0

2 files

0.98.0

2 files

0.78.1

2 files

0.78.0

2 files

0.67.0

2 files

0.66.0

2 files

0.65.0

2 files

0.64.0

2 files

0.63.0

2 files

0.62.0

2 files

0.61.2

2 files

0.61.1

2 files

0.61.0

2 files

0.60.0

2 files

0.59.0

2 files

0.58.0

2 files

0.57.0

2 files

0.56.0

2 files

0.55.1

2 files

0.55.0

2 files

0.54.0

2 files

0.53.2

2 files

0.53.1

2 files

0.53.0

2 files

0.52.0

2 files

0.51.0

2 files

0.50.0

2 files

0.49.0

2 files

This release

0.48.0 This release

2 files

0.47.0

2 files

0.46.0

2 files

0.45.0

2 files

0.44.0

2 files

0.43.0

2 files

0.42.0

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.0

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.0

2 files

0.31.0

2 files

0.30.0

2 files

0.29.0

2 files

0.28.0

2 files

0.27.0

2 files

0.26.0

2 files

0.25.0

2 files

0.24.0

2 files

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.0

2 files

0.18.0

2 files

0.17.0

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.0

2 files

0.10.0

2 files

0.9.0

2 files

0.8.1

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page