Skip to content

sno-ai/sno-station-skills / skills/J-peer-review-and-audit/peer-review/skill

peer-review

Verified

Adversarial review and fix loop for code, specs, plans, and migration manifests.

references/python-advanced-patterns.md

View on GitHub
# Advanced Python Patterns

Reference for complex patterns. Read when `python-standards.md` points you here.

## Table of Contents
1. Generic Protocols
2. Async Generators for Streaming
3. Thread-Safe Singletons
4. Custom Decorators with ParamSpec
5. Sentinel Objects
6. ContextVar for Request-Scoped State
7. Enum with Behavior

---

## 1. Generic Protocols

When a Protocol needs to work across multiple types:

```python
from typing import Protocol, TypeVar

T = TypeVar("T")

class Repository(Protocol[T]):
    """Generic repository — works for any entity type."""
    async def get(self, id: str) -> T | None: ...
    async def save(self, entity: T) -> None: ...
    async def delete(self, id: str) -> bool: ...

class UserRepo:
    """Satisfies Repository[User] without inheriting from it."""
    async def get(self, id: str) -> User | None: ...
    async def save(self, entity: User) -> None: ...
    async def delete(self, id: str) -> bool: ...

async def sync_entities(source: Repository[T], target: Repository[T]) -> int:
    """Works with any Repository — User, Document, Config, etc."""
    ...
```

The generic `T` flows through — `sync_entities(user_repo, backup_repo)` infers `T = User`. No registration, no base class.

---

## 2. Async Generators for Streaming

Yield events as they happen, don't batch-then-yield:

```python
from collections.abc import AsyncGenerator

async def stream_embeddings(
    texts: list[str],
    batch_size: int = 32,
) -> AsyncGenerator[EmbeddingResult, None]:
    """Yield embeddings as each batch completes — true streaming."""
    for i in range(0, len(texts), batch_size):
        batch = texts[i : i + batch_size]
        results = await embed_batch(batch)
        for text, embedding in zip(batch, results, strict=True):
            yield EmbeddingResult(text=text, embedding=embedding, batch_index=i)
```

Callers get results incrementally:

```python
async for result in stream_embeddings(documents):
    await index_document(result)  # process as they arrive
```

For concurrent production + consumption, use `asyncio.Queue`:

```python
async def producer(queue: asyncio.Queue[Item | None], items: list[Input]) -> None:
    for item in items:
        result = await process(item)
        await queue.put(result)
    await queue.put(None)  # sentinel

async def consumer(queue: asyncio.Queue[Item | None]) -> list[Item]:
    results: list[Item] = []
    while (item := await queue.get()) is not None:
        results.append(item)
    return results
```

---

## 3. Thread-Safe Singletons

Double-check locking for expensive initialization:

```python
import threading

_instance: ExpensiveClient | None = None
_lock = threading.Lock()

def get_client() -> ExpensiveClient:
    """Thread-safe singleton with double-check locking."""
    global _instance
    if _instance is None:
        with _lock:
            if _instance is None:  # second check inside lock
                _instance = ExpensiveClient()
    return _instance

def close_client() -> None:
    """Cleanup — always use finally or atexit."""
    global _instance
    with _lock:
        if _instance is not None:
            _instance.close()
            _instance = None
```

The first check avoids the lock in the common case (already initialized). The second check inside the lock prevents double initialization from racing threads.

For class-level singletons, use `ClassVar` + class lock:

```python
from typing import ClassVar

class CircuitBreaker:
    _instances: ClassVar[dict[str, CircuitBreaker]] = {}
    _instances_lock: ClassVar[threading.Lock] = threading.Lock()

    @classmethod
    def for_provider(cls, provider: str) -> CircuitBreaker:
        key = provider.lower()
        if key not in cls._instances:
            with cls._instances_lock:
                if key not in cls._instances:
                    cls._instances[key] = cls(provider=key)
        return cls._instances[key]
```

---

## 4. Custom Decorators with ParamSpec

Preserve the decorated function's signature for type checkers:

```python
import functools
import time
from typing import ParamSpec, TypeVar
from collections.abc import Callable, Awaitable

P = ParamSpec("P")
R = TypeVar("R")

def timed(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
    """Async timing decorator — preserves signature for type checkers."""
    @functools.wraps(func)
    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.monotonic()
        result = await func(*args, **kwargs)
        elapsed = (time.monotonic() - start) * 1000
        logger.info("Call completed", extra={"func": func.__name__, "ms": elapsed})
        return result
    return wrapper

@timed
async def fetch_user(user_id: str, include_profile: bool = False) -> User:
    ...
# Type checker knows: fetch_user(user_id: str, include_profile: bool = False) -> User
```

Without `ParamSpec`, the decorator erases the signature and the type checker only sees `(*args, **kwargs) -> Any`.

---

## 5. Sentinel Objects

When `None` is a valid value and you need a distinct "not provided" signal:

```python
from typing import Any

class _Sentinel:
    """Singleton sentinel — distinct from None, False, 0, ''."""
    _instance: _Sentinel | None = None

    def __new__(cls) -> _Sentinel:
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __repr__(self) -> str:
        return "MISSING"

    def __bool__(self) -> bool:
        return False

MISSING = _Sentinel()

def update_config(
    timeout: float | _Sentinel = MISSING,
    retries: int | _Sentinel = MISSING,
) -> None:
    """Only update fields that were explicitly passed."""
    if not isinstance(timeout, _Sentinel):
        config.timeout = timeout
    if not isinstance(retries, _Sentinel):
        config.retries = retries
```

This distinguishes `update_config(timeout=None)` (explicitly set to None) from `update_config()` (not provided).

---

## 6. ContextVar for Request-Scoped State

Thread-safe, async-safe state without passing context through every function:

```python
from contextvars import ContextVar

request_id_var: ContextVar[str] = ContextVar("request_id", default="unknown")
user_id_var: ContextVar[str | None] = ContextVar("user_id", default=None)

# Set at the request boundary (middleware)
async def middleware(request: Request, call_next: Callable) -> Response:
    token = request_id_var.set(request.headers.get("X-Request-ID", generate_id()))
    try:
        return await call_next(request)
    finally:
        request_id_var.reset(token)  # clean up

# Read anywhere in the call stack — no parameter threading
def get_log_context() -> dict[str, str]:
    return {"request_id": request_id_var.get(), "user_id": user_id_var.get() or "anonymous"}
```

`ContextVar` is the correct replacement for thread-locals in async code. Each task gets its own copy automatically.

---

## 7. Enum with Behavior

When enum members need associated logic, attach it as methods:

```python
from enum import Enum

class CircuitState(Enum):
    CLOSED = "closed"
    OPEN = "open"
    HALF_OPEN = "half_open"

    @property
    def allows_traffic(self) -> bool:
        return self in (CircuitState.CLOSED, CircuitState.HALF_OPEN)

    @property
    def label(self) -> str:
        _LABELS: dict[CircuitState, str] = {
            CircuitState.CLOSED: "healthy",
            CircuitState.OPEN: "down",
            CircuitState.HALF_OPEN: "probing",
        }
        return _LABELS[self]
```

Behavior lives with the data, not in a separate switch statement. Adding a new state without implementing `label` causes a `KeyError` — not a silent default.

For simple string unions without behavior, prefer `Literal`:

```python
# No behavior needed → Literal is simpler
Provider = Literal["openai", "anthropic", "google", "deepseek"]

# Behavior needed → Enum is better
class CircuitState(Enum): ...
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall