python-skills 1.0.0__py3-none-any.whl

skills/quality/comments.md

@@ -0,0 +1,177 @@
+# Quality: Comments
+
+**Purpose**: When and how to comment code effectively.
+
+**When to use**: All code generation and review.
+
+---
+
+## Core Rules
+
+### Comment Philosophy
+- **Code explains WHAT** — Comments explain WHY
+- **Good code > Good comments** — Refactor to make code self-explanatory
+- **Outdated comments are worse than no comments** — They mislead
+
+### When to Comment
+
+```python
+# GOOD — Why: business rule, not obvious
+def calculate_tax(amount: Decimal, region: str) -> Decimal:
+    # Region X has special 0% rate for orders > $1000 per local law
+    if region == "X" and amount > 1000:
+        return Decimal("0")
+    return amount * TAX_RATES[region]
+
+# GOOD — Why: workaround for external limitation
+def fetch_data(url: str) -> Data:
+    # API returns 500 on HEAD requests, use GET with Range header
+    response = http.get(url, headers={"Range": "bytes=0-"})
+    ...
+
+# GOOD — Why: non-obvious algorithm choice
+def sort_items(items: list[Item]) -> list[Item]:
+    # Timsort stable sort preserves insertion order for equal keys
+    # Required for consistent pagination
+    return sorted(items, key=lambda x: (x.priority, x.created_at))
+
+# BAD — Restates code
+def get_user(user_id: int) -> User:
+    # Get user by ID
+    return db.query(User).filter_by(id=user_id).first()
+
+# BAD — Obvious
+x = x + 1  # Increment x
+```
+
+### Docstrings (Not Comments)
+```python
+# Module docstring
+"""User management service.
+
+Provides CRUD operations for users and authentication.
+"""
+
+# Class docstring
+class UserService:
+    """Manages user lifecycle and authentication.
+    
+    Handles user creation, validation, and session management.
+    Uses UserRepository for persistence.
+    """
+    
+    def create_user(self, data: UserData) -> User:
+        """Create a new user.
+        
+        Args:
+            data: Validated user data.
+            
+        Returns:
+            Created user with assigned ID.
+            
+        Raises:
+            ValidationError: If data is invalid.
+            ConflictError: If email already exists.
+        """
+        ...
+```
+
+### Inline Comments (Rare)
+```python
+# Only for non-obvious logic
+result = complex_calculation()  # type: ignore[assignment]  # mypy false positive
+
+# Or algorithm explanation
+# Use Fisher-Yates shuffle for uniform distribution
+for i in range(len(items) - 1, 0, -1):
+    j = random.randint(0, i)
+    items[i], items[j] = items[j], items[i]
+```
+
+### TODO/FIXME Comments
+```python
+# Format: # TODO(author): description
+# TODO(john): Add retry logic when API supports it
+
+# FIXME: Known bug
+# FIXME: Race condition on concurrent updates
+```
+
+### Commented Code
+```python
+# NEVER commit commented-out code
+# def old_function():
+#     ...
+# Use version control history instead
+```
+
+---
+
+## Decision Rules
+
+| Situation | Comment? |
+|-----------|----------|
+| Non-obvious business logic | Yes (WHY) |
+| Workaround for external issue | Yes (WHY) |
+| Algorithm choice rationale | Yes (WHY) |
+| Complex regex | Yes (pattern explanation) |
+| Obvious code | No |
+| Restating code | No |
+| TODO without issue reference | No (use issue tracker) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Docstring for public API
+def process_payment(payment: Payment) -> PaymentResult:
+    """Process a payment through the configured gateway.
+    
+    Handles validation, authorization, and capture.
+    Retries on transient gateway errors (up to 3 attempts).
+    
+    Args:
+        payment: Validated payment with amount and method.
+        
+    Returns:
+        PaymentResult with transaction ID and status.
+        
+    Raises:
+        PaymentError: If gateway rejects payment.
+        GatewayUnavailable: If gateway is unreachable.
+    """
+    ...
+
+# Inline only for genuinely tricky code
+def hash_password(password: str) -> str:
+    # Argon2id with memory=64MB, iterations=3, parallelism=4
+    # Parameters per OWASP 2023 recommendations
+    return argon2.hash(password)
+```
+
+---
+
+## Avoid
+
+- Commented-out code blocks
+- Redundant comments (`i = i + 1  # increment`)
+- Comments that can be replaced by better naming
+- Comments explaining standard library usage
+- Outdated comments (delete when code changes)
+
+---
+
+## Validation Considerations
+
+- `ruff` checks for TODO/FIXME format
+- Docstring coverage (`pydocstyle`, `interrogate`)
+- No commented code in diffs
+
+---
+
+## Related Skills
+
+- `quality/documentation.md`
+- `quality/readability.md`
+- `quality/naming.md`

skills/quality/documentation.md

@@ -0,0 +1,176 @@
+# Quality: Documentation
+
+**Purpose**: Document public APIs and non-obvious behavior appropriately.
+
+**When to use**: Public modules, classes, functions, complex systems.
+
+---
+
+## Core Rules
+
+### Documentation Levels
+
+| Level | Audience | Format |
+|-------|----------|--------|
+| **Docstrings** | Developers using API | In-code, accessible via `help()` |
+| **README** | Users, contributors | Markdown in repo root |
+| **Architecture docs** | Maintainers | Project-specific (e.g., `project-docs/architecture.md`) |
+| **API reference** | External consumers | Generated (Sphinx, pdoc) |
+| **Changelog** | Users | `CHANGELOG.md` |
+
+### Docstring Format (Google/NumPy/Sphinx)
+```python
+def fetch_users(
+    client: APIClient,
+    filters: UserFilters | None = None,
+    limit: int = 100,
+) -> list[User]:
+    """Fetch users matching filters.
+    
+    Args:
+        client: Authenticated API client.
+        filters: Optional filters (name, status, role).
+        limit: Maximum results (default 100, max 1000).
+        
+    Returns:
+        List of users matching criteria.
+        
+    Raises:
+        APIError: If request fails.
+        ValidationError: If limit exceeds maximum.
+        
+    Example:
+        >>> client = APIClient(token="abc")
+        >>> users = fetch_users(client, UserFilters(active=True), limit=50)
+    """
+    ...
+```
+
+### Module Docstring
+```python
+"""Payment processing module.
+
+Provides payment authorization, capture, and refund operations.
+Supports multiple gateways via the PaymentGateway protocol.
+
+Typical usage:
+    gateway = StripeGateway(api_key="sk_...")
+    processor = PaymentProcessor(gateway)
+    result = processor.charge(amount=1000, currency="USD")
+"""
+```
+
+### Class Docstring
+```python
+class PaymentProcessor:
+    """Orchestrates payment operations across gateways.
+    
+    Handles retry logic, idempotency, and gateway failover.
+    Not thread-safe; use one instance per request.
+    
+    Attributes:
+        gateway: Primary payment gateway.
+        fallback: Optional fallback gateway.
+    """
+    
+    def __init__(self, gateway: PaymentGateway, fallback: PaymentGateway | None = None):
+        self.gateway = gateway
+        self.fallback = fallback
+```
+
+---
+
+## Decision Rules
+
+| Element | Docstring Required? |
+|---------|---------------------|
+| Public module | Yes |
+| Public class | Yes |
+| Public function/method | Yes |
+| Private (`_` prefix) | Optional |
+| Override (same behavior) | No (inherit) |
+| Property | Yes (describe what it returns) |
+
+### README Structure
+```markdown
+# Package Name
+
+One-line description.
+
+## Installation
+```bash
+pip install package-name
+```
+
+## Quick Start
+```python
+from package import main
+main()
+```
+
+## Configuration
+Environment variables...
+
+## API Reference
+Link to generated docs.
+
+## Contributing
+...
+
+## License
+...
+```
+
+---
+
+## Preferred Patterns
+
+```python
+# Type hints + docstring = complete API docs
+def process(
+    data: InputData,
+    config: ProcessingConfig = ProcessingConfig(),
+) -> OutputData:
+    """Process input data according to configuration.
+    
+    Args:
+        data: Input to process. Must be validated.
+        config: Processing options. Defaults used if omitted.
+        
+    Returns:
+        Processed output data.
+        
+    Raises:
+        ValidationError: If input data is invalid.
+        ProcessingError: If processing fails.
+    """
+    ...
+```
+
+---
+
+## Avoid
+
+- Missing docstrings on public API
+- Docstrings that just repeat signature
+- Outdated docstrings (update with code)
+- Documenting private implementation details
+- Redundant type information in docstring (use type hints)
+
+---
+
+## Validation Considerations
+
+- `pydocstyle` / `ruff` docstring checks
+- `interrogate` for coverage
+- `pdoc` / `sphinx` build succeeds
+- Examples in docstrings runnable (doctest)
+
+---
+
+## Related Skills
+
+- `quality/comments.md`
+- `generation/type_hints.md`
+- `engineering/packaging.md`
+- `quality/readability.md`

skills/quality/duplication.md

@@ -0,0 +1,137 @@
+# Quality: Duplication
+
+**Purpose**: Remove meaningful duplication without creating unnecessary abstractions.
+
+**When to use**: Refactoring, code review, applying DRY principle correctly.
+
+---
+
+## Core Rules
+
+### Types of Duplication
+
+| Type | Example | Action |
+|------|---------|--------|
+| **True duplication** | Same logic, same reason to change | Extract |
+| **Accidental duplication** | Same code, different reasons to change | Keep separate |
+| **Structural duplication** | Similar structure, different domain | Keep separate |
+
+### True Duplication (Extract)
+```python
+# Before — same validation logic
+def create_user(data):
+    if not data.email or "@" not in data.email:
+        raise ValueError("Invalid email")
+    if not data.name or len(data.name) < 2:
+        raise ValueError("Invalid name")
+    return save_user(data)
+
+def update_user(user_id, data):
+    if not data.email or "@" not in data.email:
+        raise ValueError("Invalid email")
+    if not data.name or len(data.name) < 2:
+        raise ValueError("Invalid name")
+    return update_user(user_id, data)
+
+# After — extract
+def validate_user_data(data):
+    if not data.email or "@" not in data.email:
+        raise ValueError("Invalid email")
+    if not data.name or len(data.name) < 2:
+        raise ValueError("Invalid name")
+
+def create_user(data):
+    validate_user_data(data)
+    return save_user(data)
+
+def update_user(user_id, data):
+    validate_user_data(data)
+    return update_user(user_id, data)
+```
+
+### Accidental Duplication (Don't Extract)
+```python
+# User validation
+def validate_user(user):
+    if not user.email or "@" not in user.email:
+        raise ValueError("Invalid email")
+    if user.age < 13:
+        raise ValueError("Too young")
+
+# Product validation — LOOKS similar but DIFFERENT rules
+def validate_product(product):
+    if not product.sku:
+        raise ValueError("SKU required")
+    if product.price <= 0:
+        raise ValueError("Price must be positive")
+
+# DON'T extract "validate_required_fields" — different domains, different change reasons
+```
+
+### Rule of Three
+- First time: Write code
+- Second time: Note similarity, but don't extract yet
+- Third time: Extract common abstraction
+
+---
+
+## Decision Rules
+
+| Duplication Type | Action |
+|------------------|--------|
+| Same logic, same domain, same change reason | Extract |
+| Similar structure, different domain | Keep separate |
+| Similar structure, different change reasons | Keep separate |
+| Boilerplate (imports, decorators) | Accept or use code gen |
+| Test setup | Fixtures/helpers OK |
+
+---
+
+## Preferred Patterns
+
+```python
+# Extract to function with clear name
+def validate_email(email: str) -> None:
+    if not email or "@" not in email:
+        raise ValidationError("email", "Invalid email format")
+
+# Extract to protocol for behavioral duplication
+class Validator(Protocol):
+    def validate(self, data: Any) -> None: ...
+
+# Use decorators for cross-cutting duplication
+def validate_request(schema: type):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(request):
+            data = schema.model_validate(request.json)
+            return func(data)
+        return wrapper
+    return decorator
+```
+
+---
+
+## Avoid
+
+- Extracting "utility" functions used once
+- Creating base classes for accidental duplication
+- Parameterizing extracted function to handle differences (creates complexity)
+- DRY obsession — "Duplication is far cheaper than the wrong abstraction" (Sandi Metz)
+
+---
+
+## Validation Considerations
+
+- `flake8-duplicates` / `pylint` duplicate-code detection
+- Manual review: "If I change X, do I need to change Y?"
+- Test each extracted unit independently
+
+---
+
+## Related Skills
+
+- `quality/abstractions.md`
+- `quality/functions.md`
+- `quality/maintainability.md`
+- `refactoring/safe_refactoring.md`

skills/quality/maintainability.md

@@ -0,0 +1,142 @@
+# Quality: Maintainability
+
+**Purpose**: Avoid unnecessary coupling and complexity for long-term maintenance.
+
+**When to use**: Architecture decisions, refactoring, code review.
+---
+---
+name: quality_maintainability
+purpose: Avoid unnecessary coupling and complexity for long-term maintenance
+category: quality
+triggers:
+  - coupling
+  - cohesion
+  - complexity
+  - architecture
+  - god class
+  - circular dependency
+dependencies:
+  - quality/abstractions.md
+  - quality/duplication.md
+  - quality/functions.md
+  - generation/protocols_generics.md
+  - engineering/modules_packages.md
+priority: primary
+estimated_tokens: 1400
+---
+
+## Core Rules
+
+### Coupling
+- **Low coupling**: Modules interact through well-defined interfaces
+- **High cohesion**: Related functionality grouped together
+
+```python
+# GOOD — low coupling via protocol
+class PaymentProcessor(Protocol):
+    def charge(self, amount: int, token: str) -> ChargeResult: ...
+
+def process_order(order: Order, processor: PaymentProcessor) -> Result:
+    ...
+
+# BAD — high coupling to concrete implementation
+def process_order(order: Order, processor: StripeProcessor) -> Result:
+    ...
+```
+
+### Dependency Direction
+```
+Domain (business logic)     <--  DOES NOT DEPEND ON  -->  Infrastructure (DB, HTTP, UI)
+       ^                                                         ^
+       +-- Depends on abstractions --+
+```
+
+- Domain defines interfaces (Protocols)
+- Infrastructure implements them
+- Application wires them together
+
+### Complexity Metrics
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| Cyclomatic complexity | >10 | Refactor |
+| Function length | >50 lines | Split |
+| Class length | >300 lines | Split |
+| Parameters | >7 | Use config object |
+| Nesting depth | >3 | Extract/guard clauses |
+
+### Single Responsibility
+- Each module/class/function has one reason to change
+- If you can't name it simply, it does too much
+
+### Change Amplification
+- A change in one place should not require changes in many others
+- If adding a field requires changes in 5+ files, design is too coupled
+- Use dependency inversion to contain changes
+
+---
+
+## Decision Rules
+
+| Situation | Approach |
+|-----------|----------|
+| New feature | Add to existing cohesive module or create new |
+| Shared code | Extract to utility only if used 3+ times |
+| Cross-cutting concern | Decorator / middleware / context manager |
+| Configuration | Central config object, not global constants |
+
+---
+
+## Preferred Patterns
+
+```python
+# Config object instead of many parameters
+@dataclass
+class ProcessingConfig:
+    timeout: float = 30.0
+    retries: int = 3
+    validate: bool = True
+    callback: Callable[[str], None] | None = None
+
+def process(data: Data, config: ProcessingConfig) -> Result:
+    ...
+
+# Protocol for dependency inversion
+class Cache(Protocol):
+    async def get(self, key: str) -> bytes | None: ...
+    async def set(self, key: str, value: bytes, ttl: int) -> None: ...
+
+class Service:
+    def __init__(self, cache: Cache):
+        self.cache = cache  # Depends on abstraction
+```
+
+---
+
+## Avoid
+
+- God classes (knows everything, does everything)
+- Circular dependencies between modules
+- Global mutable state
+- Hardcoded infrastructure in domain logic
+- Premature abstraction (wait for 3rd use case)
+- Copy-paste modification (refactor instead)
+
+---
+
+## Validation Considerations
+
+- `radon cc` for cyclomatic complexity
+- `xenon` for complexity thresholds
+- Import graph analysis (no cycles)
+- Architecture tests (import-linter, pydeps)
+- `ruff` B007 (loop variable in closure)
+
+---
+
+## Related Skills
+
+- `quality/abstractions.md`
+- `quality/duplication.md`
+- `quality/functions.md`
+- `generation/protocols_generics.md`
+- `engineering/modules_packages.md`