python-skills 1.0.0__py3-none-any.whl

skills/debugging/common_bugs.md

@@ -0,0 +1,222 @@
+# Debugging: Common Bugs
+
+**Purpose**: Quick reference for frequent Python bug patterns.
+
+**When to use**: Debugging, code review, preventing known issues.
+
+---
+
+## Core Rules
+
+### Mutable Default Arguments
+```python
+# BUG
+def append_item(item, items=[]):
+    items.append(item)
+    return items
+
+append_item(1)  # [1]
+append_item(2)  # [1, 2] — BUG: shared list!
+
+# FIX
+def append_item(item, items=None):
+    if items is None:
+        items = []
+    items.append(item)
+    return items
+```
+
+### Late Binding in Closures
+```python
+# BUG
+funcs = []
+for i in range(3):
+    funcs.append(lambda: i)
+    
+[f() for f in funcs]  # [2, 2, 2] — all capture same i!
+
+# FIX — bind early
+funcs = []
+for i in range(3):
+    funcs.append(lambda i=i: i)  # Default binds current value
+    
+# OR use functools.partial
+from functools import partial
+funcs = [partial(lambda x: x, i) for i in range(3)]
+```
+
+### Integer Division (Python 2 vs 3)
+```python
+# Python 3: / is float division, // is integer
+3 / 2   # 1.5
+3 // 2  # 1
+
+# In Python 2: / was integer division for ints
+# Not an issue in Python 3+
+```
+
+### Floating Point Precision
+```python
+# BUG
+0.1 + 0.2 == 0.3  # False! 0.30000000000000004
+
+# FIX — use Decimal for money/precision
+from decimal import Decimal
+Decimal("0.1") + Decimal("0.2") == Decimal("0.3")  # True
+
+# Or use tolerance
+abs(0.1 + 0.2 - 0.3) < 1e-9  # True
+```
+
+### Variable Shadowing
+```python
+# BUG
+def process(items):
+    list = []  # Shadows built-in list!
+    for item in items:
+        list.append(transform(item))
+    return list
+
+# FIX — never shadow builtins
+def process(items):
+    result = []
+    for item in items:
+        result.append(transform(item))
+    return result
+```
+
+### Iterable Exhaustion
+```python
+# BUG
+gen = (x for x in range(3))
+list(gen)  # [0, 1, 2]
+list(gen)  # [] — exhausted!
+
+# FIX — convert to list if reused
+gen = list(x for x in range(3))
+list(gen)  # [0, 1, 2]
+list(gen)  # [0, 1, 2]
+```
+
+### Default Dict Mutation
+```python
+# BUG
+from collections import defaultdict
+
+def add_item(key, value, d=defaultdict(list)):
+    d[key].append(value)
+    return d
+
+add_item("a", 1)  # {"a": [1]}
+add_item("b", 2)  # {"a": [1], "b": [2]} — SHARED!
+
+# FIX
+def add_item(key, value, d=None):
+    if d is None:
+        d = defaultdict(list)
+    d[key].append(value)
+    return d
+```
+
+### Exception Swallowing
+```python
+# BUG
+try:
+    risky()
+except:
+    pass  # Swallows everything including KeyboardInterrupt!
+
+# FIX — specific exceptions
+try:
+    risky()
+except SpecificError:
+    handle()
+except Exception:
+    logger.exception("Unexpected error")
+    raise
+```
+
+### Modifying During Iteration
+```python
+# BUG
+items = [1, 2, 3, 4, 5]
+for item in items:
+    if item % 2 == 0:
+        items.remove(item)  # Skips elements!
+
+# FIX — iterate over copy
+for item in items[:]:  # or list(items)
+    if item % 2 == 0:
+        items.remove(item)
+
+# OR filter
+items = [x for x in items if x % 2 != 0]
+```
+
+### String/Bytes Confusion
+```python
+# BUG
+data = b"hello"
+data + " world"  # TypeError: can't concat bytes to str
+
+# FIX — explicit encode/decode
+data.decode() + " world"  # "hello world"
+data + b" world"          # b"hello world"
+```
+
+### Path Traversal (Security)
+```python
+# BUG
+def read_file(filename):
+    with open(filename) as f:  # User controls path!
+        return f.read()
+
+# FIX — validate path
+def read_file(filename, base_dir):
+    path = (Path(base_dir) / filename).resolve()
+    if not path.is_relative_to(base_dir):
+        raise SecurityError("Path traversal")
+    return path.read_text()
+```
+
+---
+
+## Decision Rules
+
+| Symptom | Likely Cause |
+|---------|--------------|
+| State persists across calls | Mutable default argument |
+| Loop variable wrong in closure | Late binding |
+| Money calculations wrong | Float precision |
+| First/last element wrong | Off-by-one |
+| Intermittent failures | Race condition / shared state |
+| Unicode errors | Bytes/str confusion |
+| Second iteration empty | Iterator exhaustion |
+
+---
+
+## Avoid
+
+- `except:` without exception type
+- `list`, `dict`, `str` as variable names
+- `float` for money
+- Implicit iterator reuse
+- User input in file paths without validation
+
+---
+
+## Validation Considerations
+
+- `ruff` catches most of these (B006, B007, B008, etc.)
+- `mypy` catches type issues
+- Unit tests for edge cases
+- Property-based testing finds edge cases
+
+---
+
+## Related Skills
+
+- `debugging/root_cause.md`
+- `anti_patterns/index.md`
+- `security/input_validation.md`
+- `generation/type_hints.md`

skills/debugging/inspection_techniques.md

@@ -0,0 +1,249 @@
+# Debugging: Inspection Techniques
+
+**Purpose**: Tools and techniques for runtime inspection and debugging.
+
+**When to use**: Investigating bugs, understanding code behavior, profiling.
+
+---
+
+## Core Rules
+
+### Runtime Inspection
+
+#### Object Inspection
+```python
+# Type and attributes
+type(obj)
+dir(obj)
+vars(obj)           # __dict__
+hasattr(obj, 'attr')
+getattr(obj, 'attr', default)
+isinstance(obj, Type)
+issubclass(cls, Type)
+
+# Function inspection
+import inspect
+inspect.signature(func)
+inspect.getsource(func)
+inspect.getfile(func)
+inspect.getmodule(func)
+inspect.iscoroutinefunction(func)
+inspect.isgeneratorfunction(func)
+```
+
+#### Frame Inspection
+```python
+import sys
+
+# Current frame
+frame = sys._getframe()
+frame.f_locals      # Local variables
+frame.f_globals     # Global variables
+frame.f_code        # Code object
+frame.f_lineno      # Line number
+
+# Call stack
+traceback.print_stack()
+traceback.extract_stack()
+
+# In exception handler
+import traceback
+traceback.print_exc()
+traceback.format_exc()
+```
+
+#### Object Graph
+```python
+import gc
+
+# Find referrers (what references this object)
+gc.get_referrers(obj)
+
+# Find referents (what this object references)
+gc.get_referents(obj)
+
+# All objects of type
+[obj for obj in gc.get_objects() if isinstance(obj, MyClass)]
+```
+
+### Profiling
+
+#### Time Profiling
+```bash
+# cProfile
+python -m cProfile -o profile.stats script.py
+# Analyze
+python -m pstats profile.stats
+# Sort by cumulative time, show top 20
+# pstats> sort cumulative
+# pstats> stats 20
+```
+
+```python
+# In code
+import cProfile
+import pstats
+
+profiler = cProfile.Profile()
+profiler.enable()
+
+# ... code to profile ...
+
+profiler.disable()
+stats = pstats.Stats(profiler).sort_stats('cumulative')
+stats.print_stats(20)
+```
+
+#### Memory Profiling
+```bash
+# memray (modern, fast)
+pip install memray
+memray run script.py
+memray flamegraph memray-results.bin
+
+# objgraph (object counts)
+pip install objgraph
+python -c "import objgraph; objgraph.show_most_common_types()"
+```
+
+#### Line Profiling
+```bash
+# kernprof
+pip install line_profiler
+kernprof -l -v script.py
+```
+
+### Logging for Debugging
+```python
+import logging
+
+# Structured debug logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)s] %(name)s:%(lineno)d: %(message)s"
+)
+
+# Context-specific logger
+logger = logging.getLogger("myapp.debug")
+
+# Conditional debug
+if logger.isEnabledFor(logging.DEBUG):
+    logger.debug("Expensive debug: %s", expensive_computation())
+```
+
+### REPL Debugging
+```python
+# In code
+breakpoint()
+# Python 3.7+ opens pdb at this line
+# In pdb: p var, pp var, n, s, c, l, where, up, down
+
+# Or embed IPython
+import IPython
+IPython.embed()  # Rich REPL with syntax highlighting
+```
+
+### Async Debugging
+```python
+# Check running tasks
+async def debug_tasks():
+    for task in asyncio.all_tasks():
+        print(task.get_name(), task.get_coro())
+    
+    # Current task
+    current = asyncio.current_task()
+    print(current.get_stack())
+
+# Trace async calls
+import asyncio
+asyncio.set_debug(True)
+# Or
+loop = asyncio.get_event_loop()
+loop.set_debug(True)
+```
+
+### Network Debugging
+```bash
+# HTTP traffic
+mitmproxy  # Interactive
+mitmdump   # Scriptable
+
+# Or in Python
+import http.client
+http.client.HTTPConnection.debuglevel = 1
+
+# requests
+import logging
+logging.getLogger("urllib3").setLevel(logging.DEBUG)
+```
+
+### Database Debugging
+```python
+# SQLAlchemy
+import logging
+logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)
+# Shows all SQL with parameters
+
+# Or echo
+engine = create_engine("postgresql://...", echo=True)
+```
+
+---
+
+## Decision Rules
+
+| Need | Tool |
+|------|------|
+| Quick variable check | `breakpoint()` / `print()` |
+| Performance bottleneck | `cProfile` / `memray` |
+| Memory leak | `memray` / `objgraph` |
+| Async deadlock | `asyncio` debug + task inspection |
+| SQL query issues | SQLAlchemy echo |
+| HTTP issues | `mitmproxy` / request logging |
+| Object lifecycle | `gc` / `weakref` |
+
+---
+
+## Preferred Patterns
+
+```python
+# Debug helper
+def debug_obj(obj, name="obj"):
+    print(f"=== {name} ===")
+    print(f"Type: {type(obj)}")
+    print(f"Dir: {[a for a in dir(obj) if not a.startswith('_')]}")
+    if hasattr(obj, '__dict__'):
+        print(f"Dict: {vars(obj)}")
+    print(f"=== end {name} ===")
+
+# Usage
+debug_obj(user, "user")
+```
+
+---
+
+## Avoid
+
+- `print()` in production code
+- Leaving `breakpoint()` in committed code
+- Profiling in production without sampling
+- `gc.get_objects()` in hot paths (slow)
+- Modifying `sys.path` at runtime
+
+---
+
+## Validation Considerations
+
+- Debug code removed before commit
+- Profiling overhead acceptable
+- Logs don't contain secrets
+- Async debug doesn't change timing significantly
+
+---
+
+## Related Skills
+
+- `debugging/root_cause.md`
+- `debugging/common_bugs.md`
+- `stdlib/logging.md`
+- `generation/async_concurrency.md`

skills/debugging/root_cause.md

@@ -0,0 +1,203 @@
+# Debugging: Root Cause Analysis
+
+**Purpose**: Systematic approach to finding and fixing bugs.
+
+**When to use**: Any bug investigation.
+
+---
+
+## Core Rules
+
+### Debugging Process
+```
+1. REPRODUCE — Create minimal failing case
+2. ISOLATE — Narrow down location
+3. HYPOTHESIZE — Form theory of cause
+4. TEST HYPOTHESIS — Verify with experiment
+5. FIX — Minimal change addressing root cause
+6. REGRESSION TEST — Prevent recurrence
+7. DOCUMENT — Record for future
+```
+
+### Reproduction
+```python
+# Minimal reproduction script
+# reproduce_issue.py
+import sys
+sys.path.insert(0, "src")
+
+from mypackage import process
+
+# Exact input that fails
+input_data = load_failing_case()
+
+try:
+    result = process(input_data)
+    print("UNEXPECTED SUCCESS:", result)
+except Exception as e:
+    print(f"REPRODUCED: {type(e).__name__}: {e}")
+    import traceback
+    traceback.print_exc()
+```
+
+### Isolation Techniques
+
+#### Binary Search (Git Bisect)
+```bash
+# Find commit that introduced bug
+git bisect start
+git bisect bad HEAD
+git bisect good v1.0.0
+# Git checks out middle commit
+# Run tests: pytest test_failing.py
+# git bisect good/bad
+# Repeats until found
+```
+
+#### Print Debugging (Structured)
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Or structured
+import structlog
+log = structlog.get_logger()
+
+def problematic_function(data):
+    log.debug("enter", data_keys=list(data.keys()))
+    result = step1(data)
+    log.debug("after_step1", result=result)
+    result = step2(result)
+    log.debug("after_step2", result=result)
+    return result
+```
+
+#### Interactive Debugger
+```python
+# In code
+breakpoint()  # Python 3.7+
+
+# Or conditional
+if condition:
+    breakpoint()
+
+# Run: python -m pdb script.py
+# Commands: n (next), s (step), c (continue), p (print), l (list)
+```
+
+### Common Bug Patterns
+
+| Pattern | Symptoms | Investigation |
+|---------|----------|---------------|
+| Off-by-one | First/last element wrong | Check loop bounds, slice indices |
+| Mutable default | State leaks between calls | Check function defaults |
+| Race condition | Intermittent, timing-dependent | Add logging, check thread safety |
+| Null reference | AttributeError/TypeError | Trace None propagation |
+| Type mismatch | Unexpected type at runtime | Add type checks, check boundaries |
+| Resource leak | Slow degradation, OOM | Check cleanup in finally/with |
+| Encoding issue | Unicode errors, corrupt data | Check encode/decode boundaries |
+
+### Hypothesis Testing
+```python
+# Hypothesis: "The bug is in validate_email()"
+# Test: Call validate_email() directly with failing input
+
+def test_hypothesis():
+    failing_email = "USER@EXAMPLE.COM"
+    result = validate_email(failing_email)
+    # If this fails → hypothesis confirmed
+    # If this passes → bug is elsewhere
+```
+
+### Fixing Root Cause
+```python
+# BAD — symptom fix
+def process(data):
+    if data is None:  # Handles symptom
+        return default()
+    return real_process(data)
+
+# GOOD — root cause fix
+def get_data() -> Data:
+    # Fix upstream to never return None
+    data = fetch()
+    if data is None:
+        raise DataNotFoundError()  # Explicit failure
+    return data
+
+def process(data: Data) -> Result:  # Type hint documents non-None
+    return real_process(data)
+```
+
+### Regression Test
+```python
+# Always add test for the exact bug
+def test_issue_123_uppercase_email_normalized():
+    """Regression: Issue #123 - uppercase email caused duplicate"""
+    user = create_user("USER@EXAMPLE.COM", "Test")
+    assert user.email == "user@example.com"
+```
+
+---
+
+## Decision Rules
+
+| Bug Type | First Step |
+|----------|------------|
+| Crash | Get traceback, reproduce |
+| Wrong output | Create minimal input |
+| Performance | Profile, find bottleneck |
+| Intermittent | Add extensive logging |
+| Security | Isolate, assess impact |
+
+---
+
+## Preferred Patterns
+
+```python
+# Debug context manager
+from contextlib import contextmanager
+
+@contextmanager
+def debug_context(name: str):
+    log.debug(f"{name}: start")
+    try:
+        yield
+    except Exception as e:
+        log.debug(f"{name}: error", error=str(e))
+        raise
+    else:
+        log.debug(f"{name}: success")
+
+with debug_context("process_order"):
+    result = process_order(order)
+```
+
+---
+
+## Avoid
+
+- Fixing without reproducing
+- Guessing instead of isolating
+- Fixing symptoms, not root cause
+- No regression test
+- Large changes to fix small bug
+
+---
+
+## Validation Considerations
+
+- Bug reproduced before fix
+- Fix verified with reproduction case
+- Regression test added
+- Related tests still pass
+- No similar bugs elsewhere (grep for pattern)
+
+---
+
+## Related Skills
+
+- `debugging/common_bugs.md`
+- `debugging/inspection_techniques.md`
+- `testing/regression_tests.md`
+- `generation/error_handling.md`