python-skills 1.0.0__py3-none-any.whl

skills/comprehensions.md

@@ -0,0 +1,167 @@
+# Core: Comprehensions
+
+**Purpose**: Python comprehension syntax and appropriate usage.
+
+**When to use**: Transforming, filtering, or creating collections.
+
+---
+
+## Core Rules
+
+### List Comprehension
+```python
+# Basic
+squares = [x * x for x in range(10)]
+
+# With filter
+evens = [x for x in range(10) if x % 2 == 0]
+
+# Nested (cartesian product)
+pairs = [(x, y) for x in range(3) for y in range(3)]
+# [(0,0), (0,1), (0,2), (1,0), ...]
+
+# With conditional expression (ternary)
+labels = ["even" if x % 2 == 0 else "odd" for x in range(10)]
+```
+
+### Dict Comprehension
+```python
+# Basic
+name_to_len = {name: len(name) for name in names}
+
+# With filter
+short_names = {name: len(name) for name in names if len(name) < 5}
+
+# Swap keys/values (values must be unique)
+inverted = {v: k for k, v in mapping.items()}
+
+# From two sequences
+mapping = {k: v for k, v in zip(keys, values, strict=True)}
+```
+
+### Set Comprehension
+```python
+unique_lengths = {len(name) for name in names}
+```
+
+### Generator Expression
+```python
+# Lazy, memory efficient
+squares_gen = (x * x for x in range(1_000_000))
+
+# Consume
+for sq in squares_gen:
+    ...
+
+# Or convert
+list(squares_gen)
+```
+
+---
+
+## Walrus Operator (Python 3.8+)
+```python
+# Assign and use in comprehension
+results = [y for x in data if (y := compute(x)) is not None]
+
+# In while loops
+while (line := file.readline()) != '':
+    process(line)
+```
+
+---
+
+## Decision Rules
+
+| Situation | Choice |
+|-----------|--------|
+| Simple transform + filter | Comprehension |
+| Multiple transforms, complex logic | Explicit `for` loop |
+| Need to debug intermediate values | Explicit `for` loop |
+| Large/unknown size, memory concern | Generator expression |
+| Dict from two parallel sequences | `{k: v for k, v in zip(...)}` |
+| Flatten nested list | `[item for sublist in nested for item in sublist]` |
+
+---
+
+## Preferred Patterns
+
+```python
+# Flatmap pattern
+flattened = [item for sublist in nested for item in sublist]
+
+# Grouping with defaultdict (clearer than comprehension)
+from collections import defaultdict
+grouped = defaultdict(list)
+for item in items:
+    grouped[key(item)].append(item)
+
+# Set for deduplication preserving order (Python 3.7+)
+seen = set()
+unique = [x for x in items if not (x in seen or seen.add(x))]
+# Or simpler (loses order): list(set(items))
+
+# Chained operations — prefer explicit loop
+result = []
+for item in items:
+    transformed = transform(item)
+    if validate(transformed):
+        result.append(transformed)
+```
+
+---
+
+## Avoid
+
+- Nested comprehensions >2 levels deep (unreadable)
+- Side effects in comprehensions (mutating external state)
+- Complex conditional expressions (ternary) in comprehensions
+- Generator expressions passed directly to functions that consume immediately (just use list comprehension)
+- Walrus operator for trivial assignments (reduces readability)
+- Comprehensions spanning multiple lines without clear structure
+
+---
+
+## Anti-Patterns
+
+```python
+# BAD: Side effect
+[x.append(i) for i in range(10)]  # Returns [None, None, ...]
+
+# BAD: Too complex
+result = [
+    transform(x) 
+    for x in items 
+    if (cond1 := check1(x)) 
+    and (cond2 := check2(x) if cond1 else False)
+    for y in related(x)
+]
+
+# GOOD: Explicit loop
+result = []
+for x in items:
+    if not check1(x):
+        continue
+    if not check2(x):
+        continue
+    for y in related(x):
+        result.append(transform(x))
+```
+
+---
+
+## Validation Considerations
+
+- Type checkers infer comprehension types
+- Linters flag overly complex comprehensions
+- Memory profile for large comprehensions vs generators
+
+---
+
+## Related Skills
+
+- `core/data_structures.md`
+- `core/advanced_python.md` (generators)
+- `generation/type_hints.md`
+- `quality/readability.md`
+- `anti_patterns/index.md`

skills/control_flow.md

@@ -0,0 +1,175 @@
+# Core: Control Flow
+
+**Purpose**: Python control flow constructs and patterns.
+
+**When to use**: Always active. Foundation for logic implementation.
+
+---
+
+## Core Rules
+
+### Conditionals
+```python
+if condition:
+    ...
+elif other_condition:
+    ...
+else:
+    ...
+```
+
+- No parentheses required around condition
+- `elif` not `else if`
+- Truthiness: `None`, `False`, `0`, `0.0`, `""`, `[]`, `{}`, `set()` are falsy
+- Use explicit comparisons (`is None`, `== 0`, `== ""`) when falsy is a valid value
+
+### Ternary Expression
+```python
+value = true_expr if condition else false_expr
+```
+- Single expression, not statement
+- Use for simple assignments only
+
+### Match Statement (Python 3.10+)
+```python
+match value:
+    case pattern1:
+        ...
+    case pattern2 if guard:
+        ...
+    case _:
+        ...
+```
+- Structural pattern matching
+- Use for complex data structure dispatch
+- Guard clauses with `if`
+
+---
+
+## Loops
+
+### For Loop (Iteration)
+```python
+for item in iterable:
+    ...
+else:           # executes if loop completes without break
+    ...
+```
+- `else` clause runs on normal completion (no `break`)
+- Preferred over index-based loops
+
+### While Loop
+```python
+while condition:
+    ...
+else:
+    ...
+```
+- `else` runs when condition becomes false (no `break`)
+
+### Loop Control
+- `break` — exit loop immediately
+- `continue` — skip to next iteration
+- `pass` — placeholder (no-op)
+
+### Enumerate and Zip
+```python
+for i, item in enumerate(iterable, start=1):
+    ...
+
+for a, b in zip(list1, list2, strict=True):  # Python 3.10+
+    ...
+```
+- `strict=True` raises `ValueError` if lengths differ (Python 3.10+)
+
+---
+
+## Exception Control Flow
+
+```python
+try:
+    risky_operation()
+except SpecificError as e:
+    handle(e)
+except (Error1, Error2) as e:
+    handle(e)
+else:           # runs if no exception
+    success_path()
+finally:        # always runs
+    cleanup()
+```
+
+- Order: specific exceptions first, general last
+- `else` block for code that should only run on success
+- `finally` for cleanup (files, locks, connections)
+
+---
+
+## Decision Rules
+
+| Situation | Construct |
+|-----------|-----------|
+| Simple branch | `if/elif/else` |
+| Value-based dispatch (3.10+) | `match/case` |
+| Iterate known collection | `for` |
+| Iterate with index | `enumerate()` |
+| Iterate multiple aligned collections | `zip(strict=True)` |
+| Unknown iteration count | `while` |
+| Early exit on condition | `break` |
+| Skip iteration | `continue` |
+| Cleanup always | `finally` |
+| Success-only path | `else` on `try` |
+
+---
+
+## Preferred Patterns
+
+```python
+# EAFP (Easier to Ask Forgiveness than Permission)
+try:
+    value = mapping[key]
+except KeyError:
+    value = default
+
+# LBYL (Look Before You Leap) - when appropriate
+if key in mapping:
+    value = mapping[key]
+else:
+    value = default
+
+# Loop with else for search
+for item in items:
+    if condition(item):
+        found = item
+        break
+else:
+    found = default
+```
+
+---
+
+## Avoid
+
+- Deeply nested conditionals (refactor to functions/early returns)
+- `for i in range(len(list))` — use `enumerate` or direct iteration
+- `while True` with `break` when `for` or `itertools` works
+- Catching `Exception` or bare `except:` (see error_handling.md)
+- Using exceptions for normal control flow (except EAFP patterns)
+- Complex logic in ternary expressions
+
+---
+
+## Validation Considerations
+
+- Linters catch unreachable code after `return`/`break`/`continue`
+- Type checkers verify exhaustive `match` (with `assert_never`)
+- Coverage tools reveal untested branches
+
+---
+
+## Related Skills
+
+- `core/functions.md` (early returns)
+- `generation/error_handling.md`
+- `generation/async_concurrency.md` (async for/while)
+- `anti_patterns/index.md`

skills/data_structures.md

@@ -0,0 +1,243 @@
+# Core: Data Structures
+
+**Purpose**: Python built-in data structures and their appropriate use.
+
+**When to use**: Always active. Choose the right structure for the problem.
+
+---
+
+## Core Rules
+
+### List (`list`)
+- Ordered, mutable, allows duplicates
+- O(1) append, pop from end; O(n) insert/pop from front
+- Use for sequences where order matters
+
+```python
+items: list[str] = ["a", "b", "c"]
+items.append("d")
+items.extend(["e", "f"])
+items.insert(0, "start")
+popped = items.pop()      # From end
+popped = items.pop(0)     # From front (O(n))
+```
+
+### Tuple (`tuple`)
+- Ordered, immutable, allows duplicates
+- Lightweight, hashable (if contents hashable)
+- Use for fixed collections, heterogeneous data, return values
+
+```python
+point: tuple[float, float] = (1.0, 2.0)
+# Unpacking
+x, y = point
+# Named tuple alternative
+from typing import NamedTuple
+class Point(NamedTuple):
+    x: float
+    y: float
+```
+
+### Dict (`dict`)
+- Key-value mapping, mutable, keys unique and hashable
+- O(1) average lookup, insertion, deletion
+- Preserves insertion order (Python 3.7+)
+
+```python
+data: dict[str, int] = {"a": 1, "b": 2}
+data["c"] = 3
+value = data.get("key", default)  # Safe access
+value = data.setdefault("key", default)  # Get or set
+```
+
+### Set (`set`) / Frozenset (`frozenset`)
+- Unordered, unique elements, mutable (`set`) or immutable (`frozenset`)
+- O(1) membership testing
+- Mathematical set operations
+
+```python
+unique: set[int] = {1, 2, 3}
+unique.add(4)
+unique.update([5, 6])
+intersection = unique & {3, 4, 5}
+union = unique | {7, 8}
+```
+
+---
+
+## Nesting and Composition
+
+```python
+# List of dicts
+records: list[dict[str, Any]] = [{"id": 1, "name": "a"}, {"id": 2, "name": "b"}]
+
+# Dict of lists
+grouped: dict[str, list[int]] = {"even": [2, 4], "odd": [1, 3]}
+
+# Complex nesting
+matrix: list[list[int]] = [[1, 2], [3, 4]]
+```
+
+---
+
+## Indexing and Slicing
+
+```python
+seq = [0, 1, 2, 3, 4, 5]
+
+seq[0]      # First
+seq[-1]     # Last
+seq[1:4]    # Indices 1,2,3
+seq[:3]     # First 3
+seq[3:]     # From index 3
+seq[::2]    # Every 2nd
+seq[::-1]   # Reversed
+```
+
+- Slicing returns new object (shallow copy)
+- Out-of-range slice indices don't raise (clamped)
+
+---
+
+## Unpacking
+
+```python
+# Basic
+a, b, c = (1, 2, 3)
+
+# Extended (Python 3+)
+first, *middle, last = [1, 2, 3, 4, 5]
+# first=1, middle=[2,3,4], last=5
+
+# Ignored values
+_, _, value = get_triple()
+
+# Dict unpacking (Python 3.5+)
+{**dict1, **dict2}          # Merge (later wins)
+{**dict1, "new": value}     # Add key
+```
+
+---
+
+## Iteration Patterns
+
+```python
+# Direct iteration
+for item in items:
+    ...
+
+# With index
+for i, item in enumerate(items):
+    ...
+
+# Multiple sequences
+for a, b in zip(list1, list2, strict=True):
+    ...
+
+# Reverse
+for item in reversed(items):
+    ...
+
+# Sorted
+for item in sorted(items):
+    ...
+
+# Dictionary
+for key, value in mapping.items():
+    ...
+for key in mapping:
+    ...
+for value in mapping.values():
+    ...
+```
+
+---
+
+## Mutation vs Reassignment
+
+```python
+# Mutation (changes object in place)
+lst.append(x)
+lst.extend(other)
+lst[0] = new
+dct[key] = value
+s.add(item)
+
+# Reassignment (binds name to new object)
+lst = lst + [x]        # New list
+dct = {**dct, k: v}    # New dict
+```
+
+- Mutation affects all references to the object
+- Reassignment only affects the local name
+
+---
+
+## Decision Rules
+
+| Need | Structure |
+|------|-----------|
+| Ordered, mutable, duplicates | `list` |
+| Ordered, immutable, hashable | `tuple` / `NamedTuple` |
+| Key → value, fast lookup | `dict` |
+| Unique items, membership test | `set` |
+| Unique items, immutable | `frozenset` |
+| Fixed schema, heterogeneous | `dataclass` / `NamedTuple` / `TypedDict` |
+| Stack (LIFO) | `list` (append/pop) |
+| Queue (FIFO) | `collections.deque` |
+| Priority queue | `heapq` |
+| Counter/multiset | `collections.Counter` |
+| Default values for missing keys | `collections.defaultdict` |
+| Ordered dict with LRU | `collections.OrderedDict` / `functools.lru_cache` |
+
+---
+
+## Preferred Patterns
+
+```python
+# Use comprehensions for simple transformations
+squares = [x*x for x in range(10)]
+even_squares = {x*x for x in range(10) if x % 2 == 0}
+name_to_len = {name: len(name) for name in names}
+
+# Generator for large/unknown sequences
+def generate_items():
+    for i in range(1_000_000):
+        yield compute(i)
+
+# Defaultdict for grouping
+from collections import defaultdict
+grouped = defaultdict(list)
+for item in items:
+    grouped[key(item)].append(item)
+```
+
+---
+
+## Avoid
+
+- `list` for membership testing (O(n)) — use `set`
+- `list` for queue (pop(0) is O(n)) — use `deque`
+- Nested lists for matrices (use `numpy` or flat list)
+- `dict` with mutable keys (unhashable)
+- Modifying container during iteration (iterate over copy)
+- Excessive nesting depth (>3 levels) — use dataclasses
+
+---
+
+## Validation Considerations
+
+- Type checkers verify generic type parameters
+- `collections.abc` interfaces for structural typing
+- Mutation during iteration raises `RuntimeError`
+
+---
+
+## Related Skills
+
+- `core/advanced_python.md` (generators, iterators)
+- `stdlib/collections.md`
+- `stdlib/itertools.md`
+- `generation/type_hints.md` (generics)
+- `core/comprehensions.md`
+- `quality/duplication.md`