TurboAPI Docs

Drop-in FastAPI replacement with a Zig HTTP core. Change one import line — keep everything else.

Installation

Requires Python 3.13+. For maximum throughput use Python 3.14t (free-threaded build).

pip install turboapi

Verify your install:

python -c "import turboapi; print(turboapi.__version__)"

Migrating from FastAPI

In most cases, only the import line changes. Everything else — decorators, dependency injection, middleware, Pydantic models — stays the same.

- from fastapi import FastAPI, HTTPException, Depends
+ from turboapi import TurboAPI, HTTPException, Depends

  app = TurboAPI()   # identical API surface

  @app.get("/items/{id}")
  async def get_item(id: int):
      return {"id": id}

Run with uvicorn as normal:

uvicorn main:app --host 0.0.0.0 --port 8000

Architecture

TurboAPI replaces the Python HTTP/ASGI layer with a Zig-native server. Your Python code never touches the network stack.

Request
  └── Zig TCP listener (8-thread pool)
        └── Zig HTTP parser (zero-copy)
              └── Zig JSON → Python dict (no json.loads)
                    └── dhi validation (native, pre-Python)
                          └── Python route handler
                                └── Zero-copy response pipeline
                                      └── Response

Key properties:

Routing

All standard FastAPI route decorators are supported. Path parameters, query strings, and request bodies work identically.

from turboapi import TurboAPI

app = TurboAPI()

@app.get("/")
async def root():
    return {"status": "ok"}

@app.get("/items/{item_id}")
async def get_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

@app.post("/items")
async def create_item(item: Item):
    return item

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    return {"deleted": item_id}

dhi — Zig-native validation

dhi provides Pydantic-compatible models backed by Zig validators. Constraints are checked in native code before your Python handler runs.

from dhi import Model, Str, Int, Float, EmailStr

class Product(Model):
    name:  Str(min_length=1, max_length=200)
    price: Float(gt=0)
    stock: Int(ge=0)
    email: EmailStr

@app.post("/products")
async def create_product(product: Product):
    # product is already validated — no extra checks needed
    return product

Supported constraint types:

Middleware & CORS

Standard Starlette middleware works unchanged. CORS, GZip, and session middleware are all supported.

from turboapi import TurboAPI
from turboapi.middleware.cors import CORSMiddleware

app = TurboAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

Error handling

HTTPException and custom exception handlers work exactly as in FastAPI.

from turboapi import TurboAPI, HTTPException, Request
from turboapi.responses import JSONResponse

app = TurboAPI()

@app.exception_handler(404)
async def not_found(request: Request, exc: HTTPException):
    return JSONResponse({"error": "not found"}, status_code=404)

@app.get("/items/{id}")
async def get_item(id: int):
    if id < 0:
        raise HTTPException(status_code=400, detail="id must be positive")
    return {"id": id}

Native FFI handlers

For maximum performance, mount a compiled Zig or C shared library as a route handler. Zero Python overhead — requests are handled entirely in native code.

from turboapi import TurboAPI

app = TurboAPI()

# Mount a .so / .dylib — handler is called from Zig directly
app.mount_native("/fast", "./libnative_handler.dylib")

# The native handler signature (Zig):
# pub export fn handle(req: *Request, res: *Response) void

Compatibility

Current alpha compatibility status with FastAPI features: