@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/fastapi/rules/pydantic.md

@@ -0,0 +1,433 @@
+---
+paths:
+  - "**/schemas/**/*.py"
+  - "**/models/**/*.py"
+  - "**/*_schema.py"
+  - "**/*_model.py"
+---
+
+# Python Validation (Pydantic)
+
+## Basic Models
+
+```python
+# schemas/user.py
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, EmailStr, Field, field_validator
+from uuid import UUID
+
+
+class UserBase(BaseModel):
+    email: EmailStr
+    name: str = Field(..., min_length=2, max_length=100)
+
+
+class UserCreate(UserBase):
+    password: str = Field(..., min_length=8)
+
+    @field_validator("password")
+    @classmethod
+    def validate_password(cls, v: str) -> str:
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain uppercase letter")
+        if not any(c.islower() for c in v):
+            raise ValueError("Password must contain lowercase letter")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("Password must contain digit")
+        if not any(c in "!@#$%^&*" for c in v):
+            raise ValueError("Password must contain special character")
+        return v
+
+
+class UserUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=2, max_length=100)
+    phone: Optional[str] = None
+
+
+class UserResponse(UserBase):
+    id: UUID
+    is_active: bool
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+```
+
+## Nested Models
+
+```python
+# schemas/order.py
+from pydantic import BaseModel, Field, model_validator
+from typing import List
+from decimal import Decimal
+
+
+class OrderItem(BaseModel):
+    product_id: UUID
+    quantity: int = Field(..., gt=0, le=100)
+    price: Decimal = Field(..., gt=0, decimal_places=2)
+
+
+class OrderCreate(BaseModel):
+    items: List[OrderItem] = Field(..., min_length=1)
+    shipping_address: str = Field(..., min_length=10)
+    notes: Optional[str] = None
+
+    @model_validator(mode="after")
+    def validate_order(self) -> "OrderCreate":
+        total_items = sum(item.quantity for item in self.items)
+        if total_items > 100:
+            raise ValueError("Maximum 100 items per order")
+        return self
+
+
+class OrderResponse(BaseModel):
+    id: UUID
+    items: List[OrderItem]
+    total: Decimal
+    status: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+```
+
+## Custom Types
+
+```python
+# schemas/types.py
+from typing import Annotated
+from pydantic import AfterValidator, BeforeValidator
+import re
+
+
+def validate_phone(v: str) -> str:
+    pattern = r"^\+?[1-9]\d{1,14}$"
+    if not re.match(pattern, v):
+        raise ValueError("Invalid phone number format")
+    return v
+
+
+def validate_slug(v: str) -> str:
+    pattern = r"^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    if not re.match(pattern, v):
+        raise ValueError("Invalid slug format")
+    return v
+
+
+def normalize_email(v: str) -> str:
+    return v.lower().strip()
+
+
+PhoneNumber = Annotated[str, AfterValidator(validate_phone)]
+Slug = Annotated[str, AfterValidator(validate_slug)]
+NormalizedEmail = Annotated[str, BeforeValidator(normalize_email)]
+
+
+# Usage
+class UserCreate(BaseModel):
+    email: NormalizedEmail
+    phone: Optional[PhoneNumber] = None
+
+
+class PostCreate(BaseModel):
+    title: str
+    slug: Slug
+```
+
+## Enum Validation
+
+```python
+# schemas/enums.py
+from enum import Enum
+
+
+class UserRole(str, Enum):
+    USER = "user"
+    ADMIN = "admin"
+    MODERATOR = "moderator"
+
+
+class OrderStatus(str, Enum):
+    PENDING = "pending"
+    PROCESSING = "processing"
+    SHIPPED = "shipped"
+    DELIVERED = "delivered"
+    CANCELLED = "cancelled"
+
+
+# Usage
+class UserCreate(BaseModel):
+    email: EmailStr
+    role: UserRole = UserRole.USER
+
+
+class OrderUpdate(BaseModel):
+    status: OrderStatus
+```
+
+## Computed Fields
+
+```python
+# schemas/product.py
+from pydantic import BaseModel, computed_field
+from decimal import Decimal
+
+
+class Product(BaseModel):
+    name: str
+    price: Decimal
+    discount_percent: int = 0
+
+    @computed_field
+    @property
+    def discounted_price(self) -> Decimal:
+        discount = self.price * self.discount_percent / 100
+        return self.price - discount
+
+    @computed_field
+    @property
+    def display_name(self) -> str:
+        if self.discount_percent > 0:
+            return f"{self.name} ({self.discount_percent}% off)"
+        return self.name
+```
+
+## Conditional Validation
+
+```python
+# schemas/payment.py
+from pydantic import BaseModel, model_validator
+from typing import Optional
+
+
+class PaymentMethod(str, Enum):
+    CREDIT_CARD = "credit_card"
+    BANK_TRANSFER = "bank_transfer"
+    PAYPAL = "paypal"
+
+
+class PaymentCreate(BaseModel):
+    method: PaymentMethod
+    amount: Decimal
+
+    # Credit card fields
+    card_number: Optional[str] = None
+    expiry_date: Optional[str] = None
+    cvv: Optional[str] = None
+
+    # Bank transfer fields
+    bank_account: Optional[str] = None
+    routing_number: Optional[str] = None
+
+    # PayPal fields
+    paypal_email: Optional[EmailStr] = None
+
+    @model_validator(mode="after")
+    def validate_payment_details(self) -> "PaymentCreate":
+        if self.method == PaymentMethod.CREDIT_CARD:
+            if not all([self.card_number, self.expiry_date, self.cvv]):
+                raise ValueError("Card details required for credit card payment")
+
+        elif self.method == PaymentMethod.BANK_TRANSFER:
+            if not all([self.bank_account, self.routing_number]):
+                raise ValueError("Bank details required for bank transfer")
+
+        elif self.method == PaymentMethod.PAYPAL:
+            if not self.paypal_email:
+                raise ValueError("PayPal email required")
+
+        return self
+```
+
+## Generic Pagination
+
+```python
+# schemas/pagination.py
+from typing import Generic, TypeVar, List
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: List[T]
+    total: int
+    page: int
+    size: int
+    pages: int
+
+    @classmethod
+    def create(
+        cls,
+        items: List[T],
+        total: int,
+        page: int,
+        size: int,
+    ) -> "PaginatedResponse[T]":
+        return cls(
+            items=items,
+            total=total,
+            page=page,
+            size=size,
+            pages=(total + size - 1) // size,
+        )
+
+
+class PaginationParams(BaseModel):
+    page: int = Field(1, ge=1)
+    size: int = Field(10, ge=1, le=100)
+
+    @property
+    def offset(self) -> int:
+        return (self.page - 1) * self.size
+
+
+# Usage
+# PaginatedResponse[UserResponse]
+```
+
+## FastAPI Integration
+
+```python
+# api/users.py
+from fastapi import APIRouter, HTTPException, Depends, Query
+from pydantic import ValidationError
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.post("/", response_model=UserResponse, status_code=201)
+async def create_user(
+    user: UserCreate,
+    db: AsyncSession = Depends(get_db),
+) -> UserResponse:
+    # Validation already done by Pydantic
+    existing = await db.execute(
+        select(User).where(User.email == user.email)
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=409, detail="Email already registered")
+
+    new_user = User(**user.model_dump())
+    db.add(new_user)
+    await db.commit()
+    await db.refresh(new_user)
+
+    return UserResponse.model_validate(new_user)
+
+
+@router.get("/", response_model=PaginatedResponse[UserResponse])
+async def list_users(
+    pagination: PaginationParams = Depends(),
+    search: Optional[str] = Query(None, min_length=1),
+    db: AsyncSession = Depends(get_db),
+) -> PaginatedResponse[UserResponse]:
+    query = select(User)
+
+    if search:
+        query = query.where(User.name.ilike(f"%{search}%"))
+
+    total = await db.scalar(select(func.count()).select_from(query.subquery()))
+    users = await db.scalars(
+        query.offset(pagination.offset).limit(pagination.size)
+    )
+
+    return PaginatedResponse.create(
+        items=[UserResponse.model_validate(u) for u in users],
+        total=total,
+        page=pagination.page,
+        size=pagination.size,
+    )
+```
+
+## Custom Error Messages
+
+```python
+# schemas/user.py
+from pydantic import BaseModel, Field
+
+
+class UserCreate(BaseModel):
+    email: EmailStr = Field(
+        ...,
+        description="User email address",
+        json_schema_extra={"example": "user@example.com"},
+    )
+    password: str = Field(
+        ...,
+        min_length=8,
+        max_length=100,
+        description="User password (min 8 characters)",
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "email": "john@example.com",
+                    "password": "SecurePass123!",
+                }
+            ]
+        }
+    }
+```
+
+## Anti-patterns
+
+```python
+# BAD: Using dict instead of Pydantic model
+@router.post("/users")
+async def create_user(data: dict):  # No validation!
+    email = data.get("email")
+
+
+# GOOD: Use Pydantic models
+@router.post("/users")
+async def create_user(data: UserCreate):
+    email = data.email  # Validated and typed
+
+
+# BAD: Manual validation
+class UserCreate(BaseModel):
+    email: str
+
+    def validate_email(self):
+        if "@" not in self.email:
+            raise ValueError("Invalid email")
+
+
+# GOOD: Use built-in validators
+class UserCreate(BaseModel):
+    email: EmailStr  # Automatic validation
+
+
+# BAD: Catching all exceptions
+try:
+    user = UserCreate(**data)
+except Exception as e:
+    return {"error": str(e)}
+
+
+# GOOD: Catch specific validation errors
+from pydantic import ValidationError
+
+try:
+    user = UserCreate(**data)
+except ValidationError as e:
+    return {"errors": e.errors()}
+
+
+# BAD: Not using model_config for ORM
+class UserResponse(BaseModel):
+    id: UUID
+    name: str
+    # This won't work with SQLAlchemy objects
+
+
+# GOOD: Enable from_attributes
+class UserResponse(BaseModel):
+    id: UUID
+    name: str
+
+    model_config = {"from_attributes": True}
+```

package/configs/fastapi/rules/responses.md

@@ -0,0 +1,251 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI Response Patterns
+
+## Response Models
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+# GOOD - explicit response model
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    name: str
+    created_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+@router.get("/users/{user_id}", response_model=UserResponse)
+async def get_user(user_id: int, db: DbSession) -> User:
+    user = await db.get(User, user_id)
+    if not user:
+        raise HTTPException(404, "User not found")
+    return user  # Automatically serialized to UserResponse
+```
+
+## Pagination Response
+
+```python
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+class Page(BaseModel, Generic[T]):
+    items: list[T]
+    total: int
+    page: int
+    size: int
+    pages: int
+
+    @classmethod
+    def create(cls, items: list[T], total: int, page: int, size: int) -> "Page[T]":
+        return cls(
+            items=items,
+            total=total,
+            page=page,
+            size=size,
+            pages=(total + size - 1) // size,
+        )
+
+@router.get("/users", response_model=Page[UserResponse])
+async def list_users(
+    page: int = Query(1, ge=1),
+    size: int = Query(20, ge=1, le=100),
+    db: DbSession,
+) -> Page[User]:
+    total = await db.scalar(select(func.count()).select_from(User))
+
+    users = await db.scalars(
+        select(User)
+        .offset((page - 1) * size)
+        .limit(size)
+    )
+
+    return Page.create(list(users), total, page, size)
+```
+
+## Response Classes
+
+```python
+from fastapi.responses import (
+    JSONResponse,
+    HTMLResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    StreamingResponse,
+    FileResponse,
+)
+
+# JSON with custom status and headers
+@router.post("/users")
+async def create_user(data: UserCreate) -> JSONResponse:
+    user = await user_service.create(data)
+    return JSONResponse(
+        content={"id": user.id, "message": "User created"},
+        status_code=201,
+        headers={"X-Custom-Header": "value"},
+    )
+
+# HTML response
+@router.get("/page", response_class=HTMLResponse)
+async def get_page() -> str:
+    return "<html><body><h1>Hello</h1></body></html>"
+
+# Redirect
+@router.get("/old-path")
+async def redirect() -> RedirectResponse:
+    return RedirectResponse(url="/new-path", status_code=301)
+
+# File download
+@router.get("/download/{filename}")
+async def download_file(filename: str) -> FileResponse:
+    return FileResponse(
+        path=f"files/{filename}",
+        filename=filename,
+        media_type="application/octet-stream",
+    )
+```
+
+## Streaming Response
+
+```python
+import asyncio
+from typing import AsyncGenerator
+
+async def generate_data() -> AsyncGenerator[bytes, None]:
+    for i in range(100):
+        yield f"data: {i}\n\n".encode()
+        await asyncio.sleep(0.1)
+
+@router.get("/stream")
+async def stream_data() -> StreamingResponse:
+    return StreamingResponse(
+        generate_data(),
+        media_type="text/event-stream",
+    )
+
+# Stream large file
+@router.get("/large-file")
+async def stream_file() -> StreamingResponse:
+    async def iterfile():
+        async with aiofiles.open("large_file.csv", "rb") as f:
+            while chunk := await f.read(8192):
+                yield chunk
+
+    return StreamingResponse(
+        iterfile(),
+        media_type="text/csv",
+        headers={"Content-Disposition": "attachment; filename=data.csv"},
+    )
+```
+
+## Error Responses
+
+```python
+from fastapi import HTTPException
+from fastapi.responses import JSONResponse
+
+# Standard HTTP exception
+@router.get("/users/{user_id}")
+async def get_user(user_id: int) -> UserResponse:
+    user = await db.get(User, user_id)
+    if not user:
+        raise HTTPException(
+            status_code=404,
+            detail="User not found",
+            headers={"X-Error-Code": "USER_NOT_FOUND"},
+        )
+    return user
+
+# Custom error response model
+class ErrorResponse(BaseModel):
+    error: str
+    detail: str
+    request_id: str | None = None
+
+@router.get(
+    "/users/{user_id}",
+    responses={
+        200: {"model": UserResponse},
+        404: {"model": ErrorResponse, "description": "User not found"},
+        500: {"model": ErrorResponse, "description": "Internal server error"},
+    },
+)
+async def get_user(user_id: int) -> UserResponse:
+    ...
+
+# Global exception handler
+@app.exception_handler(ValueError)
+async def value_error_handler(request: Request, exc: ValueError) -> JSONResponse:
+    return JSONResponse(
+        status_code=400,
+        content={"error": "Bad Request", "detail": str(exc)},
+    )
+```
+
+## Response Headers
+
+```python
+from fastapi import Response
+
+@router.get("/data")
+async def get_data(response: Response) -> dict:
+    response.headers["X-Custom-Header"] = "custom-value"
+    response.headers["Cache-Control"] = "max-age=3600"
+    return {"data": "value"}
+
+# Set cookies
+@router.post("/login")
+async def login(response: Response) -> dict:
+    response.set_cookie(
+        key="session_id",
+        value="abc123",
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        max_age=3600,
+    )
+    return {"status": "logged_in"}
+
+# Delete cookie
+@router.post("/logout")
+async def logout(response: Response) -> dict:
+    response.delete_cookie("session_id")
+    return {"status": "logged_out"}
+```
+
+## Background Response
+
+```python
+from fastapi import BackgroundTasks
+
+@router.post("/send-email")
+async def send_email(
+    email: EmailSchema,
+    background_tasks: BackgroundTasks,
+) -> dict:
+    # Return immediately
+    background_tasks.add_task(send_email_async, email.to, email.subject, email.body)
+    return {"message": "Email queued"}
+```
+
+## No Content Response
+
+```python
+from fastapi import Response, status
+
+@router.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(user_id: int, db: DbSession) -> Response:
+    user = await db.get(User, user_id)
+    if not user:
+        raise HTTPException(404, "User not found")
+
+    await db.delete(user)
+    await db.commit()
+
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+```