Python Async

The Problem: Blocking I/O

Imagine a restaurant with a single waiter. A customer orders food. The waiter walks to the kitchen and stands there staring at the window until the food is ready — 8 minutes later. Meanwhile, no other customers can be served.

This is synchronous (blocking) I/O. The program pauses and does nothing while waiting for the slow operation to complete. In a web server:

• Each database query takes ~10ms
• Each HTTP call to Omise takes ~300ms
• If the server can only handle one request at a time, 100 customers waiting = the last customer waits 30 seconds

A smarter waiter takes orders from table 1, goes to the kitchen and puts in the order, then comes back and takes orders from table 2 while table 1's food is cooking. This is asynchronous I/O.

Synchronous vs Async Code

Here's synchronous Python code (blocks while waiting):

import time

def get_shop_from_db(slug):
    time.sleep(0.01)  # simulates a 10ms database query
    return {"name": "BKK Sports Club"}

def get_availability_from_db(resource_id):
    time.sleep(0.01)  # another 10ms query
    return ["07:00", "08:00", "09:00"]

# This takes 20ms total — the program is BLOCKED during both sleeps
shop = get_shop_from_db("bkk-sports-club")
slots = get_availability_from_db("court-a-uuid")
print(shop, slots)

Here's the async version (frees the thread while waiting):

import asyncio

async def get_shop_from_db(slug):
    await asyncio.sleep(0.01)  # yields control while waiting
    return {"name": "BKK Sports Club"}

async def get_availability_from_db(resource_id):
    await asyncio.sleep(0.01)
    return ["07:00", "08:00", "09:00"]

async def main():
    # Run both queries CONCURRENTLY — total time ~10ms, not 20ms
    shop, slots = await asyncio.gather(
        get_shop_from_db("bkk-sports-club"),
        get_availability_from_db("court-a-uuid"),
    )
    print(shop, slots)

asyncio.run(main())

async def and await

Two keywords change everything:

• async def — marks a function as a "coroutine". You cannot call it normally; you must await it.
• await — pauses this coroutine and gives control back to the event loop until the awaited thing is done. The event loop can then run other coroutines.

Rules:

• You can only use await inside an async def function
• An async def function returns a coroutine object — it doesn't run until you await it
• You must await async functions. Forgetting the await is a common bug — the function just returns a coroutine object that never runs

The Event Loop

Python runs async code on a single thread using an event loop. The loop juggles many coroutines by switching between them whenever one is waiting:

                    EVENT LOOP (single thread)

  Time →  0ms        10ms       20ms      30ms
          │           │          │         │
Request A ████████████░░░░░░░░░░░████████  (DB query 10ms, then processing)
Request B          ████████████░░░░░░░░░░░████
Request C                    ████████████░░░░░░░░░░░████

  ████ = CPU work (running Python code)
  ░░░░ = I/O wait (awaiting DB/HTTP — loop serves other requests)

All 3 requests complete in ~30ms instead of ~60ms (sequential)

The loop itself never blocks. When a coroutine hits await, the loop picks up the next ready coroutine. This is why a single FastAPI server can handle hundreds of simultaneous requests on one CPU core.

Real Project Code: create_booking

Here's the actual booking creation function from routers/public/bookings.py. Notice how many await calls there are — each one is an I/O wait where other requests can run:

@router.post("", response_model=BookingOut, status_code=201)
async def create_booking(body: BookingCreate, session: AsyncSession = Depends(get_db)):
    # ① await — database read (event loop can serve other requests here)
    resource = (await session.execute(
        select(Resource).where(Resource.id == body.resource_id, Resource.is_active == True)
    )).scalar_one_or_none()

    # ② await — another database read
    shop = (await session.execute(
        select(Shop).where(Shop.id == resource.shop_id, Shop.is_active == True)
    )).scalar_one_or_none()

    # ③ await — availability check queries (more DB reads)
    available = await get_available_slots(
        session, body.resource_id, body.booking_date, duration_min, shop.slot_increment_min
    )

    # ④ await — write to database
    session.add(booking)
    await session.commit()   # this is when the DB write actually happens
    await session.refresh(booking)  # re-reads the row to get server-generated values

    # ⑤ await — external HTTP call to Omise (slowest step, ~300ms)
    charge = await create_promptpay_charge(float(total_price), {...})

    return out  # returns immediately, no await needed

While step ⑤ waits 300ms for Omise to respond, the event loop can process dozens of other requests from other users.

async with httpx.AsyncClient

When calling external APIs (Omise, LINE), we use httpx.AsyncClient — an async HTTP client. From services/omise.py:

async def create_promptpay_charge(amount_thb: float, metadata: dict) -> dict:
    amount_satang = round(amount_thb * 100)
    async with httpx.AsyncClient() as client:   # opens a connection pool
        r = await client.post(                  # awaits the HTTP response
            "https://api.omise.co/charges",
            auth=(settings.OMISE_SECRET_KEY, ""),
            json={
                "amount": amount_satang,
                "currency": "thb",
                "source": {"type": "promptpay"},
                "metadata": metadata,
            },
        )
        r.raise_for_status()  # raises exception if status >= 400
        data = r.json()
    return {"charge_id": data["id"], "qr_url": data["source"]["scannable_code"]["image"]["download_uri"]}

async with is like with but for async context managers. It opens the HTTP client, runs the body, then properly closes the connection — even if an exception occurs.

asyncio.run() — The Entry Point

You can't just call an async function from normal Python. You need to start the event loop. The seed script uses this:

async def main() -> None:
    async with AsyncSessionLocal() as session:
        await seed(session)

if __name__ == "__main__":
    asyncio.run(main())  # starts the event loop, runs main(), then stops

FastAPI handles this for you — when you run uvicorn app.main:app, uvicorn starts and manages the event loop automatically.

The Lazy-Load Bug We Hit

The seed script had this code that caused a crash:

for staff in paw_staff:
    staff.services.extend(paw_services)  # ❌ CRASH
    # SQLAlchemy tries to lazy-load staff.services from the DB
    # But lazy loading is SYNCHRONOUS — it can't be awaited
    # In an async context, this is illegal

await session.execute(insert(resource_services), [
    {"resource_id": s.id, "service_id": svc.id}
    for s in paw_staff for svc in paw_services
])
# ✅ This is explicitly awaited — no lazy load needed

The lesson: SQLAlchemy async does not support lazy loading. Any time you access a relationship attribute on an ORM object in async code, it tries to make a synchronous DB call, which crashes. You must either eagerly load relationships with selectinload() or insert directly.