codeforge-dev 1.4.0

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/fastapi/references/pydantic-models.md

@@ -0,0 +1,245 @@
+# Pydantic v2 Models -- Deep Dive
+
+## 1. Computed Fields
+
+Computed fields are derived from other model fields at serialization time. They appear in JSON output but are not accepted in input:
+
+```python
+from pydantic import BaseModel, computed_field
+
+class Product(BaseModel):
+    price: float
+    tax_rate: float = 0.08
+
+    @computed_field
+    @property
+    def total(self) -> float:
+        return self.price * (1 + self.tax_rate)
+```
+
+```python
+p = Product(price=100)
+p.model_dump()
+# {"price": 100.0, "tax_rate": 0.08, "total": 108.0}
+```
+
+Computed fields participate in JSON Schema generation, appearing in OpenAPI docs with their return type.
+
+---
+
+## 2. Model Inheritance
+
+### Shared Base Models
+
+Factor common fields into a base class. Input and output models inherit from the base and add their specific fields:
+
+```python
+class UserBase(BaseModel):
+    email: str
+    display_name: str | None = None
+
+class UserCreate(UserBase):
+    password: str
+
+class UserUpdate(BaseModel):
+    email: str | None = None
+    display_name: str | None = None
+
+class UserResponse(UserBase):
+    model_config = {"from_attributes": True}
+
+    id: int
+    created_at: datetime
+```
+
+### Partial Models for PATCH
+
+Create update models where all fields are optional. This supports partial updates without requiring the client to send the full object:
+
+```python
+from pydantic import BaseModel
+
+class ItemBase(BaseModel):
+    name: str
+    description: str
+    price: float
+
+class ItemUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+    price: float | None = None
+```
+
+Use `model.model_dump(exclude_unset=True)` to get only the fields the client explicitly provided:
+
+```python
+@router.patch("/{item_id}")
+async def update_item(item_id: int, updates: ItemUpdate, db: DB):
+    update_data = updates.model_dump(exclude_unset=True)
+    await db.execute(
+        update(Item).where(Item.id == item_id).values(**update_data)
+    )
+```
+
+---
+
+## 3. Custom JSON Encoders
+
+Pydantic v2 uses `model_serializer` and `field_serializer` for custom encoding:
+
+```python
+from pydantic import BaseModel, field_serializer
+from datetime import datetime
+
+class Event(BaseModel):
+    name: str
+    timestamp: datetime
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, dt: datetime, _info) -> str:
+        return dt.isoformat()
+```
+
+For model-wide custom serialization:
+
+```python
+from pydantic import model_serializer
+
+class Point(BaseModel):
+    x: float
+    y: float
+
+    @model_serializer
+    def serialize_model(self) -> dict:
+        return {"coordinates": [self.x, self.y]}
+```
+
+---
+
+## 4. Discriminated Unions
+
+Use a literal discriminator field to enable efficient parsing of polymorphic types. Pydantic checks the discriminator value first, then validates against the matching model:
+
+```python
+from typing import Literal, Union, Annotated
+from pydantic import BaseModel, Field
+
+class TextBlock(BaseModel):
+    type: Literal["text"] = "text"
+    content: str
+
+class ImageBlock(BaseModel):
+    type: Literal["image"] = "image"
+    url: str
+    alt_text: str | None = None
+
+class CodeBlock(BaseModel):
+    type: Literal["code"] = "code"
+    language: str
+    source: str
+
+Block = Annotated[
+    Union[TextBlock, ImageBlock, CodeBlock],
+    Field(discriminator="type"),
+]
+
+class Document(BaseModel):
+    title: str
+    blocks: list[Block]
+```
+
+Benefits of discriminated unions:
+- Validation errors reference the specific model variant, not a generic union failure.
+- Performance is constant-time (dict lookup by discriminator), not linear (try each variant).
+- OpenAPI schema uses `oneOf` with `discriminator`, enabling typed client generation.
+
+---
+
+## 5. Validators and Constraints
+
+### Field-Level Validators
+
+```python
+from pydantic import field_validator
+
+class Registration(BaseModel):
+    username: str
+    age: int
+
+    @field_validator("username")
+    @classmethod
+    def username_alphanumeric(cls, v: str) -> str:
+        if not v.isalnum():
+            raise ValueError("must be alphanumeric")
+        return v
+
+    @field_validator("age")
+    @classmethod
+    def age_range(cls, v: int) -> int:
+        if v < 13 or v > 120:
+            raise ValueError("must be between 13 and 120")
+        return v
+```
+
+### Model-Level Validators
+
+Validate relationships between fields using `model_validator`:
+
+```python
+from pydantic import model_validator
+
+class DateRange(BaseModel):
+    start: datetime
+    end: datetime
+
+    @model_validator(mode="after")
+    def validate_range(self) -> "DateRange":
+        if self.end <= self.start:
+            raise ValueError("end must be after start")
+        return self
+```
+
+### Field Constraints
+
+```python
+from pydantic import Field
+
+class Product(BaseModel):
+    name: str = Field(min_length=1, max_length=200)
+    price: float = Field(gt=0, description="Price in USD")
+    sku: str = Field(pattern=r"^[A-Z]{2}-\d{4}$")
+    tags: list[str] = Field(default_factory=list, max_length=10)
+```
+
+---
+
+## 6. BaseSettings for Configuration
+
+`BaseSettings` reads values from environment variables, `.env` files, and constructor arguments with a defined priority:
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    model_config = {"env_file": ".env", "env_prefix": "APP_"}
+
+    database_url: str
+    redis_url: str = "redis://localhost:6379"
+    debug: bool = False
+    allowed_origins: list[str] = ["http://localhost:3000"]
+```
+
+```python
+# Usage in FastAPI
+from functools import lru_cache
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()
+
+@app.get("/info")
+async def info(settings: Settings = Depends(get_settings)):
+    return {"debug": settings.debug}
+```
+
+Priority order (highest to lowest): constructor arguments, environment variables, `.env` file, field defaults. Use `lru_cache` to parse settings once rather than on every request.

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/fastapi/references/routing-and-dependencies.md

@@ -0,0 +1,255 @@
+# Routing and Dependencies -- Deep Dive
+
+## 1. APIRouter Organization
+
+Structure routers by domain, one per module. Each router declares its own prefix, tags, and shared dependencies:
+
+```python
+# app/routers/users.py
+from fastapi import APIRouter, Depends
+from app.dependencies import get_current_user
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users"],
+    dependencies=[Depends(get_current_user)],
+)
+
+@router.get("/me")
+async def read_current_user(user: User = Depends(get_current_user)):
+    return user
+
+@router.get("/{user_id}")
+async def read_user(user_id: int):
+    return await fetch_user(user_id)
+```
+
+```python
+# app/main.py
+from fastapi import FastAPI
+from app.routers import users, items, orders
+
+app = FastAPI()
+app.include_router(users.router)
+app.include_router(items.router)
+app.include_router(orders.router)
+```
+
+### Router-Level Dependencies
+
+Dependencies declared at the router level apply to every endpoint in that router. This is ideal for authentication guards -- every endpoint in the router requires a valid user without repeating the dependency:
+
+```python
+router = APIRouter(
+    prefix="/admin",
+    dependencies=[Depends(require_admin_role)],
+)
+```
+
+Override a router-level dependency at the endpoint level by re-declaring the same parameter type with a different `Depends()`:
+
+```python
+@router.get("/public", dependencies=[])
+async def public_endpoint():
+    return {"message": "no auth required"}
+```
+
+---
+
+## 2. Path Operation Configuration
+
+### Response Model Filtering
+
+Use `response_model_exclude_unset` to omit fields the client did not send, useful for PATCH-style partial updates:
+
+```python
+@router.patch("/{item_id}", response_model=ItemResponse)
+async def update_item(
+    item_id: int,
+    updates: ItemUpdate,
+    response_model_exclude_unset=True,
+):
+    return await apply_updates(item_id, updates)
+```
+
+### Multiple Response Models
+
+Declare alternative responses for documentation and client generation:
+
+```python
+from fastapi import status
+
+@router.post(
+    "/",
+    response_model=ItemResponse,
+    status_code=status.HTTP_201_CREATED,
+    responses={
+        409: {"model": ErrorResponse, "description": "Item already exists"},
+        422: {"model": ValidationErrorResponse},
+    },
+)
+async def create_item(item: ItemCreate):
+    ...
+```
+
+### Tags and Deprecation
+
+```python
+@router.get("/legacy", deprecated=True, tags=["legacy"])
+async def legacy_endpoint():
+    ...
+```
+
+---
+
+## 3. Nested and Overridden Dependencies
+
+### Nested Dependencies
+
+Dependencies can depend on other dependencies. FastAPI resolves the full graph, caching each dependency once per request:
+
+```python
+async def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        await db.close()
+
+async def get_user_repo(db: AsyncSession = Depends(get_db)):
+    return UserRepository(db)
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    repo: UserRepository = Depends(get_user_repo),
+):
+    user = await repo.find_by_token(token)
+    if not user:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return user
+```
+
+The dependency graph resolves as: `oauth2_scheme` + `get_db` -> `get_user_repo` -> `get_current_user`. Each node executes once per request regardless of how many endpoints declare it.
+
+### Disabling Cache
+
+Force a dependency to re-execute per injection point by setting `use_cache=False`:
+
+```python
+async def get_timestamp():
+    return datetime.utcnow()
+
+@router.get("/")
+async def handler(
+    start: datetime = Depends(get_timestamp),
+    end: datetime = Depends(get_timestamp, use_cache=False),
+):
+    # start and end are different timestamps
+    ...
+```
+
+---
+
+## 4. WebSocket Endpoints
+
+WebSocket routes use `@app.websocket()` and receive a `WebSocket` object for bidirectional communication:
+
+```python
+from fastapi import WebSocket, WebSocketDisconnect
+
+@app.websocket("/ws/{client_id}")
+async def websocket_endpoint(websocket: WebSocket, client_id: str):
+    await websocket.accept()
+    try:
+        while True:
+            data = await websocket.receive_text()
+            await websocket.send_text(f"Echo: {data}")
+    except WebSocketDisconnect:
+        pass
+```
+
+Dependencies work with WebSocket endpoints. Inject shared resources the same way as HTTP handlers:
+
+```python
+@app.websocket("/ws")
+async def ws_with_deps(websocket: WebSocket, db: DB):
+    await websocket.accept()
+    ...
+```
+
+### Connection Management
+
+Track active connections for broadcasting:
+
+```python
+class ConnectionManager:
+    def __init__(self):
+        self.active: list[WebSocket] = []
+
+    async def connect(self, ws: WebSocket):
+        await ws.accept()
+        self.active.append(ws)
+
+    def disconnect(self, ws: WebSocket):
+        self.active.remove(ws)
+
+    async def broadcast(self, message: str):
+        for ws in self.active:
+            await ws.send_text(message)
+
+manager = ConnectionManager()
+```
+
+---
+
+## 5. Testing Endpoints
+
+Use `httpx.AsyncClient` with FastAPI's built-in test support. Override dependencies to inject test doubles:
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+from app.dependencies import get_db
+
+async def mock_db():
+    yield FakeDatabase()
+
+app.dependency_overrides[get_db] = mock_db
+
+@pytest.fixture
+async def client():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.anyio
+async def test_create_item(client: AsyncClient):
+    response = await client.post("/items/", json={"name": "Test", "price": 9.99})
+    assert response.status_code == 201
+    assert response.json()["name"] == "Test"
+```
+
+### Testing with Real Dependencies
+
+For integration tests, use the actual dependency graph but point to a test database:
+
+```python
+@pytest.fixture(autouse=True)
+async def setup_test_db():
+    await create_test_tables()
+    yield
+    await drop_test_tables()
+    app.dependency_overrides.clear()
+```
+
+### Testing Authentication
+
+Override the auth dependency to bypass token validation in tests:
+
+```python
+async def mock_current_user():
+    return User(id=1, email="test@example.com", role="admin")
+
+app.dependency_overrides[get_current_user] = mock_current_user
+```