devflow-kit 1.8.3 → 2.0.1

package/src/assets/skills/python/references/async.md

@@ -0,0 +1,255 @@
+# Async Python Patterns
+
+Deep-dive on async Python programming. Reference from main SKILL.md.
+All citations reference `sources.md`.
+
+## Core asyncio Patterns [16][1]
+
+asyncio implements the Reactor pattern — a single-threaded event loop dispatches
+callbacks when I/O completes [16]. Ramalho's Part V of Fluent Python covers the
+design in depth [1].
+
+### Basic Async Function [16]
+
+```python
+import asyncio
+from typing import Any
+
+async def fetch_user(user_id: str) -> User:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(f"/api/users/{user_id}") as response:
+            data = await response.json()
+            return User.model_validate(data)
+```
+
+### Concurrent Execution with gather [16][1]
+
+`asyncio.gather` runs independent coroutines concurrently — Ramalho's "spinner"
+example demonstrates that gather returns when ALL tasks complete [1]:
+
+```python
+async def load_dashboard(user_id: str) -> Dashboard:
+    # Independent fetches run concurrently
+    user, orders, preferences = await asyncio.gather(
+        fetch_user(user_id),
+        fetch_orders(user_id),
+        fetch_preferences(user_id),
+    )
+    return Dashboard(user=user, orders=orders, preferences=preferences)
+```
+
+## Structured Concurrency with TaskGroup [16]
+
+### TaskGroup for Safe Concurrency (Python 3.11+) [16]
+
+`asyncio.TaskGroup` is the structured concurrency primitive introduced in
+Python 3.11. It cancels all sibling tasks when one raises, preventing leaked
+coroutines [16]:
+
+```python
+async def process_batch(items: list[Item]) -> list[Result]:
+    results: list[Result] = []
+
+    async with asyncio.TaskGroup() as tg:
+        for item in items:
+            tg.create_task(process_and_collect(item, results))
+
+    return results
+
+async def process_and_collect(item: Item, results: list[Result]) -> None:
+    result = await process_item(item)
+    results.append(result)
+```
+
+### Error Handling with TaskGroup [16]
+
+TaskGroup cancels all tasks if one raises — wrap individual tasks for per-item
+error collection [16]:
+
+```python
+async def resilient_batch(items: list[Item]) -> tuple[list[Result], list[Error]]:
+    results: list[Result] = []
+    errors: list[Error] = []
+
+    # TaskGroup cancels all tasks if one raises — wrap individual tasks
+    async def safe_process(item: Item) -> None:
+        try:
+            result = await process_item(item)
+            results.append(result)
+        except ProcessingError as e:
+            errors.append(Error(item_id=item.id, message=str(e)))
+
+    async with asyncio.TaskGroup() as tg:
+        for item in items:
+            tg.create_task(safe_process(item))
+
+    return results, errors
+```
+
+## Async Generators [1][16]
+
+Ramalho covers async generators in depth — they enable streaming without loading
+all results into memory [1]:
+
+### Streaming Results
+
+```python
+from typing import AsyncGenerator
+
+async def stream_results(query: str, params: tuple = ()) -> AsyncGenerator[Record, None]:
+    async with get_connection() as conn:
+        cursor = await conn.execute(query, params)
+        async for row in cursor:
+            yield Record.from_row(row)
+
+# Usage
+async for record in stream_results("SELECT * FROM events WHERE type = ?", ("click",)):
+    await process(record)
+```
+
+### Async Generator with Cleanup [1]
+
+```python
+async def paginated_fetch(url: str, page_size: int = 100) -> AsyncGenerator[Item, None]:
+    page = 0
+    while True:
+        response = await fetch_page(url, page=page, size=page_size)
+        if not response.items:
+            break
+        for item in response.items:
+            yield item
+        page += 1
+```
+
+## Semaphore for Rate Limiting [16][10]
+
+asyncio Semaphore provides bounded concurrency — Beazley & Jones Cookbook
+shows this pattern for controlling outbound request volume [10][16]:
+
+### Bounded Concurrency
+
+```python
+async def fetch_all(urls: list[str], max_concurrent: int = 10) -> list[Response]:
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def bounded_fetch(url: str) -> Response:
+        async with semaphore:
+            return await fetch(url)
+
+    return await asyncio.gather(*[bounded_fetch(url) for url in urls])
+```
+
+## aiohttp Patterns [16]
+
+### Client Session Management
+
+Session reuse amortizes connection overhead across many requests [16]:
+
+```python
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+@asynccontextmanager
+async def api_client(base_url: str) -> AsyncGenerator[aiohttp.ClientSession, None]:
+    timeout = aiohttp.ClientTimeout(total=30)
+    async with aiohttp.ClientSession(base_url, timeout=timeout) as session:
+        yield session
+
+# Usage — session reused for multiple requests
+async def sync_users(user_ids: list[str]) -> list[User]:
+    async with api_client("https://api.example.com") as client:
+        tasks = [fetch_user_with_session(client, uid) for uid in user_ids]
+        return await asyncio.gather(*tasks)
+
+async def fetch_user_with_session(
+    client: aiohttp.ClientSession, user_id: str
+) -> User:
+    async with client.get(f"/users/{user_id}") as response:
+        response.raise_for_status()
+        data = await response.json()
+        return User.model_validate(data)
+```
+
+## Timeout Patterns [16]
+
+`asyncio.timeout` (Python 3.11+) replaces the `wait_for` pattern for per-operation
+timeouts [16]:
+
+### Per-Operation Timeout
+
+```python
+async def fetch_with_timeout(url: str, timeout_seconds: float = 5.0) -> dict[str, Any]:
+    try:
+        async with asyncio.timeout(timeout_seconds):
+            return await fetch(url)
+    except TimeoutError:
+        raise OperationTimeout(f"Request to {url} timed out after {timeout_seconds}s")
+```
+
+## Anti-Patterns
+
+### Blocking Calls in Async Code [16][2]
+
+Slatkin's Item 62 and asyncio docs both flag synchronous I/O inside async functions
+as blocking the event loop for all other coroutines [2][16]:
+
+```python
+# VIOLATION: Blocks the event loop [16]
+async def bad_fetch(url: str) -> str:
+    import requests
+    return requests.get(url).text  # Blocks entire event loop!
+
+# CORRECT: Use async library or run in executor [16]
+async def good_fetch(url: str) -> str:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.text()
+
+# CORRECT: Offload blocking call to thread pool [16]
+async def run_blocking(func: Callable[..., R], *args: Any) -> R:
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, func, *args)
+```
+
+### Fire-and-Forget Without Error Handling [16][1]
+
+Ramalho and asyncio docs both warn that `create_task` without a done callback
+silently discards exceptions [1][16]:
+
+```python
+# VIOLATION: Exception silently lost [16]
+async def bad_handler(event: Event) -> None:
+    asyncio.create_task(send_notification(event))  # Error vanishes
+
+# CORRECT: Track the task and handle errors [16]
+async def good_handler(event: Event) -> None:
+    task = asyncio.create_task(send_notification(event))
+    task.add_done_callback(handle_task_exception)
+
+def handle_task_exception(task: asyncio.Task[Any]) -> None:
+    if not task.cancelled() and task.exception() is not None:
+        logger.error("Background task failed", exc_info=task.exception())
+```
+
+### Sequential When Parallel Is Safe [16][1]
+
+Ramalho's dashboard example (Fluent Python Ch. 21) benchmarks sequential vs
+concurrent fetching — 3 sequential awaits take 3x longer than gather [1]:
+
+```python
+# VIOLATION: Unnecessarily sequential — 3x slower [1]
+async def slow_load(user_id: str) -> Dashboard:
+    user = await fetch_user(user_id)
+    orders = await fetch_orders(user_id)
+    prefs = await fetch_preferences(user_id)
+    return Dashboard(user=user, orders=orders, preferences=prefs)
+
+# CORRECT: Concurrent — ~1x latency [1][16]
+async def fast_load(user_id: str) -> Dashboard:
+    user, orders, prefs = await asyncio.gather(
+        fetch_user(user_id),
+        fetch_orders(user_id),
+        fetch_preferences(user_id),
+    )
+    return Dashboard(user=user, orders=orders, preferences=prefs)
+```

package/src/assets/skills/python/references/patterns.md

@@ -0,0 +1,280 @@
+# Python Correct Patterns
+
+Extended correct patterns for Python development. Reference from main SKILL.md.
+All citations reference `sources.md`.
+
+## Dependency Injection [9][1]
+
+### Constructor Injection
+
+Cosmic Python's repository pattern uses constructor injection for all service
+dependencies [9]. Ramalho notes that Protocol-typed parameters decouple interface
+from implementation [1].
+
+```python
+from typing import Protocol
+
+class EmailSender(Protocol):
+    def send(self, to: str, subject: str, body: str) -> None: ...
+
+class UserService:
+    def __init__(self, repo: UserRepository, emailer: EmailSender) -> None:
+        self._repo = repo
+        self._emailer = emailer
+
+    def create_user(self, request: CreateUserRequest) -> User:
+        user = User(name=request.name, email=request.email)
+        saved = self._repo.save(user)
+        self._emailer.send(user.email, "Welcome", f"Hello {user.name}")
+        return saved
+
+# Easy to test — inject fakes [13]
+service = UserService(repo=FakeUserRepo(), emailer=FakeEmailSender())
+```
+
+### Factory Functions [9]
+
+Cosmic Python recommends a top-level factory (bootstrap module) that wires all
+real dependencies at startup [9]:
+
+```python
+def create_app(config: AppConfig) -> Flask:
+    app = Flask(__name__)
+    db = Database(config.database_url)
+    cache = RedisCache(config.redis_url)
+    user_service = UserService(repo=SqlUserRepo(db), emailer=SmtpSender(config.smtp))
+    register_routes(app, user_service)
+    return app
+```
+
+## Decorator Patterns [10][1]
+
+### Retry Decorator
+
+Beazley & Jones Cookbook recipe for retry with exponential backoff [10].
+Uses `ParamSpec` (PEP 612) for preserving callable signatures [1]:
+
+```python
+import functools
+import time
+from typing import TypeVar, Callable, ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def retry(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            last_error: Exception | None = None
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_error = e
+                    if attempt < max_attempts - 1:
+                        time.sleep(delay * (2 ** attempt))
+            raise last_error  # type: ignore[misc]
+        return wrapper
+    return decorator
+
+@retry(max_attempts=3, delay=0.5, exceptions=(ConnectionError, TimeoutError))
+def fetch_data(url: str) -> dict[str, Any]:
+    ...
+```
+
+### Validation Decorator [12]
+
+```python
+def validate_input(schema: type[BaseModel]):
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # Validate first positional arg after self/cls
+            data = args[1] if len(args) > 1 else args[0]
+            schema.model_validate(data)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+```
+
+## Context Manager Patterns [10][9]
+
+### Database Transaction
+
+Unit-of-work pattern from Cosmic Python; transaction wraps the session lifecycle [9].
+Beazley & Jones provide the `@contextmanager` recipe [10]:
+
+```python
+from contextlib import contextmanager
+from typing import Generator
+
+@contextmanager
+def transaction(session: Session) -> Generator[Session, None, None]:
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+# Usage
+with transaction(db.session()) as session:
+    session.add(user)
+    session.add(audit_log)
+```
+
+### Temporary Directory [10]
+
+```python
+from contextlib import contextmanager
+from pathlib import Path
+import tempfile
+import shutil
+
+@contextmanager
+def temp_workspace() -> Generator[Path, None, None]:
+    path = Path(tempfile.mkdtemp())
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path, ignore_errors=True)
+```
+
+## Pytest Fixture Patterns [13][9]
+
+### Service Fixtures with DI
+
+pytest fixtures compose naturally with the DI pattern from Cosmic Python [9][13]:
+
+```python
+import pytest
+
+@pytest.fixture
+def fake_repo() -> FakeUserRepo:
+    return FakeUserRepo()
+
+@pytest.fixture
+def fake_emailer() -> FakeEmailSender:
+    return FakeEmailSender()
+
+@pytest.fixture
+def user_service(fake_repo: FakeUserRepo, fake_emailer: FakeEmailSender) -> UserService:
+    return UserService(repo=fake_repo, emailer=fake_emailer)
+
+def test_create_user_sends_welcome_email(
+    user_service: UserService,
+    fake_emailer: FakeEmailSender,
+) -> None:
+    user_service.create_user(CreateUserRequest(name="Alice", email="a@b.com"))
+    assert fake_emailer.sent_count == 1
+    assert fake_emailer.last_to == "a@b.com"
+```
+
+### Parametrized Tests [13]
+
+Slatkin's "Effective Python" recommends parametrize for exhaustive edge coverage [2][13]:
+
+```python
+@pytest.mark.parametrize(
+    "input_age, expected_valid",
+    [
+        (25, True),
+        (0, True),
+        (150, True),
+        (-1, False),
+        (151, False),
+        (None, False),
+    ],
+)
+def test_age_validation(input_age: int | None, expected_valid: bool) -> None:
+    result = validate_age(input_age)
+    assert result.is_valid == expected_valid
+```
+
+## Structured Logging [20]
+
+structlog binds context to a logger instance, producing machine-readable JSON [20]:
+
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+def process_order(order: Order) -> OrderResult:
+    log = logger.bind(order_id=order.id, user_id=order.user_id)
+    log.info("processing_order", item_count=len(order.items))
+
+    try:
+        result = fulfill(order)
+        log.info("order_fulfilled", total=result.total)
+        return result
+    except InsufficientStockError as e:
+        log.warning("order_failed_stock", item_id=e.item_id)
+        raise
+```
+
+## Enum Patterns [2][24]
+
+PEP 634 structural pattern matching works cleanly with Enum [24].
+Slatkin recommends enum state machines with explicit transition tables [2]:
+
+```python
+from enum import Enum, auto
+
+class OrderStatus(Enum):
+    PENDING = auto()
+    PROCESSING = auto()
+    SHIPPED = auto()
+    DELIVERED = auto()
+    CANCELLED = auto()
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in (OrderStatus.DELIVERED, OrderStatus.CANCELLED)
+
+    def can_transition_to(self, target: "OrderStatus") -> bool:
+        valid = {
+            OrderStatus.PENDING: {OrderStatus.PROCESSING, OrderStatus.CANCELLED},
+            OrderStatus.PROCESSING: {OrderStatus.SHIPPED, OrderStatus.CANCELLED},
+            OrderStatus.SHIPPED: {OrderStatus.DELIVERED},
+        }
+        return target in valid.get(self, set())
+```
+
+## Generic Types [7][4]
+
+PEP 695 (Python 3.12) introduces clean generic syntax [7]:
+
+```python
+# Before PEP 695
+from typing import TypeVar, Generic
+T = TypeVar("T")
+
+class Stack(Generic[T]):
+    def push(self, item: T) -> None: ...
+    def pop(self) -> T: ...
+
+# After PEP 695 (Python 3.12+)
+class Stack[T]:
+    def push(self, item: T) -> None: ...
+    def pop(self) -> T: ...
+```
+
+## Protocol vs ABC Decision [5][1][14]
+
+Use **Protocol** (structural) when:
+- The implementing class should not be forced to import the interface [5]
+- Third-party classes already satisfy the interface [1]
+- You want duck-typing behavior with static verification [5]
+
+Use **ABC** (nominal) when:
+- You need shared implementation via `@abstractmethod` + mixin [1]
+- You need `isinstance()` checks at runtime [14]
+- The interface is coupled to the hierarchy (e.g., plugin system) [9]

package/src/assets/skills/python/references/sources.md

@@ -0,0 +1,41 @@
+# Python Skill — Sources
+
+## Primary References
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 1 | "Fluent Python" 2nd Ed | Luciano Ramalho | 2022 | Purchase | Data model, protocols, iterators, async, descriptors |
+| 2 | "Effective Python" 2nd Ed | Brett Slatkin | 2020 | Purchase | 90 items for Pythonic code, type hints, concurrency |
+| 3 | PEP 20: The Zen of Python | Tim Peters | 2004 | [Free](https://peps.python.org/pep-0020/) | Core philosophy — explicit, simple, readable |
+| 4 | PEP 484: Type Hints | van Rossum, Lehtosalo, Langa | 2014 | [Free](https://peps.python.org/pep-0484/) | Type annotation foundation, Optional, Union, generics |
+| 5 | PEP 544: Protocols — Structural subtyping | Levkivskyi, Lehtosalo, van Rossum | 2017 | [Free](https://peps.python.org/pep-0544/) | Structural subtyping, duck typing formalized |
+| 6 | PEP 557: Data Classes | Eric V. Smith | 2017 | [Free](https://peps.python.org/pep-0557/) | Dataclass decorator, frozen, field, default_factory |
+| 7 | PEP 695: Type Parameter Syntax | Python 3.12 | 2023 | [Free](https://peps.python.org/pep-0695/) | Generic syntax `type[T]`, new `type` statement |
+| 8 | Google Python Style Guide | Google | 2024 | [Free](https://google.github.io/styleguide/pyguide.html) | Naming, formatting, imports, docstrings |
+| 9 | "Architecture Patterns with Python" (Cosmic Python) | Percival & Gregory | 2020 | [Free](https://www.cosmicpython.com) | DDD, repository pattern, CQRS, dependency injection |
+| 10 | "Python Cookbook" 3rd Ed | Beazley & Jones | 2013 | Purchase | Advanced recipes, metaprogramming, decorators |
+| 11 | mypy Documentation | mypy-lang.org | 2024 | [Free](https://mypy.readthedocs.io) | Static type checking, strict mode, ignore patterns |
+| 12 | Pydantic Documentation | Samuel Colvin | 2024 | [Free](https://docs.pydantic.dev) | Data validation, model_validate, field validators |
+| 13 | pytest Documentation | pytest.org | 2024 | [Free](https://docs.pytest.org) | Testing framework, fixtures, parametrize, plugins |
+| 14 | "Robust Python" | Patrick Viafore | 2021 | Purchase | Type-driven design, user-defined types, protocols |
+| 15 | PEP 3107: Function Annotations | Collin Winter | 2006 | [Free](https://peps.python.org/pep-3107/) | Annotation syntax origin, `__annotations__` |
+| 16 | asyncio Documentation | Python.org | 2024 | [Free](https://docs.python.org/3/library/asyncio.html) | Event loop, tasks, gather, TaskGroup, timeout |
+| 17 | "Python Type Checking" | Geir Arne Hjelle | 2023 | [Free](https://realpython.com/python-type-checking/) | Type hints tutorial, mypy walkthrough |
+
+## Case Studies & Design
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 18 | Dropbox typing case study | Jukka Lehtosalo | 2018 | [Free](https://dropbox.tech/application/our-journey-to-type-checking-4-million-lines-of-python) | Large-scale typing migration, mypy at Dropbox |
+| 19 | "Making wrong code look wrong" | Joel Spolsky | 2005 | [Free](https://www.joelonsoftware.com/2005/05/11/making-wrong-code-look-wrong/) | Type naming, Hungarian notation to type hints |
+| 20 | structlog Documentation | Hynek Schlawack | 2024 | [Free](https://www.structlog.org) | Structured logging, context binding, processors |
+
+## PEP Progression
+
+| # | Source | Year | Access | Topics |
+|---|--------|------|--------|--------|
+| 21 | PEP 526: Variable Annotations | 2016 | [Free](https://peps.python.org/pep-0526/) | Class-level and variable annotation syntax |
+| 22 | PEP 563: Postponed Evaluation of Annotations | 2017 | [Free](https://peps.python.org/pep-0563/) | `from __future__ import annotations` — forward refs |
+| 23 | PEP 604: Union Types with `\|` | 2020 | [Free](https://peps.python.org/pep-0604/) | `X \| Y` syntax replacing `Union[X, Y]` |
+| 24 | PEP 634: Structural Pattern Matching | 2020 | [Free](https://peps.python.org/pep-0634/) | `match`/`case` statement, structural patterns |
+| 25 | PEP 673: Self Type | 2021 | [Free](https://peps.python.org/pep-0673/) | `Self` type for methods returning same class |