@booklib/skills 1.0.0 → 1.3.0

package/effective-python/examples/before.md

@@ -0,0 +1,40 @@
+# Before
+
+Python ETL helper with a bare `except`, a mutable default argument bug, and a manual loop that should be a comprehension.
+
+```python
+import json
+import requests
+
+def fetch_orders(api_url, filters={}):
+    # filters dict persists across calls — mutable default arg bug
+    filters['status'] = 'completed'
+    try:
+        response = requests.get(api_url, params=filters)
+        data = response.json()
+    except:
+        # swallows every exception including KeyboardInterrupt
+        print("something went wrong")
+        return []
+
+    orders = []
+    for item in data['orders']:
+        if item['total'] > 0:
+            order = {
+                'id': item['id'],
+                'customer': item['customer_name'],
+                'total': item['total'],
+            }
+            orders.append(order)
+    return orders
+
+
+def summarize(orders):
+    totals = []
+    for o in orders:
+        totals.append(o['total'])
+    grand_total = 0
+    for t in totals:
+        grand_total = grand_total + t
+    return grand_total
+```

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

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