Air Web Framework

The Air API provides a comprehensive set of tools for building web applications. Key functional areas include:

• Application Lifecycle: Use Applications to instantiate your app.
• Data Handling: Use Forms for user data validation and Requests (an HTMX utility) for dependency injection.
• UI & Templating: Leverage Tags (HTML), SVG tags, Layouts (including mvcss and picocss support), and Templating (Jinja and Air Tag renderers).
• Server Logic: Manage Routing for app composition, Middleware for request processing, and Background Tasks for asynchronous work.
• Communication: Handle Responses via AirResponse or SSEResponse (Server Sent Events), and manage errors via Exception Handlers and specific Exceptions.

Use air.AirRouter() to create a router that can be included into a main air.Air() application. This allows you to modularize your application by knitting together several Python modules, each with its own Air views. Routers allow for the sharing of sessions and other application states across the included modules.

To use a router:

1. Instantiate air.AirRouter() in a module.
2. Define pages using the @router.page decorator.
3. Include the router in your main app using app.include_router(router_instance).

# cart.py
import air

router = air.AirRouter()

@router.page
def cart():
    return air.H1("I am a shopping cart")

# main.py
import air
from cart import router as cart_router

app = air.Air()
app.include_router(cart_router)

@app.page
def index():
    return air.H1("Home page")

An Air Tag is a core abstraction in Air. For detailed conceptual explanations of how they work, refer to the concepts document about tags.

Because Air Tags often correspond directly to HTML elements, their documentation is split across several specialized pages to ensure efficient compilation. If you are looking for documentation on a specific tag that maps to an HTML element, consult the categorized lists:

• A-D
• E-M
• N-S
• T-Z

As of version 0.46.0, the JinjaRenderer supports an as_string=True option. This allows you to render Jinja templates as strings and embed them directly into Air tag trees, enabling an incremental migration from Jinja-based views to Air Tags.

# Example pattern enabled by JinjaRenderer(as_string=True)
# Rendered Jinja content can be embedded directly in Air tag trees

As of version 0.48.1, Air restores standard Starlette-like behavior where every GET route automatically responds to HTTP HEAD requests with a 200 status, correct headers, and an empty body. This applies to the following route decorators:

• @app.page
• @app.get
• @router.page
• @router.get

Previously, these routes would return a 405 Method Not Allowed error because FastAPI's routing layer does not automatically add HEAD to GET routes.

Air supports both asynchronous (async def) and synchronous (def) route handlers. When you define a handler using plain def, Air runs it in a Starlette threadpool. This allows you to perform blocking operations like database queries or file I/O directly within your handler without blocking the main event loop or requiring async/await syntax.

# Synchronous handler (runs in a threadpool)
@app.page
def my_sync_page(request: air.Request):
    # Blocking I/O is safe here
    data = db.fetch_all("SELECT * FROM table")
    return air.div(air.text(f"Data: {data}"))

# Asynchronous handler
@app.page
async def my_async_page(request: air.Request):
    data = await db.fetch_all("SELECT * FROM table")
    return air.div(air.text(f"Data: {data}"))

Air is built on top of FastAPI, which in turn is built on top of Starlette. Because of this architecture, Air is essentially FastAPI with enhanced features for working with HTML and HTMX.

Key takeaway for developers: Anything you can do with FastAPI or Starlette, you can also do with Air. Air provides a high-level layer for web page generation while maintaining the full capabilities of the underlying ASGI toolkit.