@booklib/skills 1.0.0 → 1.2.0

package/effective-python-skill/ref-03-functions.md

@@ -0,0 +1,186 @@
+# Chapter 3: Functions (Items 19-26)
+
+## Item 19: Never Unpack More Than Three Variables When Functions Return Multiple Values
+```python
+# BAD — too many unpacked values, confusing
+minimum, maximum, average, median, count = get_stats(data)
+
+# GOOD — return a lightweight class or namedtuple
+from collections import namedtuple
+
+Stats = namedtuple('Stats', ['minimum', 'maximum', 'average', 'median', 'count'])
+
+def get_stats(data):
+    return Stats(
+        minimum=min(data),
+        maximum=max(data),
+        average=sum(data)/len(data),
+        median=find_median(data),
+        count=len(data)
+    )
+
+result = get_stats(data)
+print(result.average)
+```
+
+- Three or fewer values is fine to unpack
+- More than three: use a namedtuple, dataclass, or custom class
+
+## Item 20: Prefer Raising Exceptions to Returning None
+```python
+# BAD — None is ambiguous
+def careful_divide(a, b):
+    try:
+        return a / b
+    except ZeroDivisionError:
+        return None
+
+# Caller can't distinguish None from 0
+result = careful_divide(0, 5)  # returns 0.0
+if not result:  # BUG: treats 0.0 as failure
+
+# GOOD — raise an exception
+def careful_divide(a, b):
+    try:
+        return a / b
+    except ZeroDivisionError as e:
+        raise ValueError('Invalid inputs') from e
+
+# ALSO GOOD — type hints with Never-None return
+def careful_divide(a: float, b: float) -> float:
+    """Raises ValueError on invalid inputs."""
+    if b == 0:
+        raise ValueError('Invalid inputs')
+    return a / b
+```
+
+## Item 21: Know How Closures Interact with Variable Scope
+```python
+# Closures capture variables from enclosing scope
+def sort_priority(values, group):
+    found = False
+    def helper(x):
+        nonlocal found  # REQUIRED to modify enclosing variable
+        if x in group:
+            found = True
+            return (0, x)
+        return (1, x)
+    values.sort(key=helper)
+    return found
+```
+
+- Without `nonlocal`, assignment creates a new local variable
+- Prefer returning state over using `nonlocal` for complex cases
+- For complex state, use a helper class instead
+
+## Item 22: Reduce Visual Noise with Variable Positional Arguments (*args)
+```python
+# Accept variable args
+def log(message, *values):
+    if not values:
+        print(message)
+    else:
+        values_str = ', '.join(str(x) for x in values)
+        print(f'{message}: {values_str}')
+
+log('My numbers', 1, 2)
+log('Hi')
+
+# Pass a sequence as *args
+favorites = [7, 33, 99]
+log('Favorites', *favorites)
+```
+
+**Caveats:**
+- `*args` are converted to a tuple (memory issue with generators)
+- Adding positional args before *args breaks callers if not careful
+- Use keyword-only args after *args for new parameters
+
+## Item 23: Provide Optional Behavior with Keyword Arguments
+```python
+def flow_rate(weight_diff, time_diff, *, period=1):  # period is keyword-only
+    return (weight_diff / time_diff) * period
+
+# Callers must use keyword
+flow_rate(1, 2, period=3600)
+flow_rate(1, 2, 3600)  # TypeError!
+```
+
+- Keyword args make function calls more readable
+- They provide default values for optional behavior
+- Can be added to existing functions without breaking callers
+
+## Item 24: Use None and Docstrings to Specify Dynamic Default Arguments
+```python
+# BAD — mutable default is shared across calls!
+def log(message, when=datetime.now()):  # BUG: evaluated once at import
+    print(f'{when}: {message}')
+
+# GOOD — use None sentinel
+def log(message, when=None):
+    """Log a message with a timestamp.
+
+    Args:
+        message: Message to print.
+        when: datetime of when the message occurred.
+            Defaults to the present time.
+    """
+    if when is None:
+        when = datetime.now()
+    print(f'{when}: {message}')
+```
+
+- **Never use mutable objects** as default argument values (lists, dicts, sets, datetime.now())
+- Use `None` and document the actual default in the docstring
+- This also applies to type hints: `when: Optional[datetime] = None`
+
+## Item 25: Enforce Clarity with Keyword-Only and Positional-Only Arguments
+```python
+# Keyword-only: after * in signature
+def safe_division(number, divisor, *,
+                  ignore_overflow=False,
+                  ignore_zero_division=False):
+    pass
+
+# Positional-only: before / in signature (Python 3.8+)
+def safe_division(numerator, denominator, /,
+                  *, ignore_overflow=False):
+    pass
+
+# Combined: positional-only / regular / keyword-only
+def safe_division(numerator, denominator, /,
+                  ndigits=10, *,
+                  ignore_overflow=False):
+    pass
+```
+
+- `/` separates positional-only from regular params
+- `*` separates regular from keyword-only params
+- Use positional-only for params where the name is an implementation detail
+- Use keyword-only for boolean flags and optional configuration
+
+## Item 26: Define Function Decorators with functools.wraps
+```python
+from functools import wraps
+
+# BAD — decorator hides original function metadata
+def trace(func):
+    def wrapper(*args, **kwargs):
+        result = func(*args, **kwargs)
+        print(f'{func.__name__}({args}, {kwargs}) -> {result}')
+        return result
+    return wrapper
+
+# GOOD — preserves function metadata
+def trace(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        result = func(*args, **kwargs)
+        print(f'{func.__name__}({args}, {kwargs}) -> {result}')
+        return result
+    return wrapper
+```
+
+- `@wraps` copies the inner function's metadata (__name__, __module__, __doc__)
+- Without it, debugging tools, serializers, and `help()` break
+- **Always** use `@wraps` on decorator wrapper functions

package/effective-python-skill/ref-04-comprehensions-generators.md

@@ -0,0 +1,211 @@
+# Chapter 4: Comprehensions and Generators (Items 27-36)
+
+## Item 27: Use Comprehensions Instead of map and filter
+```python
+# BAD
+squares = map(lambda x: x**2, range(10))
+even_squares = map(lambda x: x**2, filter(lambda x: x % 2 == 0, range(10)))
+
+# GOOD
+squares = [x**2 for x in range(10)]
+even_squares = [x**2 for x in range(10) if x % 2 == 0]
+
+# Also works for dicts and sets
+chile_ranks = {rank: name for name, rank in names_and_ranks}
+unique_lengths = {len(name) for name in names}
+```
+
+## Item 28: Avoid More Than Two Control Subexpressions in Comprehensions
+```python
+# OK — two levels
+flat = [x for row in matrix for x in row]
+
+# OK — two conditions
+filtered = [x for x in numbers if x > 0 if x % 2 == 0]
+
+# BAD — too complex, hard to read
+result = [x for sublist1 in my_lists
+          for sublist2 in sublist1
+          for x in sublist2]
+
+# GOOD — use a loop or helper
+result = []
+for sublist1 in my_lists:
+    for sublist2 in sublist1:
+        result.extend(sublist2)
+```
+
+- Rule of thumb: max two `for` subexpressions or two conditions
+- Beyond that, use normal loops for readability
+
+## Item 29: Avoid Repeated Work in Comprehensions by Using Assignment Expressions
+```python
+# BAD — calls get_batches twice
+found = {name: batches for name in order
+         if (batches := get_batches(stock.get(name, 0), 8))}
+
+# GOOD — walrus operator avoids repeated computation
+found = {name: batches for name in order
+         if (batches := get_batches(stock.get(name, 0), 8))}
+
+# The := expression in the condition makes 'batches' available in the value expression
+```
+
+- Use `:=` in the `if` clause to compute once and reuse in the value expression
+- The walrus variable leaks into the enclosing scope (be careful with naming)
+
+## Item 30: Consider Generators Instead of Returning Lists
+```python
+# BAD — builds entire list in memory
+def index_words(text):
+    result = []
+    if text:
+        result.append(0)
+    for index, letter in enumerate(text):
+        if letter == ' ':
+            result.append(index + 1)
+    return result
+
+# GOOD — generator yields one at a time
+def index_words(text):
+    if text:
+        yield 0
+    for index, letter in enumerate(text):
+        if letter == ' ':
+            yield index + 1
+```
+
+- Generators use memory proportional to one output, not all outputs
+- Use for large or infinite sequences
+- Easy to convert: replace `result.append(x)` with `yield x`
+
+## Item 31: Be Defensive When Iterating Over Arguments
+```python
+# BAD — generator exhausted after first iteration
+def normalize(numbers):
+    total = sum(numbers)    # exhausts the generator
+    result = []
+    for value in numbers:   # nothing left to iterate!
+        result.append(value / total)
+    return result
+
+# GOOD — accept an iterable container, not iterator
+def normalize(numbers):
+    total = sum(numbers)    # iterates once
+    result = []
+    for value in numbers:   # iterates again — works with lists, not generators
+        result.append(value / total)
+    return result
+
+# BETTER — use __iter__ protocol to detect single-use iterators
+def normalize(numbers):
+    if iter(numbers) is numbers:  # iterator, not container
+        raise TypeError('Must supply a container')
+    total = sum(numbers)
+    return [value / total for value in numbers]
+```
+
+- Iterators are exhausted after one pass; containers are not
+- Check `iter(x) is x` to detect iterators
+- Or implement `__iter__` in a custom container class
+
+## Item 32: Consider Generator Expressions for Large List Comprehensions
+```python
+# BAD — creates entire list in memory
+values = [len(x) for x in open('my_file.txt')]
+
+# GOOD — generator expression, lazy evaluation
+values = (len(x) for x in open('my_file.txt'))
+
+# Chain generator expressions
+roots = ((x, x**0.5) for x in values)
+```
+
+- Generator expressions use `()` instead of `[]`
+- Lazy — only compute values as needed
+- Can be chained together without memory overhead
+
+## Item 33: Compose Multiple Generators with yield from
+```python
+# BAD — manual iteration
+def chain_generators(gen1, gen2):
+    for item in gen1:
+        yield item
+    for item in gen2:
+        yield item
+
+# GOOD — yield from
+def chain_generators(gen1, gen2):
+    yield from gen1
+    yield from gen2
+
+# Real example: tree traversal
+def traverse(tree):
+    if tree is not None:
+        yield from traverse(tree.left)
+        yield tree.value
+        yield from traverse(tree.right)
+```
+
+- `yield from` delegates to a sub-generator
+- More readable and slightly faster than manual loop + yield
+
+## Item 34: Avoid Injecting Data into Generators with send
+- `generator.send(value)` is complex and hard to understand
+- Prefer passing an iterator to the generator instead
+- Use `send` only when absolutely necessary (coroutine patterns)
+
+## Item 35: Avoid Causing State Transitions in Generators with throw
+- `generator.throw(exception)` is confusing
+- Use `__iter__` methods in a class instead for stateful iteration
+- If you need exception handling in generators, prefer try/except inside the generator
+
+## Item 36: Consider itertools for Working with Iterators and Generators
+**Linking iterators:**
+```python
+import itertools
+
+# Chain multiple iterators
+itertools.chain(iter1, iter2)
+
+# Repeat values
+itertools.repeat('hello', 3)
+
+# Cycle through an iterable
+itertools.cycle([1, 2, 3])
+
+# Parallel iteration with tee
+it1, it2 = itertools.tee(iterator, 2)
+```
+
+**Filtering:**
+```python
+# takewhile — yield while predicate is True
+itertools.takewhile(lambda x: x < 5, values)
+
+# dropwhile — skip while predicate is True
+itertools.dropwhile(lambda x: x < 5, values)
+
+# filterfalse — yield items where predicate is False
+itertools.filterfalse(lambda x: x < 5, values)
+
+# islice — slice an iterator
+itertools.islice(values, 2, 8, 2)  # start, stop, step
+```
+
+**Combining:**
+```python
+# product — cartesian product
+itertools.product([1,2], ['a','b'])  # (1,'a'), (1,'b'), (2,'a'), (2,'b')
+
+# permutations and combinations
+itertools.permutations([1,2,3], 2)
+itertools.combinations([1,2,3], 2)
+itertools.combinations_with_replacement([1,2,3], 2)
+
+# accumulate — running totals
+itertools.accumulate([1,2,3,4])  # 1, 3, 6, 10
+
+# zip_longest
+itertools.zip_longest([1,2], [1,2,3], fillvalue=0)
+```

package/effective-python-skill/ref-05-classes-interfaces.md

@@ -0,0 +1,188 @@
+# Chapter 5: Classes and Interfaces (Items 37-43)
+
+## Item 37: Compose Classes Instead of Nesting Many Levels of Built-in Types
+```python
+# BAD — deeply nested built-in types
+grades = {}  # dict of dict of list of tuples
+grades['Math'] = {}
+grades['Math']['test'] = [(95, 0.4), (87, 0.6)]
+
+# GOOD — compose with named classes
+from dataclasses import dataclass
+from collections import namedtuple
+
+Grade = namedtuple('Grade', ('score', 'weight'))
+
+@dataclass
+class Subject:
+    grades: list
+
+    def average_grade(self):
+        total = sum(g.score * g.weight for g in self.grades)
+        total_weight = sum(g.weight for g in self.grades)
+        return total / total_weight
+
+@dataclass
+class Student:
+    subjects: dict  # name -> Subject
+
+class Gradebook:
+    def __init__(self):
+        self._students = {}
+```
+
+- When nesting goes beyond dict of dict, refactor into classes
+- Use `namedtuple` for lightweight immutable data containers
+- Use `dataclass` for mutable data containers with behavior
+- Bottom-up refactoring: start with the innermost type
+
+## Item 38: Accept Functions Instead of Classes for Simple Interfaces
+```python
+# Python's hooks can accept any callable
+names = ['Socrates', 'Archimedes', 'Plato']
+names.sort(key=len)  # function as interface
+
+# Use __call__ for stateful callables
+class CountMissing:
+    def __init__(self):
+        self.added = 0
+
+    def __call__(self):
+        self.added += 1
+        return 0
+
+counter = CountMissing()
+result = defaultdict(counter, current_data)  # uses __call__
+print(counter.added)
+```
+
+- Functions are first-class in Python — use them as interfaces
+- For stateful behavior, define `__call__` on a class
+- Simpler than defining full interface classes
+
+## Item 39: Use @classmethod Polymorphism to Construct Objects Generically
+```python
+class InputData:
+    def read(self):
+        raise NotImplementedError
+
+class PathInputData(InputData):
+    def __init__(self, path):
+        self.path = path
+
+    def read(self):
+        return open(self.path).read()
+
+    @classmethod
+    def generate_inputs(cls, config):
+        """Factory that creates instances from config."""
+        data_dir = config['data_dir']
+        for name in os.listdir(data_dir):
+            yield cls(os.path.join(data_dir, name))
+```
+
+- Use `@classmethod` as a polymorphic constructor
+- Enables subclasses to provide their own construction logic
+- Avoids hardcoding class names in factory functions
+
+## Item 40: Initialize Parent Classes with super()
+```python
+# BAD — direct call to parent
+class Child(Parent):
+    def __init__(self):
+        Parent.__init__(self)  # breaks with multiple inheritance
+
+# GOOD — always use super()
+class Child(Parent):
+    def __init__(self):
+        super().__init__()
+```
+
+- `super()` follows the MRO (Method Resolution Order) correctly
+- Essential for multiple inheritance (diamond problem)
+- Always call `super().__init__()` in `__init__` methods
+- The MRO is deterministic: use `ClassName.__mro__` or `ClassName.mro()` to inspect
+
+## Item 41: Consider Composing Functionality with Mix-in Classes
+```python
+# Mix-in: a class that provides extra functionality without its own state
+class JsonMixin:
+    @classmethod
+    def from_json(cls, data):
+        kwargs = json.loads(data)
+        return cls(**kwargs)
+
+    def to_json(self):
+        return json.dumps(self.__dict__)
+
+class DatacenterRack(JsonMixin):
+    def __init__(self, switch=None, machines=None):
+        self.switch = switch
+        self.machines = machines
+
+# Usage
+rack = DatacenterRack.from_json(json_data)
+json_str = rack.to_json()
+```
+
+- Mix-ins provide reusable behavior without instance state
+- Classes can use multiple mix-ins via multiple inheritance
+- Prefer mix-ins over deep inheritance hierarchies
+- Name them with `Mixin` suffix for clarity
+
+## Item 42: Prefer Public Attributes Over Private Ones
+```python
+# BAD — private attributes (__name mangling)
+class MyObject:
+    def __init__(self):
+        self.__private_field = 10  # name-mangled to _MyObject__private_field
+
+# GOOD — protected with convention
+class MyObject:
+    def __init__(self):
+        self._protected_field = 10  # convention: internal use
+
+# Access is still possible but signals "internal"
+obj = MyObject()
+obj._protected_field  # works, but callers know it's internal
+```
+
+- `__double_underscore` causes name mangling — don't use it
+- Use `_single_underscore` for protected/internal attributes
+- Python philosophy: "We're all consenting adults"
+- Name mangling breaks subclass access and makes debugging harder
+- Only use `__` to avoid naming conflicts with subclasses (rare)
+
+## Item 43: Inherit from collections.abc for Custom Container Types
+```python
+from collections.abc import Sequence
+
+class FrequencyList(list):
+    def frequency(self):
+        counts = {}
+        for item in self:
+            counts[item] = counts.get(item, 0) + 1
+        return counts
+
+# For custom containers, inherit from collections.abc
+class BinaryNode(Sequence):
+    def __init__(self, value, left=None, right=None):
+        self.value = value
+        self.left = left
+        self.right = right
+
+    def __getitem__(self, index):
+        # Required by Sequence
+        ...
+
+    def __len__(self):
+        # Required by Sequence
+        ...
+
+    # count() and index() provided automatically by Sequence
+```
+
+- `collections.abc` provides abstract base classes for containers
+- Inheriting ensures you implement required methods
+- You get mixin methods for free (e.g., `count`, `index` from `Sequence`)
+- Available ABCs: `Sequence`, `MutableSequence`, `Set`, `MutableSet`, `Mapping`, `MutableMapping`, etc.