GitHub

Server toolkit and API stability

Besides the compiler and server, PyWeb includes small, dependency-free libraries for common server-side needs. Use them from page bodies and @server functions.

#Caching

Python
from pyweb.cache import cache, get_cache

@cache(minutes=5, tags=["products"])
def product_list():
    return expensive_query()

store = get_cache("memory")            # or get_cache("redis", url="redis://...")
store.set("k", {"v": 1}, ttl=60, tags=["user:7"])
store.invalidate_tag("user:7")

#Background jobs

Use durable jobs: @app.job and fn.enqueue(...), @app.cron(...), pyweb worker. See Background jobs.

The 0.4 in-memory @task still works (it runs in a thread of the process that called it, and is lost on restart):

Python
from pyweb.jobs import task

@task(retries=2)
def send_report(email, _job=None):     # accept _job to report progress
    _job.set_progress(0.5)
    ...

job = send_report("ada@example.com")   # returns immediately; runs in a worker thread

#Realtime fan-out

Python
from pyweb.realtime import RedisBus

bus = RedisBus("redis://localhost:6379/0")
bus.publish("room:python", {"author": "ada", "text": "hi"})
bus.since("room:python", last_id=0)    # [(1, {...}), ...] shared across processes

pyweb.publish(name, data) publishes through this bus, and pages listen with channel() and subscribe() (see Live updates). To share one bus between processes, call realtime.use_bus(bus) at startup.

#Uploads, forms, observability

  • pyweb.uploads.validate_upload(filename=, size=, content_type=, allowed_types=, max_bytes=) and safe_filename.
  • pyweb.forms.validate(model, data) / fields_for(model).
  • pyweb.telemetry: span, on_error, the metrics registry (pyweb.telemetry.metrics.REGISTRY), JSON logs with redaction (see Logs, metrics & tracing). The older pyweb.observability.Logger, Tracer, Metrics and format_error still work.
  • pyweb.security.escape, safe_join, safe_next.
  • pyweb.http.fetch(url, ...): fetch URLs that users chose without reaching your internal network (see Security).
  • pyweb.webhooks: send, publish, verify and @app.webhook receivers; pyweb.filegc.collect() deletes unreferenced uploads (see Webhooks & files).

#Stability

PyWeb follows semantic versioning. It is in the 0.x series, so minor releases (0.5, 0.6, …) may still contain breaking changes, and pyweb upgrade --check lists what an app needs to change. For the APIs marked stable below, any breaking change is listed in the changelog and, where possible, preceded by a deprecation warning in an earlier release. They are the intended 1.0 API.

Stable (intended 1.0 API)
The .pyweb languagemarkup, expressions, attributes, events, bind, control flow, components, on_mount, state classification rules
pywebApp (with page, layout, job, cron, every, use_auth), server, component, request, session, redirect, NotFound, RPCError, live, publish, subscribe
ModelsModel, Field, the field types, relations, QuerySet methods, policy, atomic (see Data)
FormsForm, Input, Textarea, Select, Checkbox, FileInput, Submit, ValidationError (see Forms)
pyweb.authkituse_auth() options, auth.user(), login=/roles=/fresh= guards, the auth Models (see Authentication)
Teamsuse_auth(orgs=True), the auth.org()/create_org/invite/... API, org_role=/feature= guards, plans(), Model, tenant=True, pyweb.tenancy.org_scope (see Teams)
pyweb.ui, pyweb.motionthe kit's components and their parameters, Theme, toast, extend, variants/style/cx; the motion attributes (initial, animate, exit, transition, variants, layout, layout_id, while_*, drag), Motion, preset (see UI kit & motion)
pyweb.webhooks, pyweb.http@app.webhook, send, publish, WebhookEndpoint; fetch
pyweb.jobs@app.job, .enqueue(), @app.cron, @app.every, current(), Worker (see Background jobs)
RPC and live wire protocolsURL, request/response JSON, error codes, the /__pyweb/ws messages
pyweb.testingTestClient (with login (including org=), logout, rpc), Factory (with for_org), as_org, serve
pyweb.asgicreate_app
pyweb.db, pyweb.db.migrateconnect, execute, transaction, stream, Query, migrations and their files
pyweb.authpasswords, sessions, TOTP, magic links, WebAuthn assertion verification
pyweb.telemetryspan, on_error, log fields, metric names
pyweb.cache, pyweb.realtimeas documented above
pyweb.platform, pyweb.desktop, pyweb.pwa, pyweb.pushdesktop/pwa/installed/web flags, the desktop API and Window, PWA, push.send (Desktop apps, Installable apps)
CLInew dev check inspect build serve worker db deploy upgrade ui desktop push openapi files mcp and their documented flags
pyweb mcptool, resource and prompt names and their arguments; results may gain fields
dist/ layoutapp.pyweb, manifest.json keys documented in Deployment

Experimental (importable, tested, but may change in any release): pyweb.livetable (in-memory live tables; it was pyweb.live before 0.4), the deploy plan's Python API (pyweb.deploy.plan; the pyweb deploy command is supported), pyweb.sync (offline sync), pyweb.css helpers, pyweb.plugins, pyweb.lsp (its Python functions; the pyweb lsp command itself is supported), pyweb.dts (TypeScript declarations to Python dataclasses; it was pyweb.npm before 0.4), pyweb.browser server-side stubs, the pyweb.compiler internals and the generated JavaScript.

Edit this page on GitHub