ndomo 0.1.0

package/skills/python-anti-patterns/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: python-anti-patterns
+description: Use this skill when reviewing Python code for common anti-patterns to avoid. Use as a checklist when reviewing code, before finalizing implementations, or when debugging issues that might stem from known bad practices.
+---
+
+# Python Anti-Patterns Checklist
+
+A reference checklist of common mistakes and anti-patterns in Python code. Review this before finalizing implementations to catch issues early.
+
+## When to Use This Skill
+
+- Reviewing code before merge
+- Debugging mysterious issues
+- Teaching or learning Python best practices
+- Establishing team coding standards
+- Refactoring legacy code
+
+**Note:** This skill focuses on what to avoid. For guidance on positive patterns and architecture, see the `python-design-patterns` skill.
+
+## Infrastructure Anti-Patterns
+
+### Scattered Timeout/Retry Logic
+
+```python
+# BAD: Timeout logic duplicated everywhere
+def fetch_user(user_id):
+    try:
+        return requests.get(url, timeout=30)
+    except Timeout:
+        logger.warning("Timeout fetching user")
+        return None
+
+def fetch_orders(user_id):
+    try:
+        return requests.get(url, timeout=30)
+    except Timeout:
+        logger.warning("Timeout fetching orders")
+        return None
+```
+
+**Fix:** Centralize in decorators or client wrappers.
+
+```python
+# GOOD: Centralized retry logic
+@retry(stop=stop_after_attempt(3), wait=wait_exponential())
+def http_get(url: str) -> Response:
+    return requests.get(url, timeout=30)
+```
+
+### Double Retry
+
+```python
+# BAD: Retrying at multiple layers
+@retry(max_attempts=3)  # Application retry
+def call_service():
+    return client.request()  # Client also has retry configured!
+```
+
+**Fix:** Retry at one layer only. Know your infrastructure's retry behavior.
+
+### Hard-Coded Configuration
+
+```python
+# BAD: Secrets and config in code
+DB_HOST = "prod-db.example.com"
+API_KEY = "sk-12345"
+
+def connect():
+    return psycopg.connect(f"host={DB_HOST}...")
+```
+
+**Fix:** Use environment variables with typed settings.
+
+```python
+# GOOD
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    db_host: str = Field(alias="DB_HOST")
+    api_key: str = Field(alias="API_KEY")
+
+settings = Settings()
+```
+
+## Architecture Anti-Patterns
+
+### Exposed Internal Types
+
+```python
+# BAD: Leaking ORM model to API
+@app.get("/users/{id}")
+def get_user(id: str) -> UserModel:  # SQLAlchemy model
+    return db.query(UserModel).get(id)
+```
+
+**Fix:** Use DTOs/response models.
+
+```python
+# GOOD
+@app.get("/users/{id}")
+def get_user(id: str) -> UserResponse:
+    user = db.query(UserModel).get(id)
+    return UserResponse.from_orm(user)
+```
+
+### Mixed I/O and Business Logic
+
+```python
+# BAD: SQL embedded in business logic
+def calculate_discount(user_id: str) -> float:
+    user = db.query("SELECT * FROM users WHERE id = ?", user_id)
+    orders = db.query("SELECT * FROM orders WHERE user_id = ?", user_id)
+    # Business logic mixed with data access
+    if len(orders) > 10:
+        return 0.15
+    return 0.0
+```
+
+**Fix:** Repository pattern. Keep business logic pure.
+
+```python
+# GOOD
+def calculate_discount(user: User, orders: list[Order]) -> float:
+    # Pure business logic, easily testable
+    if len(orders) > 10:
+        return 0.15
+    return 0.0
+```
+
+## Error Handling Anti-Patterns
+
+### Bare Exception Handling
+
+```python
+# BAD: Swallowing all exceptions
+try:
+    process()
+except Exception:
+    pass  # Silent failure - bugs hidden forever
+```
+
+**Fix:** Catch specific exceptions. Log or handle appropriately.
+
+```python
+# GOOD
+try:
+    process()
+except ConnectionError as e:
+    logger.warning("Connection failed, will retry", error=str(e))
+    raise
+except ValueError as e:
+    logger.error("Invalid input", error=str(e))
+    raise BadRequestError(str(e))
+```
+
+### Ignored Partial Failures
+
+```python
+# BAD: Stops on first error
+def process_batch(items):
+    results = []
+    for item in items:
+        result = process(item)  # Raises on error - batch aborted
+        results.append(result)
+    return results
+```
+
+**Fix:** Capture both successes and failures.
+
+```python
+# GOOD
+def process_batch(items) -> BatchResult:
+    succeeded = {}
+    failed = {}
+    for idx, item in enumerate(items):
+        try:
+            succeeded[idx] = process(item)
+        except Exception as e:
+            failed[idx] = e
+    return BatchResult(succeeded, failed)
+```
+
+### Missing Input Validation
+
+```python
+# BAD: No validation
+def create_user(data: dict):
+    return User(**data)  # Crashes deep in code on bad input
+```
+
+**Fix:** Validate early at API boundaries.
+
+```python
+# GOOD
+def create_user(data: dict) -> User:
+    validated = CreateUserInput.model_validate(data)
+    return User.from_input(validated)
+```
+
+## Resource Anti-Patterns
+
+### Unclosed Resources
+
+```python
+# BAD: File never closed
+def read_file(path):
+    f = open(path)
+    return f.read()  # What if this raises?
+```
+
+**Fix:** Use context managers.
+
+```python
+# GOOD
+def read_file(path):
+    with open(path) as f:
+        return f.read()
+```
+
+### Blocking in Async
+
+```python
+# BAD: Blocks the entire event loop
+async def fetch_data():
+    time.sleep(1)  # Blocks everything!
+    response = requests.get(url)  # Also blocks!
+```
+
+**Fix:** Use async-native libraries.
+
+```python
+# GOOD
+async def fetch_data():
+    await asyncio.sleep(1)
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url)
+```
+
+## Type Safety Anti-Patterns
+
+### Missing Type Hints
+
+```python
+# BAD: No types
+def process(data):
+    return data["value"] * 2
+```
+
+**Fix:** Annotate all public functions.
+
+```python
+# GOOD
+def process(data: dict[str, int]) -> int:
+    return data["value"] * 2
+```
+
+### Untyped Collections
+
+```python
+# BAD: Generic list without type parameter
+def get_users() -> list:
+    ...
+```
+
+**Fix:** Use type parameters.
+
+```python
+# GOOD
+def get_users() -> list[User]:
+    ...
+```
+
+## Testing Anti-Patterns
+
+### Only Testing Happy Paths
+
+```python
+# BAD: Only tests success case
+def test_create_user():
+    user = service.create_user(valid_data)
+    assert user.id is not None
+```
+
+**Fix:** Test error conditions and edge cases.
+
+```python
+# GOOD
+def test_create_user_success():
+    user = service.create_user(valid_data)
+    assert user.id is not None
+
+def test_create_user_invalid_email():
+    with pytest.raises(ValueError, match="Invalid email"):
+        service.create_user(invalid_email_data)
+
+def test_create_user_duplicate_email():
+    service.create_user(valid_data)
+    with pytest.raises(ConflictError):
+        service.create_user(valid_data)
+```
+
+### Over-Mocking
+
+```python
+# BAD: Mocking everything
+def test_user_service():
+    mock_repo = Mock()
+    mock_cache = Mock()
+    mock_logger = Mock()
+    mock_metrics = Mock()
+    # Test doesn't verify real behavior
+```
+
+**Fix:** Use integration tests for critical paths. Mock only external services.
+
+## Quick Review Checklist
+
+Before finalizing code, verify:
+
+- [ ] No scattered timeout/retry logic (centralized)
+- [ ] No double retry (app + infrastructure)
+- [ ] No hard-coded configuration or secrets
+- [ ] No exposed internal types (ORM models, protobufs)
+- [ ] No mixed I/O and business logic
+- [ ] No bare `except Exception: pass`
+- [ ] No ignored partial failures in batches
+- [ ] No missing input validation
+- [ ] No unclosed resources (using context managers)
+- [ ] No blocking calls in async code
+- [ ] All public functions have type hints
+- [ ] Collections have type parameters
+- [ ] Error paths are tested
+- [ ] Edge cases are covered
+
+## Common Fixes Summary
+
+| Anti-Pattern | Fix |
+|-------------|-----|
+| Scattered retry logic | Centralized decorators |
+| Hard-coded config | Environment variables + pydantic-settings |
+| Exposed ORM models | DTO/response schemas |
+| Mixed I/O + logic | Repository pattern |
+| Bare except | Catch specific exceptions |
+| Batch stops on error | Return BatchResult with successes/failures |
+| No validation | Validate at boundaries with Pydantic |
+| Unclosed resources | Context managers |
+| Blocking in async | Async-native libraries |
+| Missing types | Type annotations on all public APIs |
+| Only happy path tests | Test errors and edge cases |

package/skills/python-design-patterns/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: python-design-patterns
+description: Python design patterns including KISS, Separation of Concerns, Single Responsibility, and composition over inheritance. Use this skill when designing a new service or component from scratch and choosing how to layer responsibilities, when refactoring a God class or monolithic function that has grown too large, when deciding whether to add a new abstraction or live with duplication, when evaluating a pull request for structural issues like tight coupling or leaking internal types, when choosing between inheritance and composition for a new class hierarchy, or when a codebase is becoming hard to test because of entangled I/O and business logic.
+---
+
+# Python Design Patterns
+
+Write maintainable Python code using fundamental design principles. These patterns help you build systems that are easy to understand, test, and modify.
+
+## When to Use This Skill
+
+- Designing new components or services
+- Refactoring complex or tangled code
+- Deciding whether to create an abstraction
+- Choosing between inheritance and composition
+- Evaluating code complexity and coupling
+- Planning modular architectures
+
+## Core Concepts
+
+### 1. KISS (Keep It Simple)
+
+Choose the simplest solution that works. Complexity must be justified by concrete requirements.
+
+### 2. Single Responsibility (SRP)
+
+Each unit should have one reason to change. Separate concerns into focused components.
+
+### 3. Composition Over Inheritance
+
+Build behavior by combining objects, not extending classes.
+
+### 4. Rule of Three
+
+Wait until you have three instances before abstracting. Duplication is often better than premature abstraction.
+
+## Quick Start
+
+```python
+# Simple beats clever
+# Instead of a factory/registry pattern:
+FORMATTERS = {"json": JsonFormatter, "csv": CsvFormatter}
+
+def get_formatter(name: str) -> Formatter:
+    return FORMATTERS[name]()
+```
+
+## Detailed patterns and worked examples
+
+Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
+
+## Best Practices Summary
+
+1. **Keep it simple** - Choose the simplest solution that works
+2. **Single responsibility** - Each unit has one reason to change
+3. **Separate concerns** - Distinct layers with clear purposes
+4. **Compose, don't inherit** - Combine objects for flexibility
+5. **Rule of three** - Wait before abstracting
+6. **Keep functions small** - 20-50 lines (varies by complexity), one purpose
+7. **Inject dependencies** - Constructor injection for testability
+8. **Delete before abstracting** - Remove dead code, then consider patterns
+9. **Test each layer** - Isolated tests for each concern
+10. **Explicit over clever** - Readable code beats elegant code
+
+## Troubleshooting
+
+**A class is growing and seems to have multiple responsibilities, but splitting it feels wrong.**
+Apply the "reason to change" test: list every change that could require editing this class. If the list has items from different domains (e.g., HTTP parsing AND business rules AND formatting), split it. If all changes stem from the same domain concern, the class may be appropriately sized.
+
+**Injecting all dependencies through the constructor is producing constructors with 7+ parameters.**
+This is a sign of too many responsibilities in one class, not a problem with dependency injection. Split the class into smaller units first, then each constructor naturally becomes smaller.
+
+**Composition is producing deeply nested wrapper objects that are hard to trace.**
+Keep the composition shallow (2-3 levels). If wrapping is the only mechanism, consider whether a Protocol-based approach or simple function composition would be cleaner than a chain of decorator objects.
+
+**The rule of three says not to abstract yet, but the duplication is causing bugs when one copy is updated but not the other.**
+Duplication that diverges in dangerous ways should be abstracted sooner. The rule of three is a heuristic, not a law. If the copies are already diverging incorrectly, extract immediately and add a test that exercises the shared behavior.
+
+**A service layer is importing from the API layer, breaking the dependency direction.**
+This is a layering violation. The service layer must not import from handlers. Introduce a shared types/models layer that both can import from, keeping the dependency arrow pointing downward (API → Service → Repository).
+
+## Related Skills
+
+- [python-testing-patterns](../python-testing-patterns/SKILL.md) — Test each layer in isolation using the dependency injection structure established here
+- [python-project-setup](../python-project-setup/SKILL.md) — Set up project structure and tooling that enforces layer boundaries from the start