python-skills 1.0.0__py3-none-any.whl

skills/quality/type_annotations.md

@@ -0,0 +1,192 @@
+# Quality: Type Annotations
+
+**Purpose**: Appropriate type hints — useful, not noise.
+
+**When to use**: All code generation. Quality type hints improve maintainability.
+
+---
+
+## Core Rules
+
+### When to Annotate
+| Element | Annotate? |
+|---------|-----------|
+| Public function signature | Yes |
+| Public method signature | Yes |
+| Class attributes | Yes |
+| Module-level constants | Yes |
+| Local variables | Usually no (inference) |
+| Loop variables | No |
+| Trivial helpers | Optional |
+
+### Useful vs Noise
+
+```python
+# USEFUL — public API, complex types
+def fetch_users(
+    client: APIClient,
+    filters: UserFilters | None = None,
+    limit: int = 100,
+) -> list[User]:
+    ...
+
+# USEFUL — generic class
+class Repository(Generic[T]):
+    def get(self, id: str) -> T | None: ...
+
+# NOISE — obvious inference
+count: int = 0
+name: str = "default"
+items: list[str] = []
+for i, item in enumerate(items):  # i inferred as int
+    ...
+
+# NOISE — over-specified
+def add(a: int, b: int) -> int:
+    return a + b
+```
+
+### Type Hint Style
+```python
+# Python 3.9+ — prefer built-in generics
+list[str]
+dict[str, int]
+set[int]
+tuple[int, str]
+tuple[int, ...]  # variable length
+
+# Union — Python 3.10+
+int | str
+list[int | str]
+
+# Optional
+str | None
+
+# Callable
+Callable[[int, str], bool]
+# Or collections.abc.Callable
+
+# Type alias (3.12+)
+type UserID = int
+type JSONValue = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
+```
+
+### Strictness Levels
+```toml
+# pyproject.toml — mypy config
+[tool.mypy]
+# Strict (recommended for new projects)
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+
+# Gradual adoption — per module
+[[tool.mypy.overrides]]
+module = "legacy.*"
+disallow_untyped_defs = false
+```
+
+### TypedDict for External Data
+```python
+from typing import TypedDict, NotRequired
+
+class UserAPIResponse(TypedDict):
+    id: int
+    name: str
+    email: str
+    created_at: str  # ISO format
+    metadata: NotRequired[dict[str, str]]  # Optional key
+
+def parse_user(data: UserAPIResponse) -> User:
+    return User(
+        id=data["id"],
+        name=data["name"],
+        email=data["email"],
+        created_at=datetime.fromisoformat(data["created_at"]),
+    )
+```
+
+### Protocol for Interfaces
+```python
+from typing import Protocol
+
+class Cache(Protocol):
+    def get(self, key: str) -> bytes | None: ...
+    def set(self, key: str, value: bytes, ttl: int) -> None: ...
+
+# Any object with get/set implements Cache (no inheritance needed)
+```
+
+---
+
+## Decision Rules
+
+| Situation | Annotation Level |
+|-----------|------------------|
+| New project | Strict (`mypy --strict`) |
+| Existing project | Match project config |
+| Public library | Full annotations + `py.typed` |
+| Internal app | Public API annotated, internal inferred |
+| Prototyping | Minimal |
+
+---
+
+## Preferred Patterns
+
+```python
+# Function with full hints
+def process_order(
+    order: Order,
+    inventory: InventoryService,
+    payment: PaymentGateway,
+    *,
+    idempotency_key: str | None = None,
+) -> OrderResult:
+    ...
+
+# Class with typed attributes
+class Config:
+    database_url: str
+    pool_size: int = 10
+    timeout: float = 30.0
+    debug: bool = False
+
+# Generic with constraints
+T = TypeVar("T", bound=Entity)
+
+class Repository(Generic[T]):
+    def get(self, id: str) -> T | None: ...
+    def list(self) -> list[T]: ...
+```
+
+---
+
+## Avoid
+
+- `Any` without `# type: ignore[...]` justification
+- `object` as "unknown type" (use `Any` or proper protocol)
+- Overly complex nested types without aliases
+- Type hints that are wrong (lying types)
+- Ignoring mypy errors without comment
+
+---
+
+## Validation Considerations
+
+- `mypy --strict` passes
+- `pyright` passes
+- No `# type: ignore` without error code
+- `py.typed` marker for libraries
+
+---
+
+## Related Skills
+
+- `generation/type_hints.md`
+- `generation/protocols_generics.md`
+- `engineering/pyproject_toml.md`
+- `quality/readability.md`

skills/refactoring/behavior_preservation.md

@@ -0,0 +1,157 @@
+# Refactoring: Behavior Preservation
+
+**Purpose**: Ensure refactoring doesn't change observable behavior.
+
+**When to use**: Every refactoring, especially complex ones.
+
+---
+
+## Core Rules
+
+### Behavior Definition
+Behavior = **observable outputs for given inputs**
+- Return values
+- Side effects (DB writes, API calls, files, logs)
+- Exceptions raised
+- Timing (if specified in requirements)
+
+### Preservation Techniques
+
+#### 1. Characterization Tests (Golden Master)
+```python
+# Before refactoring, capture current behavior
+def test_order_calculation_golden_master():
+    """Characterization test - captures current behavior"""
+    test_cases = [
+        {"items": [{"price": 10, "qty": 2}], "tax_rate": 0.1},
+        {"items": [{"price": 100, "qty": 1}], "tax_rate": 0.0},
+        {"items": [], "tax_rate": 0.1},
+        # ... 50+ real cases from production
+    ]
+    
+    for case in test_cases:
+        result = calculate_order_total(case["items"], case["tax_rate"])
+        # Save as golden master
+        assert result == case["expected"]
+```
+
+#### 2. Property-Based Tests
+```python
+from hypothesis import given, strategies as st
+
+@given(st.lists(st.fixed_dictionaries({
+    "price": st.integers(0, 10000),
+    "qty": st.integers(1, 100),
+})), st.floats(0, 0.5))
+def test_calculation_properties(items, tax_rate):
+    """Properties that must hold after refactoring"""
+    result = calculate_order_total(items, tax_rate)
+    
+    # Property: total >= subtotal
+    subtotal = sum(i["price"] * i["qty"] for i in items)
+    assert result >= subtotal
+    
+    # Property: tax = subtotal * rate (approximately)
+    expected_tax = subtotal * tax_rate
+    actual_tax = result - subtotal
+    assert abs(actual_tax - expected_tax) < 0.01
+```
+
+#### 3. Contract Tests
+```python
+# Protocol defines contract
+class OrderCalculator(Protocol):
+    def calculate(self, items: list[Item], tax_rate: float) -> Decimal: ...
+
+# Both implementations must satisfy
+@pytest.fixture(params=[LegacyCalculator, NewCalculator])
+def calculator(request) -> OrderCalculator:
+    return request.param()
+
+def test_calculator_contract(calculator: OrderCalculator):
+    # Same tests for both implementations
+    result = calculator.calculate([Item(10, 2)], 0.1)
+    assert result == Decimal("22.00")
+```
+
+#### 4. Parallel Run (Production)
+```python
+# Shadow mode - run both, compare, log differences
+def process_order(order):
+    legacy_result = legacy_processor.process(order)
+    new_result = new_processor.process(order)
+    
+    if legacy_result != new_result:
+        logger.warning(
+            "Behavior mismatch",
+            legacy=legacy_result,
+            new=new_result,
+            order_id=order.id,
+        )
+    
+    return legacy_result  # Still return legacy during transition
+```
+
+### What Must Be Preserved
+| Aspect | Verify |
+|--------|--------|
+| Return values | Exact equality (or specified tolerance) |
+| Exceptions | Same type, message, context |
+| Side effects | Same DB writes, API calls, files |
+| Timing | Within acceptable bounds |
+| Logs | Same level, structure (optional) |
+
+---
+
+## Decision Rules
+
+| Refactor Type | Verification Method |
+|---------------|---------------------|
+| Simple extraction | Existing unit tests |
+| Algorithm change | Property tests + golden master |
+| Implementation swap | Contract tests + shadow mode |
+| Large restructuring | Characterization tests + integration tests |
+
+---
+
+## Preferred Patterns
+
+```python
+# Regression test for every behavior change
+def test_refactor_preserves_bug_fix_123():
+    """Ensures refactoring doesn't reintroduce bug #123"""
+    # Exact scenario from bug report
+    input_data = create_bug_scenario()
+    
+    result = refactored_function(input_data)
+    
+    # Bug was: returned wrong value for edge case
+    assert result == expected_correct_value
+```
+
+---
+
+## Avoid
+
+- Assuming "it's the same logic" without verification
+- Deleting characterization tests after refactor
+- Refactoring without any automated verification
+- Changing behavior "while we're at it"
+
+---
+
+## Validation Considerations
+
+- Run characterization tests before and after
+- Property tests run on both implementations
+- Shadow mode logs zero mismatches before cutover
+- Integration tests cover full workflows
+
+---
+
+## Related Skills
+
+- `refactoring/safe_refactoring.md`
+- `refactoring/incremental.md`
+- `testing/regression_tests.md`
+- `testing/edge_cases.md`

skills/refactoring/incremental.md

@@ -0,0 +1,187 @@
+# Refactoring: Incremental Changes
+
+**Purpose**: Make refactoring safe through small, verifiable increments.
+
+**When to use**: Any refactoring larger than a single function extraction.
+
+---
+
+## Core Rules
+
+### Incremental Principles
+1. **One logical change per commit**
+2. **Each commit passes all tests**
+3. **No "temporary" broken state committed**
+4. **Reviewable diffs** (<200 lines ideal)
+
+### Breaking Down Large Refactors
+
+```python
+# Goal: Replace legacy UserService with NewUserService
+
+# Step 1: Create NewUserService with same interface
+class NewUserService:
+    def get(self, id): ...
+    def create(self, data): ...
+
+# Step 2: Add feature flag
+class UserService:
+    def __init__(self):
+        self.legacy = LegacyUserService()
+        self.new = NewUserService()
+        self.use_new = settings.use_new_service
+    
+    def get(self, id):
+        if self.use_new:
+            return self.new.get(id)
+        return self.legacy.get(id)
+    
+    def create(self, data):
+        if self.use_new:
+            return self.new.create(data)
+        return self.legacy.create(data)
+
+# Step 3: Enable for 1% of users (canary)
+# Step 4: Enable for all
+# Step 5: Remove legacy code
+```
+
+### Incremental Extraction
+```python
+# Large function -> small functions (one at a time)
+
+# Original: 100-line process() function
+
+# Commit 1: Extract validation
+def validate_input(data):
+    # ... 20 lines extracted
+    pass
+
+def process(data):
+    validate_input(data)  # New call
+    # ... 80 lines remain
+
+# Commit 2: Extract calculation
+def calculate_totals(items):
+    # ... 30 lines extracted
+    pass
+
+def process(data):
+    validate_input(data)
+    totals = calculate_totals(data.items)  # New call
+    # ... 50 lines remain
+
+# Commit 3: Extract persistence
+def save_results(data, totals):
+    # ... 30 lines extracted
+    pass
+
+def process(data):
+    validate_input(data)
+    totals = calculate_totals(data.items)
+    save_results(data, totals)
+    # ... 20 lines remain (orchestration)
+```
+
+### Incremental Type Changes
+```python
+# Change function signature incrementally
+
+# Before: func(a, b, c)
+# Goal: func(config: Config)
+
+# Step 1: Add config parameter with defaults
+def func(a, b, c, config=None):
+    if config:
+        a = config.a
+        b = config.b
+        c = config.c
+    # ... rest unchanged
+
+# Step 2: Update all callers to pass config
+# Step 3: Make config required
+def func(config: Config):
+    # ... use config.a, config.b, config.c
+
+# Step 4: Remove old parameters
+```
+
+### Database Migration (Incremental)
+```python
+# Add column, migrate data, switch, remove old
+
+# Migration 1: Add new column (nullable)
+ALTER TABLE users ADD COLUMN email_normalized VARCHAR(255);
+
+# Migration 2: Backfill (batch, with progress)
+UPDATE users SET email_normalized = LOWER(email) WHERE email_normalized IS NULL;
+
+# Migration 3: Add index, make not null
+CREATE INDEX idx_users_email_norm ON users(email_normalized);
+ALTER TABLE users ALTER COLUMN email_normalized SET NOT NULL;
+
+# Migration 4: Switch application to new column
+# (Deploy code that reads/writes email_normalized)
+
+# Migration 5: Drop old column (after verification)
+ALTER TABLE users DROP COLUMN email;
+```
+
+---
+
+## Decision Rules
+
+| Refactor Size | Increments |
+|---------------|------------|
+| Single function | 1-3 commits |
+| Class extraction | 3-10 commits |
+| Module restructure | 10-30 commits |
+| Architecture change | 30+ commits (feature flags) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Commit message template
+# refactor: extract validation from process_order
+# 
+# Extracted validate_order() function from process_order()
+# to improve readability and testability.
+# No behavior change.
+
+# Git workflow
+git checkout -b refactor/extract-validation
+# ... make change ...
+git add -p  # Stage hunks selectively
+git commit -m "refactor: extract validation from process_order"
+# ... run tests ...
+# ... next increment ...
+```
+
+---
+
+## Avoid
+
+- "Refactor everything in one PR"
+- Commits that break tests
+- Mixing refactor + feature + bugfix
+- No feature flag for risky changes
+- Deleting old code before new is verified
+
+---
+
+## Validation Considerations
+
+- `git log --oneline` shows clear incremental steps
+- Each commit: `pytest` passes
+- Bisect works (each commit builds)
+- Code review per commit or small PR
+
+---
+
+## Related Skills
+
+- `refactoring/safe_refactoring.md`
+- `refactoring/behavior_preservation.md`
+- `testing/regression_tests.md`