@sylix/coworker 2.0.10 → 2.0.12

package/dist/skills/defaults/backend-development/python-design-patterns.md

@@ -0,0 +1,296 @@
+---
+name: python-design-patterns
+description: Write maintainable Python code using fundamental design principles and patterns.
+---
+
+# Python Design Patterns — CoWorker Edition
+
+Build Python code that's easy to understand, test, and modify.
+
+## When to Use This Skill
+
+- Designing new components or services
+- Refactoring complex code
+- Deciding between abstractions
+- Choosing inheritance vs composition
+
+## Core Principles
+
+### 1. KISS (Keep It Simple)
+
+Choose the simplest solution that works:
+
+```python
+# Over-engineered: Factory with registration
+class OutputFormatterFactory:
+    _formatters: dict[str, type] = {}
+
+    @classmethod
+    def register(cls, name: str):
+        def decorator(formatter_cls):
+            cls._formatters[name] = formatter_cls
+            return formatter_cls
+        return decorator
+
+    @classmethod
+    def create(cls, name: str):
+        return cls._formatters[name]()
+
+@OutputFormatterFactory.register("json")
+class JsonFormatter:
+    ...
+
+# Simple: Just use a dictionary
+FORMATTERS: dict[str, type] = {
+    "json": JsonFormatter,
+    "csv": CsvFormatter,
+}
+
+def get_formatter(name: str):
+    if name not in FORMATTERS:
+        raise ValueError(f"Unknown format: {name}")
+    return FORMATTERS[name]()
+```
+
+### 2. Single Responsibility
+
+Each class does one thing:
+
+```python
+# BAD: Handler does everything
+class UserHandler:
+    async def create_user(self, request: Request):
+        # HTTP parsing
+        data = await request.json()
+        
+        # Validation
+        if not data.get("email"):
+            return Response({"error": "email required"}, status=400)
+        
+        # Database access
+        user = await db.execute(
+            "INSERT INTO users VALUES ($1, $2)",
+            data["email"], data["name"]
+        )
+        
+        return Response({"id": user.id}, status=201)
+
+# GOOD: Separated concerns
+class UserService:
+    """Business logic only."""
+    
+    def __init__(self, repo: UserRepository):
+        self._repo = repo
+    
+    async def create_user(self, data: CreateUserInput):
+        user = User(email=data.email, name=data.name)
+        return await self._repo.save(user)
+
+class UserHandler:
+    """HTTP concerns only."""
+    
+    def __init__(self, service: UserService):
+        self._service = service
+    
+    async def create_user(self, request: Request):
+        data = CreateUserInput(**await request.json())
+        user = await self._service.create_user(data)
+        return Response(user.to_dict(), status=201)
+```
+
+### 3. Separation of Layers
+
+```
+┌─────────────────────────────────────────┐
+│  API Layer (handlers)                    │
+│  - Parse requests                        │
+│  - Call services                         │
+│  - Format responses                      │
+└─────────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────┐
+│  Service Layer (business logic)          │
+│  - Domain rules                          │
+│  - Orchestration                         │
+└─────────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────┐
+│  Repository Layer (data access)          │
+│  - SQL queries                           │
+│  - External APIs                         │
+└─────────────────────────────────────────┘
+```
+
+```python
+# Repository
+class UserRepository:
+    async def get_by_id(self, user_id: str) -> User | None:
+        row = await self.db.fetchrow(
+            "SELECT * FROM users WHERE id = $1", user_id
+        )
+        return User(**row) if row else None
+
+# Service
+class UserService:
+    def __init__(self, repo: UserRepository):
+        self._repo = repo
+    
+    async def get_user(self, user_id: str) -> User:
+        user = await self._repo.get_by_id(user_id)
+        if user is None:
+            raise UserNotFoundError(user_id)
+        return user
+
+# Handler
+@app.get("/users/{user_id}")
+async def get_user(user_id: str):
+    user = await user_service.get_user(user_id)
+    return UserResponse.from_user(user)
+```
+
+### 4. Composition Over Inheritance
+
+```python
+# Inheritance: Rigid and hard to test
+class EmailNotificationService(NotificationService):
+    def __init__(self):
+        super().__init__()
+        self._smtp = SmtpClient()
+    
+    def notify(self, user, message):
+        self._smtp.send(user.email, message)
+
+# Composition: Flexible and testable
+class NotificationService:
+    def __init__(
+        self,
+        email_sender: EmailSender,
+        sms_sender: SmsSender | None = None,
+    ):
+        self._email = email_sender
+        self._sms = sms_sender
+    
+    async def notify(self, user, message, channels=None):
+        channels = channels or {"email"}
+        
+        if "email" in channels:
+            await self._email.send(user.email, message)
+        
+        if "sms" in channels and self._sms and user.phone:
+            await self._sms.send(user.phone, message)
+
+# Easy to test
+service = NotificationService(
+    email_sender=FakeEmailSender(),
+    sms_sender=FakeSmsSender(),
+)
+```
+
+### 5. Dependency Injection
+
+```python
+from typing import Protocol
+
+class Logger(Protocol):
+    def info(self, msg: str): ...
+    def error(self, msg: str): ...
+
+class Cache(Protocol):
+    async def get(self, key: str): str | None: ...
+    async def set(self, key: str, value: str, ttl: int): ...
+
+class UserService:
+    def __init__(
+        self,
+        repository: UserRepository,
+        cache: Cache,
+        logger: Logger,
+    ):
+        self._repo = repository
+        self._cache = cache
+        self._logger = logger
+    
+    async def get_user(self, user_id: str):
+        cached = await self._cache.get(f"user:{user_id}")
+        if cached:
+            self._logger.info("Cache hit", user_id=user_id)
+            return User.from_json(cached)
+        
+        user = await self._repo.get_by_id(user_id)
+        if user:
+            await self._cache.set(f"user:{user_id}", user.to_json(), ttl=300)
+        
+        return user
+
+# Production
+service = UserService(
+    repository=PostgresUserRepository(db),
+    cache=RedisCache(redis),
+    logger=StructlogLogger(),
+)
+
+# Testing
+service = UserService(
+    repository=InMemoryUserRepository(),
+    cache=FakeCache(),
+    logger=NullLogger(),
+)
+```
+
+### 6. Rule of Three
+
+Wait until you have three similar cases before abstracting:
+
+```python
+# Two similar functions? Don't abstract yet
+def process_orders(orders: list[Order]) -> list[Result]:
+    results = []
+    for order in orders:
+        validated = validate_order(order)
+        result = process_validated_order(validated)
+        results.append(result)
+    return results
+
+def process_returns(returns: list[Return]) -> list[Result]:
+    results = []
+    for ret in returns:
+        validated = validate_return(ret)
+        result = process_validated_return(validated)
+        results.append(result)
+    return results
+
+# These look similar, but different validation/processing
+# Duplication is often better than wrong abstraction
+```
+
+### 7. Function Size Guidelines
+
+```python
+# Too long, multiple concerns
+def process_order(order):
+    # 50 lines of validation...
+    # 30 lines of inventory...
+    # 40 lines of payment...
+    pass
+
+# Better: Composed from focused functions
+def process_order(order: Order) -> Result:
+    validate_order(order)
+    reserve_inventory(order)
+    payment_result = charge_payment(order)
+    send_confirmation(order, payment_result)
+    return Result(success=True, order_id=order.id)
+```
+
+## Best Practices
+
+1. **Keep it simple** - Simpler is better
+2. **Single responsibility** - One reason to change
+3. **Separate concerns** - Distinct layers
+4. **Compose, don't inherit** - Flexibility
+5. **Rule of three** - Wait before abstracting
+6. **Small functions** - 20-50 lines max
+7. **Inject dependencies** - Testability
+8. **Explicit over clever** - Readable wins

package/dist/skills/defaults/backend-development/python-error-handling.md

@@ -0,0 +1,323 @@
+---
+name: python-error-handling
+description: Python error handling patterns including input validation, exception hierarchies, and partial failure handling. Use when implementing validation logic, designing exception strategies, handling batch processing failures, or building robust APIs.
+---
+
+# Python Error Handling
+
+Build robust Python applications with proper input validation, meaningful exceptions, and graceful failure handling. Good error handling makes debugging easier and systems more reliable.
+
+## When to Use This Skill
+
+- Validating user input and API parameters
+- Designing exception hierarchies for applications
+- Handling partial failures in batch operations
+- Converting external data to domain types
+- Building user-friendly error messages
+- Implementing fail-fast validation patterns
+
+## Core Concepts
+
+### 1. Fail Fast
+
+Validate inputs early, before expensive operations. Report all validation errors at once when possible.
+
+### 2. Meaningful Exceptions
+
+Use appropriate exception types with context. Messages should explain what failed, why, and how to fix it.
+
+### 3. Partial Failures
+
+In batch operations, don't let one failure abort everything. Track successes and failures separately.
+
+### 4. Preserve Context
+
+Chain exceptions to maintain the full error trail for debugging.
+
+## Quick Start
+
+```python
+def fetch_page(url: str, page_size: int) -> Page:
+    if not url:
+        raise ValueError("'url' is required")
+    if not 1 <= page_size <= 100:
+        raise ValueError(f"'page_size' must be 1-100, got {page_size}")
+    # Now safe to proceed...
+```
+
+## Fundamental Patterns
+
+### Pattern 1: Early Input Validation
+
+Validate all inputs at API boundaries before any processing begins.
+
+```python
+def process_order(
+    order_id: str,
+    quantity: int,
+    discount_percent: float,
+) -> OrderResult:
+    """Process an order with validation."""
+    # Validate required fields
+    if not order_id:
+        raise ValueError("'order_id' is required")
+
+    # Validate ranges
+    if quantity <= 0:
+        raise ValueError(f"'quantity' must be positive, got {quantity}")
+
+    if not 0 <= discount_percent <= 100:
+        raise ValueError(
+            f"'discount_percent' must be 0-100, got {discount_percent}"
+        )
+
+    # Validation passed, proceed with processing
+    return _process_validated_order(order_id, quantity, discount_percent)
+```
+
+### Pattern 2: Convert to Domain Types Early
+
+Parse strings and external data into typed domain objects at system boundaries.
+
+```python
+from enum import Enum
+
+class OutputFormat(Enum):
+    JSON = "json"
+    CSV = "csv"
+    PARQUET = "parquet"
+
+def parse_output_format(value: str) -> OutputFormat:
+    """Parse string to OutputFormat enum."""
+    try:
+        return OutputFormat(value.lower())
+    except ValueError:
+        valid_formats = [f.value for f in OutputFormat]
+        raise ValueError(
+            f"Invalid format '{value}'. "
+            f"Valid options: {', '.join(valid_formats)}"
+        )
+
+def export_data(data: list[dict], format_str: str) -> bytes:
+    output_format = parse_output_format(format_str)
+    ...
+```
+
+### Pattern 3: Pydantic for Complex Validation
+
+Use Pydantic models for structured input validation with automatic error messages.
+
+```python
+from pydantic import BaseModel, Field, field_validator
+
+class CreateUserInput(BaseModel):
+    email: str = Field(..., min_length=5, max_length=255)
+    name: str = Field(..., min_length=1, max_length=100)
+    age: int = Field(ge=0, le=150)
+
+    @field_validator("email")
+    @classmethod
+    def validate_email_format(cls, v: str) -> str:
+        if "@" not in v or "." not in v.split("@")[-1]:
+            raise ValueError("Invalid email format")
+        return v.lower()
+
+    @field_validator("name")
+    @classmethod
+    def normalize_name(cls, v: str) -> str:
+        return v.strip().title()
+
+try:
+    user_input = CreateUserInput(
+        email="user@example.com",
+        name="john doe",
+        age=25,
+    )
+except ValidationError as e:
+    print(e.errors())
+```
+
+### Pattern 4: Map Errors to Standard Exceptions
+
+| Failure Type | Exception | Example |
+|--------------|-----------|---------|
+| Invalid input | `ValueError` | Bad parameter values |
+| Wrong type | `TypeError` | Expected string, got int |
+| Missing item | `KeyError` | Dict key not found |
+| Operational failure | `RuntimeError` | Service unavailable |
+| Timeout | `TimeoutError` | Operation took too long |
+| File not found | `FileNotFoundError` | Path doesn't exist |
+| Permission denied | `PermissionError` | Access forbidden |
+
+```python
+# Good: Specific exception with context
+raise ValueError(f"'page_size' must be 1-100, got {page_size}")
+
+# Avoid: Generic exception, no context
+raise Exception("Invalid parameter")
+```
+
+## Advanced Patterns
+
+### Pattern 5: Custom Exceptions with Context
+
+Create domain-specific exceptions that carry structured information.
+
+```python
+class ApiError(Exception):
+    """Base exception for API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        response_body: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.response_body = response_body
+        super().__init__(message)
+
+class RateLimitError(ApiError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, retry_after: int) -> None:
+        self.retry_after = retry_after
+        super().__init__(
+            f"Rate limit exceeded. Retry after {retry_after}s",
+            status_code=429,
+        )
+
+def handle_response(response: Response) -> dict:
+    match response.status_code:
+        case 200:
+            return response.json()
+        case 401:
+            raise ApiError("Invalid credentials", 401)
+        case 404:
+            raise ApiError(f"Resource not found: {response.url}", 404)
+        case 429:
+            retry_after = int(response.headers.get("Retry-After", 60))
+            raise RateLimitError(retry_after)
+        case code if 400 <= code < 500:
+            raise ApiError(f"Client error: {response.text}", code)
+        case code if code >= 500:
+            raise ApiError(f"Server error: {response.text}", code)
+```
+
+### Pattern 6: Exception Chaining
+
+Preserve the original exception when re-raising to maintain the debug trail.
+
+```python
+import httpx
+
+class ServiceError(Exception):
+    """High-level service operation failed."""
+    pass
+
+def upload_file(path: str) -> str:
+    """Upload file and return URL."""
+    try:
+        with open(path, "rb") as f:
+            response = httpx.post("https://upload.example.com", files={"file": f})
+            response.raise_for_status()
+            return response.json()["url"]
+    except FileNotFoundError as e:
+        raise ServiceError(f"Upload failed: file not found at '{path}'") from e
+    except httpx.HTTPStatusError as e:
+        raise ServiceError(
+            f"Upload failed: server returned {e.response.status_code}"
+        ) from e
+    except httpx.RequestError as e:
+        raise ServiceError(f"Upload failed: network error") from e
+```
+
+### Pattern 7: Batch Processing with Partial Failures
+
+Never let one bad item abort an entire batch. Track results per item.
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class BatchResult[T]:
+    succeeded: dict[int, T]
+    failed: dict[int, Exception]
+
+    @property
+    def success_count(self) -> int:
+        return len(self.succeeded)
+
+    @property
+    def failure_count(self) -> int:
+        return len(self.failed)
+
+    @property
+    def all_succeeded(self) -> bool:
+        return len(self.failed) == 0
+
+def process_batch(items: list[Item]) -> BatchResult[ProcessedItem]:
+    succeeded: dict[int, ProcessedItem] = {}
+    failed: dict[int, Exception] = {}
+
+    for idx, item in enumerate(items):
+        try:
+            result = process_single_item(item)
+            succeeded[idx] = result
+        except Exception as e:
+            failed[idx] = e
+
+    return BatchResult(succeeded=succeeded, failed=failed)
+
+result = process_batch(items)
+if not result.all_succeeded:
+    logger.warning(
+        f"Batch completed with {result.failure_count} failures",
+        failed_indices=list(result.failed.keys()),
+    )
+```
+
+### Pattern 8: Progress Reporting for Long Operations
+
+Provide visibility into batch progress without coupling business logic to UI.
+
+```python
+from collections.abc import Callable
+
+ProgressCallback = Callable[[int, int, str], None]
+
+def process_large_batch(
+    items: list[Item],
+    on_progress: ProgressCallback | None = None,
+) -> BatchResult:
+    total = len(items)
+    succeeded = {}
+    failed = {}
+
+    for idx, item in enumerate(items):
+        if on_progress:
+            on_progress(idx, total, f"Processing {item.id}")
+
+        try:
+            succeeded[idx] = process_single_item(item)
+        except Exception as e:
+            failed[idx] = e
+
+    if on_progress:
+        on_progress(total, total, "Complete")
+
+    return BatchResult(succeeded=succeeded, failed=failed)
+```
+
+## Best Practices Summary
+
+1. **Validate early** - Check inputs before expensive operations
+2. **Use specific exceptions** - `ValueError`, `TypeError`, not generic `Exception`
+3. **Include context** - Messages should explain what, why, and how to fix
+4. **Convert types at boundaries** - Parse strings to enums/domain types early
+5. **Chain exceptions** - Use `raise ... from e` to preserve debug info
+6. **Handle partial failures** - Don't abort batches on single item errors
+7. **Use Pydantic** - For complex input validation with structured errors
+8. **Document failure modes** - Docstrings should list possible exceptions
+9. **Log with context** - Include IDs, counts, and other debugging info
+10. **Test error paths** - Verify exceptions are raised correctly