python-skills 1.0.0__py3-none-any.whl

skills/quality/naming.md

@@ -0,0 +1,171 @@
+# Quality: Naming
+
+**Purpose**: Meaningful, consistent naming conventions.
+
+**When to use**: All code generation. Names are the first documentation.
+
+---
+
+## Core Rules
+
+### Naming Conventions (PEP 8)
+| Type | Convention | Example |
+|------|------------|---------|
+| Module | lowercase, short | `utils`, `http_client` |
+| Package | lowercase, short | `mypackage`, `api_client` |
+| Class | PascalCase | `UserService`, `HTTPClient` |
+| Function | snake_case | `get_user`, `process_order` |
+| Method | snake_case | `save`, `validate` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRIES`, `DEFAULT_TIMEOUT` |
+| Variable | snake_case | `user_count`, `is_active` |
+| Type variable | PascalCase | `T`, `UserT`, `KeyT` |
+| Exception | PascalCase + Error/Exception | `ValidationError`, `NotFoundError` |
+
+### Descriptive Names
+```python
+# GOOD
+user_count = len(users)
+max_retry_attempts = 3
+is_user_active = user.status == "active"
+process_payment(payment)
+
+# BAD
+n = len(users)
+m = 3
+flag = user.status == "active"
+proc(p)
+```
+
+### Boolean Names
+```python
+# GOOD — positive, question form
+is_active = True
+has_permission = False
+can_edit = True
+should_retry = True
+
+# BAD
+not_inactive = True
+no_permission = False
+active = True  # Ambiguous: noun or adj?
+```
+
+### Collection Names
+```python
+# GOOD — plural for collections
+users = get_users()
+active_users = [u for u in users if u.is_active]
+user_by_id = {u.id: u for u in users}
+
+# BAD
+user_list = get_users()
+user_dict = {u.id: u for u in users}
+```
+
+### Function Names
+```python
+# GOOD — verb phrase
+get_user(user_id)
+create_user(data)
+validate_email(email)
+calculate_total(items)
+save_to_database(record)
+
+# BAD
+user(user_id)        # Noun
+user_create(data)    # Verb-noun reversed
+check(email)         # Vague
+total(items)         # Noun
+persist(record)      # Too generic
+```
+
+### Class Names
+```python
+# GOOD — noun phrase
+class UserService:
+class PaymentProcessor:
+class DatabaseConnection:
+class HTTPClient:
+class ValidationError:
+
+# BAD
+class UserManager:      # "Manager" is vague
+class Utils:            # Namespace, not class
+class Data:             # Too generic
+class HandleUser:       # Verb phrase
+```
+
+### Module Names
+```python
+# GOOD
+http_client.py
+user_service.py
+payment_processor.py
+
+# BAD
+client.py          # Too generic
+user.py            # Conflicts with class User
+service.py         # Vague
+```
+
+---
+
+## Decision Rules
+
+| Context | Convention |
+|---------|------------|
+| Public API | Full descriptive names |
+| Internal helper | Can be shorter if context clear |
+| Loop variable | `i`, `j`, `k` or `idx` |
+| Comprehension | `x`, `item`, `elem` |
+| Type variable | `T`, `K`, `V`, `T_co` |
+| Private | Leading `_` (`_internal`) |
+| Dunder | `__special__` (Python reserved) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Consistent prefixes for related functions
+def fetch_user(user_id: int) -> User:
+def fetch_users(filters: UserFilters) -> list[User]:
+def fetch_user_by_email(email: str) -> User | None:
+
+# Consistent suffixes for related classes
+class UserRepository:
+class OrderRepository:
+class ProductRepository:
+
+# Clear boolean naming
+if user.can_access(resource):
+if config.should_retry_on_failure:
+if not order.is_cancelled:
+```
+
+---
+
+## Avoid
+
+- Single letters (except loops/math)
+- Abbreviations (`cfg`, `msg`, `usr`, `tmp`)
+- Hungarian notation (`str_name`, `int_count`)
+- Redundant prefixes (`my_`, `the_`, `obj_`)
+- Name shadowing (`list = [...]`, `dict = {}`)
+- Similar names differing only by case (`user` vs `User`)
+
+---
+
+## Validation Considerations
+
+- Linter naming checks (`ruff` N800 series)
+- `pylint` naming conventions
+- Code review for clarity
+
+---
+
+## Related Skills
+
+- `quality/readability.md`
+- `quality/functions.md`
+- `core/variables_types.md`

skills/quality/quality_functions.md

@@ -0,0 +1,245 @@
+# Quality: Functions
+
+**Purpose**: Function design principles for maintainable code.
+
+**When to use**: Writing or reviewing functions.
+
+---
+---
+name: quality_functions
+purpose: Function design principles for maintainable code
+category: quality
+triggers:
+  - function
+  - method
+  - parameter
+  - signature
+  - complexity
+  - cyclomatic
+dependencies:
+  - quality/readability.md
+  - quality/maintainability.md
+  - quality/abstractions.md
+  - generation/error_handling.md
+  - testing/organization.md
+priority: primary
+estimated_tokens: 1500
+---
+
+## Core Rules
+
+### Size
+- **Target**: < 30 lines (excluding docstrings)
+- **Maximum**: 50 lines
+- Split if exceeded
+
+### Single Responsibility
+- One logical operation per function
+- Name describes what it does
+- If "and" in name → split
+
+### Parameters
+- **Target**: ≤ 4 parameters
+- **Maximum**: 7 parameters
+- Use config object for more
+
+```python
+# BAD — too many params
+def process(a, b, c, d, e, f, g, h):
+    ...
+
+# GOOD — config object
+@dataclass
+class ProcessConfig:
+    a: int
+    b: str
+    c: float
+    ...
+
+def process(config: ProcessConfig):
+    ...
+```
+
+### Return Values
+- Single return type (union if needed)
+- Early returns for guard clauses
+- Explicit `return` at end (or implicit `None`)
+
+```python
+# GOOD — early returns
+def find_user(users: list[User], id: int) -> User | None:
+    if not users:
+        return None
+    
+    for user in users:
+        if user.id == id:
+            return user
+    
+    return None
+
+# BAD — nested
+def find_user(users: list[User], id: int) -> User | None:
+    result = None
+    if users:
+        for user in users:
+            if user.id == id:
+                result = user
+                break
+    return result
+```
+
+### Side Effects
+- Document side effects in docstring
+- Prefer pure functions (same input → same output)
+- Separate pure logic from I/O
+
+```python
+# Pure
+def calculate_total(items: list[Item]) -> Decimal:
+    return sum(item.price for item in items)
+
+# Impure (I/O) — separate
+def save_order(order: Order) -> Order:
+    db.save(order)
+    return order
+```
+
+### Function Responsibility
+- One logical operation per function
+- Name describes what it does (verb + object: `validate_email`, `fetch_user`)
+- If name contains "and" → split
+- Each function should be testable in isolation
+
+### Parameter Design
+- **Positional-only** (`/`) for `self`, `cls`, or API stability
+- **Keyword-only** (`*`) for boolean flags and optional config
+- **Default values** must be immutable (use `None` sentinel)
+- **Type hints** required for public API, optional for private helpers
+
+```python
+# GOOD — clear signature
+def fetch_users(
+    client: APIClient,
+    filters: UserFilters | None = None,
+    limit: int = 100,
+    *,
+    include_inactive: bool = False,
+) -> list[User]:
+    ...
+
+# BAD — ambiguous
+def fetch_users(client, filters=None, limit=100, include_inactive=False):
+    ...
+```
+
+### Return Value Design
+- Single return type (union if needed for errors)
+- Early returns for guard clauses
+- Explicit `return` at end (or implicit `None`)
+- Use `Result` pattern for operations that can fail
+
+```python
+# GOOD — early returns, single type
+def find_user(users: list[User], id: int) -> User | None:
+    if not users:
+        return None
+    
+    for user in users:
+        if user.id == id:
+            return user
+    
+    return None
+
+# GOOD — Result pattern for fallible operations
+def parse_user(data: dict) -> Result[User, ValidationError]:
+    try:
+        return Result.ok(User.model_validate(data))
+    except ValidationError as e:
+        return Result.err(e)
+```
+
+### Side Effects
+- Document side effects in docstring (`"""Creates user and sends welcome email."""`)
+- Prefer pure functions (same input → same output, no external mutation)
+- Separate pure logic from I/O
+- Pass dependencies explicitly, not via global state
+
+```python
+# Pure
+def calculate_total(items: list[Item]) -> Decimal:
+    return sum(item.price for item in items)
+
+# Impure (I/O) — separate, inject dependencies
+def save_order(order: Order, repo: OrderRepository) -> Order:
+    repo.save(order)
+    return order
+```
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Repeated logic | Extract function |
+| Complex condition | Extract predicate function |
+| Multiple returns | Early returns |
+| Many parameters | Config dataclass |
+| Logic + I/O | Separate functions |
+| Boolean flag controls behavior | Split into two functions |
+| Output parameter (modify argument) | Return new value instead |
+| Recursive without clear base case | Use iteration |
+
+---
+
+## Preferred Patterns
+
+```python
+# Composed from small functions
+def process_order(order: Order) -> Result[Fulfillment, OrderError]:
+    validate_order(order)
+    payment = charge_payment(order)
+    fulfillment = create_fulfillment(order)
+    notify_customer(order, fulfillment)
+    return Result.ok(fulfillment)
+
+# Each small, testable
+def validate_order(order: Order) -> None:
+    if not order.items:
+        raise ValidationError("items", "Order must have items")
+    if order.total <= 0:
+        raise ValidationError("total", "Total must be positive")
+```
+
+---
+
+## Avoid
+
+- Functions doing 3+ distinct things
+- Boolean parameters controlling behavior (`process(data, True, False)`)
+- Output parameters (modify argument)
+- Global state modification
+- Recursive functions without clear base case (use iteration)
+- `*args`/`**kwargs` without documentation of expected keys
+- Modifying `**kwargs` in place (copy first)
+- Deeply nested functions (limit closure depth)
+
+---
+
+## Validation Considerations
+
+- Cyclomatic complexity per function (< 10)
+- Function length (lines) (< 50)
+- Parameter count (≤ 7)
+- Test coverage per function
+- `ruff` rules: B006 (mutable default), B007 (loop var in closure), B008 (func call in default)
+
+---
+
+## Related Skills
+
+- `quality/readability.md`
+- `quality/maintainability.md`
+- `quality/abstractions.md`
+- `generation/error_handling.md`
+- `testing/organization.md`

skills/quality/readability.md

@@ -0,0 +1,239 @@
+# Quality: Readability
+
+**Purpose**: Code should be easy for another developer to understand.
+
+**When to use**: All code generation and review.
+---
+---
+name: quality_readability
+purpose: Code should be easy for another developer to understand
+category: quality
+triggers:
+  - readability
+  - cognitive load
+  - nesting
+  - line length
+  - naming
+  - guard clause
+dependencies:
+  - quality/naming.md
+  - quality/functions.md
+  - quality/abstractions.md
+  - quality/comments.md
+priority: primary
+estimated_tokens: 1500
+---
+
+## Core Rules
+
+### Cognitive Load
+- Limit concepts per function
+- Use meaningful names (see naming.md)
+- Avoid clever tricks
+- Prefer explicit over implicit
+
+### Vertical Density
+```python
+# GOOD — spaced out
+def process_user(user: User) -> Result:
+    validate(user)
+    
+    enriched = enrich(user)
+    
+    saved = save(enriched)
+    
+    notify(saved)
+    
+    return Result.ok(saved)
+
+# BAD — cramped
+def process_user(user): validate(user); enriched=enrich(user); saved=save(enriched); notify(saved); return Result.ok(saved)
+```
+
+### Horizontal Density
+```python
+# GOOD — within line length
+result = process(
+    user=user,
+    options=default_options,
+    callback=on_complete,
+)
+
+# BAD — too wide
+result = process(user=user, options=default_options, callback=on_complete, timeout=30, retry=True, validate=True)
+```
+
+### Line Length
+- Target: 88-100 chars (configurable per project)
+- Break long lines at logical points
+- Use parentheses for implicit continuation
+
+```python
+# Good breaks
+long_function_call(
+    argument_one=value1,
+    argument_two=value2,
+    argument_three=value3,
+)
+
+# Dictionary
+config = {
+    "key_one": "value1",
+    "key_two": "value2",
+}
+
+# Type hints
+def func(
+    arg1: VeryLongTypeName,
+    arg2: AnotherVeryLongTypeName,
+) -> ReturnTypeName:
+    ...
+```
+
+### Blank Lines
+- Between logical sections in function
+- Between class methods
+- Around top-level definitions (2 blank lines)
+
+```python
+def process(data: Data) -> Result:
+    # Validation
+    if not data.is_valid:
+        return Result.error("invalid")
+    
+    # Transformation
+    transformed = transform(data)
+    
+    # Persistence
+    saved = save(transformed)
+    
+    return Result.ok(saved)
+```
+
+### Guard Clauses (Reduce Nesting)
+```python
+# GOOD — flat structure
+def process(user: User) -> Result:
+    if not user.active:
+        return Result.error("inactive")
+    
+    if not user.has_permission("write"):
+        return Result.error("forbidden")
+    
+    # Main logic at base indent
+    data = fetch_data(user)
+    return Result.ok(transform(data))
+
+# BAD — deeply nested
+def process(user: User) -> Result:
+    if user.active:
+        if user.has_permission("write"):
+            data = fetch_data(user)
+            return Result.ok(transform(data))
+        else:
+            return Result.error("forbidden")
+    else:
+        return Result.error("inactive")
+```
+
+### Named Intermediate Values
+```python
+# GOOD — self-documenting
+def calculate_price(item: Item, user: User) -> Price:
+    base_price = item.base_price
+    discount = user.discount_rate
+    tax_rate = get_tax_rate(user.region)
+    
+    discounted = base_price * (1 - discount)
+    final = discounted * (1 + tax_rate)
+    
+    return Price(amount=final, currency=item.currency)
+
+# BAD — magic calculations
+def calculate_price(item: Item, user: User) -> Price:
+    return Price(amount=item.base_price * (1 - user.discount_rate) * (1 + get_tax_rate(user.region)), currency=item.currency)
+```
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Complex condition | Extract to variable/function |
+| Long expression | Break across lines |
+| Multiple operations | Separate with blank lines |
+| Nested logic | Early return / guard clauses |
+| Magic numbers | Named constants |
+| Boolean flag controls behavior | Split into two functions |
+
+---
+
+## Preferred Patterns
+
+```python
+# Guard clauses (reduce nesting)
+def process(user: User) -> Result:
+    if not user.active:
+        return Result.error("inactive")
+    
+    if not user.has_permission("write"):
+        return Result.error("forbidden")
+    
+    # Main logic at base indent
+    data = fetch_data(user)
+    return Result.ok(transform(data))
+
+# Named intermediate values
+def calculate_price(item: Item, user: User) -> Price:
+    base_price = item.base_price
+    discount = user.discount_rate
+    tax_rate = get_tax_rate(user.region)
+    
+    discounted = base_price * (1 - discount)
+    final = discounted * (1 + tax_rate)
+    
+    return Price(amount=final, currency=item.currency)
+
+# Extract complex conditions
+def is_eligible(user: User) -> bool:
+    has_active_sub = user.subscription and user.subscription.active
+    within_trial = user.trial_end and user.trial_end > datetime.now()
+    return has_active_sub or within_trial
+
+def process(user: User) -> Result:
+    if not is_eligible(user):
+        return Result.error("not eligible")
+    ...
+```
+
+---
+
+## Avoid
+
+- Single-letter variables (except loop counters: `i`, `j`, `k`)
+- Abbreviations (`usr`, `cfg`, `msg` — use `user`, `config`, `message`)
+- Deep nesting (>3 levels)
+- Long functions (>50 lines)
+- Multiple statements per line
+- Clever one-liners that require mental parsing
+- Single-letter type variables (`T`, `U`) without context
+- Shadowing built-ins (`list`, `dict`, `str`, `type`, `id`)
+
+---
+
+## Validation Considerations
+
+- Linter line-length checks (ruff: `line-length`)
+- Cyclomatic complexity (radon, xenon)
+- Code review readability assessment
+- `ruff` rules: B007 (loop var in closure), B008 (func call in default)
+
+---
+
+## Related Skills
+
+- `quality/naming.md`
+- `quality/functions.md`
+- `quality/abstractions.md`
+- `quality/comments.md`