kui-framework

Kui Web Framework Guide

Kui is a Python web framework supporting both ASGI (async) and WSGI (sync). It provides type-safe parameter binding via Annotated, dependency injection, OpenAPI documentation generation, class-based views, and middleware composition.

ASGI imports: from kui.asgi import ... WSGI imports: from kui.wsgi import ...

The two modules expose nearly identical APIs; ASGI handlers are async def, WSGI handlers are plain def. All examples below use ASGI unless noted.

1. Application

from kui.asgi import Kui, OpenAPI

app = Kui(
    routes=[],                  # Initial routes
    http_middlewares=[],         # App-level HTTP middleware
    socket_middlewares=[],       # App-level WebSocket middleware (ASGI only)
    cors_config=None,           # Optional CORSConfig dict
    exception_handlers={},      # {status_or_exc_type: handler}
    on_startup=[], on_shutdown=[],  # Lifespan callbacks (ASGI only)
    templates=None,             # Optional Jinja2Templates instance
    response_converters={},     # {type: converter_func}
    json_encoder={},            # {type: serializer_func}
)

app is a standard ASGI callable (async def __call__(scope, receive, send)). For WSGI it is a standard def __call__(environ, start_response).

Shared state

app.state.db = create_pool()   # Set once; ImmutableAttribute prevents reassignment

2. Routing

2.1 Decorator style (most common)

@app.router.http.get("/users/{user_id:int}")
async def get_user(user_id: Annotated[int, Path()]):
    return {"id": user_id}

@app.router.http.post("/users")
async def create_user(body: Annotated[UserCreate, Body()]):
    return body, 201

# Any HTTP method
@app.router.http("/health")
async def health():
    return "ok"

Available method shortcuts: .get(), .post(), .put(), .patch(), .delete().

Decorator parameters: path, name=, middlewares=[], summary=, description=, tags=.

2.2 Route objects with << operator