Getting Started

This page walks through installing axion, scaffolding a project, and running your first server. See the table of contents for the rest of the guide.

Installation

axion requires Python 3.12 or newer.

pip install axion-framework

Database/ORM support is an optional extra:

pip install "axion-framework[db]"

Scaffolding a project

The CLI generates a complete project layout:

axion startproject my_app
cd my_app

This creates:

my_app/
├── config/
│   └── settings.py   # project settings overrides
├── static/
│   ├── css/
│   ├── js/
│   └── imgs/
├── views/
│   └── index.html    # a Jinja2 template
└── main.py           # the application entry point

Your first application

Edit main.py:

from axion import WebServer
from axion.http import Request, Response

app = WebServer(debug=True)


@app.route("/")
def index(request: Request, response: Response):
    response.render("index.html", title="Welcome to axion")


if __name__ == "__main__":
    app.run()

Run it:

python main.py

Then open http://127.0.0.1:8000/.

With hot reload (restarts on code changes):

axion run main.py --reload

A JSON API route

Route handlers receive a Request and a Response. Send JSON with response.json(...):

from axion import WebServer
from axion.http import Response

app = WebServer(debug=True)


@app.route("/api/health")
def health(response: Response):
    response.json({"status": "ok", "service": "axion"})


if __name__ == "__main__":
    app.run()

By default a route only answers GET. Pass methods to allow others:

@app.route("/api/users", methods=["GET", "POST"])
def users(response: Response):
    ...

Validating request bodies

Annotate a handler argument with a Pydantic model and axion parses and validates the JSON body for you. Invalid or missing bodies produce a 400 automatically.

from pydantic import BaseModel

from axion import WebServer
from axion.http import Response

app = WebServer(debug=True)


class User(BaseModel):
    name: str
    age: int


@app.route("/api/user", methods=["POST"])
def create_user(user: User, response: Response):
    response.json({"message": f"Hello {user.name}", "data": user.model_dump()})


if __name__ == "__main__":
    app.run()

Next steps