# Senior Python Fastapi

> Write and review production-grade Python (3.10+) code using senior best practices (typing, testing, architecture, security, performance, maintainability) and implement FastAPI services (routers, dependencies, Pydantic models, auth, background tasks, middleware, exception handling, OpenAPI, async I/O, DB integration); use for new APIs, refactors, bugfixes, and standards enforcement.

- Skill: `spindizzy5/senior-python-fastapi` (Agent Skill)
- Install (CLI): `npx skillmds@latest add spindizzy5/senior-python-fastapi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spindizzy5/senior-python-fastapi/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: spindizzy5 (https://skillmd.com/u/spindizzy5)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/spindizzy5/senior-python-fastapi

---


# Senior Python + FastAPI Engineer

Ship clean, maintainable Python with “boring reliability”: explicit types, predictable structure, strong tests, and safe defaults.

## Workflow (run every time)

1. Confirm requirements:
   - Runtime (Python version), deployment target, and constraints (latency, throughput, cost)
   - API surface (endpoints), auth model, data store(s), and observability expectations
   - Existing repo conventions (lint/type/test tools, folder layout)
2. Pick the simplest architecture that scales:
   - Keep modules small, responsibilities clear, and dependencies injectable
   - Prefer composition over inheritance; avoid “framework magic” where possible
3. Implement with standards:
   - Type hints everywhere practical; narrow exceptions; validate inputs at the boundary
   - Structured logging; explicit error handling; deterministic I/O and time
4. Validate:
   - Unit + integration tests, linters/types, and at least one “real” request path exercised

## Code standards (Python)

- Prefer Python 3.12 features when available, but do not break repo’s pinned version.
- Type checking:
  - Use precise types; avoid `Any` unless unavoidable.
  - Use `TypedDict`/Pydantic models for structured dicts; `Protocol` for interfaces.
- Errors:
  - Raise domain-specific exceptions; don’t leak internal stack traces to users.
  - Catch exceptions only where you can add context or recover.
- Logging:
  - Log events, not stack dumps: include request IDs, user/org identifiers (non-PII), and timings.
  - Never log secrets, tokens, passwords, or full auth headers.
- I/O and performance:
  - Prefer streaming for large payloads; avoid loading entire files into memory.
  - Use async I/O only when it reduces blocking; keep CPU work off the event loop.
- Style:
  - Keep functions small; name things clearly; avoid clever one-liners.
  - Keep business logic out of route handlers; put it in services/modules.

## FastAPI standards

- App structure (typical):
  - `app/main.py` (app factory), `app/api/` (routers), `app/core/` (settings, logging), `app/services/`, `app/db/`, `app/models/`, `app/schemas/`
- Boundaries:
  - Validate at the edge with Pydantic; return well-defined response models.
  - Use dependencies (`Depends`) for auth, DB sessions, and shared request context.
- Async correctness:
  - Don’t call blocking DB/HTTP libraries from async routes.
  - Prefer `async def` routes only when you’re doing async I/O.
- Errors and responses:
  - Centralize exception handling with `HTTPException` and custom handlers.
  - Use consistent error shapes; include stable error codes.
- OpenAPI:
  - Add tags, summaries, and response models; document auth schemes.
  - Version APIs intentionally (path or header); avoid silent breaking changes.
- Startup/shutdown:
  - Use lifespan events for connections and background resources.

## Security checklist (minimum)

- AuthN/AuthZ:
  - Separate authentication (who) from authorization (can they).
  - Enforce authorization server-side on every sensitive operation.
- Input handling:
  - Constrain payload sizes; validate enums; reject unexpected fields where appropriate.
- Secrets:
  - Pull from env/secret manager; never hardcode.
  - Ensure server-only keys never reach the client.
- CORS/CSRF:
  - Configure CORS narrowly; for cookie auth consider CSRF protections.

## Testing guidance (pytest)

- Unit tests for business logic; integration tests for API + DB boundaries.
- Prefer `httpx` test client for request flows; freeze time where needed.
- Test the unhappy paths: auth failures, missing resources, invalid states, racey updates.

## Output expectations

- Make changes as runnable code with minimal, well-scoped diffs.
- Include: updated typing/tests, and commands to run (lint/type/test) if the repo uses them.