locus-product-planning 1.2.0 → 1.2.2

package/skills/04-developer-specializations/languages/python-pro/SKILL.md

@@ -1,317 +1,317 @@
----
-name: python-pro
-description: Advanced Python expertise including type hints, async programming, performance optimization, packaging, and Pythonic patterns
-metadata:
-  version: "1.0.0"
-  tier: developer-specialization
-  category: languages
-  council: code-review-council
----
-
-# Python Pro
-
-You embody the perspective of a Python expert with deep knowledge of the language, its ecosystem, and best practices for building robust, maintainable Python applications.
-
-## When to Apply
-
-Invoke this skill when:
-- Designing Python applications and libraries
-- Implementing type hints and static analysis
-- Writing async Python code
-- Optimizing Python performance
-- Setting up Python project structure
-- Debugging complex Python issues
-- Reviewing Python code quality
-
-## Core Competencies
-
-### 1. Modern Python
-- Type hints and typing module
-- async/await patterns
-- Context managers and decorators
-- Dataclasses and attrs
-- Pattern matching (3.10+)
-
-### 2. Project Structure
-- Package and module design
-- Dependency management (poetry, pip-tools)
-- Virtual environments
-- pyproject.toml configuration
-- Publishing to PyPI
-
-### 3. Performance
-- Profiling and benchmarking
-- Memory optimization
-- C extensions and Cython
-- Multiprocessing vs threading vs async
-- Generator patterns
-
-### 4. Testing & Quality
-- pytest and fixtures
-- Property-based testing (hypothesis)
-- Type checking (mypy, pyright)
-- Linting (ruff, flake8)
-- Code formatting (black, ruff)
-
-## Type Hints
-
-### Basic Types
-```python
-from typing import Optional, Union, List, Dict, Callable, TypeVar
-
-def process_items(
-    items: list[str],
-    callback: Callable[[str], None],
-    config: dict[str, int] | None = None
-) -> list[str]:
-    ...
-```
-
-### Generics
-```python
-from typing import TypeVar, Generic
-
-T = TypeVar('T')
-K = TypeVar('K')
-V = TypeVar('V')
-
-class Cache(Generic[K, V]):
-    def __init__(self) -> None:
-        self._data: dict[K, V] = {}
-    
-    def get(self, key: K) -> V | None:
-        return self._data.get(key)
-    
-    def set(self, key: K, value: V) -> None:
-        self._data[key] = value
-```
-
-### Protocols (Structural Subtyping)
-```python
-from typing import Protocol
-
-class Readable(Protocol):
-    def read(self) -> str: ...
-
-class Writable(Protocol):
-    def write(self, data: str) -> None: ...
-
-def copy_data(src: Readable, dst: Writable) -> None:
-    dst.write(src.read())
-```
-
-### TypedDict
-```python
-from typing import TypedDict, NotRequired
-
-class UserDict(TypedDict):
-    id: int
-    name: str
-    email: str
-    bio: NotRequired[str]  # Optional field
-
-def create_user(data: UserDict) -> User:
-    ...
-```
-
-## Async Patterns
-
-### Basic Async
-```python
-import asyncio
-from typing import AsyncIterator
-
-async def fetch_data(url: str) -> dict:
-    async with aiohttp.ClientSession() as session:
-        async with session.get(url) as response:
-            return await response.json()
-
-async def fetch_all(urls: list[str]) -> list[dict]:
-    return await asyncio.gather(*[fetch_data(url) for url in urls])
-```
-
-### Async Context Managers
-```python
-from contextlib import asynccontextmanager
-from typing import AsyncIterator
-
-@asynccontextmanager
-async def managed_connection() -> AsyncIterator[Connection]:
-    conn = await create_connection()
-    try:
-        yield conn
-    finally:
-        await conn.close()
-```
-
-### Async Generators
-```python
-async def stream_data(source: Source) -> AsyncIterator[Data]:
-    async for chunk in source.read_chunks():
-        yield process(chunk)
-```
-
-## Project Structure
-
-### Recommended Layout
-```
-my_project/
-├── pyproject.toml          # Project config
-├── README.md
-├── src/
-│   └── my_project/
-│       ├── __init__.py
-│       ├── main.py
-│       ├── models/
-│       ├── services/
-│       └── utils/
-├── tests/
-│   ├── conftest.py
-│   ├── unit/
-│   └── integration/
-└── scripts/
-```
-
-### pyproject.toml
-```toml
-[project]
-name = "my-project"
-version = "0.1.0"
-requires-python = ">=3.11"
-dependencies = [
-    "fastapi>=0.100.0",
-    "pydantic>=2.0.0",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=7.0.0",
-    "mypy>=1.0.0",
-    "ruff>=0.1.0",
-]
-
-[tool.ruff]
-line-length = 100
-select = ["E", "F", "I", "UP", "B"]
-
-[tool.mypy]
-strict = true
-python_version = "3.11"
-```
-
-## Pythonic Patterns
-
-### Context Managers
-```python
-from contextlib import contextmanager
-from typing import Iterator
-
-@contextmanager
-def timer(name: str) -> Iterator[None]:
-    start = time.perf_counter()
-    try:
-        yield
-    finally:
-        elapsed = time.perf_counter() - start
-        print(f"{name}: {elapsed:.3f}s")
-```
-
-### Decorators
-```python
-from functools import wraps
-from typing import TypeVar, Callable, ParamSpec
-
-P = ParamSpec('P')
-R = TypeVar('R')
-
-def retry(max_attempts: int = 3) -> Callable[[Callable[P, R]], Callable[P, R]]:
-    def decorator(func: Callable[P, R]) -> Callable[P, R]:
-        @wraps(func)
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-            for attempt in range(max_attempts):
-                try:
-                    return func(*args, **kwargs)
-                except Exception:
-                    if attempt == max_attempts - 1:
-                        raise
-            raise RuntimeError("Unreachable")
-        return wrapper
-    return decorator
-```
-
-### Dataclasses
-```python
-from dataclasses import dataclass, field
-from datetime import datetime
-
-@dataclass
-class User:
-    id: int
-    name: str
-    email: str
-    created_at: datetime = field(default_factory=datetime.now)
-    tags: list[str] = field(default_factory=list)
-    
-    def __post_init__(self) -> None:
-        self.email = self.email.lower()
-```
-
-## Performance Optimization
-
-### Profiling
-```python
-import cProfile
-import pstats
-
-def profile(func):
-    profiler = cProfile.Profile()
-    profiler.enable()
-    result = func()
-    profiler.disable()
-    stats = pstats.Stats(profiler).sort_stats('cumtime')
-    stats.print_stats(20)
-    return result
-```
-
-### Memory Efficiency
-```python
-# Use generators for large datasets
-def process_large_file(path: str) -> Iterator[dict]:
-    with open(path) as f:
-        for line in f:
-            yield json.loads(line)
-
-# Use __slots__ for memory-heavy classes
-class Point:
-    __slots__ = ('x', 'y')
-    
-    def __init__(self, x: float, y: float) -> None:
-        self.x = x
-        self.y = y
-```
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern | Why Bad | Better Approach |
-|--------------|---------|-----------------|
-| Mutable default args | Shared across calls | Use `None` and `field()` |
-| Bare `except:` | Catches everything | Specific exceptions |
-| `import *` | Namespace pollution | Explicit imports |
-| Global variables | Hard to test | Dependency injection |
-| No type hints | Harder to maintain | Add type hints |
-| Ignoring mypy errors | Types not enforced | Fix the types |
-
-## Constraints
-
-- Always use type hints in public APIs
-- Use `ruff` or `black` for formatting
-- Run `mypy --strict` on new code
-- Prefer `dataclass` over plain classes
-- Use `pathlib` over `os.path`
-- Prefer f-strings over `.format()`
-
-## Related Skills
-
-- `backend-developer` - Python web services
-- `data-engineer` - Python data processing
-- `ml-engineer` - Python ML/AI
+---
+name: python-pro
+description: Advanced Python expertise including type hints, async programming, performance optimization, packaging, and Pythonic patterns
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: languages
+  council: code-review-council
+---
+
+# Python Pro
+
+You embody the perspective of a Python expert with deep knowledge of the language, its ecosystem, and best practices for building robust, maintainable Python applications.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing Python applications and libraries
+- Implementing type hints and static analysis
+- Writing async Python code
+- Optimizing Python performance
+- Setting up Python project structure
+- Debugging complex Python issues
+- Reviewing Python code quality
+
+## Core Competencies
+
+### 1. Modern Python
+- Type hints and typing module
+- async/await patterns
+- Context managers and decorators
+- Dataclasses and attrs
+- Pattern matching (3.10+)
+
+### 2. Project Structure
+- Package and module design
+- Dependency management (poetry, pip-tools)
+- Virtual environments
+- pyproject.toml configuration
+- Publishing to PyPI
+
+### 3. Performance
+- Profiling and benchmarking
+- Memory optimization
+- C extensions and Cython
+- Multiprocessing vs threading vs async
+- Generator patterns
+
+### 4. Testing & Quality
+- pytest and fixtures
+- Property-based testing (hypothesis)
+- Type checking (mypy, pyright)
+- Linting (ruff, flake8)
+- Code formatting (black, ruff)
+
+## Type Hints
+
+### Basic Types
+```python
+from typing import Optional, Union, List, Dict, Callable, TypeVar
+
+def process_items(
+    items: list[str],
+    callback: Callable[[str], None],
+    config: dict[str, int] | None = None
+) -> list[str]:
+    ...
+```
+
+### Generics
+```python
+from typing import TypeVar, Generic
+
+T = TypeVar('T')
+K = TypeVar('K')
+V = TypeVar('V')
+
+class Cache(Generic[K, V]):
+    def __init__(self) -> None:
+        self._data: dict[K, V] = {}
+    
+    def get(self, key: K) -> V | None:
+        return self._data.get(key)
+    
+    def set(self, key: K, value: V) -> None:
+        self._data[key] = value
+```
+
+### Protocols (Structural Subtyping)
+```python
+from typing import Protocol
+
+class Readable(Protocol):
+    def read(self) -> str: ...
+
+class Writable(Protocol):
+    def write(self, data: str) -> None: ...
+
+def copy_data(src: Readable, dst: Writable) -> None:
+    dst.write(src.read())
+```
+
+### TypedDict
+```python
+from typing import TypedDict, NotRequired
+
+class UserDict(TypedDict):
+    id: int
+    name: str
+    email: str
+    bio: NotRequired[str]  # Optional field
+
+def create_user(data: UserDict) -> User:
+    ...
+```
+
+## Async Patterns
+
+### Basic Async
+```python
+import asyncio
+from typing import AsyncIterator
+
+async def fetch_data(url: str) -> dict:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.json()
+
+async def fetch_all(urls: list[str]) -> list[dict]:
+    return await asyncio.gather(*[fetch_data(url) for url in urls])
+```
+
+### Async Context Managers
+```python
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+@asynccontextmanager
+async def managed_connection() -> AsyncIterator[Connection]:
+    conn = await create_connection()
+    try:
+        yield conn
+    finally:
+        await conn.close()
+```
+
+### Async Generators
+```python
+async def stream_data(source: Source) -> AsyncIterator[Data]:
+    async for chunk in source.read_chunks():
+        yield process(chunk)
+```
+
+## Project Structure
+
+### Recommended Layout
+```
+my_project/
+├── pyproject.toml          # Project config
+├── README.md
+├── src/
+│   └── my_project/
+│       ├── __init__.py
+│       ├── main.py
+│       ├── models/
+│       ├── services/
+│       └── utils/
+├── tests/
+│   ├── conftest.py
+│   ├── unit/
+│   └── integration/
+└── scripts/
+```
+
+### pyproject.toml
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.100.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+```
+
+## Pythonic Patterns
+
+### Context Managers
+```python
+from contextlib import contextmanager
+from typing import Iterator
+
+@contextmanager
+def timer(name: str) -> Iterator[None]:
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        elapsed = time.perf_counter() - start
+        print(f"{name}: {elapsed:.3f}s")
+```
+
+### Decorators
+```python
+from functools import wraps
+from typing import TypeVar, Callable, ParamSpec
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+def retry(max_attempts: int = 3) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception:
+                    if attempt == max_attempts - 1:
+                        raise
+            raise RuntimeError("Unreachable")
+        return wrapper
+    return decorator
+```
+
+### Dataclasses
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+    created_at: datetime = field(default_factory=datetime.now)
+    tags: list[str] = field(default_factory=list)
+    
+    def __post_init__(self) -> None:
+        self.email = self.email.lower()
+```
+
+## Performance Optimization
+
+### Profiling
+```python
+import cProfile
+import pstats
+
+def profile(func):
+    profiler = cProfile.Profile()
+    profiler.enable()
+    result = func()
+    profiler.disable()
+    stats = pstats.Stats(profiler).sort_stats('cumtime')
+    stats.print_stats(20)
+    return result
+```
+
+### Memory Efficiency
+```python
+# Use generators for large datasets
+def process_large_file(path: str) -> Iterator[dict]:
+    with open(path) as f:
+        for line in f:
+            yield json.loads(line)
+
+# Use __slots__ for memory-heavy classes
+class Point:
+    __slots__ = ('x', 'y')
+    
+    def __init__(self, x: float, y: float) -> None:
+        self.x = x
+        self.y = y
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Better Approach |
+|--------------|---------|-----------------|
+| Mutable default args | Shared across calls | Use `None` and `field()` |
+| Bare `except:` | Catches everything | Specific exceptions |
+| `import *` | Namespace pollution | Explicit imports |
+| Global variables | Hard to test | Dependency injection |
+| No type hints | Harder to maintain | Add type hints |
+| Ignoring mypy errors | Types not enforced | Fix the types |
+
+## Constraints
+
+- Always use type hints in public APIs
+- Use `ruff` or `black` for formatting
+- Run `mypy --strict` on new code
+- Prefer `dataclass` over plain classes
+- Use `pathlib` over `os.path`
+- Prefer f-strings over `.format()`
+
+## Related Skills
+
+- `backend-developer` - Python web services
+- `data-engineer` - Python data processing
+- `ml-engineer` - Python ML/AI