@booklib/skills 1.2.0 → 1.3.1

package/effective-java/scripts/checkstyle_setup.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+checkstyle_setup.py - Set up Checkstyle with an Effective Java-aligned configuration.
+
+Usage:
+    python checkstyle_setup.py [--output-dir ./]
+
+Generates:
+    effective-java-checkstyle.xml  - Checkstyle rules mapped to Effective Java items
+    run_checkstyle.sh              - Shell script to run Checkstyle on src/
+
+Each config section references the Effective Java item it enforces.
+"""
+
+import argparse
+import os
+import pathlib
+import stat
+import sys
+import urllib.request
+import urllib.error
+
+CHECKSTYLE_VERSION = "10.14.2"
+CHECKSTYLE_JAR = f"checkstyle-{CHECKSTYLE_VERSION}-all.jar"
+CHECKSTYLE_URL = (
+    f"https://github.com/checkstyle/checkstyle/releases/download/"
+    f"checkstyle-{CHECKSTYLE_VERSION}/{CHECKSTYLE_JAR}"
+)
+
+CHECKSTYLE_XML = """\
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+    "https://checkstyle.org/dtds/configuration_1_3.dtd">
+
+<!--
+  Effective Java - Checkstyle Configuration
+  Each module references the Effective Java item it enforces.
+  Book: "Effective Java" by Joshua Bloch, 3rd Edition.
+-->
+<module name="Checker">
+  <property name="severity" value="warning"/>
+
+  <module name="TreeWalker">
+
+    <!--
+      Item 15: Minimize the accessibility of classes and members.
+      Prefer private fields; expose only what is necessary.
+    -->
+    <module name="VisibilityModifier">
+      <property name="protectedAllowed" value="false"/>
+      <property name="publicMemberPattern" value="^serialVersionUID$"/>
+    </module>
+
+    <!--
+      Item 17: Minimize mutability — utility/helper classes should be final.
+      FinalClass flags classes with only private constructors that are not final.
+    -->
+    <module name="FinalClass"/>
+
+    <!--
+      Item 10: Obey the general contract when overriding equals.
+      Always override hashCode when you override equals.
+    -->
+    <module name="EqualsHashCode"/>
+
+    <!--
+      Item 34: Use enums instead of int constants.
+      Magic numbers in code signal that an enum or named constant should be used.
+    -->
+    <module name="MagicNumber">
+      <property name="ignoreNumbers" value="-1, 0, 1, 2"/>
+      <property name="ignoreAnnotation" value="true"/>
+      <property name="ignoreHashCodeMethod" value="true"/>
+    </module>
+
+    <!--
+      Item 77: Don't ignore exceptions.
+      Empty catch blocks hide failures; always handle or rethrow.
+    -->
+    <module name="EmptyCatchBlock">
+      <property name="exceptionVariableName" value="expected|ignore"/>
+    </module>
+
+    <!--
+      Item 2: Consider a builder when faced with many constructor parameters.
+      More than 3 parameters is a signal to introduce a Builder.
+    -->
+    <module name="ParameterNumber">
+      <property name="max" value="3"/>
+      <property name="tokens" value="METHOD_DEF, CTOR_DEF"/>
+    </module>
+
+    <!--
+      General best practice aligned with Effective Java's emphasis on small,
+      focused methods. Methods longer than 30 lines are harder to reason about.
+    -->
+    <module name="MethodLength">
+      <property name="max" value="30"/>
+      <property name="countEmpty" value="false"/>
+    </module>
+
+    <!--
+      Item 11: Always override toString.
+      Not directly checkable, but HideUtilityClassConstructor complements
+      Item 4 (enforce non-instantiability with private constructor).
+    -->
+    <module name="HideUtilityClassConstructor"/>
+
+    <!--
+      Item 57: Minimize the scope of local variables.
+      Inner assignments make scope harder to reason about.
+    -->
+    <module name="InnerAssignment"/>
+
+    <!--
+      Item 67: Optimize judiciously — avoid redundant string concatenation in loops.
+    -->
+    <module name="StringLiteralEquality"/>
+
+  </module>
+</module>
+"""
+
+RUN_SCRIPT = """\
+#!/usr/bin/env bash
+# run_checkstyle.sh
+# Runs Checkstyle with the Effective Java configuration against src/
+# Generated by checkstyle_setup.py
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+JAR="${SCRIPT_DIR}/{jar}"
+CONFIG="${SCRIPT_DIR}/effective-java-checkstyle.xml"
+SRC_DIR="${1:-src}"
+
+if [[ ! -f "$JAR" ]]; then
+  echo "ERROR: Checkstyle jar not found at $JAR"
+  echo "Run: python checkstyle_setup.py --output-dir \\"$(dirname "$JAR")\\""
+  exit 1
+fi
+
+if [[ ! -d "$SRC_DIR" ]]; then
+  echo "ERROR: Source directory not found: $SRC_DIR"
+  echo "Usage: ./run_checkstyle.sh [src-dir]"
+  exit 1
+fi
+
+echo "Running Checkstyle on $SRC_DIR ..."
+java -jar "$JAR" -c "$CONFIG" -r "$SRC_DIR"
+echo "Done."
+""".format(jar=CHECKSTYLE_JAR)
+
+
+def download_jar(output_dir: pathlib.Path) -> bool:
+    jar_path = output_dir / CHECKSTYLE_JAR
+    if jar_path.exists():
+        print(f"Checkstyle jar already present: {jar_path}")
+        return True
+    print(f"Downloading Checkstyle {CHECKSTYLE_VERSION} from GitHub ...")
+    try:
+        urllib.request.urlretrieve(CHECKSTYLE_URL, jar_path)
+        print(f"Downloaded: {jar_path}")
+        return True
+    except urllib.error.URLError as exc:
+        print(f"Download failed: {exc}")
+        print()
+        print("To install manually:")
+        print(f"  curl -L -o {jar_path} \\")
+        print(f"    {CHECKSTYLE_URL}")
+        return False
+
+
+def write_file(path: pathlib.Path, content: str, executable: bool = False) -> None:
+    path.write_text(content, encoding="utf-8")
+    if executable:
+        path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    print(f"Wrote: {path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Set up Checkstyle with an Effective Java-aligned configuration."
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=".",
+        help="Directory to write config files and download the jar (default: ./)",
+    )
+    args = parser.parse_args()
+
+    output_dir = pathlib.Path(args.output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    download_jar(output_dir)
+
+    write_file(output_dir / "effective-java-checkstyle.xml", CHECKSTYLE_XML)
+    write_file(output_dir / "run_checkstyle.sh", RUN_SCRIPT, executable=True)
+
+    print()
+    print("Setup complete.")
+    print(f"  Config : {output_dir / 'effective-java-checkstyle.xml'}")
+    print(f"  Runner : {output_dir / 'run_checkstyle.sh'}")
+    print()
+    print("Run Checkstyle:")
+    print(f"  cd {output_dir} && ./run_checkstyle.sh [src-dir]")
+
+
+if __name__ == "__main__":
+    main()

package/effective-kotlin/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-mutable-var-nullable-overuse",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nclass UserSession {\n    var userId: String? = null\n    var userName: String? = null\n    var email: String? = null\n    var isLoggedIn: Boolean = false\n    var loginTime: Long? = null\n    var sessionToken: String? = null\n    var permissionLevel: Int = 0\n    \n    fun login(userId: String, userName: String, email: String, token: String, level: Int) {\n        this.userId = userId\n        this.userName = userName\n        this.email = email\n        this.isLoggedIn = true\n        this.loginTime = System.currentTimeMillis()\n        this.sessionToken = token\n        this.permissionLevel = level\n    }\n    \n    fun logout() {\n        this.userId = null\n        this.userName = null\n        this.email = null\n        this.isLoggedIn = false\n        this.loginTime = null\n        this.sessionToken = null\n        this.permissionLevel = 0\n    }\n    \n    fun getDisplayName(): String {\n        if (userName != null) {\n            return userName!!\n        }\n        return \"Guest\"\n    }\n    \n    fun isAdmin(): Boolean {\n        if (permissionLevel != null) {\n            return permissionLevel!! >= 10\n        }\n        return false\n    }\n}\n```",
+      "expectations": [
+        "Flags Item 1 (Limit mutability): all properties are var but most could be val if the design is reconsidered — the entire class should likely be replaced with two states (LoggedIn / LoggedOut) using a sealed class",
+        "Flags Item 8 (Avoid !! operator): getDisplayName() uses userName!! after a null check — should use userName ?: \"Guest\" with Elvis or smart cast",
+        "Notes that permissionLevel is Int (non-nullable) but isAdmin() checks 'if (permissionLevel != null)' — this check is always true and indicates confusion about nullability",
+        "Flags that nullable types (String?, Long?) are used for all properties even though they are only null in the logged-out state — this is a design smell, not a nullability need",
+        "Suggests modeling this with a sealed class: sealed class SessionState with data class LoggedIn(...) and object LoggedOut — making illegal states unrepresentable",
+        "References Item 2 (Minimize variable scope): all these properties have class-wide scope when they only have meaning in the logged-in state",
+        "Notes that the login() function taking 5 positional parameters (Item 17: named arguments) is error-prone — a data class or named arguments should be used"
+      ]
+    },
+    {
+      "id": "eval-02-missing-data-class-extension",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nclass Point {\n    var x: Double\n    var y: Double\n    \n    constructor(x: Double, y: Double) {\n        this.x = x\n        this.y = y\n    }\n    \n    fun distanceTo(other: Point): Double {\n        val dx = this.x - other.x\n        val dy = this.y - other.y\n        return Math.sqrt(dx * dx + dy * dy)\n    }\n    \n    override fun toString(): String {\n        return \"Point(\" + x + \", \" + y + \")\"\n    }\n}\n\nfun translatePoints(points: List<Point>, dx: Double, dy: Double): List<Point> {\n    val result = mutableListOf<Point>()\n    for (point in points) {\n        val newPoint = Point(point.x + dx, point.y + dy)\n        result.add(newPoint)\n    }\n    return result\n}\n\nfun findClosestTo(points: List<Point>, target: Point): Point? {\n    var closest: Point? = null\n    var minDist = Double.MAX_VALUE\n    for (point in points) {\n        val dist = point.distanceTo(target)\n        if (dist < minDist) {\n            minDist = dist\n            closest = point\n        }\n    }\n    return closest\n}\n```",
+      "expectations": [
+        "Flags that Point should be a data class — it has structural equality semantics but lacks the data modifier, meaning equals() and hashCode() use reference equality by default",
+        "Flags Item 1 (Limit mutability): Point fields are var but a geometric point is naturally immutable — they should be val",
+        "Notes that translatePoints uses an imperative for-loop with a mutable list where map { Point(it.x + dx, it.y + dy) } is idiomatic and more readable",
+        "Notes that findClosestTo uses an imperative loop where minByOrNull { it.distanceTo(target) } from the stdlib is idiomatic (Item 20: use stdlib algorithms)",
+        "Points out that Math.sqrt() is Java interop — Kotlin has kotlin.math.sqrt() which is more idiomatic",
+        "May suggest an extension function Point.translate(dx: Double, dy: Double) as a cleaner API that could also be placed in the data class with copy()",
+        "Notes that the string concatenation in toString() is replaced automatically by data class, but if kept manually, string templates are idiomatic: \"Point($x, $y)\""
+      ]
+    },
+    {
+      "id": "eval-03-idiomatic-kotlin-already-good",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nsealed interface PaymentResult {\n    data class Success(val transactionId: String, val amount: Money) : PaymentResult\n    data class Failure(val code: ErrorCode, val message: String) : PaymentResult\n    data object Pending : PaymentResult\n}\n\nenum class ErrorCode { INSUFFICIENT_FUNDS, CARD_DECLINED, NETWORK_ERROR, FRAUD_DETECTED }\n\n@JvmInline\nvalue class Money(val cents: Long) {\n    init {\n        require(cents >= 0) { \"Money cannot be negative: $cents cents\" }\n    }\n    \n    operator fun plus(other: Money) = Money(cents + other.cents)\n    operator fun minus(other: Money): Money {\n        require(other.cents <= cents) { \"Cannot subtract more than available\" }\n        return Money(cents - other.cents)\n    }\n    \n    override fun toString() = \"$${cents / 100}.${(cents % 100).toString().padStart(2, '0')}\"\n}\n\nfun interface PaymentGateway {\n    suspend fun charge(amount: Money, token: String): PaymentResult\n}\n\nsuspend fun processWithRetry(\n    gateway: PaymentGateway,\n    amount: Money,\n    token: String,\n    maxAttempts: Int = 3\n): PaymentResult {\n    repeat(maxAttempts) { attempt ->\n        val result = gateway.charge(amount, token)\n        when (result) {\n            is PaymentResult.Success -> return result\n            is PaymentResult.Failure -> {\n                if (result.code != ErrorCode.NETWORK_ERROR || attempt == maxAttempts - 1) return result\n            }\n            PaymentResult.Pending -> return result\n        }\n    }\n    return PaymentResult.Failure(ErrorCode.NETWORK_ERROR, \"Max retries exceeded\")\n}\n```",
+      "expectations": [
+        "Recognizes this is already idiomatic, well-designed Kotlin and says so explicitly",
+        "Praises the use of sealed interface for PaymentResult — exhaustive when expressions, extensible outside the module",
+        "Praises @JvmInline value class Money — Item 46/49 efficiency (no boxing overhead), type-safe, with require() precondition (Item 5)",
+        "Praises operator overloading on Money — follows convention (plus/minus) and is semantically meaningful (Item 12)",
+        "Praises fun interface PaymentGateway — SAM interface enabling lambda usage, clean abstraction",
+        "Praises using repeat with when instead of a for-loop with if/else — idiomatic control flow",
+        "Praises the sealed hierarchy discriminating between Pending and Failure so the retry logic doesn't retry non-network errors",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May suggest minor optional improvements (e.g., a Currency field on Money for multi-currency support) but clearly frames them as out-of-scope for the given context"
+      ]
+    }
+  ]
+}

package/effective-kotlin/examples/after.md

@@ -0,0 +1,36 @@
+# After
+
+Idiomatic Kotlin with `val` properties, non-null types where absence is not meaningful, and a functional pipeline replacing the manual while loop.
+
+```kotlin
+class UserReportGenerator(
+    private val users: List<User>,
+    private val reportTitle: String,
+    private val includeInactive: Boolean = false,
+) {
+
+    fun generateSummary(): String {
+        val activeUsers = if (includeInactive) users else users.filter { it.active }
+
+        val lines = activeUsers.map { user ->
+            buildString {
+                append("${user.name} (${user.email})")
+                user.role?.let { append(" - $it") }
+            }
+        }
+
+        return buildString {
+            appendLine(reportTitle)
+            lines.forEach(::appendLine)
+        }
+    }
+}
+```
+
+Key improvements:
+- Constructor parameters replace mutable properties (Item 1: Limit Mutability) — the generator is now immutable after construction
+- `users: List<User>` and `reportTitle: String` are non-null types; nullability would only be meaningful if absence were valid (Item 8: Handle Nulls Properly)
+- `filter`, `map`, and `buildString` replace the manual `while` index loop — idiomatic stdlib use (Item 20: Use stdlib algorithms)
+- `user.role?.let { append(" - $it") }` replaces the null-check `if` block with a safe-call chain (Item 8)
+- `includeInactive = false` as a default parameter eliminates the need for an overloaded constructor (Item 34: Consider named and optional args)
+- `generateSummary()` returns `String` (non-null) — the empty report is a valid empty string, not `null` (Item 7: Prefer null or Failure over exceptions for expected failures)

package/effective-kotlin/examples/before.md

@@ -0,0 +1,38 @@
+# Before
+
+Kotlin code written in Java style with `var` everywhere, misused nullability, and index-based loops that ignore idiomatic Kotlin features.
+
+```kotlin
+class UserReportGenerator {
+
+    var users: MutableList<User>? = null
+    var reportTitle: String? = null
+    var includeInactive: Boolean = false
+
+    fun generateSummary(): String? {
+        var result = ""
+        if (users == null) {
+            return null
+        }
+        result = result + reportTitle + "\n"
+        var i = 0
+        while (i < users!!.size) {
+            val user = users!![i]
+            if (includeInactive == false) {
+                if (user.active == false) {
+                    i++
+                    continue
+                }
+            }
+            var line = ""
+            line = line + user.name + " (" + user.email + ")"
+            if (user.role != null) {
+                line = line + " - " + user.role
+            }
+            result = result + line + "\n"
+            i++
+        }
+        return result
+    }
+}
+```

package/effective-python/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-loop-except-mutable-default",
+      "prompt": "Review this Python code:\n\n```python\ndef process_orders(orders, results=[]):\n    for i in range(len(orders)):\n        order = orders[i]\n        try:\n            total = order['price'] * order['quantity']\n            results.append({'id': order['id'], 'total': total})\n        except:\n            pass\n\n    processed = []\n    for item in results:\n        processed.append(item['total'])\n    return processed\n\n\ndef get_high_value(orders, threshold):\n    high = []\n    for order in orders:\n        if order['total'] > threshold:\n            high.append(order)\n    return high\n```",
+      "expectations": [
+        "Flags the mutable default argument `results=[]` as a critical bug (Item 24: Use None and docstrings for dynamic default arguments)",
+        "Flags bare `except:` that silently swallows all exceptions including KeyboardInterrupt and SystemExit (Item 65: always catch specific exception types)",
+        "Identifies `for i in range(len(orders))` as non-idiomatic; recommends `for order in orders` with enumerate if index is needed (Item 7)",
+        "Identifies the manual list-building loop in `process_orders` that should be a list comprehension (Item 27)",
+        "Identifies the manual list-building loop in `get_high_value` that should be a list comprehension (Item 27)",
+        "Provides a corrected version that uses `None` as default and initializes inside the function",
+        "Provides corrected versions using list comprehensions for both loops"
+      ]
+    },
+    {
+      "id": "eval-02-class-missing-dataclass",
+      "prompt": "Review this Python code:\n\n```python\nclass Product:\n    def __init__(self, name, price, category, in_stock=True):\n        self.name = name\n        self.price = price\n        self.category = category\n        self.in_stock = in_stock\n\n    def get_name(self):\n        return self.name\n\n    def set_price(self, price):\n        if price < 0:\n            raise ValueError('Price cannot be negative')\n        self.price = price\n\n    def is_available(self):\n        return self.in_stock == True\n\n\nclass ProductCatalog:\n    def __init__(self):\n        self.__items = []\n\n    def add(self, product):\n        self.__items.append(product)\n\n    def find_by_category(self, category):\n        result = []\n        for p in self.__items:\n            if p.category == category:\n                result.append(p)\n        return result\n```",
+      "expectations": [
+        "Identifies that `Product` is a plain data holder and recommends converting it to a `@dataclass` — eliminates the boilerplate `__init__`, provides automatic `__repr__` and `__eq__`, and makes the data-holder intent explicit (Pythonic class design; Items 37–43: class and interface guidelines)",
+        "Flags `get_name()` as a Java-style getter; Pythonic code uses direct attribute access (Item 44: use plain attributes over getter/setter methods)",
+        "Flags `set_price()` as a Java-style setter; recommends replacing with `@property` with a setter that includes the validation (Item 44)",
+        "Flags `self.in_stock == True` comparison; should be `return self.in_stock` (Item 2: Follow the PEP 8 Style Guide — never compare to True with ==)",
+        "Flags `self.__items` name mangling via double underscore; recommends single underscore `_items` for internal use (Item 42: prefer public attributes)",
+        "Notes absence of `__repr__` on `Product` making debugging harder; a dataclass provides this automatically",
+        "Identifies the manual list-building loop in `find_by_category` as a candidate for a list comprehension (Item 27)",
+        "Provides a corrected version using `@dataclass` with `@property` for price validation"
+      ]
+    },
+    {
+      "id": "eval-03-idiomatic-python-already-good",
+      "prompt": "Review this Python code:\n\n```python\nfrom contextlib import contextmanager\nfrom typing import Generator, Iterator\nimport logging\n\nlogger = logging.getLogger(__name__)\n\n\n@contextmanager\ndef managed_connection(host: str, port: int) -> Generator:\n    \"\"\"Open a connection and ensure it is closed on exit.\"\"\"\n    conn = _connect(host, port)\n    try:\n        logger.debug('Opened connection to %s:%d', host, port)\n        yield conn\n    finally:\n        conn.close()\n        logger.debug('Closed connection to %s:%d', host, port)\n\n\ndef read_records(filepath: str) -> Iterator[dict]:\n    \"\"\"Yield records from a newline-delimited JSON file one at a time.\"\"\"\n    with open(filepath, encoding='utf-8') as fh:\n        for line in fh:\n            line = line.strip()\n            if line:\n                yield _parse(line)\n\n\ndef process_batch(records: Iterator[dict], batch_size: int = 500) -> Iterator[list]:\n    \"\"\"Yield successive fixed-size batches from an iterator.\"\"\"\n    batch: list[dict] = []\n    for record in records:\n        batch.append(record)\n        if len(batch) >= batch_size:\n            yield batch\n            batch = []\n    if batch:\n        yield batch\n```",
+      "expectations": [
+        "Recognizes this is already idiomatic, well-structured Python and says so explicitly",
+        "Praises the use of `@contextmanager` for resource management (Item 66: use contextlib for reusable try/finally patterns)",
+        "Praises the generator function `read_records` for memory-efficient file reading (Item 30: consider generators instead of returning lists)",
+        "Praises the generator function `process_batch` for lazy batch production without loading the entire sequence into memory (Item 30)",
+        "Praises type annotations and docstrings on all public functions (Item 84: Write docstrings for all public APIs)",
+        "Does NOT manufacture issues to appear thorough; any suggestions are explicitly framed as minor optional improvements",
+        "May note minor optional suggestions such as using `itertools.islice` for batching, but frames them as stylistic alternatives, not violations"
+      ]
+    }
+  ]
+}

package/effective-python/examples/after.md

@@ -0,0 +1,56 @@
+# After
+
+Pythonic code with specific exception handling, a dataclass for structure, a comprehension for filtering, and no mutable default argument.
+
+```python
+import requests
+from dataclasses import dataclass
+from requests.exceptions import HTTPError, ConnectionError, Timeout
+
+@dataclass
+class Order:
+    id: str
+    customer: str
+    total: float
+
+
+def fetch_orders(api_url: str, filters: dict | None = None) -> list[Order]:
+    """Fetch completed orders from the partner API.
+
+    Args:
+        api_url: Base URL for the orders endpoint.
+        filters: Optional extra query parameters. Defaults to empty dict.
+
+    Returns:
+        List of Order dataclasses for all completed orders with positive totals.
+
+    Raises:
+        HTTPError: If the API returns a non-2xx response.
+        ConnectionError: If the API is unreachable.
+        Timeout: If the request exceeds the timeout threshold.
+    """
+    params = {"status": "completed", **(filters or {})}
+
+    response = requests.get(api_url, params=params, timeout=10)
+    response.raise_for_status()  # raises HTTPError for 4xx/5xx
+
+    data = response.json()
+    return [
+        Order(id=item["id"], customer=item["customer_name"], total=item["total"])
+        for item in data["orders"]
+        if item["total"] > 0
+    ]
+
+
+def summarize(orders: list[Order]) -> float:
+    """Return the grand total revenue across all orders."""
+    return sum(order.total for order in orders)
+```
+
+Key improvements:
+- `filters: dict | None = None` with `filters or {}` fixes the mutable default argument bug (Item 24: Use None as a default for mutable default arguments)
+- Specific exceptions `HTTPError`, `ConnectionError`, `Timeout` replace the bare `except` clause — errors propagate appropriately and `KeyboardInterrupt` is no longer swallowed (Item 65: Handle exceptions specifically)
+- `response.raise_for_status()` replaces silent failure on bad HTTP responses
+- List comprehension with inline `if` replaces the manual `append` loop (Item 27: Use Comprehensions Instead of map and filter)
+- `@dataclass` replaces a raw `dict` for the order structure — typed, readable, and self-documenting (Item 37: Compose Classes Instead of Nesting Many Levels of Built-in Types)
+- `sum(order.total for order in orders)` in `summarize` is a single idiomatic expression, no intermediate list needed

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
+```