# Python Backend

> Use for Python backend services — FastAPI, Django/DRF, Flask — async patterns, Pydantic, ORM, auth, testing. Triggers — Python server code, pyproject.toml, 'fastapi', 'django', 'flask'.

- Skill: `muxammadmamajonov/python-backend` (Agent Skill)
- Install (CLI): `npx skillmds@latest add muxammadmamajonov/python-backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/muxammadmamajonov/python-backend/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: muxammadmamajonov (https://skillmd.com/u/muxammadmamajonov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/muxammadmamajonov/python-backend

---


# Python Backend Development

## When to use
- Writing REST or GraphQL APIs with FastAPI, Django REST Framework, or Flask
- Designing Pydantic models, serialisers, or schema validation
- Implementing authentication (OAuth2, JWT, session) or permission layers
- Integrating SQLAlchemy, Django ORM, or raw psycopg queries
- Writing tests with pytest (sync and async)
- Profiling and fixing slow endpoints or memory growth

## Workflow

1. **Classify** — sync Django/DRF vs async FastAPI, type of data access, auth model.
2. **Set up the environment**:
   - Python 3.11+ with `pyproject.toml` (PEP 517/518).
   - Dependency manager: `uv` (fast) or `poetry`. Avoid bare `pip install` in CI.
   - Virtual env: always isolated — never install into system Python.
3. **Scaffold**:
   - FastAPI: `app = FastAPI()` in `main.py`; split into `routers/`, `models/`, `schemas/`, `deps/`, `core/`.
   - Django: `django-admin startproject`; apps map to bounded contexts.
4. **Define Pydantic schemas (FastAPI) or serialisers (DRF) before handlers** — they document and enforce the contract.
5. **Implement business logic in service functions**, not in view/route handlers. Handlers parse → call service → serialise response.
6. **Database access**:
   - FastAPI + SQLAlchemy async: use `AsyncSession` with `async with session.begin()`.
   - Django ORM: `select_related` / `prefetch_related` to prevent N+1; use `transaction.atomic` for multi-step writes.
7. **Auth**: FastAPI uses `Depends(get_current_user)`; DRF uses `permission_classes`. Validate JWT with `python-jose` or `authlib`; never decode without signature verification.
8. **Error handling**: FastAPI `HTTPException`; DRF `ValidationError` / `APIException`; Flask `@app.errorhandler`. Always return structured JSON errors.
9. **Test**: `pytest` + `httpx.AsyncClient` for FastAPI; Django `TestClient`; use `pytest-anyio` for async tests. Cover happy path, 422/400 validation, and auth failure.
10. **Harden**: CORS allowlist, rate limiting (`slowapi` / Django Ratelimit), request size limits, SQL injection prevention via ORM/parameterised queries.
11. **Audit** against .claude/checklists/security.md and .claude/checklists/performance.md before deploying.

## Standards

### Type safety
- Use Python 3.10+ type hints everywhere: `def get_user(user_id: int) -> UserSchema:`.
- Run `mypy --strict` or `pyright` in CI.
- Pydantic v2 (`model_config = ConfigDict(strict=True)`) for FastAPI schemas.

### FastAPI specifics
- All path/query/body parameters must be typed; Pydantic validates automatically.
- Use `Depends()` for DB sessions, auth, pagination — not global variables.
- Background tasks (`BackgroundTasks` or Celery) for anything not in the critical path.
- Mount routers with prefix and tags: `app.include_router(users.router, prefix="/users", tags=["users"])`.

### Django/DRF specifics
- Use `get_object_or_404` not bare `Model.objects.get` — prevents 500 on missing records.
- ViewSets for CRUD resources; `APIView` for custom endpoints.
- `settings.py` split: `base.py`, `local.py`, `production.py`; use `django-environ` for env vars.
- Never use `DEBUG=True` in production; `ALLOWED_HOSTS` must be explicit.

### Database (SQLAlchemy)
- Always use parameterised queries — never `f"SELECT ... WHERE id={user_id}"`.
- Define models with explicit `__tablename__`, column types, and constraints.
- Async sessions must be closed; use context managers or `async_scoped_session`.
- Alembic for migrations; check migration against production schema in CI.

### Do not
- Do not use mutable default arguments (`def f(items=[])`).
- Do not catch bare `Exception` without re-raising or logging with full traceback.
- Do not use `pickle` for untrusted data deserialization.
- Do not import at module level what belongs behind a function scope (avoids circular imports and slow startup).
- Do not store secrets in `settings.py`; load from environment and validate at startup.

## Common mistakes to avoid

| Mistake | Fix |
|---|---|
| Blocking I/O in an async FastAPI handler | Use `await asyncio.to_thread(sync_fn)` or an async library. |
| SQLAlchemy lazy load outside session scope | Either `expire_on_commit=False`, eager-load, or keep the session open. |
| Django ORM queries in serialiser `to_representation` | Move queries to the view with `select_related`; serialisers must be query-free. |
| Returning Python exceptions as 500 with stack trace | Catch in error handler; return `{"detail": "..."}` with appropriate status. |
| Tests hitting the production database | Use `pytest-django`'s `@pytest.mark.django_db` with a test DB, or SQLite in-memory. |
| Circular import in FastAPI `Depends` chain | Restructure deps into a `deps.py` module imported by both sides. |

## Output format

- New endpoint: route function + Pydantic schema + service function, all typed.
- Module layout: directory tree showing `routers/`, `schemas/`, `services/`, `models/`, `tests/`.
- Test file: `pytest` functions covering success, 422 validation error, and 401 auth failure.
- Migration: Alembic `upgrade`/`downgrade` functions with comments on intent.

## Related checklists
- .claude/checklists/security.md
- .claude/checklists/performance.md
- .claude/checklists/qa.md

## Related agents
- .claude/agents/core/orchestrator.md
- .claude/agents/engineering/devops-engineer.md