Async Handlers
Handlers in async mode must be async def coroutines. Enable async mode with async_mode() and await the server.
A minimal async app
import asyncio
from oxapy import Oxapy, Router, get
@get("/")
async def home(request):
# Asynchronous operations are allowed here
data = await fetch_data_from_database()
return "Hello, World!"
async def main():
await (
Oxapy(("127.0.0.1", 8000))
.attach(Router().route(home))
.async_mode()
.run()
)
if __name__ == "__main__":
asyncio.run(main())
The two differences from a sync app:
- Handlers are declared with
async defand useawait. - The server is started with
app.async_mode().run()inside an asyncmain(), which you run withasyncio.run(main()).
Handlers in async mode cannot be synchronous
async_mode() is a server-wide setting. When async mode is enabled, all route handlers registered on the server must be async def coroutines.
You cannot mix synchronous handlers and async def handlers on the same server instance. The async runtime expects every handler execution to return an awaitable/coroutine; if a handler returns a plain synchronous value (such as a str or dict), the runtime fails when attempting to convert it into a future and returns a 500 Internal Server Error.
# ❌ INCORRECT in async mode: plain def returns a string, causing an exception
@get("/sync")
def sync_handler(request):
return "I will cause an exception in async mode"
# ✅ CORRECT in async mode: declare with async def
@get("/async")
async def async_handler(request):
result = await some_io()
return {"result": result}
If you need to perform blocking synchronous I/O or CPU-bound work inside an async app, run it inside a worker thread using asyncio.to_thread:
import asyncio
@get("/compute")
async def compute(request):
result = await asyncio.to_thread(blocking_call)
return {"result": result}
When to use async mode
Use async_mode() when handlers perform non-blocking I/O — HTTP calls, database queries through an async driver, websocket clients. It keeps the event loop free while those operations are in flight.
In async mode, app.run() returns an awaitable; calling it from a synchronous main() without awaiting will not start the server. Use the pattern above with asyncio.run().
Next steps
- Server Configuration —
async_mode()and other server options - API Reference: Server — the
async_mode()method