<!-- directive-density: intentional (teaches asyncio/SQLAlchemy anti-patterns; NEVER markers describe real event-loop/race-condition bugs, not aspirational guidance) -->

Python Backend

Patterns for building production Python backends with asyncio, FastAPI, SQLAlchemy 2.0, and connection pooling. Each category has individual rule files in rules/ loaded on-demand.

Quick Reference

Total: 12 rules across 4 categories. House decisions rescued from thinned files live in references/ork-delta.md; vendor material is linked, not restated (see [Upstream coverage](#upstream-coverage-do-not-restate)).

Quick Start

# FastAPI + SQLAlchemy async session
async def get_db() -> AsyncGenerator[AsyncSession, None]:
    async with async_session_factory() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

# Reusable dependency alias (FastAPI's recommended Annotated form)
SessionDep = Annotated[AsyncSession, Depends(get_db)]

@router.get("/users/{user_id}")
async def get_user(user_id: UUID, db: SessionDep):
    result = await db.execute(select(User).where(User.id == user_id))
    return result.scalar_one_or_none()

# Asyncio TaskGroup with timeout
async def fetch_all(urls: list[str]) -> list[dict]:
    async with asyncio.timeout(30):
        async with asyncio.TaskGroup() as tg:
            tasks = [tg.create_task(fetch_url(url)) for url in urls]
    return [t.result() for t in tasks]

Asyncio

Modern Python asyncio patterns using structured concurrency, TaskGroup, and Python 3.11+ features.

Key Patterns

• TaskGroup replaces gather() with structured concurrency and auto-cancellation
• asyncio.timeout() context manager for composable timeouts
• Semaphore for concurrency limiting (rate-limit HTTP requests)
• **except*** with ExceptionGroup for handling multiple task failures
• asyncio.to_thread() for bridging sync code to async

Key Decisions

FastAPI

Production-ready FastAPI patterns for lifespan, dependencies, middleware, and settings.

Key Patterns

• Lifespan with asynccontextmanager for startup/shutdown resource management
• Dependency injection with class-based services and Depends()
• Middleware stack: CORS -> RequestID -> Timing -> Logging
• Pydantic Settings with .env and field validation
• Exception handlers wired to RFC 9457 Problem Details bodies (the body format itself is ork:api-design)

Key Decisions

SQLAlchemy

Async database patterns with SQLAlchemy 2.0, AsyncSession, and FastAPI integration.

Key Patterns

• One AsyncSession per request with expireoncommit=False
• lazy="raise" on relationships to prevent accidental N+1 queries
• selectinload for eager loading collections
• Repository pattern with generic async CRUD
• Bulk inserts chunked 1000-10000 rows for memory management

Key Decisions

Pooling

Database and HTTP connection pooling for high-performance async Python applications.

Key Patterns

• SQLAlchemy pool with poolsize, maxoverflow, poolpreping
• Direct asyncpg pool with minsize/maxsize and connection lifecycle
• aiohttp session with TCPConnector limits and DNS caching
• FastAPI lifespan creating and closing pools at startup/shutdown
• Pool monitoring with Prometheus metrics

Pool Sizing Formula

pool_size = (concurrent_requests / avg_queries_per_request) * 1.5

That formula sizes one process. The fleet-level cap against the server's max_connections, and the pool alert thresholds, are in references/ork-delta.md.

Anti-Patterns (FORBIDDEN)

# NEVER use gather() for new code - no structured concurrency
# NEVER swallow CancelledError - breaks TaskGroup and timeout
# NEVER block the event loop with sync calls (time.sleep, requests.get)
# NEVER use global mutable state for db sessions
# NEVER skip dependency injection (create sessions in routes)
# NEVER share AsyncSession across tasks (race condition)
# NEVER use sync Session in async code (blocks event loop)
# NEVER create engine/pool per request
# NEVER forget to close pools on shutdown

Upstream coverage (do not restate)

Topics removed in the 2026-07-31 wrap-plus-delta thinning. Consult the first-party source; only the ork delta (house policy, scars, working config) belongs in this skill. Where a row says a house subset stays in a rules/ file, that file is still the authority for the OrchestKit position and the link only covers the vendor surface around it.

Related Skills

• ork:architecture-patterns - Clean architecture and layer separation
• ork:async-jobs - Celery/ARQ for background processing
• ork:api-design - Wire contract, RFC 9457 errors, SSE/WebSocket streaming
• ork:database-patterns - Database schema design
• ork:security-patterns - Auth, password hashing, token policy
• ork:testing-integration - pytest-asyncio and httpx ASGI test setup
• ork:devops-deployment - Docker and Kubernetes packaging