@booklib/skills 1.0.0 → 1.2.0

package/README.md

@@ -89,6 +89,7 @@ cp -r skills/effective-kotlin /path/to/project/.claude/skills/
 | [data-pipelines](./data-pipelines/) | Data pipeline practices from James Densmore's *Data Pipelines Pocket Reference* — ingestion, streaming, transformation, and orchestration |
 | [design-patterns](./design-patterns/) | Apply and review GoF design patterns from *Head First Design Patterns* — creational, structural, and behavioral patterns |
 | [domain-driven-design](./domain-driven-design/) | Design and review software using patterns from Eric Evans' *Domain-Driven Design* — tactical and strategic patterns, and Ubiquitous Language |
+| [effective-python](./effective-python-skill/) | Python best practices from Brett Slatkin's *Effective Python* (2nd Edition) — Pythonic thinking, functions, classes, concurrency, and testing |
 | [effective-java](./effective-java/) | Java best practices from Joshua Bloch's *Effective Java* (3rd Edition) — object creation, generics, enums, lambdas, and concurrency |
 | [effective-kotlin](./effective-kotlin/) | Best practices from Marcin Moskała's *Effective Kotlin* (2nd Ed) — safety, readability, reusability, and abstraction |
 | [kotlin-in-action](./kotlin-in-action/) | Practices from *Kotlin in Action* (2nd Ed) — functions, classes, lambdas, nullability, and coroutines |

package/effective-python-skill/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: effective-python
+description: Review existing Python code and write new Python code following the 90 best practices from "Effective Python" by Brett Slatkin (2nd Edition). Use when writing Python, reviewing Python code, or wanting idiomatic, Pythonic solutions.
+---
+
+# Effective Python Skill
+
+Apply the 90 items from Brett Slatkin's "Effective Python" (2nd Edition) to review existing code and write new Python code. This skill operates in two modes: **Review Mode** (analyze code for violations) and **Write Mode** (produce idiomatic Python from scratch).
+
+## Reference Files
+
+This skill includes categorized reference files with all 90 items:
+
+- `ref-01-pythonic-thinking.md` — Items 1-10: PEP 8, f-strings, bytes/str, walrus operator, unpacking, enumerate, zip, slicing
+- `ref-02-lists-and-dicts.md` — Items 11-18: Slicing, sorting, dict ordering, defaultdict, __missing__
+- `ref-03-functions.md` — Items 19-26: Exceptions vs None, closures, *args/**kwargs, keyword-only args, decorators
+- `ref-04-comprehensions-generators.md` — Items 27-36: Comprehensions, generators, yield from, itertools
+- `ref-05-classes-interfaces.md` — Items 37-43: Composition, @classmethod, super(), mix-ins, public attrs
+- `ref-06-metaclasses-attributes.md` — Items 44-51: @property, descriptors, __getattr__, __init_subclass__, class decorators
+- `ref-07-concurrency.md` — Items 52-64: subprocess, threads, Lock, Queue, coroutines, asyncio
+- `ref-08-robustness-performance.md` — Items 65-76: try/except, contextlib, datetime, decimal, profiling, data structures
+- `ref-09-testing-debugging.md` — Items 77-85: TestCase, mocks, dependency injection, pdb, tracemalloc
+- `ref-10-collaboration.md` — Items 86-90: Docstrings, packages, root exceptions, virtual environments
+
+## How to Use This Skill
+
+**Before responding**, read the relevant reference files based on the code's topic. For a general review, read all files. For targeted work (e.g., writing async code), read the specific reference (e.g., `ref-07-concurrency.md`).
+
+---
+
+## Mode 1: Code Review
+
+When the user asks you to **review** existing Python code, follow this process:
+
+### Step 1: Read Relevant References
+Determine which chapters apply to the code under review and read those reference files. If unsure, read all of them.
+
+### Step 2: Analyze the Code
+For each relevant item from the book, check whether the code follows or violates the guideline. Focus on:
+
+1. **Style and Idiom** (Items 1-10): Is it Pythonic? Does it use f-strings, unpacking, enumerate, zip properly?
+2. **Data Structures** (Items 11-18): Are lists and dicts used correctly? Is sorting done with key functions?
+3. **Function Design** (Items 19-26): Do functions raise exceptions instead of returning None? Are args well-structured?
+4. **Comprehensions & Generators** (Items 27-36): Are comprehensions preferred over map/filter? Are generators used for large sequences?
+5. **Class Design** (Items 37-43): Is composition preferred over deep nesting? Are mix-ins used correctly?
+6. **Metaclasses & Attributes** (Items 44-51): Are plain attributes used instead of getter/setter methods? Is @property used appropriately?
+7. **Concurrency** (Items 52-64): Are threads used only for I/O? Is asyncio structured correctly?
+8. **Robustness** (Items 65-76): Is error handling structured with try/except/else/finally? Are the right data structures chosen?
+9. **Testing** (Items 77-85): Are tests well-structured? Are mocks used appropriately?
+10. **Collaboration** (Items 86-90): Are docstrings present? Are APIs stable?
+
+### Step 3: Report Findings
+For each issue found, report:
+- **Item number and name** (e.g., "Item 4: Prefer Interpolated F-Strings")
+- **Location** in the code
+- **What's wrong** (the anti-pattern)
+- **How to fix it** (the Pythonic way)
+- **Priority**: Critical (bugs/correctness), Important (maintainability), Suggestion (style)
+
+### Step 4: Provide Fixed Code
+Offer a corrected version of the code with all issues addressed, with comments explaining each change.
+
+---
+
+## Mode 2: Writing New Code
+
+When the user asks you to **write** new Python code, follow these principles:
+
+### Always Apply These Core Practices
+
+1. **Follow PEP 8** — Use consistent naming (snake_case for functions/variables, PascalCase for classes). Use `pylint` and `black`-compatible style.
+
+2. **Use f-strings** for string formatting (Item 4). Never use % or .format() for simple cases.
+
+3. **Use unpacking** instead of indexing (Item 6). Prefer `first, second = my_list` over `my_list[0]`.
+
+4. **Use enumerate** instead of range(len(...)) (Item 7).
+
+5. **Use zip** to iterate over multiple lists in parallel (Item 8). Use `zip_longest` from itertools when lengths differ.
+
+6. **Avoid else blocks** after for/while loops (Item 9).
+
+7. **Use assignment expressions** (:= walrus operator) to reduce repetition when appropriate (Item 10).
+
+8. **Raise exceptions** instead of returning None for failure cases (Item 20).
+
+9. **Use keyword-only arguments** for clarity (Item 25). Use positional-only args to separate API from implementation (Item 25).
+
+10. **Use functools.wraps** on all decorators (Item 26).
+
+11. **Prefer comprehensions** over map/filter (Item 27). Keep them simple — no more than two expressions (Item 28).
+
+12. **Use generators** for large sequences instead of returning lists (Item 30).
+
+13. **Prefer composition** over deeply nested classes (Item 37).
+
+14. **Use @classmethod** for polymorphic constructors (Item 39).
+
+15. **Always call super().__init__** (Item 40).
+
+16. **Use plain attributes** instead of getter/setter methods. Use @property for special behavior (Item 44).
+
+17. **Use try/except/else/finally** structure correctly (Item 65).
+
+18. **Write docstrings** for every module, class, and function (Item 84).
+
+### Code Structure Template
+
+When writing new modules or classes, follow this structure:
+
+```python
+"""Module docstring describing purpose."""
+
+# Standard library imports
+# Third-party imports
+# Local imports
+
+# Module-level constants
+
+class MyClass:
+    """Class docstring describing purpose and usage.
+
+    Attributes:
+        attr_name: Description of attribute.
+    """
+
+    def __init__(self, param: type) -> None:
+        """Initialize with description of params."""
+        self.param = param  # Use public attributes (Item 42)
+
+    @classmethod
+    def from_alternative(cls, data):
+        """Alternative constructor (Item 39)."""
+        return cls(processed_data)
+
+    def method(self, arg: type) -> return_type:
+        """Method docstring.
+
+        Args:
+            arg: Description.
+
+        Returns:
+            Description of return value.
+
+        Raises:
+            ValueError: When arg is invalid (Item 20).
+        """
+        pass
+```
+
+### Concurrency Guidelines
+
+- Use `subprocess` for managing child processes (Item 52)
+- Use threads **only** for blocking I/O, never for parallelism (Item 53)
+- Use `threading.Lock` to prevent data races (Item 54)
+- Use `Queue` for coordinating work between threads (Item 55)
+- Use `asyncio` for highly concurrent I/O (Item 60)
+- Never mix blocking calls in async code (Item 62)
+
+### Testing Guidelines
+
+- Subclass `TestCase` and use `setUp`/`tearDown` (Item 78)
+- Use `unittest.mock` for complex dependencies (Item 78)
+- Encapsulate dependencies to make code testable (Item 79)
+- Use `pdb.set_trace()` or `breakpoint()` for debugging (Item 80)
+- Use `tracemalloc` for memory debugging (Item 81)
+
+---
+
+## Priority of Items by Impact
+
+When time is limited, focus on these highest-impact items first:
+
+### Critical (Correctness & Bugs)
+- Item 20: Raise exceptions instead of returning None
+- Item 53: Use threads for I/O only, not parallelism
+- Item 54: Use Lock to prevent data races
+- Item 40: Initialize parent classes with super()
+- Item 65: Use try/except/else/finally correctly
+- Item 73: Use datetime instead of time module for timezone handling
+
+### Important (Maintainability)
+- Item 1: Follow PEP 8 style
+- Item 4: Use f-strings
+- Item 19: Never unpack more than 3 variables
+- Item 25: Use keyword-only and positional-only arguments
+- Item 26: Use functools.wraps for decorators
+- Item 37: Compose classes instead of deep nesting
+- Item 42: Prefer public attributes over private
+- Item 44: Use plain attributes over getter/setter
+- Item 84: Write docstrings for all public APIs
+
+### Suggestions (Polish & Optimization)
+- Item 7: Use enumerate instead of range
+- Item 8: Use zip for parallel iteration
+- Item 10: Use walrus operator to reduce repetition
+- Item 27: Use comprehensions over map/filter
+- Item 30: Use generators for large sequences
+- Item 70: Profile before optimizing (cProfile)

package/effective-python-skill/ref-01-pythonic-thinking.md

@@ -0,0 +1,202 @@
+# Chapter 1: Pythonic Thinking (Items 1-10)
+
+## Item 1: Know Which Version of Python You're Using
+- Use `python3` explicitly, not `python`
+- Check version with `python3 --version` or `sys.version_info`
+- Python 2 is end-of-life; always target Python 3
+
+## Item 2: Follow the PEP 8 Style Guide
+**Whitespace:**
+- Use 4 spaces for indentation (never tabs)
+- Lines should be 79 characters or fewer
+- Continuations should be indented by 4 extra spaces
+- Put two blank lines before/after top-level functions and classes
+- One blank line between methods in a class
+
+**Naming:**
+- Functions, variables, attributes: `lowercase_underscore`
+- Protected instance attributes: `_leading_underscore`
+- Private instance attributes: `__double_leading_underscore`
+- Classes and exceptions: `CapitalizedWord`
+- Module-level constants: `ALL_CAPS`
+- Instance methods use `self` as first parameter; class methods use `cls`
+
+**Expressions & Statements:**
+- Use inline negation (`if a is not b`) instead of negating positive (`if not a is b`)
+- Don't check for empty containers with length (`if len(list) == 0`); use `if not list`
+- Use `if list` to check for non-empty
+- Avoid single-line `if`, `for`, `while`, `except`
+- Always use absolute imports, not relative
+- Put imports at top in order: stdlib, third-party, local
+
+**Tools:** Use `pylint` for static analysis, `black` for formatting.
+
+## Item 3: Know the Differences Between bytes and str
+- `bytes` contains raw unsigned 8-bit values; `str` contains Unicode code points
+- Use helper functions to convert between them:
+
+```python
+# BAD
+def to_str(data):
+    if isinstance(data, bytes):
+        return data.decode('utf-8')
+    return data
+
+# GOOD — be explicit about encoding
+def to_str(bytes_or_str):
+    if isinstance(bytes_or_str, bytes):
+        value = bytes_or_str.decode('utf-8')
+    else:
+        value = bytes_or_str
+    return value
+
+def to_bytes(bytes_or_str):
+    if isinstance(bytes_or_str, str):
+        value = bytes_or_str.encode('utf-8')
+    else:
+        value = bytes_or_str
+    return value
+```
+
+- Use `'rb'` and `'wb'` modes for binary file I/O
+- Specify encoding explicitly: `open(path, 'r', encoding='utf-8')`
+
+## Item 4: Prefer Interpolated F-Strings Over C-style Format Strings and str.format
+```python
+# BAD — C-style
+'Hello, %s. You are %d.' % (name, age)
+
+# BAD — str.format
+'Hello, {}. You are {}.'.format(name, age)
+
+# GOOD — f-string
+f'Hello, {name}. You are {age}.'
+
+# F-strings support expressions
+f'{key!r}: {value:.2f}'
+f'result: {some_func(x)}'
+
+# Multi-line f-strings
+f'{key:<10} = {value:.2f}'
+```
+
+## Item 5: Write Helper Functions Instead of Complex Expressions
+- If an expression is hard to read, move it to a helper function
+- Clarity over brevity: `if`/`else` is clearer than `or` for defaults
+
+```python
+# BAD
+values = query_string.get('red', [''])
+red = int(values[0]) if values[0] else 0
+
+# GOOD
+def get_first_int(values, key, default=0):
+    found = values.get(key, [''])
+    if found[0]:
+        return int(found[0])
+    return default
+
+red = get_first_int(values, 'red')
+```
+
+## Item 6: Prefer Multiple Assignment Unpacking Over Indexing
+```python
+# BAD
+item = ('Peanut Butter', 3.50)
+name = item[0]
+price = item[1]
+
+# GOOD
+name, price = item
+
+# Works with nested structures
+((name1, cal1), (name2, cal2)) = snacks
+
+# Use _ for unused values
+_, price = item
+
+# Swap without temp variable
+a, b = b, a
+```
+
+## Item 7: Prefer enumerate Over range
+```python
+# BAD
+for i in range(len(flavor_list)):
+    flavor = flavor_list[i]
+    print(f'{i + 1}: {flavor}')
+
+# GOOD
+for i, flavor in enumerate(flavor_list):
+    print(f'{i + 1}: {flavor}')
+
+# Start from a different index
+for i, flavor in enumerate(flavor_list, 1):
+    print(f'{i}: {flavor}')
+```
+
+## Item 8: Use zip to Process Iterators in Parallel
+```python
+# BAD
+for i in range(len(names)):
+    print(f'{names[i]}: {counts[i]}')
+
+# GOOD
+for name, count in zip(names, counts):
+    print(f'{name}: {count}')
+
+# When lengths differ, use zip_longest
+from itertools import zip_longest
+for name, count in zip_longest(names, counts, fillvalue=0):
+    print(f'{name}: {count}')
+```
+
+- `zip` truncates to shortest iterator (use `itertools.zip_longest` if needed)
+- zip is lazy — produces one tuple at a time
+
+## Item 9: Avoid else Blocks After for and while Loops
+- `else` on loops runs when the loop completes *without* `break`
+- This is counterintuitive and confuses readers
+- Instead, use a helper function with early return:
+
+```python
+# BAD — confusing else on loop
+for i in range(n):
+    if condition(i):
+        break
+else:
+    handle_no_break()
+
+# GOOD — helper function
+def find_match(n):
+    for i in range(n):
+        if condition(i):
+            return i
+    return None  # explicit "not found"
+
+result = find_match(n)
+if result is None:
+    handle_no_match()
+```
+
+## Item 10: Prevent Repetition with Assignment Expressions (Walrus Operator)
+```python
+# BAD — repeated call or extra variable
+count = fresh_fruit.get('lemon', 0)
+if count:
+    make_lemonade(count)
+
+# GOOD — walrus operator
+if count := fresh_fruit.get('lemon', 0):
+    make_lemonade(count)
+
+# Useful in while loops
+while chunk := f.read(8192):
+    process(chunk)
+
+# Useful in comprehensions
+result = [y for x in data if (y := f(x)) is not None]
+```
+
+- Use `:=` when you need to both assign and test a value
+- Don't overuse — only when it clearly reduces repetition

package/effective-python-skill/ref-02-lists-and-dicts.md

@@ -0,0 +1,146 @@
+# Chapter 2: Lists and Dictionaries (Items 11-18)
+
+## Item 11: Know How to Slice Sequences
+```python
+a = [1, 2, 3, 4, 5, 6, 7, 8]
+
+# Basic slicing
+a[:4]   # [1, 2, 3, 4] — first 4
+a[-3:]  # [6, 7, 8] — last 3
+a[3:5]  # [4, 5]
+
+# Don't use 0 for start or len for end
+a[:5]   # GOOD
+a[0:5]  # BAD — redundant 0
+
+# Slicing makes a new list (shallow copy)
+b = a[:]  # copy of a
+
+# Slice assignment replaces in place
+a[2:4] = [10, 11]  # can be different length
+```
+
+## Item 12: Avoid Striding and Slicing in a Single Expression
+```python
+# BAD — confusing stride + slice
+x = a[2::2]    # skip start, stride by 2
+x = a[-2::-2]  # reverse with stride
+
+# GOOD — separate steps
+y = a[::2]     # stride first
+z = y[1:3]     # then slice
+
+# Reverse a sequence
+x = a[::-1]    # OK for simple reversal, but avoid combining with slicing
+```
+
+## Item 13: Prefer Catch-All Unpacking Over Slicing
+```python
+# BAD — manual slicing
+oldest = ages[0]
+rest = ages[1:]
+
+# GOOD — starred expression
+oldest, *rest = ages
+oldest, second, *rest = ages
+first, *middle, last = ages
+
+# Works with any iterable
+it = iter(range(10))
+first, second, *rest = it
+```
+
+- Starred expressions always produce a list (may be empty)
+- Cannot have more than one starred expression in a single assignment
+
+## Item 14: Sort by Complex Criteria Using the key Parameter
+```python
+# Sort with key function
+tools = [Tool('drill', 4), Tool('saw', 2)]
+tools.sort(key=lambda x: x.weight)
+
+# Multiple criteria — use tuple
+tools.sort(key=lambda x: (x.name, x.weight))
+
+# Reverse one criterion using negation (numeric)
+tools.sort(key=lambda x: (-x.weight, x.name))
+
+# For non-numeric reverse, use multiple sort passes (stable sort)
+tools.sort(key=lambda x: x.name)             # secondary first
+tools.sort(key=lambda x: x.weight, reverse=True)  # primary last
+```
+
+- Python sort is stable — equal elements maintain relative order
+- Use `operator.attrgetter` for attribute access as key
+
+## Item 15: Be Cautious When Relying on dict Insertion Order
+- Since Python 3.7, dicts maintain insertion order
+- But don't assume all dict-like objects do (e.g., custom classes)
+- Use explicit ordering when you need it:
+
+```python
+# If order matters and you're creating a protocol
+class MyDB:
+    def __init__(self):
+        self._data = {}
+
+    # Be explicit that order is part of the contract
+```
+
+- For **kwargs, insertion order is preserved
+- Standard dict methods (keys, values, items) follow insertion order
+
+## Item 16: Prefer get Over in and KeyError to Handle Missing Dictionary Keys
+```python
+# BAD — check then access
+if key in counters:
+    count = counters[key]
+else:
+    count = 0
+counters[key] = count + 1
+
+# BAD — try/except
+try:
+    count = counters[key]
+except KeyError:
+    count = 0
+counters[key] = count + 1
+
+# GOOD — use get
+count = counters.get(key, 0)
+counters[key] = count + 1
+
+# For complex default values, consider setdefault or defaultdict
+```
+
+## Item 17: Prefer defaultdict Over setdefault to Handle Missing Items in Internal State
+```python
+from collections import defaultdict
+
+# BAD — setdefault (confusing API)
+visits = {}
+visits.setdefault('France', []).append('Paris')
+
+# GOOD — defaultdict
+visits = defaultdict(list)
+visits['France'].append('Paris')
+```
+
+- `defaultdict` is clearer when you control the dict creation
+- `setdefault` is better when you don't control the dict (external data)
+
+## Item 18: Know How to Construct Key-Dependent Default Values with __missing__
+```python
+# When the default value depends on the key, use __missing__
+class Pictures(dict):
+    def __missing__(self, key):
+        value = open_picture(key)  # default depends on key
+        self[key] = value
+        return value
+
+pictures = Pictures()
+handle = pictures[path]  # calls __missing__ if path not present
+```
+
+- Use when `defaultdict` isn't sufficient (default factory doesn't receive the key)
+- `__missing__` is called by `__getitem__` when key is not found