@booklib/skills 1.0.0 → 1.3.0

package/effective-python/references/practices-catalog.md

@@ -0,0 +1,483 @@
+# Effective Python — Practices Catalog
+
+The 20 most impactful items from Brett Slatkin's *Effective Python* (2nd Edition),
+each with the problem it solves, the Pythonic solution, and a before/after code example.
+
+---
+
+## Item 4 — Prefer Interpolated F-Strings Over C-style Format Strings and str.format
+
+**Problem:** `%` format strings are verbose and error-prone with multiple values. `.format()` is better but still cluttered with braces and positional indices. Both separate the format template from the values being formatted.
+
+**Solution:** Use f-strings — they embed expressions directly in string literals, are more readable, and support the full power of format specifiers inline.
+
+```python
+# Before
+name, age = "Alice", 30
+msg = "User %s is %d years old" % (name, age)
+msg = "User {} is {} years old".format(name, age)
+
+# After
+msg = f"User {name} is {age} years old"
+msg = f"Pi to 4 places: {3.14159:.4f}"
+```
+
+---
+
+## Item 6 — Prefer Multiple Assignment Unpacking Over Indexing
+
+**Problem:** Accessing sequence elements by index (`pair[0]`, `pair[1]`) is opaque — the reader must know what position 0 or 1 represents. It is verbose and error-prone when indices change.
+
+**Solution:** Unpack sequences into named variables in a single assignment. The names document meaning; the structure enforces the expected shape.
+
+```python
+# Before
+item = ("Alice", 25, "engineer")
+name = item[0]
+age = item[1]
+role = item[2]
+
+# After
+name, age, role = item
+first, *rest = items          # catch-all unpacking
+head, *middle, tail = items   # discard the middle
+```
+
+---
+
+## Item 7 — Prefer enumerate Over range for Indexed Iteration
+
+**Problem:** `for i in range(len(sequence))` is verbose and indirect. It requires manually indexing the sequence on each iteration, which is error-prone and harder to read.
+
+**Solution:** Use `enumerate(sequence)` to get both the index and value together. Pass a `start` argument to control the counter's starting value.
+
+```python
+# Before
+flavors = ["vanilla", "chocolate", "strawberry"]
+for i in range(len(flavors)):
+    print(f"{i}: {flavors[i]}")
+
+# After
+for i, flavor in enumerate(flavors, start=1):
+    print(f"{i}: {flavor}")
+```
+
+---
+
+## Item 8 — Use zip to Process Iterators in Parallel
+
+**Problem:** Iterating over two related sequences using a shared index is verbose and fragile. If the sequences have different lengths, off-by-one bugs or IndexError occur silently.
+
+**Solution:** Use `zip()` to pair up items from multiple sequences. Use `itertools.zip_longest()` when sequences may have different lengths and you want to handle all items.
+
+```python
+# Before
+for i in range(len(names)):
+    print(f"{names[i]}: {scores[i]}")
+
+# After
+from itertools import zip_longest
+for name, score in zip(names, scores):
+    print(f"{name}: {score}")
+for name, score in zip_longest(names, scores, fillvalue=0):
+    print(f"{name}: {score}")
+```
+
+---
+
+## Item 20 — Prefer Raising Exceptions to Returning None
+
+**Problem:** Functions that return `None` to signal failure require callers to check the return value — and if they forget, the `None` silently propagates until it crashes somewhere unrelated. `None` and `0`, `""`, `[]` all evaluate as falsy, making the check ambiguous.
+
+**Solution:** Raise an exception for failure cases. Callers that want to handle the failure use `try/except`; callers that don't care let the exception propagate. The failure is never silently ignored.
+
+```python
+# Before
+def parse_ratio(a, b):
+    try:
+        return a / b
+    except ZeroDivisionError:
+        return None  # caller may forget to check
+
+result = parse_ratio(5, 0)
+if result:  # BUG: 0.0 is also falsy!
+    print(result)
+
+# After
+def parse_ratio(a, b):
+    try:
+        return a / b
+    except ZeroDivisionError:
+        raise ValueError(f"parse_ratio({a}, {b}): b must be non-zero")
+```
+
+---
+
+## Item 24 — Use None and Docstrings to Specify Dynamic Default Arguments
+
+**Problem:** Using a mutable object (list, dict) or dynamic expression (`datetime.now()`) as a default argument value is evaluated once at function definition time, not at call time. All callers share the same default object, leading to subtle, hard-to-find bugs.
+
+**Solution:** Use `None` as the default and initialize the mutable/dynamic value inside the function body. Document the actual default in the docstring.
+
+```python
+# Before — BUG: all calls share the same list
+def log(message, when=datetime.now(), tags=[]):
+    tags.append("debug")  # mutates the shared default!
+    print(f"{when}: {message} {tags}")
+
+# After
+def log(message, when=None, tags=None):
+    """Log a message with a timestamp.
+    
+    Args:
+        when: Timestamp for the log entry. Defaults to now.
+        tags: List of tags. Defaults to an empty list.
+    """
+    if when is None:
+        when = datetime.now()
+    if tags is None:
+        tags = []
+    tags.append("debug")
+    print(f"{when}: {message} {tags}")
+```
+
+---
+
+## Item 25 — Enforce Clarity with Keyword-Only and Positional-Only Arguments
+
+**Problem:** Functions with multiple boolean or configuration parameters are ambiguous at the call site. `safe_divide(1.0, 5.0, True, False)` — what do `True` and `False` mean? Callers can pass args in the wrong order and get no error.
+
+**Solution:** Use keyword-only arguments (after `*` or `*args`) to force callers to name certain parameters. Use positional-only arguments (before `/`) to prevent callers from naming implementation details.
+
+```python
+# Before — ambiguous call
+def safe_divide(number, divisor, ignore_overflow, ignore_zero):
+    ...
+safe_divide(1.0, 5.0, True, False)  # what does True mean?
+
+# After — keyword-only enforces clarity
+def safe_divide(number, divisor, *, ignore_overflow=False, ignore_zero=False):
+    ...
+safe_divide(1.0, 5.0, ignore_zero=True)  # clear at the call site
+```
+
+---
+
+## Item 26 — Define Function Decorators with functools.wraps
+
+**Problem:** A decorator replaces the wrapped function with a new wrapper function. Without `functools.wraps`, the wrapped function loses its `__name__`, `__doc__`, `__module__`, and other metadata. This breaks debugging, documentation tools, and introspection.
+
+**Solution:** Apply `@functools.wraps(func)` to the inner wrapper function in every decorator.
+
+```python
+# Before — metadata lost
+def trace(func):
+    def wrapper(*args, **kwargs):
+        result = func(*args, **kwargs)
+        return result
+    return wrapper  # wrapper.__name__ is "wrapper", not "fibonacci"
+
+# After — metadata preserved
+import functools
+def trace(func):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        result = func(*args, **kwargs)
+        return result
+    return wrapper  # wrapper.__name__ is "fibonacci"
+```
+
+---
+
+## Item 27 — Use Comprehensions Instead of map and filter
+
+**Problem:** `map()` and `filter()` with `lambda` are verbose and require the reader to mentally parse the lambda, the outer function, and the argument order. They return iterators that must be explicitly materialized.
+
+**Solution:** Use list, dict, and set comprehensions. They are more readable, support conditions inline, and work naturally for all collection types.
+
+```python
+# Before
+squares_of_evens = list(map(lambda x: x**2, filter(lambda x: x % 2 == 0, range(10))))
+
+# After
+squares_of_evens = [x**2 for x in range(10) if x % 2 == 0]
+
+# Dict comprehension
+square_map = {x: x**2 for x in range(10)}
+
+# Set comprehension
+unique_lengths = {len(name) for name in names}
+```
+
+---
+
+## Item 30 — Consider Generators Instead of Returning Lists
+
+**Problem:** A function that builds and returns a list must hold the entire result in memory before the first item is available to the caller. For large sequences, this wastes memory and delays the first result.
+
+**Solution:** Use `yield` to make the function a generator. The caller receives items one at a time; no full list is ever built in memory. The generator is lazy — it computes only what the caller consumes.
+
+```python
+# Before — entire list built in memory
+def index_words(text):
+    result = []
+    for i, char in enumerate(text):
+        if i == 0 or char == " ":
+            result.append(i)
+    return result
+
+# After — generator, one item at a time
+def index_words(text):
+    for i, char in enumerate(text):
+        if i == 0 or char == " ":
+            yield i
+```
+
+---
+
+## Item 37 — Compose Classes Instead of Nesting Many Levels of Built-in Types
+
+**Problem:** Deeply nested dicts, lists, and tuples (e.g., a dict of dicts of lists of tuples) are hard to read, document, and extend. Adding a new field requires updating every place that constructs or unpacks the data.
+
+**Solution:** When a structure exceeds two levels of nesting, define small helper classes or use `collections.namedtuple` / `dataclasses.dataclass`. This provides named access, documentation, and the ability to add methods later.
+
+```python
+# Before — opaque nested dict
+grades = {"Alice": {"Math": [90, 88], "English": [75, 82]}}
+
+# After — self-documenting classes
+from dataclasses import dataclass, field
+@dataclass
+class Subject:
+    name: str
+    scores: list = field(default_factory=list)
+    def average(self): return sum(self.scores) / len(self.scores)
+
+@dataclass
+class Student:
+    name: str
+    subjects: dict = field(default_factory=dict)
+```
+
+---
+
+## Item 40 — Initialize Parent Classes with super()
+
+**Problem:** Calling `ParentClass.__init__(self)` directly breaks with multiple inheritance and the Method Resolution Order (MRO). It can call a parent's `__init__` twice or miss it entirely when the class hierarchy is diamond-shaped.
+
+**Solution:** Always use `super().__init__()` without arguments. Python resolves the correct class to call based on the MRO, making multiple inheritance predictable.
+
+```python
+# Before — fragile with multiple inheritance
+class MyChild(ParentA, ParentB):
+    def __init__(self):
+        ParentA.__init__(self)  # may call Base twice in diamond inheritance
+        ParentB.__init__(self)
+
+# After — MRO-correct
+class MyChild(ParentA, ParentB):
+    def __init__(self):
+        super().__init__()  # follows MRO, each parent called exactly once
+```
+
+---
+
+## Item 44 — Use Plain Attributes Instead of Get and Set Methods
+
+**Problem:** Java-style getter/setter method pairs (`get_voltage()`, `set_voltage()`) are verbose and un-Pythonic. They add noise without benefit when no special behavior is needed.
+
+**Solution:** Use plain public attributes by default. If you later need validation, caching, or computed values, migrate to `@property` without changing the external interface.
+
+```python
+# Before — Java-style
+class OldResistor:
+    def __init__(self, ohms):
+        self._ohms = ohms
+    def get_ohms(self): return self._ohms
+    def set_ohms(self, ohms): self._ohms = ohms
+
+# After — plain attribute first
+class Resistor:
+    def __init__(self, ohms):
+        self.ohms = ohms  # plain attribute; add @property later if needed
+        self.voltage = 0
+        self.current = 0
+```
+
+---
+
+## Item 45 — Consider @property Instead of Refactoring Attributes
+
+**Problem:** Once a class is published with a plain attribute, changing it to a method breaks all callers. If behavior (validation, computation, side effects) is needed on attribute access, the API must change.
+
+**Solution:** Use `@property` to add behavior to attribute access while keeping the same attribute-style interface. The caller never knows whether it's a stored value or a computed one.
+
+```python
+# Before — breaks callers if changed to a method
+class Circle:
+    def __init__(self, radius):
+        self.radius = radius
+    def area(self):  # caller must use circle.area()
+        return 3.14 * self.radius ** 2
+
+# After — area looks like an attribute
+class Circle:
+    def __init__(self, radius):
+        self.radius = radius
+    @property
+    def area(self):     # caller uses circle.area (no parentheses)
+        return 3.14 * self.radius ** 2
+```
+
+---
+
+## Item 53 — Use Threads for Blocking I/O, Avoid for Parallelism
+
+**Problem:** Python's Global Interpreter Lock (GIL) prevents multiple threads from executing Python bytecode simultaneously. Using threads to parallelize CPU-bound work achieves no speedup and adds complexity.
+
+**Solution:** Use threads only for blocking I/O (network calls, disk reads) where threads wait idle most of the time. Use `multiprocessing` or `concurrent.futures.ProcessPoolExecutor` for CPU-bound parallelism.
+
+```python
+# CPU-bound — threads give no benefit (GIL)
+from concurrent.futures import ProcessPoolExecutor
+def factorize(number): ...  # CPU work
+with ProcessPoolExecutor() as pool:
+    results = list(pool.map(factorize, numbers))
+
+# I/O-bound — threads work well
+from concurrent.futures import ThreadPoolExecutor
+def fetch_url(url): ...  # blocking network I/O
+with ThreadPoolExecutor(max_workers=10) as pool:
+    results = list(pool.map(fetch_url, urls))
+```
+
+---
+
+## Item 54 — Use Lock to Prevent Data Races in Threads
+
+**Problem:** When multiple threads read and write shared mutable state without synchronization, the operations interleave unpredictably. The GIL does not protect against data races at the level of compound operations like `counter += 1`.
+
+**Solution:** Use `threading.Lock` to protect all accesses to shared mutable state. Acquire the lock before reading or writing, release it after. Use `with lock:` for automatic release even on exceptions.
+
+```python
+# Before — data race: final count is unpredictable
+counter = 0
+def increment():
+    global counter
+    counter += 1  # not atomic: read, add, write — can interleave
+
+# After — Lock prevents interleaving
+import threading
+lock = threading.Lock()
+counter = 0
+def increment():
+    global counter
+    with lock:
+        counter += 1
+```
+
+---
+
+## Item 65 — Take Advantage of Each Block in try/except/else/finally
+
+**Problem:** Developers often use `try/except` with all code inside `try`, catching exceptions that were not intended to be caught. The `else` and `finally` clauses are underused.
+
+**Solution:** Use the full four-part structure: `try` for only the risky operation, `except` for specific exceptions, `else` for code that runs only on success, `finally` for cleanup that always runs.
+
+```python
+# Before — too broad, may catch unexpected exceptions
+try:
+    data = json.loads(text)
+    process(data)         # this exception is caught too!
+    save(data)
+except ValueError:
+    log("Invalid JSON")
+
+# After — precise structure
+try:
+    data = json.loads(text)  # only the risky part
+except ValueError as e:
+    log(f"Invalid JSON: {e}")
+else:
+    process(data)            # runs only if no exception
+    save(data)
+finally:
+    cleanup()                # always runs
+```
+
+---
+
+## Item 78 — Use TestCase Subclasses for Tests
+
+**Problem:** Writing tests as standalone functions without a `TestCase` class misses built-in helpers: `setUp`/`tearDown` for fixtures, `subTest` for variations, and assertion methods like `assertRaises`, `assertEqual`, `assertAlmostEqual` that produce clear failure messages.
+
+**Solution:** Subclass `unittest.TestCase`. Use `setUp` for common setup and `tearDown` for cleanup. Use `subTest` to run the same test with multiple inputs.
+
+```python
+# After — structured TestCase
+import unittest
+class TestMyFunction(unittest.TestCase):
+    def setUp(self):
+        self.db = FakeDatabase()
+    def tearDown(self):
+        self.db.close()
+    def test_normal_case(self):
+        self.assertEqual(my_function(self.db, 1), "expected")
+    def test_multiple_inputs(self):
+        cases = [(1, "a"), (2, "b"), (3, "c")]
+        for inp, expected in cases:
+            with self.subTest(inp=inp):
+                self.assertEqual(my_function(self.db, inp), expected)
+```
+
+---
+
+## Item 80 — Consider Interactive Debugging with pdb
+
+**Problem:** Adding `print()` statements to debug code produces cluttered output, requires multiple edit-run cycles, and must be cleaned up afterward. It provides no way to interactively explore state.
+
+**Solution:** Use `breakpoint()` (Python 3.7+) to drop into the interactive pdb debugger at a specific line. Step through code, inspect variables, call functions, and modify state interactively. Remove the breakpoint when done.
+
+```python
+# Before — print debugging
+def complex_function(data):
+    print(f"DEBUG: data={data}")  # must be cleaned up
+    result = transform(data)
+    print(f"DEBUG: result={result}")
+    return result
+
+# After — interactive debugger
+def complex_function(data):
+    breakpoint()  # drops into pdb; type 'n' (next), 's' (step), 'p var' (print)
+    result = transform(data)
+    return result
+```
+
+---
+
+## Item 84 — Write Docstrings for Every Function, Class, and Module
+
+**Problem:** Functions and classes without docstrings force readers to read the implementation to understand the contract. Automated documentation tools (`pydoc`, Sphinx) produce empty or useless output.
+
+**Solution:** Write a docstring for every public module, class, and function. Describe what it does, its arguments, return value, and any exceptions it raises. Use the first line as a one-sentence summary.
+
+```python
+# Before — no documentation
+def find_anagrams(word, candidates):
+    word_letters = Counter(word.lower())
+    return [c for c in candidates if Counter(c.lower()) == word_letters]
+
+# After — documented contract
+def find_anagrams(word, candidates):
+    """Find all anagrams of word in the candidates list.
+    
+    Args:
+        word: The word to find anagrams for. Case-insensitive.
+        candidates: Sequence of words to search.
+    
+    Returns:
+        List of strings from candidates that are anagrams of word.
+    """
+    word_letters = Counter(word.lower())
+    return [c for c in candidates if Counter(c.lower()) == word_letters]
+```

package/effective-python/references/review-checklist.md

@@ -0,0 +1,190 @@
+# Effective Python — Code Review Checklist
+
+Systematic checklist for reviewing Python code against the 90 best practices from
+*Effective Python: 90 Specific Ways to Write Better Python* (2nd Edition) by Brett Slatkin.
+
+---
+
+## Chapter 1 — Pythonic Thinking (Items 1–10)
+
+### Style and Idiom
+- [ ] **Item 1 — Python version** — Is the code targeting a current, supported Python version? Are any version-specific compatibility shims present that can be removed?
+- [ ] **Item 2 — PEP 8 style** — Does the code follow PEP 8? snake_case for functions/variables, PascalCase for classes, UPPER_CASE for module-level constants, 4-space indentation, 79-character lines?
+- [ ] **Item 3 — bytes vs. str** — Is the code clear about whether it's operating on `bytes` or `str`? Are encoding/decoding boundaries explicit? Is `open()` called with the correct mode (`'b'` vs. `'t'`)?
+
+### String Formatting
+- [ ] **Item 4 — f-strings** — Are f-strings used instead of `%` formatting or `.format()`? Is every formatted string using the simplest, most readable form available?
+
+### Data Unpacking
+- [ ] **Item 5 — Helper functions over complex expressions** — Are complex multi-step expressions broken into helper functions with descriptive names?
+- [ ] **Item 6 — Unpacking instead of indexing** — Are sequences unpacked directly (`first, second = pair`) instead of accessed by index (`pair[0]`, `pair[1]`)?
+- [ ] **Item 7 — enumerate instead of range** — Is `enumerate(sequence)` used instead of `range(len(sequence))` when both the index and value are needed?
+- [ ] **Item 8 — zip for parallel iteration** — Is `zip()` used to iterate over multiple sequences in parallel instead of indexing? Is `itertools.zip_longest` used when sequence lengths might differ?
+
+### Control Flow
+- [ ] **Item 9 — No else after for/while** — Are `else` blocks after `for` or `while` loops absent? This construct is confusing — use a flag variable or `break` + check instead.
+- [ ] **Item 10 — Walrus operator** — Is `:=` used to reduce redundant expressions where appropriate (e.g., assigning and testing in the same expression in a `while` or `if`)? Is it avoided where it would reduce clarity?
+
+---
+
+## Chapter 2 — Lists and Dicts (Items 11–18)
+
+### Sequence Operations
+- [ ] **Item 11 — Slicing** — Is slicing used idiomatically? Are start/end omitted when slicing from the beginning or to the end (`a[:5]`, `a[3:]`)? Is stride-slicing (`a[::2]`) with start/end avoided in favor of clarity?
+- [ ] **Item 12 — No start, stop, stride together** — Is `a[2::2]` or `a[:-1:2]` avoided in favor of two separate operations? Combining start, stop, and stride in one slice is hard to read.
+- [ ] **Item 13 — Catch-all unpacking** — Is starred unpacking (`first, *rest = items`) used instead of slicing for splitting sequences? Is `*_` used to discard unwanted items cleanly?
+
+### Sorting
+- [ ] **Item 14 — Sort with key parameter** — Are `sort()` and `sorted()` called with a `key=` function rather than `cmp=` or manual tuple sorting hacks?
+- [ ] **Item 15 — Sorting by multiple criteria** — When sorting by multiple fields in different directions, is `key=` with a tuple used, combined with `reverse=True` where needed, or multiple stable sorts applied in reverse priority order?
+
+### Dicts
+- [ ] **Item 16 — dict.get with default** — Is `dict.get(key, default)` used instead of checking `key in dict` before accessing? Are `setdefault` or `defaultdict` used for dict initialization patterns?
+- [ ] **Item 17 — defaultdict for internal state** — Is `collections.defaultdict` used for dicts where missing keys should be initialized automatically? Is `__missing__` used for more complex initialization logic?
+- [ ] **Item 18 — __missing__ for custom defaults** — When `defaultdict` is insufficient (e.g., default value depends on the key), is `__missing__` implemented on a `dict` subclass?
+
+---
+
+## Chapter 3 — Functions (Items 19–26)
+
+### Return Values and Errors
+- [ ] **Item 19 — Never unpack more than 3 variables** — Does any function return a tuple of more than 3 elements for unpacking? Use a `namedtuple` or small class instead.
+- [ ] **Item 20 — Raise exceptions instead of returning None** — Do functions raise exceptions for failure cases instead of returning `None`? Is `None` used only to mean "no value" — not "error"?
+
+### Closures and Scoping
+- [ ] **Item 21 — Closures and variable scope** — Do closures reference variables from the enclosing scope correctly? Is `nonlocal` used when a closure must modify an enclosing variable?
+- [ ] **Item 22 — Variable positional arguments with *args** — When a function accepts a variable number of positional args, is `*args` used? Is the caller passing generators directly into `*args` functions (risky — exhausts the generator)?
+
+### Function Arguments
+- [ ] **Item 23 — Keyword arguments** — Are functions that accept many arguments using keyword arguments for clarity at the call site?
+- [ ] **Item 24 — None for dynamic defaults** — Are mutable objects or dynamic values (lists, dicts, `datetime.now()`) never used as default argument values? Is `None` used as the default with a `if param is None: param = []` pattern?
+- [ ] **Item 25 — Keyword-only and positional-only arguments** — Are ambiguous boolean or configuration arguments declared keyword-only (after `*`)? Is the public/private boundary of an API enforced with positional-only args (before `/`)?
+
+### Decorators
+- [ ] **Item 26 — functools.wraps on all decorators** — Does every decorator use `@functools.wraps(func)` to preserve the wrapped function's `__name__`, `__doc__`, and other metadata?
+
+---
+
+## Chapter 4 — Comprehensions and Generators (Items 27–36)
+
+### Comprehensions
+- [ ] **Item 27 — Comprehensions over map/filter** — Are list/dict/set comprehensions used instead of `map()` and `filter()` with `lambda`? Comprehensions are more readable.
+- [ ] **Item 28 — No more than two expressions** — Do all comprehensions contain at most two expressions (e.g., one loop and one condition)? Comprehensions with three or more expressions are harder to read than a plain loop.
+- [ ] **Item 29 — No walrus in comprehensions for leaking** — Is `:=` in comprehensions used carefully? Walrus operator assignments in comprehensions can leak scope in unexpected ways.
+- [ ] **Item 30 — Generators instead of lists** — When a function produces a sequence for a caller to iterate, does it use `yield` instead of building and returning a list? Does it avoid holding the entire sequence in memory?
+
+### Generators and Iterators
+- [ ] **Item 31 — Aware of single-iteration behavior** — Does code that iterates over an iterator do so only once? Is a container (list, tuple) used when multiple iterations are needed?
+- [ ] **Item 32 — Iterator protocol** — When implementing a custom iterable, does the class implement `__iter__` returning `self` and `__next__`? Or does `__iter__` return a generator?
+- [ ] **Item 33 — yield from for delegation** — Does generator code that delegates to another iterator use `yield from` instead of a manual `for` loop with `yield`?
+- [ ] **Item 34 — send for generator communication** — If a generator must receive values from the caller, is `.send()` used? Is the protocol clear and documented?
+- [ ] **Item 35 — throw and close on generators** — Are `generator.throw()` and `generator.close()` used for error injection and cleanup when needed?
+- [ ] **Item 36 — itertools for complex iteration** — Are `itertools` functions (`chain`, `islice`, `tee`, `zip_longest`, `product`, `permutations`, `combinations`, `groupby`) used instead of hand-rolled equivalents?
+
+---
+
+## Chapter 5 — Classes and Interfaces (Items 37–43)
+
+### Class Design
+- [ ] **Item 37 — Compose classes instead of deep nesting** — Are deeply nested dicts/lists/tuples replaced with small helper classes or `namedtuple`/`dataclass`? Is composition preferred over inheritance?
+- [ ] **Item 38 — Simple interfaces with functions** — When a simple callback interface is needed, is a plain function (or callable object) accepted instead of defining a single-method interface class?
+- [ ] **Item 39 — @classmethod for polymorphic construction** — Are alternative constructors implemented as `@classmethod` methods rather than freestanding functions or `__init__` overloads?
+- [ ] **Item 40 — super().__init__() always called** — Does every class that inherits from another call `super().__init__()` in its own `__init__`? Is `super()` used without arguments (Python 3 style)?
+
+### Mix-ins and Attributes
+- [ ] **Item 41 — Mix-ins for reusable behavior** — Are mix-ins used for reusable behavior that should be composed into multiple classes? Do mix-ins avoid `__init__` and instance state?
+- [ ] **Item 42 — Public attributes over private** — Are attributes defined as public (`self.value`) by default? Is `__private` (name-mangled) used only when deliberate subclass protection is needed? Is `_protected` used to signal "internal use" conventionally?
+- [ ] **Item 43 — Inherit from collections.abc** — When defining a custom container type (sequence, mapping, set), does the class inherit from the appropriate `collections.abc` abstract base class?
+
+---
+
+## Chapter 6 — Metaclasses and Attributes (Items 44–51)
+
+### Properties and Descriptors
+- [ ] **Item 44 — Plain attributes over getter/setter** — Are plain public attributes used instead of getter/setter method pairs? Java-style `get_value()`/`set_value()` methods are un-Pythonic.
+- [ ] **Item 45 — @property for special behavior** — When an attribute access needs validation, lazy computation, or side effects, is `@property` used? Does the getter avoid slow computation or surprising side effects?
+- [ ] **Item 46 — @property.setter validates** — Do property setters validate input before assigning? Do setters raise `ValueError` for invalid input rather than silently accepting bad values?
+- [ ] **Item 47 — Descriptors for reusable @property logic** — When the same `@property` logic must apply to multiple attributes or multiple classes, is a descriptor class used instead of repeating the property code?
+
+### Metaclasses and Dynamic Attributes
+- [ ] **Item 48 — __getattr__, __getattribute__, __setattr__** — Is `__getattr__` used for lazy attribute initialization (called only when attribute is missing)? Is `__getattribute__` avoided unless interception of all attribute access is genuinely needed?
+- [ ] **Item 49 — __init_subclass__ for subclass validation** — When a base class needs to validate or register all its subclasses at class definition time, is `__init_subclass__` used instead of a metaclass?
+- [ ] **Item 50 — __set_name__ on descriptors** — Do descriptors use `__set_name__` to learn the attribute name they are assigned to, rather than requiring the name to be passed explicitly?
+- [ ] **Item 51 — Class decorators over metaclasses** — When class-level transformation is needed, is a class decorator used rather than a metaclass? Metaclasses should be a last resort.
+
+---
+
+## Chapter 7 — Concurrency and Parallelism (Items 52–64)
+
+### Processes and Threads
+- [ ] **Item 52 — subprocess for child processes** — Are child processes managed through `subprocess.run()` or `Popen` rather than `os.system()` or `os.popen()`?
+- [ ] **Item 53 — Threads only for I/O** — Is the `threading` module used only for blocking I/O concurrency, never for CPU parallelism? Is `multiprocessing` or `concurrent.futures.ProcessPoolExecutor` used for CPU-bound work?
+- [ ] **Item 54 — Lock for thread safety** — Is `threading.Lock` (or `RLock`) used to protect all shared mutable state accessed by multiple threads?
+- [ ] **Item 55 — Queue for thread coordination** — Is `queue.Queue` used for passing work and results between producer and consumer threads instead of shared mutable lists?
+
+### Coroutines and asyncio
+- [ ] **Item 60 — Coroutines for high-concurrency I/O** — Is `asyncio` used for highly concurrent I/O instead of threads when many simultaneous connections are needed?
+- [ ] **Item 61 — Blocking I/O never in async** — Does all `async` code use `await` for I/O? Are blocking calls (`requests.get`, `time.sleep`, file reads without `aiofiles`) absent from `async def` functions?
+- [ ] **Item 62 — asyncio.run at the entry point** — Is `asyncio.run()` used to start the event loop rather than `loop.run_until_complete()`?
+- [ ] **Item 63 — asyncio.gather for concurrent tasks** — When multiple coroutines should run concurrently, is `asyncio.gather()` or `asyncio.create_task()` used instead of awaiting them sequentially?
+
+---
+
+## Chapter 8 — Robustness and Performance (Items 65–79)
+
+### Error Handling
+- [ ] **Item 65 — try/except/else/finally structure** — Does error handling use the full `try/except/else/finally` structure correctly? Is `else` used for code that runs only when no exception is raised? Is `finally` used for cleanup?
+- [ ] **Item 66 — Reraise with raise** — When catching and reraising exceptions, is bare `raise` used to preserve the original traceback, rather than `raise e` which replaces it?
+- [ ] **Item 67 — Exception chaining** — When raising a new exception in response to a caught one, is `raise NewException(...) from original` used to preserve the chain?
+- [ ] **Item 73 — datetime for timezone handling** — Is `datetime` (with `pytz` or `zoneinfo`) used for timezone-aware operations instead of the `time` module?
+
+### Data Structures and Performance
+- [ ] **Item 70 — Profile before optimizing** — Is any performance optimization justified by profiling output (`cProfile`, `timeit`) rather than intuition?
+- [ ] **Item 71 — Prefer deque for FIFO** — Is `collections.deque` used for queues needing efficient append and pop from both ends, rather than a `list` (which makes `list.pop(0)` O(n))?
+- [ ] **Item 72 — Consider bisect for sorted sequences** — Is `bisect.bisect_left` / `bisect.insort` used for efficient insertion and search in sorted sequences rather than a linear scan?
+- [ ] **Item 73 — heapq for priority queues** — Is `heapq` used for priority queue operations rather than re-sorting a list on every insertion?
+- [ ] **Item 74 — Avoid copying on each iteration** — Are large data copies inside loops avoided? Is `memoryview` used for zero-copy slicing of bytes objects?
+
+---
+
+## Chapter 9 — Testing and Debugging (Items 80–85)
+
+### Testing
+- [ ] **Item 78 — TestCase and subTest** — Are tests structured as `unittest.TestCase` subclasses with `setUp`/`tearDown`? Is `self.subTest()` used to run variations within a single test method?
+- [ ] **Item 79 — Mocks for complex dependencies** — Are external dependencies (network, filesystem, databases, time) mocked using `unittest.mock.Mock` or `MagicMock` in tests?
+- [ ] **Item 80 — Encapsulate dependencies** — Is code structured so dependencies can be injected (passed as arguments or set as attributes) rather than hardcoded? Does testability drive class design?
+
+### Debugging
+- [ ] **Item 81 — pdb for debugging** — Is `breakpoint()` (Python 3.7+) used for interactive debugging rather than scatter-gunning print statements?
+- [ ] **Item 82 — tracemalloc for memory** — Is `tracemalloc` used to identify the source of unexpected memory growth rather than guessing?
+
+---
+
+## Chapter 10 — Collaboration (Items 86–90)
+
+- [ ] **Item 84 — Docstrings for all public APIs** — Do all public modules, classes, and functions have docstrings? Do docstrings describe *what* the function does, its arguments, return value, and any exceptions raised?
+- [ ] **Item 85 — Packages for API namespacing** — Is code organized into packages with `__init__.py` files? Does the package's `__init__.py` expose a clean public API?
+- [ ] **Item 86 — Root exception for packages** — Does each package define its own root exception class that all other package exceptions inherit from? Does this let callers catch all package errors with one `except` clause?
+- [ ] **Item 87 — Circular imports avoided** — Are there any circular imports between modules? Are they resolved by restructuring or by moving imports inside functions?
+- [ ] **Item 88 — Virtual environments** — Is a `requirements.txt`, `Pipfile`, or `pyproject.toml` used to pin dependencies? Is the project developed in a virtual environment?
+
+---
+
+## Quick Review Workflow
+
+1. **Pythonic idiom pass** — Check f-strings, unpacking, enumerate, zip, comprehensions (Items 1-10, 27-36)
+2. **Function design** — Argument count, keyword-only args, return None vs. exceptions, functools.wraps (Items 19-26)
+3. **Class structure** — Composition vs. inheritance, super(), @property vs. plain attributes (Items 37-51)
+4. **Concurrency safety** — Thread-only for I/O, Lock, Queue, no blocking in async (Items 52-64)
+5. **Error handling** — try/except/else/finally, exception chaining, reraise (Items 65-67)
+6. **Test quality** — TestCase structure, mocks, one concept per test, testable design (Items 78-82)
+7. **Documentation** — Docstrings, package root exceptions, dependency management (Items 84-88)
+
+## Severity Levels
+
+| Severity | Description | Examples |
+|----------|-------------|---------|
+| **Critical** | Correctness bugs or unsafe patterns | Threads for CPU parallelism (Item 53), blocking I/O in async (Item 61), mutable default arguments (Item 24), missing Lock on shared state (Item 54) |
+| **High** | Maintainability violations that will cause pain | Returning None for errors (Item 20), missing super().__init__() (Item 40), no functools.wraps (Item 26), missing docstrings on public APIs (Item 84) |
+| **Medium** | Un-Pythonic patterns that should be corrected | map/filter instead of comprehensions (Item 27), range(len()) instead of enumerate (Item 7), getter/setter instead of @property (Item 44) |
+| **Low** | Polish and idiomatic improvements | Missing f-string (Item 4), index access instead of unpacking (Item 6), missing zip for parallel iteration (Item 8) |