python-skills 1.0.0__py3-none-any.whl

skills/generation/error_handling.md

@@ -0,0 +1,276 @@
+# Generation: Error Handling
+
+**Purpose**: Consistent, safe error handling patterns for code generation.
+
+**When to use**: All code generation. Error handling is critical for correctness.
+
+---
+
+## Core Rules
+
+### Exception Hierarchy
+```
+BaseException
+├── KeyboardInterrupt
+├── SystemExit
+├── GeneratorExit
+└── Exception
+    ├── StopIteration
+    ├── StopAsyncIteration
+    ├── ArithmeticError
+    │   ├── ZeroDivisionError
+    │   └── ...
+    ├── AssertionError
+    ├── AttributeError
+    ├── BufferError
+    ├── EOFError
+    ├── ImportError
+    │   └── ModuleNotFoundError
+    ├── LookupError
+    │   ├── IndexError
+    │   └── KeyError
+    ├── MemoryError
+    ├── NameError
+    │   └── UnboundLocalError
+    ├── OSError
+    │   ├── BlockingIOError
+    │   ├── ChildProcessError
+    │   ├── ConnectionError
+    │   ├── FileExistsError
+    │   ├── FileNotFoundError
+    │   ├── InterruptedError
+    │   ├── IsADirectoryError
+    │   ├── NotADirectoryError
+    │   ├── PermissionError
+    │   ├── ProcessLookupError
+    │   └── TimeoutError
+    ├── ReferenceError
+    ├── RuntimeError
+    │   ├── NotImplementedError
+    │   └── RecursionError
+    ├── SyntaxError
+    │   └── IndentationError
+    ├── SystemError
+    ├── TypeError
+    ├── ValueError
+    │   └── UnicodeError
+    └── Warning
+```
+
+### Catch Specific Exceptions
+```python
+# GOOD — specific
+try:
+    data = json.loads(text)
+except json.JSONDecodeError as e:
+    logger.error("Invalid JSON", extra={"error": str(e), "pos": e.pos})
+    raise ValueError("Invalid JSON input") from e
+
+# GOOD — tuple of related
+try:
+    response = requests.get(url, timeout=5)
+except (requests.Timeout, requests.ConnectionError) as e:
+    logger.warning("Request failed", extra={"url": url, "error": str(e)})
+    raise ServiceUnavailable("Service unreachable") from e
+
+# BAD — bare except
+try:
+    ...
+except:
+    ...  # Catches KeyboardInterrupt, SystemExit!
+
+# BAD — broad Exception
+try:
+    ...
+except Exception:
+    ...  # Swallows everything, hard to debug
+```
+
+### Exception Chaining
+```python
+# Explicit chaining (preserves original traceback)
+try:
+    risky()
+except OriginalError as e:
+    raise NewError("Context") from e
+
+# Implicit chaining (automatic when raising in except)
+try:
+    risky()
+except OriginalError:
+    raise NewError("Context")  # __context__ set automatically
+
+# Suppress chaining
+try:
+    risky()
+except OriginalError:
+    raise NewError("Context") from None
+```
+
+### Custom Exceptions
+```python
+# Domain-specific exceptions
+class DomainError(Exception):
+    """Base for domain errors."""
+    def __init__(self, message: str, code: str, details: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.details = details or {}
+
+class ValidationError(DomainError):
+    def __init__(self, field: str, message: str):
+        super().__init__(message, "VALIDATION_ERROR", {"field": field})
+
+class NotFoundError(DomainError):
+    def __init__(self, resource: str, id: str):
+        super().__init__(f"{resource} not found: {id}", "NOT_FOUND", {"resource": resource, "id": id})
+
+class ConflictError(DomainError):
+    pass
+
+# Usage
+raise ValidationError("email", "Invalid format")
+raise NotFoundError("User", "123")
+```
+
+### Error Categories (For Handling Strategy)
+
+| Category | Examples | Handling |
+|----------|----------|----------|
+| Expected operational failure | `NotFoundError`, `ValidationError`, `ConflictError` | Handle explicitly, return error result |
+| Programming bug | `AssertionError`, `TypeError`, `IndexError` | Let crash, fix code |
+| Invalid external input | `ValueError`, `JSONDecodeError` | Validate early, return 400 |
+| Configuration failure | `KeyError` (missing config), `ImproperlyConfigured` | Fail fast at startup |
+| System failure | `OSError`, `MemoryError`, `ConnectionError` | Retry, circuit breaker, degrade |
+
+### Result Pattern (Alternative to Exceptions)
+```python
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+E = TypeVar("E", bound=Exception)
+
+@dataclass(frozen=True)
+class Result(Generic[T, E]):
+    value: T | None = None
+    error: E | None = None
+    
+    @property
+    def is_ok(self) -> bool:
+        return self.error is None
+    
+    @property
+    def is_err(self) -> bool:
+        return self.error is not None
+    
+    def unwrap(self) -> T:
+        if self.error:
+            raise self.error
+        return self.value
+    
+    def map[U](self, func: Callable[[T], U]) -> "Result[U, E]":
+        if self.error:
+            return Result(error=self.error)
+        try:
+            return Result(value=func(self.value))
+        except Exception as e:
+            return Result(error=e)
+
+# Usage
+def parse_int(s: str) -> Result[int, ValueError]:
+    try:
+        return Result(value=int(s))
+    except ValueError as e:
+        return Result(error=e)
+
+result = parse_int("42")
+if result.is_ok:
+    print(result.value)
+else:
+    print(f"Error: {result.error}")
+```
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Expected failure (validation, not found) | Custom exception or `Result` |
+| Programming bug | `assert` or let built-in raise |
+| External API failure | Custom exception wrapping original |
+| Retryable failure | Catch specific, retry with backoff |
+| Cleanup needed | `try/finally` or context manager |
+| Multiple independent failures | `ExceptionGroup` (3.11+) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Validation at boundaries
+def create_user(data: dict) -> User:
+    # Validate input early
+    email = data.get("email")
+    if not email or "@" not in email:
+        raise ValidationError("email", "Invalid email format")
+    
+    # Business logic
+    if user_repo.exists(email):
+        raise ConflictError("User already exists")
+    
+    return user_repo.save(User(email=email))
+
+# Graceful degradation
+async def get_user_profile(user_id: str) -> UserProfile:
+    try:
+        return await user_service.get_profile(user_id)
+    except UserService.Unavailable:
+        # Fallback to cache
+        return await cache.get_profile(user_id)
+    except UserService.NotFound:
+        raise NotFoundError("User", user_id)
+
+# Structured error responses (API)
+def handle_error(e: Exception) -> ErrorResponse:
+    if isinstance(e, ValidationError):
+        return ErrorResponse(400, e.code, e.details)
+    if isinstance(e, NotFoundError):
+        return ErrorResponse(404, e.code, e.details)
+    if isinstance(e, ConflictError):
+        return ErrorResponse(409, e.code, e.details)
+    logger.exception("Unhandled error")
+    return ErrorResponse(500, "INTERNAL_ERROR", {})
+```
+
+---
+
+## Avoid
+
+- Bare `except:` or `except Exception:`
+- Swallowing exceptions silently
+- Using exceptions for control flow (except EAFP)
+- Custom exceptions without `__init__` for context
+- Raising generic `Exception` or `RuntimeError`
+- Losing original exception context (use `from e`)
+- Catching `KeyboardInterrupt` / `SystemExit` (unless shutting down)
+
+---
+
+## Validation Considerations
+
+- Test error paths explicitly
+- Verify exception messages don't leak secrets
+- Check logging includes context for debugging
+- Ensure `Result` pattern doesn't hide errors
+
+---
+
+## Related Skills
+
+- `generation/workflow.md`
+- `generation/async_concurrency.md` (async errors)
+- `security/input_validation.md`
+- `testing/edge_cases.md`
+- `quality/functions.md`

skills/generation/protocols_generics.md

@@ -0,0 +1,243 @@
+# Generation: Protocols and Generics
+
+**Purpose**: Advanced typing with protocols, generics, and variance.
+
+**When to use**: Designing flexible, decoupled interfaces and reusable components.
+
+---
+
+## Core Rules
+
+### Protocols (Structural Subtyping)
+```python
+from typing import Protocol, runtime_checkable
+
+# Basic protocol
+class Serializable(Protocol):
+    def to_json(self) -> str: ...
+    def to_bytes(self) -> bytes: ...
+
+# With generics
+T = TypeVar("T")
+
+class Repository(Protocol[T]):
+    def get(self, id: str) -> T: ...
+    def save(self, entity: T) -> None: ...
+    def delete(self, id: str) -> bool: ...
+
+# Runtime checkable (for isinstance)
+@runtime_checkable
+class Configurable(Protocol):
+    def configure(self, settings: dict) -> None: ...
+
+# Multiple protocols
+class Service(Repository[User], Configurable, Protocol):
+    def start(self) -> None: ...
+```
+
+### Protocol vs ABC
+| Feature | Protocol | ABC |
+|---------|----------|-----|
+| Inheritance required | No | Yes |
+| Runtime isinstance | Only `@runtime_checkable` | Yes |
+| Multiple implementations | Easy | Requires inheritance |
+| Third-party classes | Works if structure matches | Must subclass |
+| Method enforcement | Static only | Static + runtime |
+
+**Prefer Protocol** for interfaces unless runtime checks needed.
+
+### Generic Classes
+```python
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+K = TypeVar("K")
+V = TypeVar("V")
+
+class Box(Generic[T]):
+    def __init__(self, value: T) -> None:
+        self._value = value
+    
+    def get(self) -> T:
+        return self._value
+    
+    def map[U](self, func: Callable[[T], U]) -> Box[U]:
+        return Box(func(self._value))
+
+# Multiple type vars
+class Pair(Generic[T, U]):
+    def __init__(self, first: T, second: U) -> None:
+        self.first = first
+        self.second = second
+```
+
+### Variance (Covariance/Contravariance)
+```python
+from typing import TypeVar, Generic, Protocol
+
+# Covariant (output only) — use +T
+T_co = TypeVar("T_co", covariant=True)
+
+class Producer(Generic[T_co]):
+    def produce(self) -> T_co: ...
+
+# Contravariant (input only) — use -T
+T_contra = TypeVar("T_contra", contravariant=True)
+
+class Consumer(Generic[T_contra]):
+    def consume(self, item: T_contra) -> None: ...
+
+# Invariant (both) — default
+T = TypeVar("T")
+
+class Processor(Generic[T]):
+    def process(self, item: T) -> T: ...
+```
+
+### Variance Rules
+| Position | Variance |
+|----------|----------|
+| Return type | Covariant (+) |
+| Argument type | Contravariant (-) |
+| Mutable attribute | Invariant |
+| Read-only property | Covariant |
+
+### Protocol Variance
+```python
+T_co = TypeVar("T_co", covariant=True)
+
+class Readable(Protocol[T_co]):
+    def read(self) -> T_co: ...  # Covariant OK
+
+T_contra = TypeVar("T_contra", contravariant=True)
+
+class Writable(Protocol[T_contra]):
+    def write(self, data: T_contra) -> None: ...  # Contravariant OK
+```
+
+### Constrained TypeVars
+```python
+# Only these types allowed
+T = TypeVar("T", int, float, str)
+
+def process(x: T) -> T:  # Only int, float, str accepted
+    return x
+```
+
+### Bound TypeVars
+```python
+# Must be subclass of bound
+T = TypeVar("T", bound="BaseEntity")
+
+class BaseEntity:
+    id: int
+
+def save(entity: T) -> T:  # Must be BaseEntity subclass
+    return entity
+```
+
+### Higher-Kinded Types (Simulated)
+```python
+from typing import TypeVar, Generic, Callable
+
+# Functor-like
+F = TypeVar("F", bound=Callable[..., Any])
+
+def map_func[F](func: Callable[[A], B], fa: F[A]) -> F[B]:  # Not directly expressible
+    ...
+
+# Use protocols for typeclass-like patterns
+class Functor(Protocol[T]):
+    def map[U](self, func: Callable[[T], U]) -> "Functor[U]": ...
+```
+
+### Type Parameters (Python 3.12+)
+```python
+# New syntax
+class Box[T]:
+    def __init__(self, value: T) -> None:
+        self.value = value
+    
+    def get(self) -> T:
+        return self.value
+
+def identity[T](x: T) -> T:
+    return x
+```
+
+---
+
+## Decision Rules
+
+| Need | Pattern |
+|------|---------|
+| Interface for duck typing | `Protocol` |
+| Interface needing `isinstance` | `@runtime_checkable Protocol` |
+| Reusable container | `Generic[T]` |
+| Read-only collection | `Generic[+T]` (covariant) |
+| Callback handler | `Generic[-T]` (contravariant) |
+| Limited type set | `TypeVar("T", A, B, C)` |
+| Subtype constraint | `TypeVar("T", bound=Base)` |
+| Self-returning methods | `Self` (3.11+) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Repository pattern with protocol
+class UserRepo(Protocol):
+    def get(self, id: UserID) -> User | None: ...
+    def list(self, filter: UserFilter) -> list[User]: ...
+    def save(self, user: User) -> User: ...
+
+# Generic service
+class CrudService(Generic[T]):
+    def __init__(self, repo: Repository[T]) -> None:
+        self.repo = repo
+    
+    def get_or_create(self, id: str, factory: Callable[[], T]) -> T:
+        if (existing := self.repo.get(id)) is not None:
+            return existing
+        new = factory()
+        self.repo.save(new)
+        return new
+
+# Covariant read-only view
+class ReadOnlyList(Generic[T_co]):
+    def __init__(self, items: list[T_co]) -> None:
+        self._items = tuple(items)
+    
+    def __getitem__(self, i: int) -> T_co:
+        return self._items[i]
+    
+    def __iter__(self) -> Iterator[T_co]:
+        return iter(self._items)
+```
+
+---
+
+## Avoid
+
+- Overusing generics (YAGNI)
+- Invariant generics when covariant/contravariant works
+- `@runtime_checkable` on large protocols (performance)
+- Complex variance without clear need
+- Protocols with too many methods (split them)
+
+---
+
+## Validation Considerations
+
+- `mypy --strict` catches variance errors
+- Protocol conformance checked structurally
+- `isinstance(obj, Protocol)` only works with `@runtime_checkable`
+
+---
+
+## Related Skills
+
+- `generation/type_hints.md`
+- `core/oop.md` (ABCs)
+- `quality/abstractions.md`
+- `engineering/dependency_management.md`