@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/fastapi/.claude/rules/dependencies.md

@@ -0,0 +1,170 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI Dependency Injection
+
+## Basic Dependencies
+
+```python
+# GOOD - reusable dependency
+from typing import Annotated
+from fastapi import Depends
+
+async def get_db():
+    async with async_session() as session:
+        yield session
+
+DbSession = Annotated[AsyncSession, Depends(get_db)]
+
+@router.get("/users/{user_id}")
+async def get_user(user_id: int, db: DbSession) -> User:
+    return await db.get(User, user_id)
+```
+
+## Dependency with Parameters
+
+```python
+# GOOD - parameterized dependency
+def get_pagination(
+    page: int = Query(1, ge=1),
+    size: int = Query(20, ge=1, le=100),
+) -> Pagination:
+    return Pagination(page=page, size=size)
+
+Paginated = Annotated[Pagination, Depends(get_pagination)]
+
+@router.get("/users")
+async def list_users(pagination: Paginated) -> Page[User]:
+    ...
+```
+
+## Class-Based Dependencies
+
+```python
+# GOOD - stateful dependency
+class RateLimiter:
+    def __init__(self, requests_per_minute: int):
+        self.rpm = requests_per_minute
+        self.requests: dict[str, list[float]] = {}
+
+    async def __call__(self, request: Request) -> None:
+        client_ip = request.client.host
+        now = time.time()
+
+        # Clean old requests
+        self.requests[client_ip] = [
+            t for t in self.requests.get(client_ip, [])
+            if now - t < 60
+        ]
+
+        if len(self.requests[client_ip]) >= self.rpm:
+            raise HTTPException(429, "Rate limit exceeded")
+
+        self.requests[client_ip].append(now)
+
+rate_limiter = RateLimiter(requests_per_minute=60)
+
+@router.get("/api/data", dependencies=[Depends(rate_limiter)])
+async def get_data():
+    ...
+```
+
+## Authentication Dependencies
+
+```python
+# GOOD - reusable auth dependency
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/token")
+
+async def get_current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: DbSession,
+) -> User:
+    payload = verify_token(token)
+    if not payload:
+        raise HTTPException(401, "Invalid token")
+
+    user = await db.get(User, payload["sub"])
+    if not user:
+        raise HTTPException(401, "User not found")
+
+    return user
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+
+# Role-based dependency
+def require_role(role: str):
+    async def check_role(user: CurrentUser) -> User:
+        if user.role != role:
+            raise HTTPException(403, "Insufficient permissions")
+        return user
+    return check_role
+
+AdminUser = Annotated[User, Depends(require_role("admin"))]
+```
+
+## Dependency Chaining
+
+```python
+# Dependencies can depend on other dependencies
+async def get_user_service(db: DbSession) -> UserService:
+    return UserService(db)
+
+async def get_current_user_with_service(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    service: Annotated[UserService, Depends(get_user_service)],
+) -> User:
+    return await service.get_by_token(token)
+```
+
+## Global Dependencies
+
+```python
+# Apply to all routes in router
+router = APIRouter(
+    prefix="/admin",
+    dependencies=[Depends(require_role("admin"))],
+)
+
+# Apply to entire app
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+```
+
+## Yield Dependencies (Context Managers)
+
+```python
+# GOOD - cleanup after request
+async def get_db_transaction():
+    async with async_session() as session:
+        async with session.begin():
+            yield session
+            # Commit happens automatically if no exception
+        # Rollback happens automatically on exception
+
+# GOOD - resource cleanup
+async def get_temp_file():
+    path = Path(tempfile.mktemp())
+    try:
+        yield path
+    finally:
+        path.unlink(missing_ok=True)
+```
+
+## Testing Dependencies
+
+```python
+# Override dependencies in tests
+from fastapi.testclient import TestClient
+
+def get_test_db():
+    return TestDatabase()
+
+app.dependency_overrides[get_db] = get_test_db
+
+with TestClient(app) as client:
+    response = client.get("/users")
+
+# Clean up
+app.dependency_overrides.clear()
+```

package/configs/{python → fastapi}/.claude/rules/fastapi.md

@@ -1,6 +1,11 @@
 ---
 paths:
-  - "**/*.py"
+  - "**/routers/**/*.py"
+  - "**/routes/**/*.py"
+  - "**/api/**/*.py"
+  - "**/endpoints/**/*.py"
+  - "**/main.py"
+  - "**/app.py"
 ---
 
 # FastAPI Rules
@@ -270,3 +275,58 @@ app = FastAPI(
 if settings.environment == "production":
     app = FastAPI(docs_url=None, redoc_url=None)
 ```
+
+## Type Hints
+
+Always use modern syntax (Python 3.10+):
+
+```python
+# Modern type hints
+async def get_user(user_id: int) -> User | None:
+    ...
+
+def process_items(items: list[str]) -> dict[str, int]:
+    ...
+
+# Annotated for dependency injection
+DbSession = Annotated[AsyncSession, Depends(get_db)]
+CurrentUser = Annotated[User, Depends(get_current_user)]
+
+@router.get("/{user_id}")
+async def get_user(
+    user_id: int,
+    db: DbSession,
+    current_user: CurrentUser,
+) -> UserResponse:
+    ...
+```
+
+## Custom Exception Handling
+
+```python
+# Custom exceptions
+class NotFoundError(Exception):
+    def __init__(self, resource: str, id: int):
+        self.resource = resource
+        self.id = id
+
+class BusinessError(Exception):
+    def __init__(self, message: str, code: str):
+        self.message = message
+        self.code = code
+
+# FastAPI exception handlers
+@app.exception_handler(NotFoundError)
+async def not_found_handler(request: Request, exc: NotFoundError):
+    return JSONResponse(
+        status_code=404,
+        content={"detail": f"{exc.resource} {exc.id} not found"}
+    )
+
+@app.exception_handler(BusinessError)
+async def business_error_handler(request: Request, exc: BusinessError):
+    return JSONResponse(
+        status_code=422,
+        content={"detail": exc.message, "code": exc.code}
+    )
+```

package/configs/fastapi/.claude/rules/lifespan.md

@@ -0,0 +1,274 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI Lifespan Management
+
+## Lifespan Context Manager
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: runs before app starts accepting requests
+    print("Starting up...")
+    app.state.db = await create_database_pool()
+    app.state.redis = await create_redis_pool()
+
+    yield  # App runs here
+
+    # Shutdown: runs when app is shutting down
+    print("Shutting down...")
+    await app.state.db.close()
+    await app.state.redis.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## Database Connection Pool
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Create engine
+    engine = create_async_engine(
+        settings.database_url,
+        pool_size=10,
+        max_overflow=20,
+        pool_pre_ping=True,
+    )
+
+    # Create session factory
+    app.state.async_session = async_sessionmaker(
+        engine,
+        expire_on_commit=False,
+    )
+
+    yield
+
+    # Dispose engine
+    await engine.dispose()
+
+# Dependency
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with app.state.async_session() as session:
+        yield session
+```
+
+## Redis Connection
+
+```python
+import redis.asyncio as redis
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Redis pool
+    app.state.redis = await redis.from_url(
+        settings.redis_url,
+        encoding="utf-8",
+        decode_responses=True,
+    )
+
+    yield
+
+    await app.state.redis.close()
+
+# Usage
+@router.get("/cached/{key}")
+async def get_cached(key: str, request: Request) -> dict:
+    value = await request.app.state.redis.get(key)
+    return {"key": key, "value": value}
+```
+
+## HTTP Client Pool
+
+```python
+import httpx
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Create shared HTTP client
+    app.state.http_client = httpx.AsyncClient(
+        timeout=30.0,
+        limits=httpx.Limits(max_connections=100),
+    )
+
+    yield
+
+    await app.state.http_client.aclose()
+
+# Usage
+async def call_external_api(request: Request) -> dict:
+    client = request.app.state.http_client
+    response = await client.get("https://api.example.com/data")
+    return response.json()
+```
+
+## Background Task Scheduler
+
+```python
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    scheduler = AsyncIOScheduler()
+
+    # Add scheduled jobs
+    scheduler.add_job(
+        cleanup_expired_sessions,
+        "interval",
+        hours=1,
+        id="cleanup_sessions",
+    )
+
+    scheduler.add_job(
+        send_daily_reports,
+        "cron",
+        hour=9,
+        minute=0,
+        id="daily_reports",
+    )
+
+    scheduler.start()
+    app.state.scheduler = scheduler
+
+    yield
+
+    scheduler.shutdown(wait=True)
+```
+
+## Multiple Resources
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize all resources
+    engine = create_async_engine(settings.database_url)
+    redis_pool = await redis.from_url(settings.redis_url)
+    http_client = httpx.AsyncClient()
+
+    # Store in app state
+    app.state.db_engine = engine
+    app.state.async_session = async_sessionmaker(engine)
+    app.state.redis = redis_pool
+    app.state.http_client = http_client
+
+    # Run migrations
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    # Log startup
+    logger.info("Application started", extra={
+        "database": settings.database_url,
+        "redis": settings.redis_url,
+    })
+
+    yield
+
+    # Cleanup in reverse order
+    await http_client.aclose()
+    await redis_pool.close()
+    await engine.dispose()
+
+    logger.info("Application shutdown complete")
+```
+
+## Health Checks with Lifespan
+
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class AppHealth:
+    started_at: datetime = field(default_factory=datetime.utcnow)
+    ready: bool = False
+    checks: dict = field(default_factory=dict)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    health = AppHealth()
+    app.state.health = health
+
+    # Initialize resources
+    try:
+        app.state.db = await create_database_pool()
+        health.checks["database"] = "ok"
+    except Exception as e:
+        health.checks["database"] = f"error: {e}"
+
+    try:
+        app.state.redis = await create_redis_pool()
+        health.checks["redis"] = "ok"
+    except Exception as e:
+        health.checks["redis"] = f"error: {e}"
+
+    health.ready = all(v == "ok" for v in health.checks.values())
+
+    yield
+
+    health.ready = False
+    await cleanup_resources(app)
+
+@router.get("/health/live")
+async def liveness() -> dict:
+    return {"status": "ok"}
+
+@router.get("/health/ready")
+async def readiness(request: Request) -> dict:
+    health = request.app.state.health
+
+    if not health.ready:
+        raise HTTPException(503, detail=health.checks)
+
+    return {
+        "status": "ready",
+        "uptime": (datetime.utcnow() - health.started_at).total_seconds(),
+        "checks": health.checks,
+    }
+```
+
+## Deprecated: on_event
+
+```python
+# DEPRECATED - Don't use this pattern
+@app.on_event("startup")
+async def startup():
+    ...
+
+@app.on_event("shutdown")
+async def shutdown():
+    ...
+
+# Use lifespan instead (see above)
+```
+
+## Testing with Lifespan
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+@pytest.fixture
+async def client():
+    # Lifespan is automatically handled
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
+
+# Or override lifespan for tests
+@asynccontextmanager
+async def test_lifespan(app: FastAPI):
+    app.state.db = MockDatabase()
+    app.state.redis = MockRedis()
+    yield
+
+app_for_testing = FastAPI(lifespan=test_lifespan)
+```