@booklib/skills 1.0.0 → 1.3.0

package/effective-python/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/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.

package/effective-python/ref-06-metaclasses-attributes.md

@@ -0,0 +1,209 @@
+# Chapter 6: Metaclasses and Attributes (Items 44-51)
+
+## Item 44: Use Plain Attributes Instead of Setter and Getter Methods
+```python
+# BAD — Java-style getters/setters
+class OldResistor:
+    def __init__(self, ohms):
+        self._ohms = ohms
+
+    def get_ohms(self):
+        return self._ohms
+
+    def set_ohms(self, ohms):
+        self._ohms = ohms
+
+# GOOD — plain attributes
+class Resistor:
+    def __init__(self, ohms):
+        self.ohms = ohms
+
+# If you later need behavior, migrate to @property (Item 44)
+```
+
+- Start with simple public attributes
+- If you need special behavior later, use `@property` without changing the API
+- Never write explicit getter/setter methods in Python
+
+## Item 45: Consider @property Instead of Refactoring Attributes
+```python
+class Bucket:
+    def __init__(self, period):
+        self.period = period
+        self.quota = 0
+
+    @property
+    def quota(self):
+        return self._quota
+
+    @quota.setter
+    def quota(self, value):
+        if value < 0:
+            raise ValueError('Quota must be >= 0')
+        self._quota = value
+```
+
+- Use `@property` to add validation, logging, or computed behavior
+- Keeps backward-compatible API (attribute access syntax)
+- Don't do too much work in property getters — keep them fast
+- If a property is getting complex, refactor to a normal method
+
+## Item 46: Use Descriptors for Reusable @property Methods
+```python
+class Grade:
+    """Reusable validation descriptor."""
+    def __init__(self):
+        self._values = {}
+
+    def __get__(self, instance, instance_type):
+        if instance is None:
+            return self
+        return self._values.get(instance, 0)
+
+    def __set__(self, instance, value):
+        if not (0 <= value <= 100):
+            raise ValueError('Grade must be between 0 and 100')
+        self._values[instance] = value
+
+class Exam:
+    math_grade = Grade()
+    writing_grade = Grade()
+    science_grade = Grade()
+
+exam = Exam()
+exam.math_grade = 95  # calls Grade.__set__
+print(exam.math_grade)  # calls Grade.__get__
+```
+
+- Use descriptors when you'd copy-paste `@property` logic
+- Store per-instance data using `WeakKeyDictionary` to avoid memory leaks:
+```python
+from weakref import WeakKeyDictionary
+class Grade:
+    def __init__(self):
+        self._values = WeakKeyDictionary()
+```
+
+## Item 47: Use __getattr__, __getattribute__, and __setattr__ for Lazy Attributes
+```python
+# __getattr__ — called only when attribute not found normally
+class LazyRecord:
+    def __init__(self):
+        self.exists = 5
+
+    def __getattr__(self, name):
+        value = f'Value for {name}'
+        setattr(self, name, value)  # cache it
+        return value
+
+# __getattribute__ — called for EVERY attribute access
+class ValidatingRecord:
+    def __getattribute__(self, name):
+        value = super().__getattribute__(name)
+        # validate or log every access
+        return value
+
+# __setattr__ — called for EVERY attribute assignment
+class SavingRecord:
+    def __setattr__(self, name, value):
+        super().__setattr__(name, value)
+        # save to database, etc.
+```
+
+- `__getattr__` is for lazy/dynamic attributes (called only on missing)
+- `__getattribute__` intercepts ALL attribute access (use carefully)
+- Always use `super()` in these methods to avoid infinite recursion
+- `hasattr` and `getattr` also trigger `__getattribute__`
+
+## Item 48: Validate Subclasses with __init_subclass__
+```python
+class Polygon:
+    sides = None
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if cls.sides is None or cls.sides < 3:
+            raise ValueError('Polygons need 3+ sides')
+
+class Triangle(Polygon):
+    sides = 3  # OK
+
+class Line(Polygon):
+    sides = 2  # Raises ValueError at class definition time!
+```
+
+- `__init_subclass__` is called when a class is subclassed
+- Use it for validation, registration, or class setup
+- Much simpler than metaclasses for most use cases
+- Works with multiple inheritance (use `**kwargs` to pass through)
+
+## Item 49: Register Class Existence with __init_subclass__
+```python
+registry = {}
+
+class Serializable:
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        registry[cls.__name__] = cls
+
+class Point(Serializable):
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+
+# Point is automatically registered
+assert registry['Point'] is Point
+```
+
+- Auto-registration pattern: base class registers all subclasses
+- Useful for serialization, plugin systems, ORM models
+- Replaces the need for explicit registration decorators or metaclasses
+
+## Item 50: Annotate Class Attributes with __set_name__
+```python
+class Field:
+    def __set_name__(self, owner, name):
+        self.name = name          # attribute name on the class
+        self.internal_name = '_' + name  # storage name
+
+    def __get__(self, instance, instance_type):
+        if instance is None:
+            return self
+        return getattr(instance, self.internal_name, '')
+
+    def __set__(self, instance, value):
+        setattr(instance, self.internal_name, value)
+
+class Customer:
+    first_name = Field()  # __set_name__ called with name='first_name'
+    last_name = Field()
+```
+
+- `__set_name__` is called automatically when a descriptor is assigned to a class attribute
+- Eliminates the need to repeat the attribute name
+- Works with descriptors to provide clean, DRY class definitions
+
+## Item 51: Prefer Class Decorators Over Metaclasses for Composable Class Extensions
+```python
+# Class decorator — simple and composable
+def my_class_decorator(cls):
+    # modify or wrap cls
+    original_init = cls.__init__
+
+    def new_init(self, *args, **kwargs):
+        print(f'Creating {cls.__name__}')
+        original_init(self, *args, **kwargs)
+
+    cls.__init__ = new_init
+    return cls
+
+@my_class_decorator
+class MyClass:
+    def __init__(self, value):
+        self.value = value
+```
+
+- Class decorators are simpler than metaclasses
+- They compose easily (stack multiple decorators)
+- Use metaclasses only when you need to control the class creation process itself
+- Prefer: `__init_subclass__` > class decorators > metaclasses