Python Microservice

Python Microservice

Overview

A Python service is six things: config, an HTTP surface, state (DB + cache), async work, outbound calls, and operability. Python's specific hazard is that the wrong call in the wrong place silently destroys concurrency — one blocking line in an async def stalls every request on that worker, and nothing warns you. Most of this skill is about staying on the correct side of that line.

Verified against Python 3.14 and FastAPI 0.141.x as of 2026-08. Library versions throughout come from the PyPI registry, not from blog posts.

When to Use

• Starting a new Python service, or adding an endpoint/worker/MCP tool
• Choosing a framework, ORM, cache, task queue, or server
• Reviewing Python service code for production-readiness
• Building an MCP server (FastMCP) — see references/fastmcp.md
• Diagnosing: "fast locally, slow under load", event-loop stalls, connection-pool exhaustion, N+1 queries, memory growth across workers, wrong Prometheus numbers
• Containerising a Python service, or moving one to Python 3.13/3.14

Not for: data pipelines, notebooks, ML training, or scripts.

Step 0: Choose the framework

On Python 3.14 you need FastAPI ≥ 0.128.1 — PEP 649 changed annotation evaluation, and older FastAPI breaks on endpoints with TYPE_CHECKING-only imports in their signatures. Upgrade both together. Full comparison in references/frameworks.md.

Quick Reference

Bootstrap a new service

myservice/
  pyproject.toml             # uv-managed, PEP 621
  uv.lock                    # committed
  src/myservice/
    __init__.py
    main.py                  # app factory + lifespan
    config.py                # pydantic-settings, validated
    api/                     # routers
    services/                # business logic — no HTTP/ORM types
    repositories/            # DB access
    clients/                 # outbound HTTP
    models.py                # SQLAlchemy models
    schemas.py               # Pydantic request/response models
  migrations/                # Alembic
  tests/
  Dockerfile

1. uv init + uv add fastapi uvicorn[standard] sqlalchemy[asyncio] asyncpg pydantic-settings
2. Settings(BaseSettings) instantiated at import — a missing env var must fail at startup, not at 3am in a request path.
3. lifespan context manager creating the httpx client and DB engine once, closing both on shutdown. Never @app.on_event (deprecated).
4. Keep models (SQLAlchemy) and schemas (Pydantic) separate — returning ORM objects directly is how password_hash leaks.
5. Annotated[Session, Depends(get_session)] type aliases, not = Depends(...).
6. Exception handlers for one error envelope; override the framework's defaults too.
7. /healthz (liveness) and /readyz (readiness) — different checks.
8. ruff check + ruff format + mypy in CI.

The non-negotiables

1. Never block the event loop. No requests, time.sleep, sync DB driver, or CPU loop inside async def. Use the async equivalent, or asyncio.to_thread, or declare the handler plain def so the framework runs it in a threadpool.
2. Every HTTP call has an explicit timeout. requests defaults to waiting forever. httpx defaults to 5 s — better, still be explicit with Timeout(connect=, read=, write=, pool=).
3. One httpx client per process, created in lifespan, reused. Per-request clients throw away connection pooling entirely.
4. Config validated at startup via pydantic-settings. Fail fast.
5. asyncio.TaskGroup, not gather. gather's defaults leave siblings running unsupervised on failure, or hide exceptions in the results list.
6. Hold references to background tasks. A bare asyncio.create_task(...) can be garbage-collected mid-flight and silently never finish.
7. Separate Pydantic schemas from ORM models, and set response_model.
8. Sessions are per-request, never global, never shared across tasks.
9. prometheus_client needs multiprocess mode with multiple workers, or your metrics are one random worker's view.
10. Re-raise CancelledError. Swallowing it breaks graceful shutdown.

Reference Map

Common Mistakes