devflow-kit 1.8.3 → 2.0.0

package/shared/skills/python/references/async.md

@@ -1,220 +0,0 @@
-# Async Python Patterns
-
-Deep-dive on async Python programming. Reference from main SKILL.md.
-
-## Core asyncio Patterns
-
-### Basic Async Function
-
-```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
-
-```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
-
-### TaskGroup for Safe Concurrency (Python 3.11+)
-
-```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
-
-```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
-
-### 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
-
-```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
-
-### 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
-
-### Client Session Management
-
-```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
-
-### 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
-
-```python
-# VIOLATION: Blocks the event loop
-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
-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
-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
-
-```python
-# VIOLATION: Exception silently lost
-async def bad_handler(event: Event) -> None:
-    asyncio.create_task(send_notification(event))  # Error vanishes
-
-# CORRECT: Track the task and handle errors
-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
-
-```python
-# VIOLATION: Unnecessarily sequential — 3x slower
-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
-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/shared/skills/python/references/detection.md

@@ -1,128 +0,0 @@
-# Python Issue Detection
-
-Grep patterns for finding common Python issues. Reference from main SKILL.md.
-
-## Type Safety Detection
-
-### Missing Type Hints
-
-```bash
-# Functions without return type annotation
-grep -rn "def .*):$" --include="*.py" | grep -v "->.*:"
-
-# Functions without any annotations
-grep -rn "def .*([a-z_][a-z_0-9]*\s*," --include="*.py" | grep -v ":"
-```
-
-### Bare Except Clauses
-
-```bash
-# Bare except (catches everything)
-grep -rn "except:" --include="*.py"
-
-# Overly broad except Exception
-grep -rn "except Exception:" --include="*.py" | grep -v "# noqa"
-```
-
-## Data Modeling Detection
-
-### Mutable Default Arguments
-
-```bash
-# List defaults
-grep -rn "def .*=\s*\[\]" --include="*.py"
-
-# Dict defaults
-grep -rn "def .*=\s*{}" --include="*.py"
-
-# Set defaults
-grep -rn "def .*=\s*set()" --include="*.py"
-```
-
-### Raw Dict Usage Instead of Dataclasses
-
-```bash
-# Dict literals assigned to typed variables
-grep -rn ': dict\[' --include="*.py" | grep "= {"
-
-# Nested dict access patterns (fragile)
-grep -rn '\["[a-z].*\]\["' --include="*.py"
-```
-
-## Anti-Pattern Detection
-
-### Assert in Production Code
-
-```bash
-# Assert statements outside test files
-grep -rn "^    assert " --include="*.py" | grep -v "test_\|_test\.py\|tests/"
-```
-
-### Global Mutable State
-
-```bash
-# Global variable assignment
-grep -rn "^[a-z_].*= \[\]\|^[a-z_].*= {}\|^[a-z_].*= set()" --include="*.py"
-
-# Global keyword usage
-grep -rn "global " --include="*.py"
-```
-
-### Old-Style String Formatting
-
-```bash
-# Percent formatting
-grep -rn '"%.*" %' --include="*.py"
-grep -rn "'%.*' %" --include="*.py"
-
-# .format() where f-strings would be cleaner
-grep -rn '\.format(' --include="*.py"
-```
-
-### Wildcard Imports
-
-```bash
-# Star imports
-grep -rn "from .* import \*" --include="*.py"
-```
-
-## Async Detection
-
-### Missing Await
-
-```bash
-# Coroutine called without await (common mistake)
-grep -rn "async def" --include="*.py" -l | xargs grep -n "[^await ]fetch\|[^await ]save\|[^await ]send"
-```
-
-### Blocking Calls in Async Code
-
-```bash
-# time.sleep in async context
-grep -rn "time\.sleep" --include="*.py"
-
-# requests library in async files (should use aiohttp/httpx)
-grep -rn "import requests\|from requests" --include="*.py"
-```
-
-## Security Detection
-
-### Unsafe Deserialization
-
-```bash
-# pickle usage (arbitrary code execution risk)
-grep -rn "pickle\.loads\|pickle\.load(" --include="*.py"
-
-# yaml.load without SafeLoader
-grep -rn "yaml\.load(" --include="*.py" | grep -v "SafeLoader\|safe_load"
-```
-
-### Shell Injection
-
-```bash
-# subprocess with shell=True
-grep -rn "shell=True" --include="*.py"
-
-# os.system calls
-grep -rn "os\.system(" --include="*.py"
-```

package/shared/skills/python/references/patterns.md

@@ -1,226 +0,0 @@
-# Python Correct Patterns
-
-Extended correct patterns for Python development. Reference from main SKILL.md.
-
-## Dependency Injection
-
-### Constructor Injection
-
-```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
-service = UserService(repo=FakeUserRepo(), emailer=FakeEmailSender())
-```
-
-### Factory Functions
-
-```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
-
-### Retry Decorator
-
-```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
-
-```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
-
-### Database Transaction
-
-```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
-
-```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
-
-### Service Fixtures with DI
-
-```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
-
-```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
-
-```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
-
-```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())
-```