Introduction

Stario is a Python framework for building web apps. You write one async function for each route. The function gets the request and a writer. You put HTML into the writer, and the page is done. When a page needs to change while someone is looking at it, you keep the writer open and send new HTML. There is no template language, no client build step, and no separate server to install.

Here is a complete Stario app.

import asyncio

from stario import App, Context, Route, Span, Writer, h, serve

HOME = Route("GET /")

async def home(c: Context, w: Writer) -> None:

    page = h.HtmlDocument(

        h.Head(h.Title("Hello")),

        h.Body(h.H1("Hello, Stario")),

    )

    w.html(page)

async def bootstrap(app: App, span: Span):

    app.add(HOME, home)

    yield

if __name__ == "__main__":

    asyncio.run(serve(bootstrap))

Save it as main.py, run uv add stario and then uv run python main.py, and open http://127.0.0.1:8000. That is the whole app: one route, one handler, one bootstrap. Install has the details.

Every Stario app is this file, grown. Hello world builds it line by line. Stario in ten minutes gives you the five ideas behind it.

Who this book is for#

• I assume you know Python and have written an async def.

• I assume you know what an HTTP request and an HTML page are.

• I do not assume you have used Stario, Datastar, or any particular web framework.

• I do not assume you want realtime. Most pages do not need it. Stario makes it available when a page does.

What you get#

A Stario app is a few plain parts, and you can see all of them.

A Route is one HTTP method on one path. It is a value. You register it, and you build links from it. There is no decorator and no name lookup.

A handler is async def handler(c, w). c is the request. w is the response. The handler writes; it does not return.

HTML is Python. h.Div(...) builds a tree. A view is a function that returns one.

A live page keeps one response open and pushes HTML through it. Datastar, a small browser library, puts each patch into the page.

Telemetry follows the request. Every request is a span. You can watch spans in the terminal while you work, or store them in SQLite and query them later.

That is most of the vocabulary. The rest of this book is detail.

How to read this book#

Tutorials build three apps: a page, a live board, and a project with a database and tests. They are cumulative and they move quickly.

How-tos each do one job: serve a file, sign a user in, test a handler, deploy.

Explanation tells you why things are shaped this way. Read it when a design choice surprises you.

Reference states the contract for each type and module. Read it when you need exact behaviour.

One caveat#

Stario is my project, and this book has opinions. I will tell you what I would do and why. If you prefer another shape, Stario will not stop you. The goal is to remove obstacles from your way, not to put my style in it.

— Adam