@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/fastapi/rules/background-tasks.md

@@ -0,0 +1,254 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI Background Tasks
+
+## Simple Background Tasks
+
+```python
+from fastapi import BackgroundTasks
+
+def write_log(message: str):
+    with open("log.txt", "a") as f:
+        f.write(f"{datetime.now()}: {message}\n")
+
+@router.post("/items")
+async def create_item(
+    item: ItemCreate,
+    background_tasks: BackgroundTasks,
+) -> ItemResponse:
+    # Process item
+    created_item = await item_service.create(item)
+
+    # Queue background task
+    background_tasks.add_task(write_log, f"Item created: {created_item.id}")
+
+    # Return immediately
+    return created_item
+```
+
+## Async Background Tasks
+
+```python
+async def send_notification(user_id: int, message: str):
+    async with httpx.AsyncClient() as client:
+        await client.post(
+            "https://notification-service/send",
+            json={"user_id": user_id, "message": message},
+        )
+
+@router.post("/orders")
+async def create_order(
+    order: OrderCreate,
+    background_tasks: BackgroundTasks,
+    db: DbSession,
+) -> OrderResponse:
+    created_order = await order_service.create(db, order)
+
+    # Async task
+    background_tasks.add_task(
+        send_notification,
+        order.user_id,
+        f"Order {created_order.id} confirmed",
+    )
+
+    return created_order
+```
+
+## Multiple Background Tasks
+
+```python
+@router.post("/signup")
+async def signup(
+    user: UserCreate,
+    background_tasks: BackgroundTasks,
+) -> UserResponse:
+    created_user = await user_service.create(user)
+
+    # Queue multiple tasks
+    background_tasks.add_task(send_welcome_email, created_user.email)
+    background_tasks.add_task(notify_admin, created_user.id)
+    background_tasks.add_task(update_analytics, "new_signup")
+
+    return created_user
+```
+
+## Background Tasks in Dependencies
+
+```python
+async def log_request(
+    request: Request,
+    background_tasks: BackgroundTasks,
+):
+    background_tasks.add_task(
+        log_to_database,
+        path=request.url.path,
+        method=request.method,
+        timestamp=datetime.now(),
+    )
+
+@router.get("/data", dependencies=[Depends(log_request)])
+async def get_data() -> dict:
+    return {"data": "value"}
+```
+
+## Long-Running Tasks with Celery
+
+```python
+# tasks.py
+from celery import Celery
+
+celery_app = Celery(
+    "tasks",
+    broker="redis://localhost:6379/0",
+    backend="redis://localhost:6379/0",
+)
+
+@celery_app.task
+def process_large_file(file_path: str) -> dict:
+    # Long-running process
+    result = heavy_computation(file_path)
+    return {"status": "completed", "result": result}
+
+# router.py
+from tasks import process_large_file
+
+@router.post("/process")
+async def process_file(file: UploadFile) -> dict:
+    # Save file
+    file_path = f"/tmp/{file.filename}"
+    async with aiofiles.open(file_path, "wb") as f:
+        await f.write(await file.read())
+
+    # Queue Celery task
+    task = process_large_file.delay(file_path)
+
+    return {"task_id": task.id, "status": "processing"}
+
+@router.get("/process/{task_id}")
+async def get_task_status(task_id: str) -> dict:
+    task = process_large_file.AsyncResult(task_id)
+
+    if task.ready():
+        return {"status": "completed", "result": task.result}
+
+    return {"status": task.status}
+```
+
+## ARQ (Async Redis Queue)
+
+```python
+# tasks.py
+from arq import create_pool
+from arq.connections import RedisSettings
+
+async def send_email_task(ctx, email: str, subject: str, body: str):
+    await email_service.send(email, subject, body)
+
+class WorkerSettings:
+    functions = [send_email_task]
+    redis_settings = RedisSettings()
+
+# router.py
+from arq import create_pool
+
+@router.post("/send-email")
+async def send_email(email: EmailSchema) -> dict:
+    redis = await create_pool(RedisSettings())
+
+    job = await redis.enqueue_job(
+        "send_email_task",
+        email.to,
+        email.subject,
+        email.body,
+    )
+
+    return {"job_id": job.job_id, "status": "queued"}
+```
+
+## Periodic Tasks
+
+```python
+# Using APScheduler
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+
+async def cleanup_expired_sessions():
+    async with async_session() as db:
+        await db.execute(
+            delete(Session).where(Session.expires_at < datetime.utcnow())
+        )
+        await db.commit()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Start scheduler
+    scheduler.add_job(
+        cleanup_expired_sessions,
+        "interval",
+        hours=1,
+    )
+    scheduler.start()
+    yield
+    # Shutdown
+    scheduler.shutdown()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## Task Status Tracking
+
+```python
+from enum import Enum
+import uuid
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+# In-memory store (use Redis in production)
+tasks_store: dict[str, dict] = {}
+
+async def process_with_tracking(task_id: str, data: dict):
+    tasks_store[task_id]["status"] = TaskStatus.RUNNING
+
+    try:
+        result = await heavy_process(data)
+        tasks_store[task_id].update({
+            "status": TaskStatus.COMPLETED,
+            "result": result,
+        })
+    except Exception as e:
+        tasks_store[task_id].update({
+            "status": TaskStatus.FAILED,
+            "error": str(e),
+        })
+
+@router.post("/process")
+async def start_processing(
+    data: ProcessData,
+    background_tasks: BackgroundTasks,
+) -> dict:
+    task_id = str(uuid.uuid4())
+
+    tasks_store[task_id] = {
+        "status": TaskStatus.PENDING,
+        "created_at": datetime.utcnow(),
+    }
+
+    background_tasks.add_task(process_with_tracking, task_id, data.dict())
+
+    return {"task_id": task_id}
+
+@router.get("/process/{task_id}")
+async def get_status(task_id: str) -> dict:
+    if task_id not in tasks_store:
+        raise HTTPException(404, "Task not found")
+
+    return tasks_store[task_id]
+```

package/configs/fastapi/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/.claude → fastapi}/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}
+    )
+```