Cursor rule

1---
2description: Enforce the use of FastAPI and its ecosystem for all Python API backends
3globs: ["**/backend/**/*.py", "**/api/**/*.py", "**/app/**/*.py"]
4alwaysApply: false
5---
6 
7# Python FastAPI Backend Rules
8 
9## Framework and Core Dependencies
10 
11For all Python API backend development, use **FastAPI** and its ecosystem:
12 
13### Required Core Stack
14- **FastAPI** (>=0.104.0) - Modern, fast web framework for building APIs
15- **Uvicorn** (>=0.24.0) - ASGI server with `[standard]` extras for production features
16- **Pydantic** (>=2.0.0) - Data validation using Python type annotations
17- **Pydantic Settings** (>=2.0.0) - Settings management using Pydantic models
18 
19### Database and ORM
20- **SQLAlchemy** (>=2.0.0) - Modern ORM with async support
21- **Alembic** (>=1.12.0) - Database migration tool
22- **psycopg2-binary** (>=2.9.9) - PostgreSQL adapter (or appropriate database driver)
23 
24### Development Tools
25- **pytest** (>=7.4.0) - Testing framework
26- **pytest-asyncio** (>=0.21.0) - Async test support
27- **httpx** (>=0.25.0) - HTTP client for testing
28- **black** (>=23.0.0) - Code formatter
29- **isort** (>=5.12.0) - Import sorter
30- **mypy** (>=1.6.0) - Static type checker
31 
32## Code Structure and Patterns
33 
34### Application Structure
35```
36backend/
37├── app/
38│   ├── __init__.py
39│   ├── main.py              # FastAPI app instance
40│   ├── config.py            # Pydantic Settings
41│   ├── database.py          # SQLAlchemy setup
42│   ├── api/                 # API routes
43│   │   ├── __init__.py
44│   │   └── *.py
45│   ├── models/              # SQLAlchemy models
46│   │   ├── __init__.py
47│   │   └── *.py
48│   ├── schemas/             # Pydantic schemas
49│   │   ├── __init__.py
50│   │   └── *.py
51│   ├── crud/                # Database operations
52│   │   ├── __init__.py
53│   │   └── *.py
54│   └── utils/               # Utility functions
55│       ├── __init__.py
56│       └── *.py
57├── alembic/                 # Database migrations
58├── tests/                   # Test files
59├── pyproject.toml          # Project dependencies
60└── alembic.ini             # Alembic configuration
61```
62 
63### FastAPI Application Setup
64 
65```python
66from fastapi import FastAPI
67from fastapi.middleware.cors import CORSMiddleware
68from .config import settings
69 
70app = FastAPI(
71    title=settings.PROJECT_NAME,
72    version="0.1.0",
73    description="API Description",
74    openapi_url=f"{settings.API_V1_PREFIX}/openapi.json",
75    docs_url=f"{settings.API_V1_PREFIX}/docs",
76    redoc_url=f"{settings.API_V1_PREFIX}/redoc",
77)
78 
79# CORS middleware
80app.add_middleware(
81    CORSMiddleware,
82    allow_origins=settings.ALLOWED_ORIGINS,
83    allow_credentials=True,
84    allow_methods=["*"],
85    allow_headers=["*"],
86)
87```
88 
89### Configuration Management
90 
91Use **Pydantic Settings** for configuration:
92 
93```python
94from pydantic_settings import BaseSettings
95 
96class Settings(BaseSettings):
97    PROJECT_NAME: str
98    API_V1_PREFIX: str = "/api/v1"
99    DATABASE_URL: str
100    ALLOWED_ORIGINS: list[str] = ["*"]
101 
102    class Config:
103        env_file = ".env"
104        case_sensitive = True
105 
106settings = Settings()
107```
108 
109### Database Setup
110 
111Use **SQLAlchemy 2.0** with async support:
112 
113```python
114from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
115from sqlalchemy.orm import declarative_base, sessionmaker
116 
117engine = create_async_engine(DATABASE_URL, echo=True)
118AsyncSessionLocal = sessionmaker(
119    engine, class_=AsyncSession, expire_on_commit=False
120)
121Base = declarative_base()
122```
123 
124### Dependency Injection
125 
126Use FastAPI's dependency injection for database sessions:
127 
128```python
129from fastapi import Depends
130from sqlalchemy.ext.asyncio import AsyncSession
131 
132async def get_db() -> AsyncSession:
133    async with AsyncSessionLocal() as session:
134        yield session
135 
136@app.get("/items/")
137async def read_items(db: AsyncSession = Depends(get_db)):
138    # Use db session
139    pass
140```
141 
142### API Routes
143 
144Organize routes using APIRouter:
145 
146```python
147from fastapi import APIRouter
148 
149router = APIRouter()
150 
151@router.get("/items/")
152async def list_items():
153    pass
154 
155@router.post("/items/")
156async def create_item():
157    pass
158```
159 
160### Pydantic Schemas
161 
162Use Pydantic v2 models for request/response validation:
163 
164```python
165from pydantic import BaseModel, Field
166 
167class ItemCreate(BaseModel):
168    name: str = Field(..., min_length=1, max_length=100)
169    description: str | None = None
170 
171class ItemResponse(BaseModel):
172    id: int
173    name: str
174    description: str | None
175 
176    class Config:
177        from_attributes = True  # Pydantic v2
178```
179 
180### CRUD Operations
181 
182Separate database operations into CRUD modules:
183 
184```python
185from sqlalchemy.ext.asyncio import AsyncSession
186from sqlalchemy import select
187 
188async def create_item(db: AsyncSession, item_data: ItemCreate):
189    db_item = Item(**item_data.model_dump())
190    db.add(db_item)
191    await db.commit()
192    await db.refresh(db_item)
193    return db_item
194```
195 
196### Testing
197 
198Use **pytest** with **httpx** for API testing:
199 
200```python
201import pytest
202from httpx import AsyncClient
203from app.main import app
204 
205@pytest.mark.asyncio
206async def test_create_item():
207    async with AsyncClient(app=app, base_url="http://test") as client:
208        response = await client.post("/api/v1/items/", json={"name": "Test"})
209        assert response.status_code == 201
210```
211 
212## Best Practices
213 
2141. **Type Hints**: Always use type hints for function parameters and return types
2152. **Async/Await**: Use async/await for all database operations and I/O-bound tasks
2163. **Error Handling**: Use FastAPI's HTTPException for API errors
2174. **Validation**: Leverage Pydantic for automatic request/response validation
2185. **Documentation**: FastAPI auto-generates OpenAPI docs - use docstrings and response models
2196. **Migrations**: Always use Alembic for database schema changes
2207. **Testing**: Write tests for all API endpoints using pytest
2218. **Code Quality**: Use black (line-length=100) and isort for formatting
2229. **Type Checking**: Use mypy for static type checking
223 
224## Prohibited Patterns
225 
226- ❌ Do NOT use Flask, Django REST Framework, or other web frameworks
227- ❌ Do NOT use synchronous database operations when async is available
228- ❌ Do NOT bypass Pydantic validation
229- ❌ Do NOT manually manage database migrations
230- ❌ Do NOT use `@app.on_event("startup")` for database table creation (use Alembic)
231 
232## Version Requirements
233 
234- Python: >=3.11
235- FastAPI: >=0.104.0
236- SQLAlchemy: >=2.0.0 (use async patterns)
237- Pydantic: >=2.0.0 (use v2 syntax)
238