https://github.com/feldroy/air
The new web framework that breathes fresh air into Python web development. Built with FastAPI, Starlette, Pydantic, and HTMX.
https://github.com/feldroy/air
fastapi pydantic python starlette web
Last synced: about 2 months ago
JSON representation
The new web framework that breathes fresh air into Python web development. Built with FastAPI, Starlette, Pydantic, and HTMX.
- Host: GitHub
- URL: https://github.com/feldroy/air
- Owner: feldroy
- License: mit
- Created: 2015-12-11T05:08:09.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2025-08-12T04:53:30.000Z (about 2 months ago)
- Last Synced: 2025-08-12T11:30:20.540Z (about 2 months ago)
- Topics: fastapi, pydantic, python, starlette, web
- Language: Python
- Homepage: https://airdocs.fastapicloud.dev
- Size: 1.56 MB
- Stars: 92
- Watchers: 6
- Forks: 9
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
## Air 💨: The new web framework that breathes fresh air into Python web development. Built with FastAPI, Starlette, and Pydantic.
[](https://github.com/feldroy/air/actions/workflows/python-package.yml?query=branch%3Amain+event%3Apush)
[](https://github.com/feldroy/air/actions/workflows/python-package.yml?query=tag%3Alatest+event%3Apush)
[](https://codecov.io/gh/feldroy/air)
[](https://github.com/feldroy/air/blob/main/LICENSE)
[](https://pypi.org/project/air)
[](https://pepy.tech/projects/air)
[](https://pepy.tech/projects/air)
[](https://pepy.tech/projects/air)
[](https://pypi.org/project/air)
[](https://github.com/feldroy/air/commit/main)
[](https://github.com/feldroy/air/releases/latest)
[](https://github.com/feldroy/air/graphs/contributors)
[](https://discord.gg/aTzWBVrtEs)
[](https://x.com/AirWebFramework)
[](https://bsky.app/profile/airwebframework.bsky.social)
[](https://feldroy.github.io/air)
[](https://fastapi.tiangolo.com)
[](https://docs.pydantic.dev/latest)
[](https://jinja.palletsprojects.com/en/latest)
[](https://docs.astral.sh)
> [!CAUTION]
> Air is currently in an alpha state. While breaking changes are becoming less common, nevertheless, anything and everything could change.
> [!IMPORTANT]
> If you have an idea for a new feature, discuss it with us by opening an issue before writing any code. Do understand that we are working to remove features from core, and for new features you will almost always create your own package that extends or uses Air instead of adding to this package. This is by design, as our vision is for the Air package ecosystem to be as much a "core" part of Air as the code in this minimalist base package.
## Why use Air?
- **Powered by FastAPI** - Designed to work with FastAPI so you can serve your API and web pages from one app
- **Fast to code** - Tons of intuitive shortcuts and optimizations designed to expedite coding HTML with FastAPI
- **Air Tags** - Easy to write and performant HTML content generation using Python classes to render HTML
- **Jinja Friendly** - No need to write `response_class=HtmlResponse` and `templates.TemplateResponse` for every HTML view
- **Mix Jinja and Air Tags** - Jinja and Air Tags both are first class citizens. Use either or both in the same view!
- **HTMX friendly** - We love HTMX and provide utilities to use it with Air
- **HTML form validation powered by pydantic** - We love using pydantic to validate incoming data. Air Forms provide two ways to use pydantic with HTML forms (dependency injection or from within views)
- **Easy to learn yet well documented** - Hopefully Air is so intuitive and well-typed you'll barely need to use the documentation. In case you do need to look something up we're taking our experience writing technical books and using it to make documentation worth boasting about
---
**Documentation**: https://airdocs.fastapicloud.dev
**Source Code**: https://github.com/feldroy/air
## Installation
Install using `pip install -U air` or `conda install air -c conda-forge`.
For `uv` users, just create a virtualenv and install the air package, like:
```sh
uv venv
source .venv/bin/activate
uv add air
uv add "fastapi[standard]"
```
## A Simple Example
Create a `main.py` with:
```python
import air
app = air.Air()
@app.get("/")
async def index():
return air.Html(air.H1("Hello, world!", style="color: blue;"))
```
Run the app with:
```sh
fastapi dev
```
> [!NOTE]
> This example uses Air Tags, which are Python classes that render as HTML. Air Tags are typed and documented, designed to work well with any code completion tool.
> You can also run this with `uv run uvicorn main:app --reload` if you prefer using Uvicorn directly.
Then open your browser to to see the result.
## Combining FastAPI and Air
Air is just a layer over FastAPI. So it is trivial to combine sophisticated HTML pages and a REST API into one app.
```python
import air
from fastapi import FastAPI
app = air.Air()
api = FastAPI()
@app.get("/")
def landing_page():
return air.Html(
air.Head(air.Title("Awesome SaaS")),
air.Body(
air.H1("Awesome SaaS"),
air.P(air.A("API Docs", target="_blank", href="/api/docs")),
),
)
@api.get("/")
def api_root():
return {"message": "Awesome SaaS is powered by FastAPI"}
# Combining the Air and and FastAPI apps into one
app.mount("/api", api)
```
## Combining FastAPI and Air using Jinja2
Want to use Jinja2 instead of Air Tags? We've got you covered.
```python
import air
from air.requests import Request
from fastapi import FastAPI
app = air.Air()
api = FastAPI()
# Air's JinjaRenderer is a shortcut for using Jinja templates
jinja = air.JinjaRenderer(directory="templates")
@app.get("/")
def index(request: Request):
return jinja(request, name="home.html")
@api.get("/")
def api_root():
return {"message": "Awesome SaaS is powered by FastAPI"}
# Combining the Air and and FastAPI apps into one
app.mount("/api", api)
```
Don't forget the Jinja template!
```html
Awesome SaaS
Awesome SaaS