Air: The Hypermedia-Driven Python Framework

Hypermedia-Driven Python Framework : Build dynamic web applications with Air

In the ever-evolving landscape of Python web development, a new framework has emerged that promises to breathe fresh air into how we build dynamic web applications. Air is a modern Python web framework built on top of FastAPI, Starlette, and Pydantic that brings hypermedia-driven development and Pythonic HTML generation to the forefront . Created by the authors of the renowned "Two Scoops of Django" series, Air represents a thoughtful departure from traditional web frameworks, offering a minimalist yet powerful approach to full-stack development.

The Vision: Pythonic HTML Generation

Air was born from a simple observation: building HTML in Python should feel natural, intuitive, and productive. The framework introduces Air Tags—Python classes that render as HTML, providing an elegant way to generate HTML content without writing template strings or wrestling with HTML syntax in Python code . This approach transforms how developers think about server-rendered HTML, making it as Pythonic as the rest of their application code.

The framework was designed with a clear philosophy: minimal, extensible, and fast to code . It strips away unnecessary complexity while providing the batteries needed for modern web development. The result is a framework that feels both familiar to FastAPI developers and refreshingly new to anyone tired of traditional HTML templating approaches.

Core Architecture and Technology Stack

Built on FastAPI, Starlette, and Pydantic

Air leverages the power of FastAPI as its foundation, meaning your FastAPI knowledge and routes carry over seamlessly . You can serve your API and web pages from one project, eliminating the need for separate frontend and backend servers. The framework inherits FastAPI's performance characteristics and type safety while adding HTML-specific features :

python:

import air

app = air.Air()

@app.get("/")
async def index():
    return air.Html(air.H1("Hello, world!", style="color: blue;"))

This example demonstrates the simplicity: a complete web page rendered with just a few lines of Python code. The H1 Air Tag renders as an HTML heading, with attributes passed as keyword arguments.

Air Tags: Python Classes for HTML Generation

Air Tags are the heart of the framework's HTML generation capabilities. They are Python classes that render as HTML, designed to work seamlessly with any code completion tool . Each tag is typed and documented, providing autocomplete support for attributes and child elements:

python:

from air import Article, H1, P

content = Article(
    H1("Air Tags"),
    P("Air Tags are a fast, expressive way to generate HTML.", class_="subtitle"),
)

When rendered, this produces clean HTML :

html:

<article>
    <h1>Air Tags</h1>
    <p class="subtitle">Air Tags are a fast, expressive way to generate HTML.

</article>

Air Tags handle Python reserved words gracefully. For instance, since class is a reserved word in Python, you use class_ for the HTML class attribute :

python:

air.P("Hello", class_="plain")
# Renders: 
Hello

Similarly, for_ is used for the HTML for attribute, making the experience intuitive for Python developers .

Jinja2 Integration: The Best of Both Worlds

Not everyone wants to write HTML in Python, and Air respects that. Jinja2 is a first-class citizen in the Air ecosystem . You can use Air Tags, Jinja templates, or even mix both in the same view. This flexibility allows teams to adopt Air gradually, using Air Tags for components where type safety matters and Jinja for complex templates with designers' involvement.

python:

from air import JinjaRenderer

jinja = JinjaRenderer(directory="templates")

@app.get("/")
def index(request: Request):
    return jinja(request, name="home.html", context={"title": "My Site"})

Hypermedia-Driven Development with HTMX

Air was built with HTMX in mind, providing utilities that make hypermedia-driven development natural and straightforward . The framework includes dependency injection helpers for detecting HTMX requests, allowing you to return different responses for HTMX partial updates versus full page loads :

python:

import air
from fastapi import Depends

@app.get("/users")
def get_users(is_htmx: bool = Depends(air.is_htmx_request)):
    users = ["Alice", "Bob", "Charlie"]
    if is_htmx:
        # Return just the user list for partial updates
        return air.Ul([air.Li(user) for user in users])
    else:
        # Return full page for regular requests
        return air.Html(
            air.Head(air.Title("Users")),
            air.Body(air.H1("User List"), air.Ul([air.Li(user) for user in users]))
        )

This pattern enables progressive enhancement—your pages work with or without HTMX, and you can progressively enhance the user experience as needed . For form handling, Air makes it easy to respond differently to HTMX requests:

python:

@app.post("/submit")
def submit_form(is_htmx: bool = Depends(air.is_htmx_request)):
    if is_htmx:
        return air.Div("Success!", class_="alert-success")
    else:
        return air.RedirectResponse("/success", status_code=303)

Pydantic-Powered Form Validation

Air embraces Pydantic for HTML form validation, providing two ways to validate incoming form data: dependency injection or directly within views . This approach eliminates the need for manual validation boilerplate and ensures type safety throughout the request lifecycle.

The validation integrates seamlessly with Air's form handling, making it easy to build robust, type-safe forms without the complexity typically associated with web form validation.

Built for AI-Assisted Development

One of Air's most distinctive features is its design for AI-assisted development. The API is fully typed and comprehensively documented in-source, meaning AI coding assistants can understand the framework by reading the installed package without fetching external documentation.

This approach, described by its creators as "the first web framework designed for AI to write," means that AI agents and editors understand the API without needing external docs. For AI context, Air provides complete documentation files (llms-full.txt) that can be consumed by AI assistants, making it easier to get accurate code suggestions and completions.

Deployment and Production Features

Multiple Deployment Paths

Air runs on standard ASGI servers, making deployment straightforward:

bash:

# Using FastAPI CLI
fastapi dev

# Using Uvicorn directly
uv run uvicorn main:app --reload

The framework includes a convenient CLI (air run) for development, but production deployments work with any ASGI server.

Integration with FastAPI APIs

Air apps can be combined with FastAPI applications in two ways :

Mount a FastAPI sub-app: Keep separate apps, with Air serving pages and FastAPI serving your API:

python:

app = air.Air()
api = FastAPI()

@app.get("/")
def landing_page():
    return air.Html(...)

@api.get("/")
def api_root():
    return {"message": "Hello from API"}

app.mount("/api", api)

Wrap a single FastAPI instance: Add Air's features on top of an existing FastAPI app, getting OpenAPI docs, response models, and WebSockets alongside HTML pages.

User Benefits

Reduced Boilerplate

Air eliminates the repetitive code typically associated with HTML responses in FastAPI. No more response_class=HtmlResponse and templates.TemplateResponse for every HTML view—Air handles this automatically . The framework provides intuitive shortcuts designed to expedite coding HTML with FastAPI.

Type-Safe HTML Generation

Air Tags provide type safety for HTML generation. Your editor can autocomplete attributes, your type checker can validate nesting, and you catch mistakes before they reach production. This reduces debugging time and improves code confidence.

Development Speed

The framework is designed to be "fast to code," with intuitive shortcuts and optimizations that make building dynamic web applications in Python a joy . The combination of type safety, Pythonic HTML generation, and HTMX utilities dramatically accelerates development cycles.

Modern, Batteries-Included-but-Minimalist

Air includes modern web development features while remaining intentionally minimalist. The core is small and focused, with optional features available through extra packages . This design philosophy ensures the framework stays fast, maintainable, and easy to understand.

Getting Started

Installation

Installing Air is straightforward using uv or pip :

bash:

uv venv
source .venv/bin/activate
uv init
uv add air

For FastAPI's recommended extras, use:

bash:

uv add "air[standard]"

A Simple Example

Create a main.py file:

python:

import air

app = air.Air()

@app.get("/")
async def index():
    return air.Html(air.H1("Hello, world!", style="color: blue;"))

Run it with:

bash:

fastapi dev

Visit http://127.0.0.1:8000 to see your Air application in action.

Conclusion

Air represents a thoughtful evolution in Python web development, combining the performance and familiarity of FastAPI with Pythonic HTML generation through Air Tags. The framework's commitment to type safety, AI-assisted development, and hypermedia-driven interactions makes it a compelling choice for modern web applications.

Whether you're building a SaaS dashboard, an e-commerce product catalog, or a real-time chat application, Air provides the tools to build it efficiently and maintainably . The framework's minimalism means you learn it quickly, and its extensibility means it grows with you as your needs evolve.

In a world of increasingly complex web frameworks, Air stands as a testament to the power of thoughtful design and pragmatic choices. It's a breath of fresh air for Python web developers who want to build modern, interactive applications without the overhead of JavaScript toolchains or the complexity of traditional full-stack frameworks.