async-await-checker
Automatically applies when writing Python functions that call async operations. Ensures proper async/await pattern usage (not asyncio.run) to prevent event loop errors.
When & Why to Use This Skill
The async-await-checker is a specialized Python development skill designed to enforce best practices in asynchronous programming. It automatically detects and corrects common async pitfalls, such as the improper use of asyncio.run() within existing event loops and the presence of blocking I/O calls, ensuring your code remains high-performance and error-free in frameworks like FastAPI and Sanic.
Use Cases
- Refactoring legacy synchronous Python code into non-blocking asynchronous functions for modern web backends.
- Debugging and fixing 'RuntimeError: This event loop is already running' by implementing proper await patterns and call chains.
- Optimizing I/O-bound application performance by replacing sequential await statements with parallel execution using asyncio.gather.
- Standardizing asynchronous unit testing by automatically applying @pytest.mark.asyncio decorators and proper async mock configurations.
| name | async-await-checker |
|---|---|
| description | Automatically applies when writing Python functions that call async operations. Ensures proper async/await pattern usage (not asyncio.run) to prevent event loop errors. |
Async/Await Pattern Enforcer
When you are writing or modifying Python functions that:
- Call any function with
async def - Work with async I/O operations (database, HTTP, file I/O)
- Need to run in an async context (FastAPI, async frameworks)
Always apply these patterns:
✅ Correct Pattern
# Helper function
async def fetch_user_data(user_id: str) -> dict:
"""Fetch user data from database."""
result = await db.query(user_id) # ✅ Use await
return result
# API endpoint (FastAPI)
@app.get("/users/{user_id}")
async def get_user(user_id: str) -> dict: # ✅ async def
data = await fetch_user_data(user_id) # ✅ await
return data
# Multiple async calls
async def process_order(order_id: str) -> dict:
# ✅ Run sequentially
user = await fetch_user(order_id)
payment = await process_payment(user.id)
# ✅ Run in parallel with asyncio.gather
results = await asyncio.gather(
send_email(user.email),
update_inventory(order_id),
log_transaction(payment.id)
)
return {"status": "success"}
❌ Incorrect Pattern (Causes Runtime Errors)
# ❌ Don't do this
def fetch_user_data(user_id: str):
result = asyncio.run(db.query(user_id)) # ❌ asyncio.run in event loop = error!
return result
# ❌ Missing async
@app.get("/users/{user_id}")
def get_user(user_id: str): # ❌ Should be async def
data = fetch_user_data(user_id) # ❌ Not awaiting
return data
# ❌ Blocking in async function
async def process_order(order_id: str):
time.sleep(5) # ❌ Blocks event loop! Use asyncio.sleep(5)
return await fetch_data()
Why This Matters
Runtime Error: asyncio.run() fails when called from within an already-running event loop.
Solution: Always use async def + await pattern.
Performance: Blocking operations in async functions defeat the purpose of async code.
Common Async Operations
Database queries:
async def get_records():
async with db.session() as session:
result = await session.execute(query)
return result.fetchall()
HTTP requests:
import httpx
async def fetch_api_data(url: str):
async with httpx.AsyncClient() as client:
response = await client.get(url)
return response.json()
File I/O:
import aiofiles
async def read_file(path: str):
async with aiofiles.open(path, 'r') as f:
content = await f.read()
return content
Error Handling in Async
async def safe_api_call(url: str):
try:
async with httpx.AsyncClient() as client:
response = await client.get(url, timeout=10.0)
response.raise_for_status()
return response.json()
except httpx.TimeoutException:
raise TimeoutError(f"Request to {url} timed out")
except httpx.HTTPStatusError as e:
raise APIError(f"API error: {e.response.status_code}")
Testing Async Code
import pytest
@pytest.mark.asyncio
async def test_fetch_user_data():
"""Test async function"""
result = await fetch_user_data("user_123")
assert result["id"] == "user_123"
@pytest.mark.asyncio
async def test_with_mock():
"""Test with mocked async dependency"""
with patch('module.db.query') as mock_query:
mock_query.return_value = {"id": "test"}
result = await fetch_user_data("test")
assert result["id"] == "test"
❌ Anti-Patterns
# ❌ Mixing sync and async incorrectly
def sync_function():
return asyncio.run(async_function()) # Only OK at top level!
# ❌ Not using asyncio.gather for parallel operations
async def slow_version():
result1 = await operation1() # Waits
result2 = await operation2() # Waits
result3 = await operation3() # Waits
return [result1, result2, result3]
# ✅ Better: parallel execution
async def fast_version():
results = await asyncio.gather(
operation1(),
operation2(),
operation3()
)
return results
# ❌ Forgetting error handling in gather
async def unsafe():
await asyncio.gather(op1(), op2()) # If op1 fails, op2 continues
# ✅ Better: return exceptions
async def safe():
results = await asyncio.gather(
op1(), op2(),
return_exceptions=True
)
for result in results:
if isinstance(result, Exception):
handle_error(result)
Best Practices Checklist
- ✅ Use
async deffor any function that awaits - ✅ Use
awaitfor all async calls - ✅ Use
asyncio.gather()for parallel operations - ✅ Use
async withfor async context managers - ✅ Use
asyncio.sleep()instead oftime.sleep() - ✅ Add proper error handling with try/except
- ✅ Use
@pytest.mark.asynciofor async tests - ✅ Consider timeouts for external operations
- ✅ Use
return_exceptions=Truein gather when appropriate
Auto-Apply
When you see code calling async functions, automatically:
- Make the calling function
async def - Use
awaitfor async calls - Update callers to also be async (chain up)
- Add
@pytest.mark.asyncioto tests - Replace blocking calls with async equivalents
Related Skills
- pytest-patterns - For testing async code
- structured-errors - For async error handling
- tool-design-pattern - For async tools