trove-python

Session Init

This skill ships Trove conventions. Prefer existing project patterns over generic best practices when they conflict.

Python / FastAPI Conventions

Imports

• Top-level imports only — never inline imports inside functions
• Organization: stdlib → third-party → local (isort-compatible)
• Use from __future__ import annotations when needed for forward refs

Type Hints

• All function signatures must have type hints (params + return)
• Use from typing import for complex types (Optional, Union, etc.)
• Pydantic models for all request/response schemas
• Prefer X | None over Optional[X] (Python 3.10+)

Async Patterns (CRITICAL)

Never call blocking I/O in async functions:

# BAD — blocks the event loop
async def get_user(user_id: str):
    response = requests.get(f"/users/{user_id}")  # BLOCKING!
    time.sleep(1)  # BLOCKING!

# GOOD — non-blocking
async def get_user(user_id: str):
    async with httpx.AsyncClient() as client:
        response = await client.get(f"/users/{user_id}")
    await asyncio.sleep(1)

• Use httpx.AsyncClient for HTTP (not requests)
• Use asyncio.sleep for delays (not time.sleep)
• Use async with for context managers (DB sessions, HTTP clients)

Logging

# INFO/DEBUG — f-strings are fine (fast path, no Sentry indexing needed)
logger.info(f"Processing user {user_id}")

# WARNING/ERROR — static message + extra dict (enables Sentry grouping)
logger.warning("Payment failed", extra={"user_id": user_id, "amount": amount})

# EXCEPTION — use in except blocks (auto-captures stack trace)
try:
    await process()
except Exception:
    logger.exception("Processing failed", extra={"user_id": user_id})

Never use sentry_sdk.capture_exception() — use logger.exception() instead.

SQLAlchemy Async

# Always use async session context manager
async with get_async_session() as session:
    result = await session.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()

# Eager loading to avoid N+1
stmt = select(User).options(selectinload(User.posts)).where(User.id == user_id)