ndomo 0.1.0

package/skills/python-design-patterns/references/details.md

@@ -0,0 +1,353 @@
+# python-design-patterns — detailed patterns and worked examples
+
+## Fundamental Patterns
+
+### Pattern 1: KISS - Keep It Simple
+
+Before adding complexity, ask: does a simpler solution work?
+
+```python
+# Over-engineered: Factory with registration
+class OutputFormatterFactory:
+    _formatters: dict[str, type[Formatter]] = {}
+
+    @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) -> Formatter:
+        return cls._formatters[name]()
+
+@OutputFormatterFactory.register("json")
+class JsonFormatter(Formatter):
+    ...
+
+# Simple: Just use a dictionary
+FORMATTERS = {
+    "json": JsonFormatter,
+    "csv": CsvFormatter,
+    "xml": XmlFormatter,
+}
+
+def get_formatter(name: str) -> Formatter:
+    """Get formatter by name."""
+    if name not in FORMATTERS:
+        raise ValueError(f"Unknown format: {name}")
+    return FORMATTERS[name]()
+```
+
+The factory pattern adds code without adding value here. Save patterns for when they solve real problems.
+
+### Pattern 2: Single Responsibility Principle
+
+Each class or function should have one reason to change.
+
+```python
+# BAD: Handler does everything
+class UserHandler:
+    async def create_user(self, request: Request) -> Response:
+        # 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 (email, name) VALUES ($1, $2) RETURNING *",
+            data["email"], data["name"]
+        )
+
+        # Response formatting
+        return Response({"id": user.id, "email": user.email}, status=201)
+
+# GOOD: Separated concerns
+class UserService:
+    """Business logic only."""
+
+    def __init__(self, repo: UserRepository) -> None:
+        self._repo = repo
+
+    async def create_user(self, data: CreateUserInput) -> User:
+        # Only business rules here
+        user = User(email=data.email, name=data.name)
+        return await self._repo.save(user)
+
+class UserHandler:
+    """HTTP concerns only."""
+
+    def __init__(self, service: UserService) -> None:
+        self._service = service
+
+    async def create_user(self, request: Request) -> Response:
+        data = CreateUserInput(**(await request.json()))
+        user = await self._service.create_user(data)
+        return Response(user.to_dict(), status=201)
+```
+
+Now HTTP changes don't affect business logic, and vice versa.
+
+### Pattern 3: Separation of Concerns
+
+Organize code into distinct layers with clear responsibilities.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  API Layer (handlers)                                │
+│  - Parse requests                                    │
+│  - Call services                                     │
+│  - Format responses                                  │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────┐
+│  Service Layer (business logic)                      │
+│  - Domain rules and validation                       │
+│  - Orchestrate operations                            │
+│  - Pure functions where possible                     │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────┐
+│  Repository Layer (data access)                      │
+│  - SQL queries                                       │
+│  - External API calls                                │
+│  - Cache operations                                  │
+└─────────────────────────────────────────────────────┘
+```
+
+Each layer depends only on layers below it:
+
+```python
+# Repository: Data access
+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: Business logic
+class UserService:
+    def __init__(self, repo: UserRepository) -> None:
+        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: HTTP concerns
+@app.get("/users/{user_id}")
+async def get_user(user_id: str) -> UserResponse:
+    user = await user_service.get_user(user_id)
+    return UserResponse.from_user(user)
+```
+
+### Pattern 4: Composition Over Inheritance
+
+Build behavior by combining objects rather than inheriting.
+
+```python
+# Inheritance: Rigid and hard to test
+class EmailNotificationService(NotificationService):
+    def __init__(self):
+        super().__init__()
+        self._smtp = SmtpClient()  # Hard to mock
+
+    def notify(self, user: User, message: str) -> None:
+        self._smtp.send(user.email, message)
+
+# Composition: Flexible and testable
+class NotificationService:
+    """Send notifications via multiple channels."""
+
+    def __init__(
+        self,
+        email_sender: EmailSender,
+        sms_sender: SmsSender | None = None,
+        push_sender: PushSender | None = None,
+    ) -> None:
+        self._email = email_sender
+        self._sms = sms_sender
+        self._push = push_sender
+
+    async def notify(
+        self,
+        user: User,
+        message: str,
+        channels: set[str] | None = None,
+    ) -> 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)
+
+        if "push" in channels and self._push and user.device_token:
+            await self._push.send(user.device_token, message)
+
+# Easy to test with fakes
+service = NotificationService(
+    email_sender=FakeEmailSender(),
+    sms_sender=FakeSmsSender(),
+)
+```
+
+## Advanced Patterns
+
+### Pattern 5: Rule of Three
+
+Wait until you have three instances 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 wait! Are they actually the same?
+# Different validation, different processing, different errors...
+# Duplication is often better than the wrong abstraction
+
+# Only after a third case, consider if there's a real pattern
+# But even then, sometimes explicit is better than abstract
+```
+
+### Pattern 6: Function Size Guidelines
+
+Keep functions focused. Extract when a function:
+
+- Exceeds 20-50 lines (varies by complexity)
+- Serves multiple distinct purposes
+- Has deeply nested logic (3+ levels)
+
+```python
+# Too long, multiple concerns mixed
+def process_order(order: Order) -> Result:
+    # 50 lines of validation...
+    # 30 lines of inventory check...
+    # 40 lines of payment processing...
+    # 20 lines of notification...
+    pass
+
+# Better: Composed from focused functions
+def process_order(order: Order) -> Result:
+    """Process a customer order through the complete workflow."""
+    validate_order(order)
+    reserve_inventory(order)
+    payment_result = charge_payment(order)
+    send_confirmation(order, payment_result)
+    return Result(success=True, order_id=order.id)
+```
+
+### Pattern 7: Dependency Injection
+
+Pass dependencies through constructors for testability.
+
+```python
+from typing import Protocol
+
+class Logger(Protocol):
+    def info(self, msg: str, **kwargs) -> None: ...
+    def error(self, msg: str, **kwargs) -> None: ...
+
+class Cache(Protocol):
+    async def get(self, key: str) -> str | None: ...
+    async def set(self, key: str, value: str, ttl: int) -> None: ...
+
+class UserService:
+    """Service with injected dependencies."""
+
+    def __init__(
+        self,
+        repository: UserRepository,
+        cache: Cache,
+        logger: Logger,
+    ) -> None:
+        self._repo = repository
+        self._cache = cache
+        self._logger = logger
+
+    async def get_user(self, user_id: str) -> User:
+        # Check cache first
+        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)
+
+        # Fetch from database
+        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(),
+)
+```
+
+### Pattern 8: Avoiding Common Anti-Patterns
+
+**Don't expose internal types:**
+
+```python
+# BAD: Leaking ORM model to API
+@app.get("/users/{id}")
+def get_user(id: str) -> UserModel:  # SQLAlchemy model
+    return db.query(UserModel).get(id)
+
+# GOOD: Use response schemas
+@app.get("/users/{id}")
+def get_user(id: str) -> UserResponse:
+    user = db.query(UserModel).get(id)
+    return UserResponse.from_orm(user)
+```
+
+**Don't mix I/O with business logic:**
+
+```python
+# BAD: SQL embedded in business logic
+def calculate_discount(user_id: str) -> float:
+    user = db.query("SELECT * FROM users WHERE id = ?", user_id)
+    orders = db.query("SELECT * FROM orders WHERE user_id = ?", user_id)
+    # Business logic mixed with data access
+
+# GOOD: Repository pattern
+def calculate_discount(user: User, order_history: list[Order]) -> float:
+    # Pure business logic, easily testable
+    if len(order_history) > 10:
+        return 0.15
+    return 0.0
+```

package/skills/python-error-handling/SKILL.md

@@ -0,0 +1,193 @@
+---
+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.
+
+    Args:
+        value: Format string from user input.
+
+    Returns:
+        Validated OutputFormat enum member.
+
+    Raises:
+        ValueError: If format is not recognized.
+    """
+    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)}"
+        )
+
+# Usage at API boundary
+def export_data(data: list[dict], format_str: str) -> bytes:
+    output_format = parse_output_format(format_str)  # Fail fast
+    # Rest of function uses typed OutputFormat
+    ...
+```
+
+### 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):
+    """Input model for user creation."""
+
+    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()
+
+# Usage
+try:
+    user_input = CreateUserInput(
+        email="user@example.com",
+        name="john doe",
+        age=25,
+    )
+except ValidationError as e:
+    # Pydantic provides detailed error information
+    print(e.errors())
+```
+
+### Pattern 4: Map Errors to Standard Exceptions
+
+Use Python's built-in exception types appropriately, adding context as needed.
+
+| 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")
+```
+
+## Detailed worked examples and patterns
+
+Detailed sections (starting with `## Advanced Patterns`) live in `references/details.md`. Read that file when the navigation summary above is insufficient.
+
+## 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

package/skills/python-error-handling/references/details.md

@@ -0,0 +1,171 @@
+# python-error-handling — detailed worked examples
+
+## 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,
+        )
+
+# Usage
+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]:
+    """Results from batch processing."""
+
+    succeeded: dict[int, T]  # index -> result
+    failed: dict[int, Exception]  # index -> error
+
+    @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]:
+    """Process items, capturing individual failures.
+
+    Args:
+        items: Items to process.
+
+    Returns:
+        BatchResult with succeeded and failed items by index.
+    """
+    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)
+
+# Caller handles partial results
+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]  # current, total, status
+
+def process_large_batch(
+    items: list[Item],
+    on_progress: ProgressCallback | None = None,
+) -> BatchResult:
+    """Process batch with optional progress reporting.
+
+    Args:
+        items: Items to process.
+        on_progress: Optional callback receiving (current, total, status).
+    """
+    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)
+```