---
name: fastapi-python-pro
description: "FastAPI + Pydantic v2 + SQLAlchemy 2: async Python APIs with auto-generated OpenAPI docs. Scaffolds FastAPI apps: dependency injection, Pydantic v2 models, async SQLAlchemy, JWT auth, and Alembic migrations."
license: MIT
---

# FastAPI Python Pro

A scaffolding and code-assist skill for building production async APIs with FastAPI, Pydantic v2, and SQLAlchemy 2.0. It wires up the parts that are fiddly to assemble by hand — async session management, typed request/response models, JWT auth, and Alembic migrations — so you start from a working, idiomatic project instead of a blank `main.py`. Aimed at backend and full-stack developers who want correct async patterns rather than copy-pasted snippets that block the event loop.

## When to use it

- Starting a new service and you want a sane layout (`routers/`, `models/`, `schemas/`, `deps.py`) from the first commit.
- Adding async database access with SQLAlchemy 2.0's `async_sessionmaker` and `AsyncSession` without leaking sessions across requests.
- Bolting JWT login onto an existing app, or migrating Pydantic v1 models to v2.
- You keep getting `greenlet_spawn` errors or "this session is already flushing" and need the dependency lifecycle done right.

## What it does

- Generates Pydantic v2 schemas using `model_config = ConfigDict(from_attributes=True)`, `Field` constraints, and `field_validator` / `model_validator` — not the deprecated v1 `Config` class or `@validator`.
- Sets up async SQLAlchemy with `create_async_engine`, `DeclarativeBase`, and `Mapped[...]` / `mapped_column()` typed models.
- Provides a `get_db()` dependency yielding an `AsyncSession`, injected via `Depends()`, and an `OAuth2PasswordBearer` flow issuing JWTs (python-jose + passlib/bcrypt).
- Initializes Alembic (`alembic init`, `env.py` pointed at your async engine) and writes the first autogenerated revision.
- OpenAPI docs come free at `/docs` and `/redoc` from your typed signatures.

## Example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/fastapi-python-pro/SKILL.md https://claudeskil.com/skills/fastapi-python-pro/SKILL.md

# then, in your project:
"Scaffold a FastAPI app with a User model, async Postgres,
 JWT auth, and an Alembic baseline migration."
```

Generated route:

```python
@router.get("/users/{user_id}", response_model=UserRead)
async def read_user(user_id: int, db: AsyncSession = Depends(get_db)):
    user = await db.get(User, user_id)
    if user is None:
        raise HTTPException(404, "User not found")
    return user
```

## Tips & gotchas

- Define `get_db` with `async with async_sessionmaker() as session: yield session` — never share one session across requests.
- Set `expire_on_commit=False` on the sessionmaker, or attributes become un-awaited and detached after commit.
- Alembic autogenerate needs your models imported into `env.py`'s `target_metadata`, and the async engine wrapped with `run_sync` in `run_migrations_online`.
- Use `await db.execute(select(...))` then `.scalars()`; the old `db.query()` API is removed in 2.0 style.

## FAQ

**Does it require Postgres?** No — defaults to `asyncpg`/Postgres but works with `aiosqlite` for local dev; swap the `DATABASE_URL`.

**Pydantic v1 or v2?** Strictly v2 (`ConfigDict`, `model_dump()`, `Annotated` fields). It can help port v1 code.

**Can I run sync DB drivers?** Possible, but the scaffold assumes async; mixing sync drivers under async routes will block the loop.