thrustly 0.1.1

Typed-first Python web framework for fast, stable APIs.

thrustly

Typed-first Python web framework for fast, stable APIs. Built on Granian and Pydantic.

Alpha -- Thrustly is under active development. APIs may change between releases. Not recommended for production use yet.

Quick Start

uv add thrustly

from thrustly import Thrustly, Request, JSONResponse

app = Thrustly()

@app.get("/")
async def index(request: Request) -> JSONResponse:
    return JSONResponse({"message": "hello, world"})

@app.get("/users/{user_id:int}")
async def get_user(request: Request, user_id: int) -> JSONResponse:
    return JSONResponse({"id": user_id})

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

Features

• Typed path parameters -- {id:int}, {slug:str}, {amount:float}, {uid:uuid}, {filepath:path}
• Pydantic serialization -- return Pydantic models directly from JSONResponse
• Sync and async handlers -- sync handlers run in a thread executor automatically
• Strict mode -- validates handler return type annotations at registration time
• Middleware -- standard ASGI middleware wrapping
• Granian server -- built-in app.run() for development, or use Granian directly in production

Handlers

Handlers receive a Request object and any matched path parameters as keyword arguments:

@app.post("/items")
async def create_item(request: Request) -> JSONResponse:
    data = await request.json()
    return JSONResponse(data, status_code=201)

Sync handlers work too -- they're offloaded to a thread pool so they don't block the event loop:

@app.get("/sync")
def health(request: Request) -> JSONResponse:
    return JSONResponse({"status": "ok"})

Return dicts or lists directly and they'll be serialized as JSON:

@app.get("/simple")
async def simple(request: Request) -> dict:
    return {"works": True}

Strict Mode

Catch handler signature mistakes at import time instead of at request time:

app = Thrustly(strict=True)

@app.get("/x")
def bad(request: Request) -> dict:  # TypeError -- must return Response or subclass
    return {}

Middleware

Standard ASGI middleware pattern -- a function that takes an app and returns an app:

def add_cors(inner_app):
    async def middleware(scope, receive, send):
        async def custom_send(message):
            if message["type"] == "http.response.start":
                headers = list(message.get("headers", []))
                headers.append((b"access-control-allow-origin", b"*"))
                message = {**message, "headers": headers}
            await send(message)
        await inner_app(scope, receive, custom_send)
    return middleware

app.add_middleware(add_cors)

Development

Prerequisites

• Python 3.12+
• uv for package management

Setup

git clone https://github.com/ritwiktiwari/thrustly.git
cd thrustly
make install

Running Tests

make test

# With coverage
make test-cov

# Across all Python versions
make test-matrix

Code Quality

# Run all checks (lint, format, type-check)
make verify

# Auto-fix lint and format issues
make fix

Documentation

make docs-serve

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.