aigroup-workflow 2.1.1 → 2.2.0

package/skills/python-pro/SKILL.md

@@ -1,177 +0,0 @@
----
-name: python-pro
-description: Use when building Python 3.11+ applications requiring type safety, async programming, or robust error handling. Generates type-annotated Python code, configures mypy in strict mode, writes pytest test suites with fixtures and mocking, and validates code with black and ruff. Invoke for type hints, async/await patterns, dataclasses, dependency injection, logging configuration, and structured error handling.
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.1.0"
-  domain: language
-  triggers: Python development, type hints, async Python, pytest, mypy, dataclasses, Python best practices, Pythonic code
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: fastapi-expert, devops-engineer
----
-
-# Python Pro
-
-Modern Python 3.11+ specialist focused on type-safe, async-first, production-ready code.
-
-## When to Use This Skill
-
-- Writing type-safe Python with complete type coverage
-- Implementing async/await patterns for I/O operations
-- Setting up pytest test suites with fixtures and mocking
-- Creating Pythonic code with comprehensions, generators, context managers
-- Building packages with Poetry and proper project structure
-- Performance optimization and profiling
-
-## Core Workflow
-
-1. **Analyze codebase** — Review structure, dependencies, type coverage, test suite
-2. **Design interfaces** — Define protocols, dataclasses, type aliases
-3. **Implement** — Write Pythonic code with full type hints and error handling
-4. **Test** — Create comprehensive pytest suite with >90% coverage
-5. **Validate** — Run `mypy --strict`, `black`, `ruff`
-   - If mypy fails: fix type errors reported and re-run before proceeding
-   - If tests fail: debug assertions, update fixtures, and iterate until green
-   - If ruff/black reports issues: apply auto-fixes, then re-validate
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Type System | `references/type-system.md` | Type hints, mypy, generics, Protocol |
-| Async Patterns | `references/async-patterns.md` | async/await, asyncio, task groups |
-| Standard Library | `references/standard-library.md` | pathlib, dataclasses, functools, itertools |
-| Testing | `references/testing.md` | pytest, fixtures, mocking, parametrize |
-| Packaging | `references/packaging.md` | poetry, pip, pyproject.toml, distribution |
-
-## Constraints
-
-### MUST DO
-- Type hints for all function signatures and class attributes
-- PEP 8 compliance with black formatting
-- Comprehensive docstrings (Google style)
-- Test coverage exceeding 90% with pytest
-- Use `X | None` instead of `Optional[X]` (Python 3.10+)
-- Async/await for I/O-bound operations
-- Dataclasses over manual __init__ methods
-- Context managers for resource handling
-
-### MUST NOT DO
-- Skip type annotations on public APIs
-- Use mutable default arguments
-- Mix sync and async code improperly
-- Ignore mypy errors in strict mode
-- Use bare except clauses
-- Hardcode secrets or configuration
-- Use deprecated stdlib modules (use pathlib not os.path)
-
-## Code Examples
-
-### Type-annotated function with error handling
-```python
-from pathlib import Path
-
-def read_config(path: Path) -> dict[str, str]:
-    """Read configuration from a file.
-
-    Args:
-        path: Path to the configuration file.
-
-    Returns:
-        Parsed key-value configuration entries.
-
-    Raises:
-        FileNotFoundError: If the config file does not exist.
-        ValueError: If a line cannot be parsed.
-    """
-    config: dict[str, str] = {}
-    with path.open() as f:
-        for line in f:
-            key, _, value = line.partition("=")
-            if not key.strip():
-                raise ValueError(f"Invalid config line: {line!r}")
-            config[key.strip()] = value.strip()
-    return config
-```
-
-### Dataclass with validation
-```python
-from dataclasses import dataclass, field
-
-@dataclass
-class AppConfig:
-    host: str
-    port: int
-    debug: bool = False
-    allowed_origins: list[str] = field(default_factory=list)
-
-    def __post_init__(self) -> None:
-        if not (1 <= self.port <= 65535):
-            raise ValueError(f"Invalid port: {self.port}")
-```
-
-### Async pattern
-```python
-import asyncio
-import httpx
-
-async def fetch_all(urls: list[str]) -> list[bytes]:
-    """Fetch multiple URLs concurrently."""
-    async with httpx.AsyncClient() as client:
-        tasks = [client.get(url) for url in urls]
-        responses = await asyncio.gather(*tasks)
-        return [r.content for r in responses]
-```
-
-### pytest fixture and parametrize
-```python
-import pytest
-from pathlib import Path
-
-@pytest.fixture
-def config_file(tmp_path: Path) -> Path:
-    cfg = tmp_path / "config.txt"
-    cfg.write_text("host=localhost\nport=8080\n")
-    return cfg
-
-@pytest.mark.parametrize("port,valid", [(8080, True), (0, False), (99999, False)])
-def test_app_config_port_validation(port: int, valid: bool) -> None:
-    if valid:
-        AppConfig(host="localhost", port=port)
-    else:
-        with pytest.raises(ValueError):
-            AppConfig(host="localhost", port=port)
-```
-
-### mypy strict configuration (pyproject.toml)
-```toml
-[tool.mypy]
-python_version = "3.11"
-strict = true
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = true
-```
-
-Clean `mypy --strict` output looks like:
-```
-Success: no issues found in 12 source files
-```
-Any reported error (e.g., `error: Function is missing a return type annotation`) must be resolved before the implementation is considered complete.
-
-## Output Templates
-
-When implementing Python features, provide:
-1. Module file with complete type hints
-2. Test file with pytest fixtures
-3. Type checking confirmation (mypy --strict passes)
-4. Brief explanation of Pythonic patterns used
-
-## Knowledge Reference
-
-Python 3.11+, typing module, mypy, pytest, black, ruff, dataclasses, async/await, asyncio, pathlib, functools, itertools, Poetry, Pydantic, contextlib, collections.abc, Protocol

package/skills/python-pro/references/async-patterns.md

@@ -1,356 +0,0 @@
-# Async Programming Patterns
-
-## Basic Async/Await
-
-```python
-import asyncio
-from collections.abc import Coroutine
-
-# Basic async function
-async def fetch_data(url: str) -> dict[str, str]:
-    await asyncio.sleep(1)  # Simulate I/O
-    return {"url": url, "status": "ok"}
-
-# Running async code
-async def main() -> None:
-    result = await fetch_data("https://api.example.com")
-    print(result)
-
-if __name__ == "__main__":
-    asyncio.run(main())
-
-# Multiple concurrent operations
-async def fetch_all(urls: list[str]) -> list[dict[str, str]]:
-    tasks = [fetch_data(url) for url in urls]
-    return await asyncio.gather(*tasks)
-
-# Error handling with gather
-async def safe_fetch_all(urls: list[str]) -> list[dict[str, str] | None]:
-    tasks = [fetch_data(url) for url in urls]
-    results = await asyncio.gather(*tasks, return_exceptions=True)
-    return [r if not isinstance(r, Exception) else None for r in results]
-```
-
-## Task Groups (Python 3.11+)
-
-```python
-from asyncio import TaskGroup
-
-# Task groups for structured concurrency
-async def process_batch(items: list[int]) -> list[int]:
-    results: list[int] = []
-
-    async with TaskGroup() as tg:
-        tasks = [tg.create_task(process_item(item)) for item in items]
-
-    # All tasks complete before this line
-    return [task.result() for task in tasks]
-
-# Error handling with TaskGroup
-async def robust_processing(items: list[str]) -> tuple[list[str], list[Exception]]:
-    results: list[str] = []
-    errors: list[Exception] = []
-
-    try:
-        async with TaskGroup() as tg:
-            for item in items:
-                tg.create_task(process_item_safe(item))
-    except ExceptionGroup as eg:
-        for exc in eg.exceptions:
-            errors.append(exc)
-
-    return results, errors
-```
-
-## Async Context Managers
-
-```python
-from typing import Self
-from collections.abc import AsyncIterator
-
-class AsyncDatabaseConnection:
-    def __init__(self, url: str) -> None:
-        self.url = url
-        self._conn: Connection | None = None
-
-    async def __aenter__(self) -> Self:
-        self._conn = await connect(self.url)
-        return self
-
-    async def __aexit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: Any,
-    ) -> None:
-        if self._conn:
-            await self._conn.close()
-
-    async def query(self, sql: str) -> list[dict[str, Any]]:
-        if not self._conn:
-            raise RuntimeError("Not connected")
-        return await self._conn.execute(sql)
-
-# Usage
-async def get_users() -> list[dict[str, Any]]:
-    async with AsyncDatabaseConnection("postgresql://...") as db:
-        return await db.query("SELECT * FROM users")
-
-# Async context manager with contextlib
-from contextlib import asynccontextmanager
-
-@asynccontextmanager
-async def get_db_session() -> AsyncIterator[Session]:
-    session = await create_session()
-    try:
-        yield session
-        await session.commit()
-    except Exception:
-        await session.rollback()
-        raise
-    finally:
-        await session.close()
-```
-
-## Async Generators
-
-```python
-from collections.abc import AsyncIterator
-
-# Async generator for streaming data
-async def read_lines(filepath: str) -> AsyncIterator[str]:
-    async with aiofiles.open(filepath) as f:
-        async for line in f:
-            yield line.strip()
-
-# Process stream
-async def process_file(filepath: str) -> int:
-    count = 0
-    async for line in read_lines(filepath):
-        await process_line(line)
-        count += 1
-    return count
-
-# Async generator with cleanup
-async def fetch_paginated(url: str) -> AsyncIterator[dict[str, Any]]:
-    page = 1
-    session = await create_session()
-    try:
-        while True:
-            data = await session.get(f"{url}?page={page}")
-            if not data:
-                break
-            yield data
-            page += 1
-    finally:
-        await session.close()
-```
-
-## Async Comprehensions
-
-```python
-# Async list comprehension
-async def fetch_all_users(user_ids: list[int]) -> list[User]:
-    return [user async for user in fetch_users(user_ids)]
-
-# Async dict comprehension
-async def build_user_map(user_ids: list[int]) -> dict[int, User]:
-    return {
-        user.id: user
-        async for user in fetch_users(user_ids)
-    }
-
-# Conditional async comprehension
-async def get_active_users(user_ids: list[int]) -> list[User]:
-    return [
-        user
-        async for user in fetch_users(user_ids)
-        if user.is_active
-    ]
-```
-
-## Synchronization Primitives
-
-```python
-import asyncio
-
-# Lock for critical sections
-class SharedResource:
-    def __init__(self) -> None:
-        self._lock = asyncio.Lock()
-        self._data: dict[str, Any] = {}
-
-    async def update(self, key: str, value: Any) -> None:
-        async with self._lock:
-            # Critical section
-            current = self._data.get(key, 0)
-            await asyncio.sleep(0.1)  # Simulate processing
-            self._data[key] = current + value
-
-# Semaphore for rate limiting
-class RateLimiter:
-    def __init__(self, max_concurrent: int) -> None:
-        self._semaphore = asyncio.Semaphore(max_concurrent)
-
-    async def process(self, item: str) -> str:
-        async with self._semaphore:
-            return await expensive_operation(item)
-
-# Event for coordination
-class AsyncWorker:
-    def __init__(self) -> None:
-        self._ready = asyncio.Event()
-        self._shutdown = asyncio.Event()
-
-    async def start(self) -> None:
-        # Initialization
-        await self._initialize()
-        self._ready.set()
-
-        # Wait for shutdown
-        await self._shutdown.wait()
-
-    async def wait_ready(self) -> None:
-        await self._ready.wait()
-
-    def stop(self) -> None:
-        self._shutdown.set()
-```
-
-## Async Queue Patterns
-
-```python
-from asyncio import Queue
-
-# Producer-consumer pattern
-async def producer(queue: Queue[int], n: int) -> None:
-    for i in range(n):
-        await queue.put(i)
-        await asyncio.sleep(0.1)
-
-async def consumer(queue: Queue[int], name: str) -> None:
-    while True:
-        item = await queue.get()
-        try:
-            await process_item(item)
-        finally:
-            queue.task_done()
-
-async def run_pipeline(num_items: int, num_workers: int) -> None:
-    queue: Queue[int] = Queue(maxsize=10)
-
-    # Start producer and consumers
-    async with TaskGroup() as tg:
-        tg.create_task(producer(queue, num_items))
-        for i in range(num_workers):
-            tg.create_task(consumer(queue, f"worker-{i}"))
-
-        # Wait for all items to be processed
-        await queue.join()
-```
-
-## Async Timeouts
-
-```python
-# Timeout for single operation
-async def fetch_with_timeout(url: str, timeout: float) -> dict[str, Any]:
-    try:
-        async with asyncio.timeout(timeout):
-            return await fetch_data(url)
-    except TimeoutError:
-        return {"error": "timeout"}
-
-# Timeout for multiple operations
-async def fetch_all_with_timeout(
-    urls: list[str],
-    timeout: float
-) -> list[dict[str, Any] | None]:
-    try:
-        async with asyncio.timeout(timeout):
-            return await fetch_all(urls)
-    except TimeoutError:
-        return [None] * len(urls)
-```
-
-## Background Tasks
-
-```python
-from asyncio import create_task, Task
-
-class BackgroundTaskManager:
-    def __init__(self) -> None:
-        self._tasks: set[Task[None]] = set()
-
-    def create_task(self, coro: Coroutine[None, None, None]) -> Task[None]:
-        task = create_task(coro)
-        self._tasks.add(task)
-        task.add_done_callback(self._tasks.discard)
-        return task
-
-    async def shutdown(self) -> None:
-        # Cancel all background tasks
-        for task in self._tasks:
-            task.cancel()
-        # Wait for cancellation
-        await asyncio.gather(*self._tasks, return_exceptions=True)
-
-# Usage
-manager = BackgroundTaskManager()
-manager.create_task(background_job())
-```
-
-## Async Iteration Protocol
-
-```python
-class AsyncRange:
-    def __init__(self, start: int, end: int) -> None:
-        self.start = start
-        self.end = end
-        self.current = start
-
-    def __aiter__(self) -> Self:
-        return self
-
-    async def __anext__(self) -> int:
-        if self.current >= self.end:
-            raise StopAsyncIteration
-        await asyncio.sleep(0.1)  # Simulate async work
-        value = self.current
-        self.current += 1
-        return value
-
-# Usage
-async for i in AsyncRange(0, 5):
-    print(i)
-```
-
-## Mixing Sync and Async
-
-```python
-from concurrent.futures import ThreadPoolExecutor
-import functools
-
-# Run sync code in executor
-async def run_in_executor(func: Callable[..., T], *args: Any) -> T:
-    loop = asyncio.get_running_loop()
-    return await loop.run_in_executor(None, func, *args)
-
-# Run async code from sync context
-def sync_wrapper(coro: Coroutine[None, None, T]) -> T:
-    loop = asyncio.new_event_loop()
-    try:
-        return loop.run_until_complete(coro)
-    finally:
-        loop.close()
-
-# Async wrapper for sync function
-def to_async(func: Callable[..., T]) -> Callable[..., Coroutine[None, None, T]]:
-    @functools.wraps(func)
-    async def wrapper(*args: Any, **kwargs: Any) -> T:
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            functools.partial(func, *args, **kwargs)
-        )
-    return wrapper
-```