Pagination

Semblance provides helpers for offset/limit pagination.

PageParams

Use PageParams as a base for your input model to get limit and offset:

from semblance import PageParams, PaginatedResponse

class UserListQuery(PageParams, BaseModel):
    name: str = "alice"

PageParams adds limit: int = 10 and offset: int = 0.

Use PaginatedResponse[Model] as the output type:

@api.get("/users", input=UserListQuery, output=PaginatedResponse[User])
def users():
    pass

Responses include items, total, limit, and offset:

{
  "items": [
    {"name": "alice"},
    {"name": "alice"},
    {"name": "alice"}
  ],
  "total": 3,
  "limit": 3,
  "offset": 0
}

curl "http://127.0.0.1:8000/users?name=alice&limit=5&offset=10"

total is the simulated collection size for the request (items generated before applying offset/limit).
In stateless mode, each request generates fresh data. Use SemblanceAPI(stateful=True) if you need persistent collections.