python-dev

---
name: python-dev
description: >
  Python backend development: FastAPI, SQLAlchemy 2.0, Alembic, Pydantic v2,
  async Python, testing with pytest. Use when implementing or modifying API endpoints,
  database models/migrations, services, schemas, or backend tests.
metadata:
  version: "0.1"
  scope: "Python backend / FastAPI / SQLAlchemy / async"
---

# Python Development

## When to use this skill

Use this whenever you are asked to:
- Build or modify FastAPI endpoints, middleware, or dependencies
- Work with SQLAlchemy models, queries, or Alembic migrations
- Define or update Pydantic schemas (request/response, config, validation)
- Write async services, integrations, or data pipelines
- Write or update backend tests (pytest, pytest-asyncio)

## Outcome targets

- **Correctness:** endpoints return proper status codes; data integrity maintained
- **Type safety:** type hints everywhere; Pydantic at all boundaries
- **Async discipline:** no blocking calls in async paths
- **Testability:** behavior-focused tests; mocked external dependencies
- **Clarity:** small functions, meaningful errors, structured logging

---

## Stack and tooling

- **FastAPI** — async endpoints, dependency injection, lifespan events, middleware
- **Pydantic v2** — schemas, settings, validation, serialization
- **SQLAlchemy 2.0** — async sessions, declarative models, `Mapped[]`, `select()` style
- **Alembic** — async migrations, autogenerate, manual revision editing
- **Async Python** — asyncio, asyncpg, httpx, proper concurrency patterns
- **Testing** — pytest, pytest-asyncio, httpx AsyncClient, fixtures, coverage

---

## Coding standards

1. **Async-first** — all I/O (DB, HTTP, LLM) must be async. No blocking calls in async paths.
2. **Type hints everywhere** — use modern Python syntax (PEP 604 unions, generics, etc.).
3. **Pydantic at all boundaries** — request/response models, config, inter-module data. No raw dicts across boundaries.
4. **SQLAlchemy 2.0 only** — no legacy 1.x Query API. Use `select()`, `Mapped[]`, `mapped_column()`.
5. **Dependency injection** — use FastAPI `Depends()` for sessions, config, auth, services.
6. **Structured logging** — use the project's logging setup, not bare `print()`.
7. **Meaningful errors** — `HTTPException` with correct status codes and clear detail messages.
8. **Small, focused functions** — single responsibility. Easy to read, easy to test.

---

## Best-practice rules

### A) Async discipline

- All I/O operations must be awaited — database queries, HTTP calls, file I/O.
- Never call blocking functions (e.g., `time.sleep`, synchronous DB drivers) inside async endpoints or services.
- Use `asyncio.gather` for independent concurrent operations; avoid creating tasks you don't track.
- If you must call blocking code, use `asyncio.to_thread()` or a thread pool executor.

### B) FastAPI patterns

- Use `Depends()` for cross-cutting concerns: DB sessions, auth, config, services.
- Use lifespan events for startup/shutdown (connection pools, caches).
- Prefer path operation decorators that declare response models: `response_model=FooResponse`.
- Use `status_code` parameter on decorators for non-200 success responses (201, 204).
- Group related endpoints in routers; keep `main.py` thin.

### C) Pydantic schemas

- Separate request and response models — don't reuse the same schema for both.
- Use `model_config = ConfigDict(from_attributes=True)` for ORM-backed response models.
- Validate early: let Pydantic reject bad input at the API boundary, not deep in business logic.
- Use `Field()` for constraints, defaults, descriptions, and examples.
- Prefer `Annotated[str, Field(...)]` style for reusable type annotations.

### D) SQLAlchemy 2.0

- Use declarative models with `Mapped[]` and `mapped_column()`.
- Use `select()` statement style — never legacy `session.query()`.
- Prefer `session.scalars(select(...))` over `session.execute(select(...)).scalars()`.
- Use relationships with `lazy="selectin"` or explicit eager loading to avoid N+1 queries.
- Always scope sessions properly — one session per request via dependency injection.

### E) Alembic migrations

- Run `alembic revision --autogenerate -m "description"` after model changes.
- Always review autogenerated migrations — they can miss renames, data migrations, or constraints.
- For data migrations, write explicit `op.execute()` SQL in the migration.
- Test migrations forward and backward (`upgrade` + `downgrade`).

### F) Error handling

- Use `HTTPException` for expected errors (validation, not-found, auth failures).
- Use exception handlers for domain-specific error classes.
- Return consistent error response shapes across the API.
- Log unexpected errors with full context; return generic 500 to clients.
- Never expose internal details (tracebacks, DB errors) in API responses.

### G) Project structure

- Keep business logic in service modules, not in endpoint functions.
- Endpoints should: validate input, call services, return responses.
- Avoid circular imports — use dependency injection and interfaces.
- Group by feature/domain, not by layer, when the project grows.

---

## Testing

- **Write tests alongside implementation** — new endpoints, services, and schema changes should include corresponding tests.
- **Test behavior, not internals** — test inputs -> outputs, status codes, side effects.
- **Use fixtures for shared setup** — DB sessions, test clients, sample data. Keep `conftest.py` organized by scope.
- **Async tests** — use `pytest-asyncio` and `httpx.AsyncClient` for endpoint tests.
- **Mock external dependencies** — LLM calls, external HTTP, scheduled jobs. Never hit real external services in tests.
- **Cover the important paths** — happy path, validation errors (422), auth failures (401/403), not-found (404), and domain-specific edge cases.
- **Run tests after changes** — if tests exist in the area you touched, run them and fix failures before finishing.
- **Coverage awareness** — prioritize coverage for business logic and API boundaries over boilerplate.

---

## Common failure modes (fast triage)

| Symptom | Likely cause | Fix |
|---|---|---|
| `RuntimeWarning: coroutine was never awaited` | Missing `await` on async call | Add `await` |
| Endpoint hangs / slow response | Blocking call in async path | Replace with async equivalent or `to_thread()` |
| `DetachedInstanceError` | Accessing lazy-loaded attribute outside session | Use eager loading or access within session scope |
| N+1 queries | Lazy loading in a loop | Use `selectin` loading or explicit joins |
| Migration autogenerate misses change | Rename or complex alteration | Write manual migration operations |
| 422 with unclear message | Pydantic validation error | Check schema constraints and field types |
| Circular import | Modules importing each other at top level | Use `TYPE_CHECKING` guard or restructure |

---

## Sources

### FastAPI
- FastAPI docs — https://fastapi.tiangolo.com/
- Dependencies — https://fastapi.tiangolo.com/tutorial/dependencies/
- Lifespan events — https://fastapi.tiangolo.com/advanced/events/
- Testing — https://fastapi.tiangolo.com/tutorial/testing/

### Pydantic
- Pydantic v2 docs — https://docs.pydantic.dev/latest/
- Model config — https://docs.pydantic.dev/latest/concepts/config/
- Field types — https://docs.pydantic.dev/latest/concepts/fields/

### SQLAlchemy
- SQLAlchemy 2.0 — https://docs.sqlalchemy.org/en/20/
- Mapped columns — https://docs.sqlalchemy.org/en/20/orm/mapped_attributes.html
- Async session — https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html

### Alembic
- Alembic tutorial — https://alembic.sqlalchemy.org/en/latest/tutorial.html
- Autogenerate — https://alembic.sqlalchemy.org/en/latest/autogenerate.html

### Testing
- pytest — https://docs.pytest.org/
- pytest-asyncio — https://pytest-asyncio.readthedocs.io/
- httpx — https://www.python-httpx.org/

More agent context in jaansokk/cursor_tools

16 other files this repository gives its agents.