python-skills 1.0.0__py3-none-any.whl

skills/refactoring/interface_stability.md

@@ -0,0 +1,199 @@
+# Refactoring: Interface Stability
+
+**Purpose**: Maintain stable public APIs during refactoring.
+
+**When to use**: Any change to public functions, classes, or module APIs.
+
+---
+
+## Core Rules
+
+### Public API Definition
+- Functions/classes in `__all__`
+- Exported in package `__init__.py`
+- Documented in public docs
+- Used by external consumers
+
+### Stability Principles
+1. **Add, don't remove** — Add new parameters with defaults
+2. **Deprecate gracefully** — Warn before removing
+3. **Version bump** — Breaking changes = major version
+4. **Migration path** — Provide upgrade guide
+
+### Safe API Evolution
+
+#### Adding Parameters
+```python
+# Before
+def fetch_users(client, limit=100):
+    ...
+
+# After — add with default (backward compatible)
+def fetch_users(client, limit=100, *, filter=None, sort=None):
+    ...
+```
+
+#### Changing Return Type
+```python
+# BAD — breaks callers
+def get_user(id) -> User:
+    ...
+
+def get_user(id) -> User | None:  # Breaking!
+    ...
+
+# GOOD — add new function
+def get_user(id) -> User:
+    ...
+
+def get_user_or_none(id) -> User | None:
+    ...
+
+# Or use Result type
+def get_user(id) -> Result[User, NotFoundError]:
+    ...
+```
+
+#### Deprecation Pattern
+```python
+import warnings
+from functools import wraps
+
+def deprecated(reason: str, version: str):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f"{func.__name__} is deprecated since {version}: {reason}",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+@deprecated("Use fetch_users_v2()", "2.0")
+def fetch_users(client, limit=100):
+    ...
+
+# Type stub for deprecated
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    def fetch_users(...) -> list[User]: ...
+```
+
+#### Removing Parameters
+```python
+# Step 1: Make optional with deprecation
+def process(data, *, old_param=None, new_param=None):
+    if old_param is not None:
+        warnings.warn("old_param deprecated", DeprecationWarning)
+        new_param = old_param
+    # Use new_param
+
+# Step 2: Remove after deprecation period (major version)
+def process(data, *, new_param):
+    ...
+```
+
+### Versioning
+```toml
+# pyproject.toml
+[project]
+version = "2.1.0"  # Semantic: MAJOR.MINOR.PATCH
+
+# MAJOR: Breaking API changes
+# MINOR: New features, backward compatible
+# PATCH: Bug fixes, backward compatible
+```
+
+### Interface Testing
+```python
+# Test public API surface
+def test_public_api_surface():
+    """Ensure public API hasn't accidentally changed"""
+    from mypackage import __all__
+    
+    expected = {
+        "UserService",
+        "User",
+        "create_user",
+        "get_user",
+        "ValidationError",
+    }
+    assert set(__all__) == expected
+
+# Test signatures
+import inspect
+
+def test_user_service_signatures():
+    sig = inspect.signature(UserService.create)
+    params = list(sig.parameters.keys())
+    assert params == ["self", "data", "validate"]
+```
+
+---
+
+## Decision Rules
+
+| Change | Approach |
+|--------|----------|
+| New optional parameter | Add with default |
+| New function | Add alongside old |
+| Change return type | New function + deprecate old |
+| Remove parameter | Deprecate → Major version remove |
+| Change behavior | New function + deprecate old |
+| Rename | Add alias + deprecate old |
+
+---
+
+## Preferred Patterns
+
+```python
+# Version-gated imports
+# mypackage/__init__.py
+__version__ = "2.1.0"
+
+# V1 API (deprecated)
+from .v1 import UserService as UserServiceV1
+from .v1 import create_user as create_user_v1
+
+# V2 API (current)
+from .v2 import UserService
+from .v2 import create_user
+
+# Deprecated aliases
+import warnings
+warnings.warn(
+    "UserServiceV1 is deprecated, use UserService",
+    DeprecationWarning,
+)
+```
+
+---
+
+## Avoid
+
+- Silent breaking changes
+- Removing public API in patch/minor
+- Changing exception types
+- Modifying default behavior
+- Breaking `__all__` without major version
+
+---
+
+## Validation Considerations
+
+- `pytest --collect-only` shows API surface
+- `pip install -e . && python -c "import mypackage"` works
+- Downstream consumers tested (if possible)
+- Changelog documents all API changes
+
+---
+
+## Related Skills
+
+- `refactoring/safe_refactoring.md`
+- `refactoring/behavior_preservation.md`
+- `engineering/pyproject_toml.md`
+- `engineering/packaging.md`

skills/refactoring/safe_refactoring.md

@@ -0,0 +1,206 @@
+# Refactoring: Safe Refactoring
+
+**Purpose**: Refactoring rules that preserve behavior and minimize risk.
+
+**When to use**: Any code restructuring, cleanup, or improvement.
+
+---
+
+## Core Rules
+
+### Refactoring Principles
+1. **Tests first** — No refactoring without tests
+2. **Small steps** — One change at a time
+3. **Run tests after each step** — Verify immediately
+4. **Preserve behavior** — No functional changes
+5. **Commit often** — Easy rollback
+
+### Refactoring Workflow
+```
+1. RUN TESTS (baseline)
+2. IDENTIFY refactoring goal
+3. MAKE SMALLEST CHANGE
+4. RUN TESTS
+5. REPEAT 3-4 until goal achieved
+6. RUN FULL TEST SUITE
+7. REVIEW DIFF
+```
+
+### Safe Refactoring Patterns
+
+#### Extract Function
+```python
+# Before
+def process_order(order):
+    validate(order)
+    total = calculate_total(order.items)
+    tax = total * TAX_RATE
+    final = total + tax
+    save_order(order, final)
+    send_confirmation(order)
+
+# After — extract calculation
+def calculate_final_total(items):
+    total = calculate_total(items)
+    tax = total * TAX_RATE
+    return total + tax
+
+def process_order(order):
+    validate(order)
+    final = calculate_final_total(order.items)
+    save_order(order, final)
+    send_confirmation(order)
+```
+
+#### Extract Class
+```python
+# Before — mixed responsibilities
+class OrderProcessor:
+    def process(self, order):
+        self.validate(order)
+        self.calculate_pricing(order)
+        self.save(order)
+        self.notify(order)
+
+# After — separate concerns
+class OrderValidator:
+    def validate(self, order): ...
+
+class PricingCalculator:
+    def calculate(self, order): ...
+
+class OrderRepository:
+    def save(self, order): ...
+
+class NotificationService:
+    def notify(self, order): ...
+
+class OrderProcessor:
+    def __init__(self, validator, calculator, repo, notifier):
+        self.validator = validator
+        self.calculator = calculator
+        self.repo = repo
+        self.notifier = notifier
+    
+    def process(self, order):
+        self.validator.validate(order)
+        self.calculator.calculate(order)
+        self.repo.save(order)
+        self.notifier.notify(order)
+```
+
+#### Replace Conditional with Polymorphism
+```python
+# Before
+def process_payment(payment):
+    if payment.type == "credit":
+        process_credit(payment)
+    elif payment.type == "debit":
+        process_debit(payment)
+    elif payment.type == "paypal":
+        process_paypal(payment)
+
+# After
+class PaymentProcessor(Protocol):
+    def process(self, payment): ...
+
+class CreditProcessor:
+    def process(self, payment): ...
+
+class DebitProcessor:
+    def process(self, payment): ...
+
+class PayPalProcessor:
+    def process(self, payment): ...
+
+PROCESSORS = {
+    "credit": CreditProcessor(),
+    "debit": DebitProcessor(),
+    "paypal": PayPalProcessor(),
+}
+
+def process_payment(payment):
+    PROCESSORS[payment.type].process(payment)
+```
+
+#### Introduce Parameter Object
+```python
+# Before
+def create_user(email, name, age, address, phone, preferences, referral):
+    ...
+
+# After
+@dataclass
+class UserData:
+    email: str
+    name: str
+    age: int
+    address: str
+    phone: str
+    preferences: dict
+    referral: str | None = None
+
+def create_user(data: UserData):
+    ...
+```
+
+---
+
+## Decision Rules
+
+| Refactoring | When Safe |
+|-------------|-----------|
+| Extract function | Pure logic, well-tested |
+| Extract class | Clear responsibility boundary |
+| Rename | IDE refactoring, all references updated |
+| Move method | No behavior change |
+| Replace conditional | Open/closed principle needed |
+| Introduce parameter object | >4 related parameters |
+
+---
+
+## Preferred Patterns
+
+```python
+# Strangler Fig for large refactors
+# 1. Create new implementation alongside old
+# 2. Route new calls to new implementation
+# 3. Migrate callers one by one
+# 4. Remove old implementation
+
+# Feature flag for safe rollout
+def process_order(order):
+    if settings.use_new_pricing:
+        return new_pricing.calculate(order)
+    return old_pricing.calculate(order)
+```
+
+---
+
+## Avoid
+
+- Refactoring without tests
+- Multiple changes in one step
+- "While I'm here" changes
+- Changing behavior during refactor
+- Big bang refactoring
+- Refactoring working code unnecessarily
+
+---
+
+## Validation Considerations
+
+- Tests pass at every step
+- `git diff` shows only refactoring
+- No behavior changes in diff
+- Performance regression check
+- Code review focused on structure
+
+---
+
+## Related Skills
+
+- `refactoring/incremental.md`
+- `refactoring/behavior_preservation.md`
+- `testing/regression_tests.md`
+- `testing/organization.md`

skills/security/auth_boundaries.md

@@ -0,0 +1,200 @@
+# Security: Authentication/Authorization Boundaries
+
+**Purpose**: Enforce auth boundaries correctly in code.
+
+**When to use**: Any code with user identity, permissions, or access control.
+
+---
+
+## Core Rules
+
+### Authentication vs Authorization
+- **Authentication**: Who are you? (Identity)
+- **Authorization**: What can you do? (Permissions)
+
+### Never Trust Client-Side Identity
+```python
+# WRONG — trusting header
+def get_user_profile(request, user_id: str):
+    return db.get_user(user_id)  # User can access ANY profile!
+
+# CORRECT — verified identity
+def get_user_profile(request, current_user: User):
+    if current_user.id != request.path_params["user_id"]:
+        raise ForbiddenError()
+    return current_user
+```
+
+### Authorization at Boundary
+```python
+# Dependency injection (FastAPI example)
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    user_service: UserService = Depends(),
+) -> User:
+    user = await user_service.verify_token(token)
+    if not user:
+        raise UnauthorizedError()
+    return user
+
+@app.get("/users/{user_id}")
+async def get_user(
+    user_id: str,
+    current_user: User = Depends(get_current_user),
+    user_service: UserService = Depends(),
+):
+    # Authorization check
+    if not current_user.can_access_user(user_id):
+        raise ForbiddenError("Cannot access this user")
+    return await user_service.get(user_id)
+```
+
+### Permission Models
+```python
+# Role-based
+class Role(str, Enum):
+    ADMIN = "admin"
+    USER = "user"
+    VIEWER = "viewer"
+
+# Permission-based (more flexible)
+class Permission(str, Enum):
+    USER_READ = "user:read"
+    USER_WRITE = "user:write"
+    ADMIN_PANEL = "admin:panel"
+
+# User model
+class User(BaseModel):
+    id: str
+    roles: list[Role] = []
+    permissions: list[Permission] = []
+    
+    def has_permission(self, perm: Permission) -> bool:
+        return perm in self.permissions or Role.ADMIN in self.roles
+    
+    def can_access_user(self, user_id: str) -> bool:
+        return self.id == user_id or self.has_permission(Permission.USER_READ)
+```
+
+### Resource-Level Authorization
+```python
+# Policy-based
+class AuthorizationPolicy:
+    def can_read(self, user: User, resource: Resource) -> bool:
+        if user.has_permission(Permission.ADMIN):
+            return True
+        return resource.owner_id == user.id or resource.is_public
+    
+    def can_write(self, user: User, resource: Resource) -> bool:
+        if user.has_permission(Permission.ADMIN):
+            return True
+        return resource.owner_id == user.id
+
+# Usage
+policy = AuthorizationPolicy()
+
+@app.put("/resources/{resource_id}")
+async def update_resource(
+    resource_id: str,
+    data: ResourceUpdate,
+    current_user: User = Depends(get_current_user),
+    resource_service: ResourceService = Depends(),
+):
+    resource = await resource_service.get(resource_id)
+    if not policy.can_write(current_user, resource):
+        raise ForbiddenError()
+    return await resource_service.update(resource_id, data)
+```
+
+### Secure Session/Cookie Handling
+```python
+# HttpOnly, Secure, SameSite cookies
+response.set_cookie(
+    "session",
+    session_token,
+    httponly=True,
+    secure=True,        # HTTPS only
+    samesite="lax",     # CSRF protection
+    max_age=3600,
+)
+
+# CSRF protection for state-changing operations
+@app.post("/action")
+async def action(
+    request: Request,
+    csrf_token: str = Form(),
+    session: Session = Depends(get_session),
+):
+    if not verify_csrf(session, csrf_token):
+        raise ForbiddenError("Invalid CSRF token")
+```
+
+---
+
+## Decision Rules
+
+| Boundary | Enforcement |
+|----------|-------------|
+| API endpoint | Dependency injection + policy check |
+| Database query | Filter by user_id in query (not post-filter) |
+| File access | Verify ownership before serve |
+| Admin panel | Role check + audit log |
+| Internal service | mTLS / service mesh / shared secret |
+
+---
+
+## Preferred Patterns
+
+```python
+# Centralized authorization
+class AuthorizationService:
+    def __init__(self, policy: AuthorizationPolicy):
+        self.policy = policy
+    
+    def authorize(self, user: User, action: str, resource: Resource) -> None:
+        if not self.policy.check(user, action, resource):
+            raise ForbiddenError(f"Cannot {action} {resource}")
+
+# Decorator for endpoints
+def require_permission(perm: Permission):
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, current_user: User = Depends(get_current_user), **kwargs):
+            if not current_user.has_permission(perm):
+                raise ForbiddenError(f"Requires {perm}")
+            return await func(*args, current_user=current_user, **kwargs)
+        return wrapper
+    return decorator
+
+@require_permission(Permission.USER_WRITE)
+async def create_user(...):
+    ...
+```
+
+---
+
+## Avoid
+
+- Checking permissions after fetching data (leak via error messages)
+- Client-controlled authorization (user_id in body/query)
+- Missing authorization on any state-changing endpoint
+- Hardcoded role checks (`if user.role == "admin"`) instead of permissions
+- No audit logging for sensitive operations
+
+---
+
+## Validation Considerations
+
+- Test with different user roles
+- Test resource access boundaries
+- Test privilege escalation attempts
+- Audit log review
+
+---
+
+## Related Skills
+
+- `security/input_validation.md`
+- `security/secrets.md`
+- `generation/error_handling.md`
+- `engineering/http_clients.md`