GitHub

Tutorial: a notes app

We'll build a small multi-user notes app in one file: a page with browser-side state, a reusable component, a SQLite database behind server functions, sign-in with sessions, and the UI kit. Each step is a complete app.

#1. A page with state

app.pyweb
from pyweb import App

app = App(title="Notes")


@app.page("/")
def Home():
    notes = ["Try PyWeb"]
    draft = ""

    def save():
        if draft.strip():
            notes.append(draft.strip())
        draft = ""

    <main>
        <h1>Notes ({len(notes)})</h1>
        <form onsubmit={save}>
            <input bind={draft} placeholder="Write a note" />
            <button disabled={not draft.strip()}>Save</button>
        </form>
        <ul>
            for note in notes:
                <li>{note}</li>
        </ul>
    </main>
What this compiles to
JavaScript
// Home.js
function Home($s) {
  const notes = $signal("notes" in $s ? $s["notes"] : ["Try PyWeb"], "notes");
  const draft = $signal("draft" in $s ? $s["draft"] : "", "draft");
  function save() {
    if ($py.truth($py.m(draft(), "strip"))) {
      $py.mut(notes, [], ($v) => $py.m($v, "append", $py.m(draft(), "strip")));
    }
    draft("");
  }
  return [$h("main", null, () => [
      $h("h1", null, () => [
        $t("Notes ("),
        $dyn(() => $py.len(notes())),
        $t(")")
      ]),
      $h("form", {"onsubmit": save}, () => [
        $h("input", {"$bind": draft, "placeholder": "Write a note"}),
        $h("button", {"disabled": () => !$py.truth($py.m(draft(), "strip"))}, () => [$t("Save")])
      ]),
      $h("ul", null, () => [$list(() => notes(), (note) => [$h("li", null, () => [$t($py.text(note))])])])
    ])];
}
$mount("Home", Home);
  • bind={draft} keeps the input and the variable in sync both ways.
  • onsubmit={save} runs save and prevents the browser's default form submission.
  • notes.append(...) mutates a list that markup reads. PyWeb makes the update copy-on-write, so the <ul> adds exactly one <li> and the heading's count updates.
  • disabled={not draft.strip()} re-evaluates as you type.

Inside handlers, assigning a page variable (draft = "") updates the page state. There is no nonlocal and no setState.

#2. A component

Any capitalised function containing markup is a component. Parameters are props; children receives nested markup.

app.pyweb
from pyweb import App, component

app = App(title="Notes")


@component
def Note(text, on_delete):
    <li>
        <span>{text}</span>
        <button onclick={on_delete} aria-label="Delete">×</button>
    </li>


@app.page("/")
def Home():
    notes = ["Try PyWeb", "Write docs"]

    def delete(i):
        del notes[i]

    <ul>
        for i, text in enumerate(notes):
            <Note text={text} on_delete={lambda: delete(i)} />
    </ul>
What this compiles to
JavaScript
// Home.js
function Note($p) {
  const text = $p["text"] || (() => null);
  const on_delete = $p["on_delete"] || (() => null);
  return [$h("li", null, () => [
      $h("span", null, () => [$dyn(() => text())]),
      $h("button", {"onclick": (e) => { const f = on_delete(); return f ? f(e) : undefined; }, "aria-label": "Delete"}, () => [$t("\u00d7")])
    ])];
}
function Home($s) {
  const notes = $signal("notes" in $s ? $s["notes"] : ["Try PyWeb", "Write docs"], "notes");
  function delete_(i) {
    $py.delp(notes, [i]);
  }
  return [$h("ul", null, () => [$list(() => $py.enumerate(notes()), ([i, text]) => [Note({"text": () => text, "on_delete": () => (() => (delete_(i)))})])])];
}
$mount("Home", Home);

onclick={delete(i)} would also work: an event attribute's expression runs when the event fires, not while rendering.

#3. Persist to a database with server functions

A Model is a table: each annotated attribute is a column, and Field holds its rules. Functions marked @server run only on the server. Calling one from a handler sends a typed RPC request and waits for the result; the compiler generates both ends.

app.pyweb
from pyweb import App, Field, Model, RPCError, server

app = App(title="Notes", database="sqlite:///notes.db")


class Note(Model):
    body: str = Field(min=1, max=500)


def all_notes():
    return Note.query().order("id").all()


@server
def add_note(body: str = Field(min=1, max=500)) -> list:
    Note.create(body=body.strip())
    return all_notes()


@server
def delete_note(note_id: int) -> list:
    Note.get_or_404(note_id).delete()
    return all_notes()


@app.page("/")
def Home():
    notes = all_notes()
    draft = ""
    error = ""

    def save():
        try:
            notes = add_note(draft)
            draft = ""
            error = ""
        except RPCError as e:
            error = str(e)

    def remove(note):
        notes = delete_note(note["id"])

    <main>
        <form onsubmit={save}>
            <input bind={draft} />
            <button>Save</button>
        </form>
        <p class="error">{error}</p>
        <ul>
            for note in notes:
                <li>{note["body"]} <button onclick={remove(note)}>×</button></li>
        </ul>
    </main>
What this compiles to
JavaScript
// Home.js
function Home($s) {
  const notes = $signal("notes" in $s ? $s["notes"] : null, "notes");
  const draft = $signal("draft" in $s ? $s["draft"] : "", "draft");
  const error = $signal("error" in $s ? $s["error"] : "", "error");
  async function save() {
    let e;
    try {
      notes((await $rpc("add_note", {"body": draft()})));
      draft("");
      error("");
    } catch ($err) {
      if ($py.exc($err, ["RPCError"])) {
        e = $err;
        error($py.str(e));
      } else { throw $err; }
    }
  }
  async function remove(note) {
    notes((await $rpc("delete_note", {"note_id": $py.at(note, "id")})));
  }
  return [$h("main", null, () => [
      $h("form", {"onsubmit": save}, () => [
        $h("input", {"$bind": draft}),
        $h("button", null, () => [$t("Save")])
      ]),
      $h("p", {"class": "error"}, () => [$dyn(() => error())]),
      $h("ul", null, () => [$list(() => notes(), (note) => [$h("li", null, () => [
            $t($py.text($py.at(note, "body"))),
            $t(" "),
            $h("button", {"onclick": (async () => (await remove(note)))}, () => [$t("\u00d7")])
          ])])])
    ])];
}
$mount("Home", Home);

While you develop, the notes table is created the first time the Model is used. When the app grows up, pyweb db diff writes a migration for it (see Data & databases).

What the compiler did (run pyweb inspect app.pyweb to see it):

  • notes = all_notes() calls a module function, so it runs on the server for each request; its value is rendered into the HTML and sent to the browser as initial state.
  • save and remove are compiled to async JavaScript functions that call /__pyweb/rpc/add_note and /__pyweb/rpc/delete_note.
  • Note and the database never reach the browser. Querying a Model from a handler is a compile error that points at the line.
  • body: str = Field(min=1, max=500) is checked on every call. An empty note comes back as an RPCError with the code validation_error and the message "Body is required", and except RPCError as e catches it in the browser.

For bigger forms, <Form action={add_note}> builds the inputs from the function's parameters, checks them as you type and works without JavaScript: see Forms & uploads.

#4. Sign-in with sessions

pyweb.session stores a signed, HTTP-only cookie. Pages can redirect before rendering.

app.pyweb
from pyweb import App, redirect, server, session

app = App(title="Notes")


@server
def sign_in(name: str) -> bool:
    if not name.strip():
        return False
    session.login(name.strip())
    return True


@app.page("/login")
def Login():
    name = ""
    error = ""

    def go():
        if sign_in(name):
            window.location.href = "/"
        else:
            error = "Enter a name"

    <form onsubmit={go}>
        <input bind={name} placeholder="Your name" />
        <button>Sign in</button>
        <p>{error}</p>
    </form>


@app.page("/")
def Home():
    user = session.user()
    if not user:
        return redirect("/login")
    who = user["sub"]

    <h1>Hello, {who}</h1>
What this compiles to
JavaScript
// Login.js
function Login($s) {
  const name = $signal("name" in $s ? $s["name"] : "", "name");
  const error = $signal("error" in $s ? $s["error"] : "", "error");
  async function go() {
    if ($py.truth((await $rpc("sign_in", {"name": name()})))) {
      window.location.href = "/";
    } else {
      error("Enter a name");
    }
  }
  return [$h("form", {"onsubmit": go}, () => [
      $h("input", {"$bind": name, "placeholder": "Your name"}),
      $h("button", null, () => [$t("Sign in")]),
      $h("p", null, () => [$dyn(() => error())])
    ])];
}
$mount("Login", Login);

Only who is sent to the browser. The full session record in user stays on the server because browser code never reads it.

In server functions, session.require() returns the session or raises an unauthenticated RPC error. Set PYWEB_AUTH_SECRET in production (see Authentication).

This is the do-it-yourself version. For real accounts, one line, auth = app.use_auth(), adds sign-up with email confirmation, password reset, passkeys, OAuth, two-factor and an admin. Then @app.page("/", login=True) and @server(login=True) keep visitors out, and auth.user() is the person signed in. The SaaS tutorial builds on it.

#5. Make it look good

The UI kit (pyweb.ui) has accessible, themed components; one Theme(...) sets the colours, corners and type for all of them, and for the sign-in and admin pages too. animate= adds motion:

app.pyweb
from pyweb import App, Field, Model, server
from pyweb.ui import Button, Card, CardContent, CardHeader, CardTitle, Theme

app = App(title="Notes", database="sqlite:///notes.db", theme=Theme.preset("emerald"))


class Note(Model):
    body: str = Field(min=1, max=500)


@server
def add_note(body: str = Field(min=1, max=500)) -> list:
    Note.create(body=body.strip())
    return Note.query().order("id").all()


@app.page("/")
def Home():
    notes = Note.query().order("id").all()
    draft = ""

    def save():
        notes = add_note(draft)
        draft = ""

    <main>
        <Card>
            <CardHeader><CardTitle>Notes ({len(notes)})</CardTitle></CardHeader>
            <CardContent>
                <form onsubmit={save}>
                    <input class="pw-control" bind={draft} aria-label="New note" placeholder="Write a note" />
                    <Button type="submit">Save</Button>
                </form>
                <ul>
                    for note in notes:
                        <li animate="fade-up">{note["body"]}</li>
                </ul>
            </CardContent>
        </Card>
    </main>
What this compiles to
JavaScript
// Home.js
// card.pyweb
const { Card, CardHeader, CardTitle, CardContent } = (() => {
  function Card($p) {
    const children = $p["children"] || (() => null);
    const attrs = $p["$rest"] || (() => ({}));
    return [$h("div", {"class": "pw-card", "data-pw-ui": "card", "data-part": "card", "$spread3": () => attrs()}, () => [$dyn(() => children())])];
  }
  function CardHeader($p) {
    const children = $p["children"] || (() => null);
    const attrs = $p["$rest"] || (() => ({}));
    return [$h("div", {"data-part": "header", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
  }
  function CardTitle($p) {
    const children = $p["children"] || (() => null);
    const attrs = $p["$rest"] || (() => ({}));
    return [$h("h3", {"data-part": "title", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
  }
  function CardContent($p) {
    const children = $p["children"] || (() => null);
    const attrs = $p["$rest"] || (() => ({}));
    return [$h("div", {"data-part": "content", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
  }
  return { Card, CardHeader, CardTitle, CardContent };
})();
// button.pyweb
const { Button } = (() => {
  function Button($p) {
    const variant = $p["variant"] || (() => "default");
    const size = $p["size"] || (() => "md");
    const type = $p["type"] || (() => "button");
    const href = $p["href"] || (() => null);
    const loading = $p["loading"] || (() => false);
    const disabled = $p["disabled"] || (() => false);
    const onclick = $p["onclick"] || (() => null);
    const children = $p["children"] || (() => null);
    const attrs = $p["$rest"] || (() => ({}));
    const busy = $computed(() => ($py.truth(loading()) ? "true" : null));
    const part = $computed(() => $py.or($py.m(attrs(), "get", "data-part"), () => "button"));
    return [$when(() => $py.truth(href()), () => [$h("a", {"class": "pw-button", "data-part": () => part(), "data-variant": () => variant(), "data-size": () => size(), "href": () => href(), "aria-disabled": () => ($py.truth(disabled()) ? "true" : null), "onclick": (e) => { const f = onclick(); return f ? f(e) : undefined; }, "$spread7": () => attrs()}, () => [$dyn(() => children())])], () => [$h("button", {"class": "pw-button", "data-part": () => part(), "data-variant": () => variant(), "data-size": () => size(), "type": () => type(), "disabled": () => $py.or(disabled(), () => loading()), "aria-busy": () => busy(), "onclick": (e) => { const f = onclick(); return f ? f(e) : undefined; }, "$spread8": () => attrs()}, () => [
          $when(() => $py.truth(loading()), () => [$h("span", {"class": "pw-spinner", "aria-hidden": "true"})]),
          $dyn(() => children())
        ])])];
  }
  return { Button };
})();
function Home($s) {
  const notes = $signal("notes" in $s ? $s["notes"] : null, "notes");
  const draft = $signal("draft" in $s ? $s["draft"] : "", "draft");
  async function save() {
    notes((await $rpc("add_note", {"body": draft()})));
    draft("");
  }
  return [$h("main", null, () => [Card({"children": () => [
        CardHeader({"children": () => [CardTitle({"children": () => [
            $t("Notes ("),
            $dyn(() => $py.len(notes())),
            $t(")")
          ]})]}),
        CardContent({"children": () => [
          $h("form", {"onsubmit": save}, () => [
            $h("input", {"class": "pw-control", "$bind": draft, "aria-label": "New note", "placeholder": "Write a note"}),
            Button({"type": () => "submit", "children": () => [$t("Save")]})
          ]),
          $h("ul", null, () => [$list(() => notes(), (note) => [$h("li", {"data-pw-motion": JSON.stringify({"animate": "fade-up"}), "style": ((i, s) => s)(null, null, null, "fade-up")}, () => [$t($py.text($py.at(note, "body")))])])])
        ]})
      ]})])];
}
$mount("Home", Home);
  • Card, CardHeader, CardTitle and Button render plain HTML on the server; the kit's stylesheet comes with them. The pw-control class styles your own inputs the same way.
  • Theme.preset("emerald") picks a preset; Theme(accent="#0f766e", radius=6, font="inter") sets your own. In pyweb dev, the toolbar's Theme tab changes it live and saves it into app.pyweb.
  • animate="fade-up" makes each new note slide in; people who ask their system for less motion get none.

See UI kit & motion for every component.

#6. Ship it

Terminal
pyweb check app.pyweb
pyweb build app.pyweb --out dist --production
PYWEB_AUTH_SECRET=change-me pyweb serve dist

The complete, tested versions of these apps live in examples/.

Edit this page on GitHub