@booklib/skills 1.0.0 → 1.3.0

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/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: effective-python
+description: Review existing Python code and write new Python code following the 90 best practices from "Effective Python" by Brett Slatkin (2nd Edition). Use when writing Python, reviewing Python code, or wanting idiomatic, Pythonic solutions.
+---
+
+# Effective Python Skill
+
+Apply the 90 items from Brett Slatkin's "Effective Python" (2nd Edition) to review existing code and write new Python code. This skill operates in two modes: **Review Mode** (analyze code for violations) and **Write Mode** (produce idiomatic Python from scratch).
+
+## Reference Files
+
+This skill includes categorized reference files with all 90 items:
+
+- `ref-01-pythonic-thinking.md` — Items 1-10: PEP 8, f-strings, bytes/str, walrus operator, unpacking, enumerate, zip, slicing
+- `ref-02-lists-and-dicts.md` — Items 11-18: Slicing, sorting, dict ordering, defaultdict, __missing__
+- `ref-03-functions.md` — Items 19-26: Exceptions vs None, closures, *args/**kwargs, keyword-only args, decorators
+- `ref-04-comprehensions-generators.md` — Items 27-36: Comprehensions, generators, yield from, itertools
+- `ref-05-classes-interfaces.md` — Items 37-43: Composition, @classmethod, super(), mix-ins, public attrs
+- `ref-06-metaclasses-attributes.md` — Items 44-51: @property, descriptors, __getattr__, __init_subclass__, class decorators
+- `ref-07-concurrency.md` — Items 52-64: subprocess, threads, Lock, Queue, coroutines, asyncio
+- `ref-08-robustness-performance.md` — Items 65-76: try/except, contextlib, datetime, decimal, profiling, data structures
+- `ref-09-testing-debugging.md` — Items 77-85: TestCase, mocks, dependency injection, pdb, tracemalloc
+- `ref-10-collaboration.md` — Items 86-90: Docstrings, packages, root exceptions, virtual environments
+
+## How to Use This Skill
+
+**Before responding**, read the relevant reference files based on the code's topic. For a general review, read all files. For targeted work (e.g., writing async code), read the specific reference (e.g., `ref-07-concurrency.md`).
+
+---
+
+## Mode 1: Code Review
+
+When the user asks you to **review** existing Python code, follow this process:
+
+### Step 1: Read Relevant References
+Determine which chapters apply to the code under review and read those reference files. If unsure, read all of them.
+
+### Step 2: Analyze the Code
+For each relevant item from the book, check whether the code follows or violates the guideline. Focus on:
+
+1. **Style and Idiom** (Items 1-10): Is it Pythonic? Does it use f-strings, unpacking, enumerate, zip properly?
+2. **Data Structures** (Items 11-18): Are lists and dicts used correctly? Is sorting done with key functions?
+3. **Function Design** (Items 19-26): Do functions raise exceptions instead of returning None? Are args well-structured?
+4. **Comprehensions & Generators** (Items 27-36): Are comprehensions preferred over map/filter? Are generators used for large sequences?
+5. **Class Design** (Items 37-43): Is composition preferred over deep nesting? Are mix-ins used correctly?
+6. **Metaclasses & Attributes** (Items 44-51): Are plain attributes used instead of getter/setter methods? Is @property used appropriately?
+7. **Concurrency** (Items 52-64): Are threads used only for I/O? Is asyncio structured correctly?
+8. **Robustness** (Items 65-76): Is error handling structured with try/except/else/finally? Are the right data structures chosen?
+9. **Testing** (Items 77-85): Are tests well-structured? Are mocks used appropriately?
+10. **Collaboration** (Items 86-90): Are docstrings present? Are APIs stable?
+
+### Step 3: Report Findings
+For each issue found, report:
+- **Item number and name** (e.g., "Item 4: Prefer Interpolated F-Strings")
+- **Location** in the code
+- **What's wrong** (the anti-pattern)
+- **How to fix it** (the Pythonic way)
+- **Priority**: Critical (bugs/correctness), Important (maintainability), Suggestion (style)
+
+### Step 4: Provide Fixed Code
+Offer a corrected version of the code with all issues addressed, with comments explaining each change.
+
+---
+
+## Mode 2: Writing New Code
+
+When the user asks you to **write** new Python code, follow these principles:
+
+### Always Apply These Core Practices
+
+1. **Follow PEP 8** — Use consistent naming (snake_case for functions/variables, PascalCase for classes). Use `pylint` and `black`-compatible style.
+
+2. **Use f-strings** for string formatting (Item 4). Never use % or .format() for simple cases.
+
+3. **Use unpacking** instead of indexing (Item 6). Prefer `first, second = my_list` over `my_list[0]`.
+
+4. **Use enumerate** instead of range(len(...)) (Item 7).
+
+5. **Use zip** to iterate over multiple lists in parallel (Item 8). Use `zip_longest` from itertools when lengths differ.
+
+6. **Avoid else blocks** after for/while loops (Item 9).
+
+7. **Use assignment expressions** (:= walrus operator) to reduce repetition when appropriate (Item 10).
+
+8. **Raise exceptions** instead of returning None for failure cases (Item 20).
+
+9. **Use keyword-only arguments** for clarity (Item 25). Use positional-only args to separate API from implementation (Item 25).
+
+10. **Use functools.wraps** on all decorators (Item 26).
+
+11. **Prefer comprehensions** over map/filter (Item 27). Keep them simple — no more than two expressions (Item 28).
+
+12. **Use generators** for large sequences instead of returning lists (Item 30).
+
+13. **Prefer composition** over deeply nested classes (Item 37).
+
+14. **Use @classmethod** for polymorphic constructors (Item 39).
+
+15. **Always call super().__init__** (Item 40).
+
+16. **Use plain attributes** instead of getter/setter methods. Use @property for special behavior (Item 44).
+
+17. **Use try/except/else/finally** structure correctly (Item 65).
+
+18. **Write docstrings** for every module, class, and function (Item 84).
+
+### Code Structure Template
+
+When writing new modules or classes, follow this structure:
+
+```python
+"""Module docstring describing purpose."""
+
+# Standard library imports
+# Third-party imports
+# Local imports
+
+# Module-level constants
+
+class MyClass:
+    """Class docstring describing purpose and usage.
+
+    Attributes:
+        attr_name: Description of attribute.
+    """
+
+    def __init__(self, param: type) -> None:
+        """Initialize with description of params."""
+        self.param = param  # Use public attributes (Item 42)
+
+    @classmethod
+    def from_alternative(cls, data):
+        """Alternative constructor (Item 39)."""
+        return cls(processed_data)
+
+    def method(self, arg: type) -> return_type:
+        """Method docstring.
+
+        Args:
+            arg: Description.
+
+        Returns:
+            Description of return value.
+
+        Raises:
+            ValueError: When arg is invalid (Item 20).
+        """
+        pass
+```
+
+### Concurrency Guidelines
+
+- Use `subprocess` for managing child processes (Item 52)
+- Use threads **only** for blocking I/O, never for parallelism (Item 53)
+- Use `threading.Lock` to prevent data races (Item 54)
+- Use `Queue` for coordinating work between threads (Item 55)
+- Use `asyncio` for highly concurrent I/O (Item 60)
+- Never mix blocking calls in async code (Item 62)
+
+### Testing Guidelines
+
+- Subclass `TestCase` and use `setUp`/`tearDown` (Item 78)
+- Use `unittest.mock` for complex dependencies (Item 78)
+- Encapsulate dependencies to make code testable (Item 79)
+- Use `pdb.set_trace()` or `breakpoint()` for debugging (Item 80)
+- Use `tracemalloc` for memory debugging (Item 81)
+
+---
+
+## Priority of Items by Impact
+
+When time is limited, focus on these highest-impact items first:
+
+### Critical (Correctness & Bugs)
+- Item 20: Raise exceptions instead of returning None
+- Item 53: Use threads for I/O only, not parallelism
+- Item 54: Use Lock to prevent data races
+- Item 40: Initialize parent classes with super()
+- Item 65: Use try/except/else/finally correctly
+- Item 73: Use datetime instead of time module for timezone handling
+
+### Important (Maintainability)
+- Item 1: Follow PEP 8 style
+- Item 4: Use f-strings
+- Item 19: Never unpack more than 3 variables
+- Item 25: Use keyword-only and positional-only arguments
+- Item 26: Use functools.wraps for decorators
+- Item 37: Compose classes instead of deep nesting
+- Item 42: Prefer public attributes over private
+- Item 44: Use plain attributes over getter/setter
+- Item 84: Write docstrings for all public APIs
+
+### Suggestions (Polish & Optimization)
+- Item 7: Use enumerate instead of range
+- Item 8: Use zip for parallel iteration
+- Item 10: Use walrus operator to reduce repetition
+- Item 27: Use comprehensions over map/filter
+- Item 30: Use generators for large sequences
+- Item 70: Profile before optimizing (cProfile)

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