turboapi

TurboAPI API Reference

This document covers the full public API exported by from turbo import * in py-turbo-api.

Package Exports

The package exports these symbols:

Usage Quickstart

from turbo import Turbo, Model, field, Query, Depends, HTTPError

app = Turbo(title="Todo API", version="1.0.0")

class TodoIn(Model):
    title: str = field(min_len=1, max_len=200)

class TodoOut(Model):
    id: int
    title: str

def require_tenant(x_tenant: str = Query(alias="tenant")):
    if not x_tenant:
        raise HTTPError(400, "tenant is required")
    return x_tenant

@app.post("/todos", response_model=TodoOut, status_code=201)
async def create_todo(body: TodoIn, tenant=Depends(require_tenant)):
    return {"id": 1, "title": body.title}

1. App and Routing

Turbo

Create the ASGI app and register routes, middleware, docs, and lifecycle handlers.

Constructor:

Turbo(
    *,
    request_timeout=10.0,
    max_body_bytes=1_000_000,
    max_concurrency=200,
    title="TurboAPI",
    version="0.1.0",
    multipart_max_fields=1000,
    multipart_max_file_size=10_000_000,
    multipart_spool_threshold=1_000_000,
    multipart_max_part_size=10_000_000,
    redirect_slashes=True,
    redirect_status_code=307,
    openapi_url="/openapi.json",
    docs_url="/docs",
    redoc_url="/redoc",
    swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
    swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
    redoc_js_url="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",
    docs_auth=None,
    operation_id_strategy="function",
    operation_id_generator=None,
    shutdown_drain_timeout=10.0,
    dependencies=None,
)

Main methods:

Route decorator extras are available on HTTP methods and route(...):

WebSocket decorator extras on websocket(...):

APIRouter

Sub-router for route grouping and composition.

APIRouter(*, prefix="", tags=None, dependencies=None)

dependencies applies shared dependencies to all routes in the router.

Methods:

include_router(router, prefix="", tags=None, dependencies=None) can add extra dependencies to all included routes.

Usage:

from turbo import Turbo, APIRouter

app = Turbo()
users = APIRouter(prefix="/users", tags=["users"])

@users.get("/{user_id:int}")
async def get_user(user_id: int):
    return {"id": user_id}

app.include_router(users, prefix="/v1")

TurboSettings

Dataclass for env-driven runtime config.

TurboSettings(
    request_timeout=10.0,
    max_body_bytes=1_000_000,
    max_concurrency=200,
    multipart_max_fields=1000,
    multipart_max_file_size=10_000_000,
    multipart_spool_threshold=1_000_000,
    multipart_max_part_size=10_000_000,
    redirect_slashes=True,
    redirect_status_code=307,
    openapi_url="/openapi.json",
    docs_url="/docs",
    redoc_url="/redoc",
    shutdown_drain_timeout=10.0,
    title="TurboAPI",
    version="0.1.0",
)

Methods:

2. Request and WebSocket API

Request

HTTP request wrapper.

Key properties:

Methods:

Notes:

Lifespan state helpers

UploadFile

Uploaded multipart file object.

WebSocket

WebSocket connection wrapper with helpers.

Key properties:

Methods:

ConnectionManager

Tracks active sockets and group membership.

Methods:

Property:

Utilities

3. Responses

Base types

SSE helpers

Content negotiation and cache helpers

Background work

JSON encoders

4. Errors and Dependency Injection

HTTPError

HTTPError(status, message="Error", detail=None)

Raised to return structured error responses (for example raise HTTPError(404, "Not Found")).

Dependency primitives

Parameter markers

Example:

from turbo import Turbo, Query, Header, Depends

app = Turbo()

def auth(authorization: str = Header(alias="authorization")):
    return authorization

@app.get("/items/{item_id:int}")
async def read_item(
    item_id: int,
    q: str = Query(required=False),
    token=Depends(auth),
):
    return {"item_id": item_id, "q": q, "token": token}

5. Validation Models

Model

Typed validation and schema base class.

Optional compatibility:

Field and validator decorators

Example:

from turbo import Model, field, field_validator, model_validator

class UserIn(Model):
    email: str = field(min_len=5, max_len=320)
    age: int = field(ge=13)

    @field_validator("email")
    def normalize_email(cls, value: str):
        return value.strip().lower()

    @model_validator()
    def ensure_domain(cls, data):
        if "@example.com" not in data["email"]:
            raise ValueError("email domain must be @example.com")
        return data

6. Security API

HTTP auth builders

OAuth2 builders

CSRF helpers

WebSocket auth

JWKS cache

7. Middleware

Add middleware via app.use(...) or app.use_asgi(...).

8. Observability

Events:

Helpers:

9. Testing Helpers

TestClient

Synchronous test client for app-level testing.

Constructor:

TestClient(app)

Request methods:

TestResponse

Example:

from turbo import Turbo, TestClient

app = Turbo()

@app.get("/ping")
async def ping():
    return {"ok": True}

def test_ping():
    client = TestClient(app)
    resp = client.get("/ping")
    assert resp.status_code == 200
    assert resp.json() == {"ok": True}

AsyncTestClient

Async test client with lifespan support and HTTP/WebSocket helpers.

WebSocketTestSession

Returned by AsyncTestClient.websocket_connect(...).

10. Job Queue Primitives

InMemoryJobQueue

In-process async queue for background jobs.

Retry and records

External queue adapters

Extension helpers (turbo.extensions)

Integration bridges (turbo.integrations)

12. GitHub Pages Publishing

Use /docs as the Pages source:

  1. Push docs changes to GitHub.
  2. In your repository settings, set Pages source to branch main (or master) and folder /docs.
  3. Use docs/index.md as landing page and link all sections from there.
This site is open source. Improve this page.