python-skills 1.0.0__py3-none-any.whl

skills/functions.md

@@ -0,0 +1,244 @@
+---
+name: core_functions
+purpose: Python function definition, calling conventions, and patterns
+category: core
+triggers:
+  - function
+  - def
+  - method
+  - parameter
+  - argument
+  - callable
+  - closure
+  - decorator
+dependencies:
+  - core/advanced_python.md
+  - generation/type_hints.md
+  - quality/functions.md
+  - anti_patterns/index.md
+priority: primary
+estimated_tokens: 2000
+---
+# Core: Functions
+
+**Purpose**: Python function definition, calling conventions, and patterns.
+
+**When to use**: Always active. Functions are the primary abstraction unit.
+
+---
+
+## Core Rules
+
+### Definition
+```python
+def function_name(
+    positional: type,
+    positional_with_default: type = default,
+    *args: type,
+    keyword_only: type,
+    keyword_only_with_default: type = default,
+    **kwargs: type,
+) -> return_type:
+    """Docstring describing what, args, returns, raises."""
+    ...
+```
+
+### Parameter Kinds (PEP 3102, PEP 570)
+| Kind | Syntax | Position | Use For |
+|------|--------|----------|---------|
+| Positional-only | `pos_only, /` | Before `/` | API stability, `self`/`cls` |
+| Positional-or-keyword | `pos_or_kw` | Default | Most parameters |
+| Keyword-only | `*, kw_only` | After `*` | Required named args, clarity |
+| Var-positional | `*args` | After positional | Variable positional args |
+| Var-keyword | `**kwargs` | Last | Variable keyword args |
+
+### Default Arguments
+- Evaluated **once** at function definition time
+- **Never use mutable defaults** (`[]`, `{}`, `set()`) — creates shared state
+- Use `None` sentinel pattern instead
+
+```python
+# WRONG
+def bad(items=[]):
+    items.append(1)
+    return items
+
+# CORRECT
+def good(items=None):
+    if items is None:
+        items = []
+    items.append(1)
+    return items
+```
+
+### Return Values
+- Implicit `return None` if no return statement
+- Multiple returns via tuple: `return a, b`
+- Explicit `return` for early exits
+- Type hint return type (`-> Type`)
+
+### Function Attributes
+```python
+func.__name__        # Name
+func.__doc__         # Docstring
+func.__annotations__ # Type hints
+func.__defaults__    # Default values tuple
+func.__kwdefaults__  # Keyword-only defaults dict
+```
+
+---
+
+## Calling Conventions
+
+```python
+# Positional
+func(1, 2)
+
+# Keyword
+func(pos=1, kw=2)
+
+# Mixed (positional before keyword)
+func(1, kw=2)
+
+# Unpacking
+func(*args, **kwargs)
+```
+
+### Positional-Only Parameters (Python 3.8+)
+```python
+def func(pos_only, /, pos_or_kw, *, kw_only):
+    ...
+```
+- Use `/` to enforce positional-only (e.g., `self`, `cls`, builtins like `len`)
+
+---
+
+## Advanced Patterns
+
+### Closures
+```python
+def outer(x):
+    def inner(y):
+        return x + y  # Captures x from enclosing scope
+    return inner
+
+add5 = outer(5)
+add5(3)  # 8
+```
+- Use `nonlocal` to modify captured variables
+
+### Callable Objects
+```python
+class Adder:
+    def __init__(self, n):
+        self.n = n
+    def __call__(self, x):
+        return self.n + x
+
+add5 = Adder(5)
+add5(3)  # 8
+```
+
+### Decorators
+```python
+def decorator(func):
+    @functools.wraps(func)  # Preserves metadata
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+    return wrapper
+
+@decorator
+def my_func():
+    ...
+```
+- Always use `@functools.wraps` on wrapper functions
+- Decorators execute at **definition time**
+
+---
+
+## Type Hints for Functions
+
+```python
+from typing import Callable, TypeVar
+
+T = TypeVar('T')
+
+def map_func(func: Callable[[int], T], values: list[int]) -> list[T]:
+    return [func(v) for v in values]
+
+# Overloads for complex signatures
+from typing import overload
+
+@overload
+def func(x: int) -> int: ...
+@overload
+def func(x: str) -> str: ...
+def func(x: int | str) -> int | str:
+    return x
+```
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Simple transformation | `def` + type hints |
+| Need to capture state | Closure or callable class |
+| Multiple related operations | Class with methods |
+| Cross-cutting concerns | Decorator |
+| Variable positional args | `*args` |
+| Variable keyword args | `**kwargs` |
+| API stability required | Positional-only (`/`) |
+| Clarity for boolean flags | Keyword-only (`*`) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Small, focused functions
+def parse_date(s: str) -> datetime.date:
+    return datetime.date.fromisoformat(s)
+
+# Early returns for guard clauses
+def process(user: User) -> Result:
+    if not user.is_active:
+        return Result.error("inactive")
+    if not user.has_permission("read"):
+        return Result.error("forbidden")
+    return do_process(user)
+
+# Keyword-only for clarity
+def connect(host: str, port: int, *, timeout: float = 5.0, ssl: bool = True) -> Connection:
+    ...
+```
+
+---
+
+## Avoid
+
+- Mutable default arguments (see anti-patterns)
+- Functions with >7 parameters (use dataclass/config object)
+- Deeply nested functions (limit closure depth)
+- Decorators that change function signature unexpectedly
+- `*args`/`**kwargs` without documentation of expected keys
+- Modifying `**kwargs` in place (copy first)
+
+---
+
+## Validation Considerations
+
+- Type checkers verify signatures and return types
+- `inspect.signature()` for runtime introspection
+- `functools.wraps` preserves signature for tooling
+
+---
+
+## Related Skills
+
+- `generation/type_hints.md`
+- `core/advanced_python.md` (decorators, closures)
+- `anti_patterns/index.md` (mutable defaults)
+- `quality/functions.md` (size, focus)
+- `engineering/cli_apps.md` (CLI entry points)

skills/generation/async_concurrency.md

@@ -0,0 +1,291 @@
+---
+name: generation_async_concurrency
+purpose: Async/await patterns, concurrency primitives, and correct usage
+category: generation
+triggers:
+  - async
+  - await
+  - concurrent
+  - parallel
+  - asyncio
+  - task
+  - semaphore
+  - queue
+dependencies:
+  - generation/error_handling.md
+  - testing/async_tests.md
+  - stdlib/subprocess.md
+  - engineering/http_clients.md
+priority: primary
+estimated_tokens: 2700
+---
+# Generation: Async and Concurrency
+
+**Purpose**: Async/await patterns, concurrency primitives, and correct usage.
+
+**When to use**: I/O-bound operations, high-concurrency servers, parallel I/O.
+
+---
+
+## Core Rules
+
+### When to Use Async
+- I/O-bound: HTTP requests, database, file I/O, subprocess
+- Many concurrent connections (web servers, websockets)
+- Not for CPU-bound (use multiprocessing)
+
+### Basic Syntax
+```python
+import asyncio
+
+async def fetch(url: str) -> str:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as resp:
+            return await resp.text()
+
+async def main():
+    result = await fetch("https://example.com")
+    print(result)
+
+asyncio.run(main())
+```
+
+### Task Management
+```python
+async def main():
+    # Concurrent execution
+    task1 = asyncio.create_task(fetch(url1))
+    task2 = asyncio.create_task(fetch(url2))
+    result1, result2 = await asyncio.gather(task1, task2)
+    
+    # With timeout
+    try:
+        result = await asyncio.wait_for(fetch(url), timeout=5.0)
+    except asyncio.TimeoutError:
+        ...
+    
+    # As completed
+    for coro in asyncio.as_completed([fetch(u) for u in urls]):
+        result = await coro
+        process(result)
+    
+    # Shield from cancellation
+    await asyncio.shield(critical_operation())
+```
+
+### Cancellation
+```python
+async def long_running():
+    try:
+        while True:
+            await asyncio.sleep(1)
+            # Check cancellation
+    except asyncio.CancelledError:
+        cleanup()
+        raise  # Must re-raise!
+
+# Cancellation propagation
+async def parent():
+    child = asyncio.create_task(long_running())
+    await asyncio.sleep(0.1)
+    child.cancel()
+    try:
+        await child
+    except asyncio.CancelledError:
+        pass
+```
+
+### Async Context Managers
+```python
+class AsyncResource:
+    async def __aenter__(self):
+        await self.connect()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+        return False  # Don't suppress
+
+async def use():
+    async with AsyncResource() as r:
+        await r.do_something()
+```
+
+### Async Iterators
+```python
+async def async_gen() -> AsyncGenerator[int, None]:
+    for i in range(10):
+        await asyncio.sleep(0.1)
+        yield i
+
+async def consume():
+    async for item in async_gen():
+        print(item)
+    
+    # Or collect
+    items = [item async for item in async_gen()]
+```
+
+### Synchronization Primitives
+```python
+# Lock
+lock = asyncio.Lock()
+async with lock:
+    critical_section()
+
+# Semaphore (limit concurrency)
+sem = asyncio.Semaphore(10)
+async with sem:
+    await limited_operation()
+
+# Event
+event = asyncio.Event()
+async def waiter():
+    await event.wait()
+async def setter():
+    await asyncio.sleep(1)
+    event.set()
+
+# Queue
+queue: asyncio.Queue[str] = asyncio.Queue()
+await queue.put("item")
+item = await queue.get()
+
+# Condition
+cond = asyncio.Condition()
+async with cond:
+    await cond.wait()
+    cond.notify()
+```
+
+### Running in Threads (Blocking I/O)
+```python
+# Run sync function in thread pool
+result = await asyncio.to_thread(blocking_func, arg1, arg2)
+
+# Custom executor
+loop = asyncio.get_event_loop()
+result = await loop.run_in_executor(None, blocking_func, arg1)
+```
+
+### Exception Handling
+```python
+async def main():
+    try:
+        await risky_async()
+    except SpecificError:
+        handle()
+    except ExceptionGroup as eg:  # Python 3.11+
+        for e in eg.exceptions:
+            handle(e)
+    except* ValueError as eg:  # except* syntax (3.11+)
+        for e in eg.exceptions:
+            handle(e)
+    finally:
+        cleanup()
+```
+
+### Task Groups (Python 3.11+)
+```python
+async def main():
+    async with asyncio.TaskGroup() as tg:
+        task1 = tg.create_task(fetch(url1))
+        task2 = tg.create_task(fetch(url2))
+    # All tasks completed or first exception raised
+    results = [task1.result(), task2.result()]
+```
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Multiple independent I/O | `asyncio.gather` / `TaskGroup` |
+| Rate limiting | `Semaphore` |
+| Producer/consumer | `asyncio.Queue` |
+| Timeout | `asyncio.wait_for` |
+| Cancellation | `task.cancel()` + `CancelledError` handling |
+| Blocking call | `asyncio.to_thread` |
+| Background task | `create_task` (track for cleanup) |
+| Cleanup on exit | `async with` / `try/finally` |
+
+---
+
+## Preferred Patterns
+
+```python
+# Bounded concurrency
+async def fetch_all(urls: list[str], max_concurrent: int = 10) -> list[str]:
+    sem = asyncio.Semaphore(max_concurrent)
+    
+    async def bounded_fetch(url: str) -> str:
+        async with sem:
+            return await fetch(url)
+    
+    return await asyncio.gather(*[bounded_fetch(u) for u in urls])
+
+# Retry with backoff
+async def retry_async(
+    func: Callable[..., Awaitable[T]],
+    *args,
+    attempts: int = 3,
+    base_delay: float = 1.0,
+    **kwargs,
+) -> T:
+    for attempt in range(attempts):
+        try:
+            return await func(*args, **kwargs)
+        except Exception:
+            if attempt == attempts - 1:
+                raise
+            await asyncio.sleep(base_delay * (2 ** attempt))
+
+# Graceful shutdown
+async def run_server():
+    server = await start_server()
+    try:
+        await server.serve_forever()
+    except asyncio.CancelledError:
+        await server.shutdown()
+        raise
+```
+
+---
+
+## Avoid
+
+- `asyncio.run()` inside async function (nested event loops)
+- Blocking calls in async functions (use `to_thread`)
+- `asyncio.sleep(0)` for yielding (use `await asyncio.shield` or proper design)
+- Creating tasks without tracking (memory leaks)
+- Catching `CancelledError` without re-raising
+- Mixing `asyncio` with `threading` primitives
+- Global event loop references
+
+---
+
+## Python Version Notes
+
+- 3.11+: `TaskGroup`, `except*`, `asyncio.timeout()`
+- 3.10+: `asyncio.timeout()` context manager
+- 3.7+: `asyncio.run()`, `asyncio.create_task()`
+
+---
+
+## Validation Considerations
+
+- Test cancellation scenarios
+- Test timeout behavior
+- Check for resource leaks (open connections, files)
+- Verify no blocking calls in async path
+- `pytest-asyncio` for testing
+
+---
+
+## Related Skills
+
+- `generation/error_handling.md`
+- `testing/async_tests.md`
+- `stdlib/subprocess.md` (async subprocess)
+- `engineering/http_clients.md` (aiohttp, httpx)