@punks/cli 1.0.1 → 1.0.3

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

@@ -0,0 +1,433 @@
+---
+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]()
+```
+
+## Fundamental Patterns
+
+### Pattern 1: KISS - Keep It Simple
+
+Before adding complexity, ask: does a simpler solution work?
+
+```python
+# Over-engineered: Factory with registration
+class OutputFormatterFactory:
+    _formatters: dict[str, type[Formatter]] = {}
+
+    @classmethod
+    def register(cls, name: str):
+        def decorator(formatter_cls):
+            cls._formatters[name] = formatter_cls
+            return formatter_cls
+        return decorator
+
+    @classmethod
+    def create(cls, name: str) -> Formatter:
+        return cls._formatters[name]()
+
+@OutputFormatterFactory.register("json")
+class JsonFormatter(Formatter):
+    ...
+
+# Simple: Just use a dictionary
+FORMATTERS = {
+    "json": JsonFormatter,
+    "csv": CsvFormatter,
+    "xml": XmlFormatter,
+}
+
+def get_formatter(name: str) -> Formatter:
+    """Get formatter by name."""
+    if name not in FORMATTERS:
+        raise ValueError(f"Unknown format: {name}")
+    return FORMATTERS[name]()
+```
+
+The factory pattern adds code without adding value here. Save patterns for when they solve real problems.
+
+### Pattern 2: Single Responsibility Principle
+
+Each class or function should have one reason to change.
+
+```python
+# BAD: Handler does everything
+class UserHandler:
+    async def create_user(self, request: Request) -> Response:
+        # HTTP parsing
+        data = await request.json()
+
+        # Validation
+        if not data.get("email"):
+            return Response({"error": "email required"}, status=400)
+
+        # Database access
+        user = await db.execute(
+            "INSERT INTO users (email, name) VALUES ($1, $2) RETURNING *",
+            data["email"], data["name"]
+        )
+
+        # Response formatting
+        return Response({"id": user.id, "email": user.email}, status=201)
+
+# GOOD: Separated concerns
+class UserService:
+    """Business logic only."""
+
+    def __init__(self, repo: UserRepository) -> None:
+        self._repo = repo
+
+    async def create_user(self, data: CreateUserInput) -> User:
+        # Only business rules here
+        user = User(email=data.email, name=data.name)
+        return await self._repo.save(user)
+
+class UserHandler:
+    """HTTP concerns only."""
+
+    def __init__(self, service: UserService) -> None:
+        self._service = service
+
+    async def create_user(self, request: Request) -> Response:
+        data = CreateUserInput(**(await request.json()))
+        user = await self._service.create_user(data)
+        return Response(user.to_dict(), status=201)
+```
+
+Now HTTP changes don't affect business logic, and vice versa.
+
+### Pattern 3: Separation of Concerns
+
+Organize code into distinct layers with clear responsibilities.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  API Layer (handlers)                                │
+│  - Parse requests                                    │
+│  - Call services                                     │
+│  - Format responses                                  │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────┐
+│  Service Layer (business logic)                      │
+│  - Domain rules and validation                       │
+│  - Orchestrate operations                            │
+│  - Pure functions where possible                     │
+└─────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────┐
+│  Repository Layer (data access)                      │
+│  - SQL queries                                       │
+│  - External API calls                                │
+│  - Cache operations                                  │
+└─────────────────────────────────────────────────────┘
+```
+
+Each layer depends only on layers below it:
+
+```python
+# Repository: Data access
+class UserRepository:
+    async def get_by_id(self, user_id: str) -> User | None:
+        row = await self._db.fetchrow(
+            "SELECT * FROM users WHERE id = $1", user_id
+        )
+        return User(**row) if row else None
+
+# Service: Business logic
+class UserService:
+    def __init__(self, repo: UserRepository) -> None:
+        self._repo = repo
+
+    async def get_user(self, user_id: str) -> User:
+        user = await self._repo.get_by_id(user_id)
+        if user is None:
+            raise UserNotFoundError(user_id)
+        return user
+
+# Handler: HTTP concerns
+@app.get("/users/{user_id}")
+async def get_user(user_id: str) -> UserResponse:
+    user = await user_service.get_user(user_id)
+    return UserResponse.from_user(user)
+```
+
+### Pattern 4: Composition Over Inheritance
+
+Build behavior by combining objects rather than inheriting.
+
+```python
+# Inheritance: Rigid and hard to test
+class EmailNotificationService(NotificationService):
+    def __init__(self):
+        super().__init__()
+        self._smtp = SmtpClient()  # Hard to mock
+
+    def notify(self, user: User, message: str) -> None:
+        self._smtp.send(user.email, message)
+
+# Composition: Flexible and testable
+class NotificationService:
+    """Send notifications via multiple channels."""
+
+    def __init__(
+        self,
+        email_sender: EmailSender,
+        sms_sender: SmsSender | None = None,
+        push_sender: PushSender | None = None,
+    ) -> None:
+        self._email = email_sender
+        self._sms = sms_sender
+        self._push = push_sender
+
+    async def notify(
+        self,
+        user: User,
+        message: str,
+        channels: set[str] | None = None,
+    ) -> None:
+        channels = channels or {"email"}
+
+        if "email" in channels:
+            await self._email.send(user.email, message)
+
+        if "sms" in channels and self._sms and user.phone:
+            await self._sms.send(user.phone, message)
+
+        if "push" in channels and self._push and user.device_token:
+            await self._push.send(user.device_token, message)
+
+# Easy to test with fakes
+service = NotificationService(
+    email_sender=FakeEmailSender(),
+    sms_sender=FakeSmsSender(),
+)
+```
+
+## Advanced Patterns
+
+### Pattern 5: Rule of Three
+
+Wait until you have three instances before abstracting.
+
+```python
+# Two similar functions? Don't abstract yet
+def process_orders(orders: list[Order]) -> list[Result]:
+    results = []
+    for order in orders:
+        validated = validate_order(order)
+        result = process_validated_order(validated)
+        results.append(result)
+    return results
+
+def process_returns(returns: list[Return]) -> list[Result]:
+    results = []
+    for ret in returns:
+        validated = validate_return(ret)
+        result = process_validated_return(validated)
+        results.append(result)
+    return results
+
+# These look similar, but wait! Are they actually the same?
+# Different validation, different processing, different errors...
+# Duplication is often better than the wrong abstraction
+
+# Only after a third case, consider if there's a real pattern
+# But even then, sometimes explicit is better than abstract
+```
+
+### Pattern 6: Function Size Guidelines
+
+Keep functions focused. Extract when a function:
+
+- Exceeds 20-50 lines (varies by complexity)
+- Serves multiple distinct purposes
+- Has deeply nested logic (3+ levels)
+
+```python
+# Too long, multiple concerns mixed
+def process_order(order: Order) -> Result:
+    # 50 lines of validation...
+    # 30 lines of inventory check...
+    # 40 lines of payment processing...
+    # 20 lines of notification...
+    pass
+
+# Better: Composed from focused functions
+def process_order(order: Order) -> Result:
+    """Process a customer order through the complete workflow."""
+    validate_order(order)
+    reserve_inventory(order)
+    payment_result = charge_payment(order)
+    send_confirmation(order, payment_result)
+    return Result(success=True, order_id=order.id)
+```
+
+### Pattern 7: Dependency Injection
+
+Pass dependencies through constructors for testability.
+
+```python
+from typing import Protocol
+
+class Logger(Protocol):
+    def info(self, msg: str, **kwargs) -> None: ...
+    def error(self, msg: str, **kwargs) -> None: ...
+
+class Cache(Protocol):
+    async def get(self, key: str) -> str | None: ...
+    async def set(self, key: str, value: str, ttl: int) -> None: ...
+
+class UserService:
+    """Service with injected dependencies."""
+
+    def __init__(
+        self,
+        repository: UserRepository,
+        cache: Cache,
+        logger: Logger,
+    ) -> None:
+        self._repo = repository
+        self._cache = cache
+        self._logger = logger
+
+    async def get_user(self, user_id: str) -> User:
+        # Check cache first
+        cached = await self._cache.get(f"user:{user_id}")
+        if cached:
+            self._logger.info("Cache hit", user_id=user_id)
+            return User.from_json(cached)
+
+        # Fetch from database
+        user = await self._repo.get_by_id(user_id)
+        if user:
+            await self._cache.set(f"user:{user_id}", user.to_json(), ttl=300)
+
+        return user
+
+# Production
+service = UserService(
+    repository=PostgresUserRepository(db),
+    cache=RedisCache(redis),
+    logger=StructlogLogger(),
+)
+
+# Testing
+service = UserService(
+    repository=InMemoryUserRepository(),
+    cache=FakeCache(),
+    logger=NullLogger(),
+)
+```
+
+### Pattern 8: Avoiding Common Anti-Patterns
+
+**Don't expose 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)
+
+# GOOD: Use response schemas
+@app.get("/users/{id}")
+def get_user(id: str) -> UserResponse:
+    user = db.query(UserModel).get(id)
+    return UserResponse.from_orm(user)
+```
+
+**Don't mix I/O with 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
+
+# GOOD: Repository pattern
+def calculate_discount(user: User, order_history: list[Order]) -> float:
+    # Pure business logic, easily testable
+    if len(order_history) > 10:
+        return 0.15
+    return 0.0
+```
+
+## 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

package/dist/skills/languages/python/python-project-structure/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: python-project-structure
+description: Python project organization, module architecture, and public API design. Use when setting up new projects, organizing modules, defining public interfaces with __all__, or planning directory layouts.
+---
+
+# Python Project Structure & Module Architecture
+
+Design well-organized Python projects with clear module boundaries, explicit public interfaces, and maintainable directory structures. Good organization makes code discoverable and changes predictable.
+
+## When to Use This Skill
+
+- Starting a new Python project from scratch
+- Reorganizing an existing codebase for clarity
+- Defining module public APIs with `__all__`
+- Deciding between flat and nested directory structures
+- Determining test file placement strategies
+- Creating reusable library packages
+
+## Core Concepts
+
+### 1. Module Cohesion
+
+Group related code that changes together. A module should have a single, clear purpose.
+
+### 2. Explicit Interfaces
+
+Define what's public with `__all__`. Everything not listed is an internal implementation detail.
+
+### 3. Flat Hierarchies
+
+Prefer shallow directory structures. Add depth only for genuine sub-domains.
+
+### 4. Consistent Conventions
+
+Apply naming and organization patterns uniformly across the project.
+
+## Quick Start
+
+```
+myproject/
+├── src/
+│   └── myproject/
+│       ├── __init__.py
+│       ├── services/
+│       ├── models/
+│       └── api/
+├── tests/
+├── pyproject.toml
+└── README.md
+```
+
+## Fundamental Patterns
+
+### Pattern 1: One Concept Per File
+
+Each file should focus on a single concept or closely related set of functions. Consider splitting when a file:
+
+- Handles multiple unrelated responsibilities
+- Grows beyond 300-500 lines (varies by complexity)
+- Contains classes that change for different reasons
+
+```python
+# Good: Focused files
+# user_service.py - User business logic
+# user_repository.py - User data access
+# user_models.py - User data structures
+
+# Avoid: Kitchen sink files
+# user.py - Contains service, repository, models, utilities...
+```
+
+### Pattern 2: Explicit Public APIs with `__all__`
+
+Define the public interface for every module. Unlisted members are internal implementation details.
+
+```python
+# mypackage/services/__init__.py
+from .user_service import UserService
+from .order_service import OrderService
+from .exceptions import ServiceError, ValidationError
+
+__all__ = [
+    "UserService",
+    "OrderService",
+    "ServiceError",
+    "ValidationError",
+]
+
+# Internal helpers remain private by omission
+# from .internal_helpers import _validate_input  # Not exported
+```
+
+### Pattern 3: Flat Directory Structure
+
+Prefer minimal nesting. Deep hierarchies make imports verbose and navigation difficult.
+
+```
+# Preferred: Flat structure
+project/
+├── api/
+│   ├── routes.py
+│   └── middleware.py
+├── services/
+│   ├── user_service.py
+│   └── order_service.py
+├── models/
+│   ├── user.py
+│   └── order.py
+└── utils/
+    └── validation.py
+
+# Avoid: Deep nesting
+project/core/internal/services/impl/user/
+```
+
+Add sub-packages only when there's a genuine sub-domain requiring isolation.
+
+### Pattern 4: Test File Organization
+
+Choose one approach and apply it consistently throughout the project.
+
+**Option A: Colocated Tests**
+
+```
+src/
+├── user_service.py
+├── test_user_service.py
+├── order_service.py
+└── test_order_service.py
+```
+
+Benefits: Tests live next to the code they verify. Easy to see coverage gaps.
+
+**Option B: Parallel Test Directory**
+
+```
+src/
+├── services/
+│   ├── user_service.py
+│   └── order_service.py
+tests/
+├── services/
+│   ├── test_user_service.py
+│   └── test_order_service.py
+```
+
+Benefits: Clean separation between production and test code. Standard for larger projects.
+
+## Advanced Patterns
+
+### Pattern 5: Package Initialization
+
+Use `__init__.py` to provide a clean public interface for package consumers.
+
+```python
+# mypackage/__init__.py
+"""MyPackage - A library for doing useful things."""
+
+from .core import MainClass, HelperClass
+from .exceptions import PackageError, ConfigError
+from .config import Settings
+
+__all__ = [
+    "MainClass",
+    "HelperClass",
+    "PackageError",
+    "ConfigError",
+    "Settings",
+]
+
+__version__ = "1.0.0"
+```
+
+Consumers can then import directly from the package:
+
+```python
+from mypackage import MainClass, Settings
+```
+
+### Pattern 6: Layered Architecture
+
+Organize code by architectural layer for clear separation of concerns.
+
+```
+myapp/
+├── api/           # HTTP handlers, request/response
+│   ├── routes/
+│   └── middleware/
+├── services/      # Business logic
+├── repositories/  # Data access
+├── models/        # Domain entities
+├── schemas/       # API schemas (Pydantic)
+└── config/        # Configuration
+```
+
+Each layer should only depend on layers below it, never above.
+
+### Pattern 7: Domain-Driven Structure
+
+For complex applications, organize by business domain rather than technical layer.
+
+```
+ecommerce/
+├── users/
+│   ├── models.py
+│   ├── services.py
+│   ├── repository.py
+│   └── api.py
+├── orders/
+│   ├── models.py
+│   ├── services.py
+│   ├── repository.py
+│   └── api.py
+└── shared/
+    ├── database.py
+    └── exceptions.py
+```
+
+## File and Module Naming
+
+### Conventions
+
+- Use `snake_case` for all file and module names: `user_repository.py`
+- Avoid abbreviations that obscure meaning: `user_repository.py` not `usr_repo.py`
+- Match class names to file names: `UserService` in `user_service.py`
+
+### Import Style
+
+Use absolute imports for clarity and reliability:
+
+```python
+# Preferred: Absolute imports
+from myproject.services import UserService
+from myproject.models import User
+
+# Avoid: Relative imports
+from ..services import UserService
+from . import models
+```
+
+Relative imports can break when modules are moved or reorganized.
+
+## Best Practices Summary
+
+1. **Keep files focused** - One concept per file, consider splitting at 300-500 lines (varies by complexity)
+2. **Define `__all__` explicitly** - Make public interfaces clear
+3. **Prefer flat structures** - Add depth only for genuine sub-domains
+4. **Use absolute imports** - More reliable and clearer
+5. **Be consistent** - Apply patterns uniformly across the project
+6. **Match names to content** - File names should describe their purpose
+7. **Separate concerns** - Keep layers distinct and dependencies flowing one direction
+8. **Document your structure** - Include a README explaining the organization