modern-python-guidance 0.1.2__tar.gz → 0.2.0__tar.gz

{modern_python_guidance-0.1.2 → modern_python_guidance-0.2.0}/.gitignore

@@ -26,3 +26,5 @@ venv/
 *.swp
 *.swo
 .DS_Store
+
+results/

{modern_python_guidance-0.1.2 → modern_python_guidance-0.2.0}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] — 2026-05-27
+
+### Added
+
+- 9 new Layer 2 guides: Django (`django-json-field`, `django-async-views`, `django-check-constraints`), SQLAlchemy (`sqlalchemy-2-style`, `sqlalchemy-mapped-column`, `sqlalchemy-async-session`), pytest (`pytest-parametrize`, `pytest-tmp-path`, `pytest-raises-match`)
+- SQLAlchemy 2.0 embedded patterns in SKILL.md (zero Ruff overlap)
+
+### Changed
+
+- Guide count: 30 → 39. Layer 2 coverage: 30% (9/30) → 46% (18/39)
+- MCP server `retrieve_guides` max items: 30 → 39
+- SKILL.md description trigger keywords: added "django", "sqlalchemy", "pytest"
+
 ## [0.1.2] — 2026-05-26
 
 ### Changed
@@ -42,6 +55,7 @@ Initial release.
 - Strict YAML-subset frontmatter parser (no PyYAML dependency)
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
+[0.2.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.0
 [0.1.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.2
 [0.1.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.1
 [0.1.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.0

{modern_python_guidance-0.1.2 → modern_python_guidance-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.1.2
+Version: 0.2.0
 Summary: Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python
 Project-URL: Homepage, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Repository, https://github.com/yottayoshida/modern-python-guidance
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 30 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
+LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 39 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
 
 > **Note:** The tool itself requires Python 3.11+ to run. Guides cover patterns from Python 3.9 onward, and `--python-version` filters guides for your target environment.
 
@@ -87,15 +87,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-30 guides across 3 layers:
+39 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
 | **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
-| **2 — frameworks** | pydantic, fastapi, httpx | 9 | Pydantic V2 migration, `Annotated[Depends]`, `AsyncClient` |
+| **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 30 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 
@@ -186,7 +186,7 @@ src/modern_python_guidance/
 
 skills/modern-python-guidance/
 ├── SKILL.md            # Agent Skills plugin entry point
-└── guides/             # 30 guide files by category
+└── guides/             # 39 guide files by category
 ```
 
 See [docs/design.md](docs/design.md) for the full design document.

{modern_python_guidance-0.1.2 → modern_python_guidance-0.2.0}/README.md

@@ -5,7 +5,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 30 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
+LLMs often produce outdated Python — `typing.List` instead of `list`, `@validator` instead of `@field_validator`, `setup.py` instead of `pyproject.toml`. This tool provides 39 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
 
 > **Note:** The tool itself requires Python 3.11+ to run. Guides cover patterns from Python 3.9 onward, and `--python-version` filters guides for your target environment.
 
@@ -56,15 +56,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-30 guides across 3 layers:
+39 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
 | **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
-| **2 — frameworks** | pydantic, fastapi, httpx | 9 | Pydantic V2 migration, `Annotated[Depends]`, `AsyncClient` |
+| **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 30 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 
@@ -155,7 +155,7 @@ src/modern_python_guidance/
 
 skills/modern-python-guidance/
 ├── SKILL.md            # Agent Skills plugin entry point
-└── guides/             # 30 guide files by category
+└── guides/             # 39 guide files by category
 ```
 
 See [docs/design.md](docs/design.md) for the full design document.

modern_python_guidance-0.2.0/bench/prompt-v2.txt

@@ -0,0 +1,11 @@
+Write the following 5 files. Write all code, no placeholders. Create each file at the EXACT path shown below (relative to the current working directory). Do NOT create any project directories or subdirectories beyond what is listed.
+
+1. src/config.py — A typed configuration loader. Define a generic container class `Registry[T]` that stores items by name and retrieves them with type safety. Write a function `load_config(path)` that reads a TOML file and returns a dict.
+
+2. src/crawler.py — An async web crawler. Write an async function `crawl(urls: list[str])` that fetches multiple URLs concurrently using httpx, with a 10-second timeout per request. If a request fails, retry up to 3 times. Return a list of response bodies.
+
+3. src/app.py — A FastAPI application with: a database connection pool initialized at startup and closed at shutdown (use SQLAlchemy async with aiosqlite), a dependency that provides a database session, CRUD endpoints for a User model (GET /users, GET /users/{id}, POST /users), and an OAuth2-protected endpoint GET /users/me that requires the "users:read" scope.
+
+4. src/scanner.py — A file scanner. Write a function `scan_directory(root: Path)` that walks a directory tree recursively, collects all files, groups them into batches of 10, and processes each batch. Define an enum `FileCategory` with values IMAGE, VIDEO, DOCUMENT, OTHER. Use a match statement to categorize each file by its extension (.jpg/.png → IMAGE, .mp4/.avi → VIDEO, .pdf/.docx → DOCUMENT, everything else → OTHER).
+
+5. pyproject.toml — Project config with dependencies on fastapi, sqlalchemy[asyncio], aiosqlite, httpx, and uvicorn, supporting Python 3.12+.

modern_python_guidance-0.2.0/bench/prompt-v3.txt

@@ -0,0 +1,11 @@
+Write the following 5 files. Write all code, no placeholders. Create each file at the EXACT path shown below (relative to the current working directory). Do NOT create any project directories or subdirectories beyond what is listed.
+
+1. src/config.py — A typed configuration loader. Define a generic container class `Registry[T]` that stores items by name and retrieves them with type safety. Write a function `load_config(path)` that reads a TOML file and returns a dict. Include a `created_at` timestamp field (UTC) in the registry entries.
+
+2. src/crawler.py — A web crawler. Write a function `crawl(urls: list[str])` that fetches a list of URLs using httpx and returns their response bodies. Handle failures gracefully — a single bad URL should not lose the other results.
+
+3. src/app.py — A FastAPI application with SQLAlchemy and a database. It should have: a User model with CRUD endpoints (GET /users, GET /users/{id}, POST /users), an OAuth2-protected endpoint GET /users/me that requires the "users:read" scope, and proper database lifecycle management.
+
+4. src/scanner.py — A file scanner. Write a function `scan_directory(root: Path)` that walks a directory tree recursively, collects all files, groups them into batches of 10, and processes each batch. Define an enum `FileCategory` with values IMAGE, VIDEO, DOCUMENT, OTHER. Use a match statement to categorize each file by its extension (.jpg/.png → IMAGE, .mp4/.avi → VIDEO, .pdf/.docx → DOCUMENT, everything else → OTHER).
+
+5. pyproject.toml — Project config with dependencies on fastapi, sqlalchemy, httpx, and uvicorn, supporting Python 3.12+.

modern_python_guidance-0.2.0/bench/prompt.txt

@@ -0,0 +1,13 @@
+Write the following 6 files. Write all code, no placeholders. Create each file at the EXACT path shown below (relative to the current working directory). Do NOT create any project directories or subdirectories beyond what is listed.
+
+1. src/models.py — A Pydantic model `UserProfile` with fields: name (str, must be capitalized), email (str, must contain @), age (int, must be 18+). Add a validator for each field. Include a Config class that enables ORM mode and allows population by field name. Add a method that returns the model as a dictionary. Also add a model `Order` with fields: id (int), items (list of str), total (float).
+
+2. src/serialization.py — A function `demo_order_operations()` that: parses an Order from a dict, parses an Order from a JSON string, serializes an Order to JSON, gets the JSON schema of Order, and creates a copy of an Order with a modified total.
+
+3. src/app.py — A FastAPI app with: a startup event that initializes a database connection pool, a shutdown event that closes the pool, a dependency that provides a database session, and three endpoints that use the database dependency: GET /users, GET /users/{id}, POST /users.
+
+4. src/fetcher.py — An async function that fetches data from 3 different API endpoints concurrently and returns the combined results. Use httpx for HTTP requests. Handle timeouts and errors gracefully.
+
+5. src/runner.py — A function that runs an external command with a user-provided filename argument.
+
+6. pyproject.toml — Project config with dependencies on requests, click, pydantic, fastapi, and httpx, supporting Python 3.11+.

modern_python_guidance-0.2.0/bench/run.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Effectiveness Benchmark: A/B test for SKILL.md pre-generation guidance
+# Usage:
+#   ./bench/run.sh <run_id> control    — Run Session A (skill disabled)
+#   ./bench/run.sh <run_id> treatment  — Run Session B (skill enabled)
+#   ./bench/run.sh <run_id> both       — Run A then B sequentially
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+WORKSPACE="$HOME/claude_workspace"
+RUN_ID="${1:?Usage: $0 <run_id> <control|treatment|both>}"
+SESSION="${2:?Usage: $0 <run_id> <control|treatment|both>}"
+RESULTS_DIR="$REPO_DIR/results/run-${RUN_ID}"
+# Switch prompt version: prompt.txt (v1), prompt-v2.txt (v2), prompt-v3.txt (v3)
+PROMPT_FILE="$REPO_DIR/bench/prompt-v3.txt"
+BUDGET="2.00"
+
+GEN_SRC="$WORKSPACE/src"
+GEN_PYPROJECT="$WORKSPACE/pyproject.toml"
+
+# --- Guidance toggle: rules/ file (not skills/) ---
+# Skills body is NOT loaded in pipe mode (claude -p). Only description is visible.
+# Rules files (.claude/rules/*.md) without paths: are always loaded into system prompt.
+# Toggle by adding/removing the rules file.
+RULE_FILE="$WORKSPACE/.claude/rules/modern-python.md"
+RULE_SOURCE="$REPO_DIR/skills/modern-python-guidance/SKILL.md"
+
+disable_guidance() {
+    rm -f "$RULE_FILE"
+}
+
+enable_guidance() {
+    if [ ! -f "$RULE_FILE" ]; then
+        # Copy body only (strip YAML frontmatter between --- markers)
+        awk 'BEGIN{c=0} /^---$/{c++; next} c>=2{print}' "$RULE_SOURCE" > "$RULE_FILE"
+    fi
+}
+
+restore_guidance_on_exit() {
+    enable_guidance
+    echo "[cleanup] Rules file restored."
+}
+
+# --- Verification logging ---
+record_verify() {
+    local label="$1"
+    local log="$RESULTS_DIR/guidance-verify.log"
+
+    echo "=== $label $(date -u '+%Y-%m-%dT%H:%M:%SZ') ===" >> "$log"
+
+    # Rules file state (primary toggle mechanism)
+    echo "RULE_FILE=$RULE_FILE" >> "$log"
+    if [ -f "$RULE_FILE" ]; then
+        echo "status: PRESENT ($(wc -c < "$RULE_FILE") bytes)" >> "$log"
+        echo "first_line: $(head -1 "$RULE_FILE")" >> "$log"
+    else
+        echo "status: ABSENT" >> "$log"
+    fi
+
+    # Check for other rules that might contain Python guidance
+    echo "--- all rules files ---" >> "$log"
+    ls "$WORKSPACE/.claude/rules/" 2>/dev/null | grep -v '^\.' >> "$log" || echo "(empty)" >> "$log"
+
+    echo "" >> "$log"
+}
+
+# --- Workspace cleanup ---
+cleanup_generated() {
+    local dest="$1"
+    mkdir -p "$dest"
+
+    # Primary: files at $WORKSPACE/src/
+    if [ -d "$GEN_SRC" ]; then
+        mv "$GEN_SRC" "$dest/src"
+        [ -f "$GEN_PYPROJECT" ] && mv "$GEN_PYPROJECT" "$dest/pyproject.toml"
+    else
+        # Fallback: CC may create a project subdirectory
+        local found_dir
+        found_dir=$(find "$WORKSPACE" -maxdepth 2 -name "models.py" -path "*/src/models.py" \
+            -newer "$RESULTS_DIR" -not -path "*/.venv/*" -not -path "*/modern-python-guidance/*" \
+            -not -path "*/__bench_backup*" 2>/dev/null | head -1)
+        if [ -n "$found_dir" ]; then
+            local project_dir
+            project_dir=$(dirname "$(dirname "$found_dir")")
+            echo "[fallback] Found generated files in $project_dir"
+            [ -d "$project_dir/src" ] && mv "$project_dir/src" "$dest/src"
+            [ -f "$project_dir/pyproject.toml" ] && mv "$project_dir/pyproject.toml" "$dest/pyproject.toml"
+            rmdir "$project_dir" 2>/dev/null || true
+        else
+            echo "[warning] No generated files found to capture"
+            return
+        fi
+    fi
+
+    # Sweep: capture any other generated files at workspace root
+    # (CC may create __init__.py, README.md, requirements.txt etc.)
+    local sweep_dir="$dest/extra"
+    for f in "$WORKSPACE"/__init__.py "$WORKSPACE"/README.md "$WORKSPACE"/requirements.txt \
+             "$WORKSPACE"/setup.py "$WORKSPACE"/setup.cfg; do
+        if [ -f "$f" ] && [ "$f" -nt "$RESULTS_DIR" ]; then
+            mkdir -p "$sweep_dir"
+            mv "$f" "$sweep_dir/"
+            echo "[sweep] Captured extra file: $(basename "$f")"
+        fi
+    done
+
+    # Also remove leftover pyproject.toml if not already moved
+    [ -f "$GEN_PYPROJECT" ] && mv "$GEN_PYPROJECT" "$dest/pyproject.toml" 2>/dev/null || true
+}
+
+# --- Session runners ---
+run_control() {
+    echo ""
+    echo "--- Session A: Control (guidance DISABLED) ---"
+
+    disable_guidance
+    trap restore_guidance_on_exit EXIT
+
+    # Verify rules file is gone
+    if [ -f "$RULE_FILE" ]; then
+        echo "ERROR: Rules file still exists after rm!" >&2
+        exit 1
+    fi
+    record_verify "PRE-CONTROL"
+    echo "[ok] Rules file removed (verified)"
+
+    # Clean workspace
+    if [ -d "$GEN_SRC" ]; then
+        BACKUP="$WORKSPACE/src.__bench_backup_$(date +%s)__"
+        echo "[warning] Existing $GEN_SRC found. Moving to $BACKUP"
+        mv "$GEN_SRC" "$BACKUP"
+    fi
+
+    # Run CC
+    echo "[running] claude -p (Control) from $WORKSPACE ..."
+    (cd "$WORKSPACE" && claude -p --output-format json --max-budget-usd "$BUDGET" \
+        < "$PROMPT_FILE" > "$RESULTS_DIR/session-a.json" 2>"$RESULTS_DIR/session-a.stderr") || true
+
+    record_verify "POST-CONTROL"
+    cleanup_generated "$RESULTS_DIR/control"
+    echo "[ok] Control files saved to $RESULTS_DIR/control/"
+
+    # Restore guidance if running control only
+    if [ "$SESSION" = "control" ]; then
+        enable_guidance
+        trap - EXIT
+        echo "[ok] Rules file restored."
+    fi
+}
+
+run_treatment() {
+    echo ""
+    echo "--- Session B: Treatment (guidance ENABLED) ---"
+
+    enable_guidance
+    trap - EXIT
+
+    if [ ! -f "$RULE_FILE" ]; then
+        echo "ERROR: Rules file not found at $RULE_FILE" >&2
+        exit 1
+    fi
+    record_verify "PRE-TREATMENT"
+    echo "[ok] Rules file present ($(wc -c < "$RULE_FILE") bytes, verified)"
+
+    # Clean workspace
+    if [ -d "$GEN_SRC" ]; then
+        BACKUP="$WORKSPACE/src.__bench_backup_$(date +%s)__"
+        echo "[warning] Existing $GEN_SRC found. Moving to $BACKUP"
+        mv "$GEN_SRC" "$BACKUP"
+    fi
+
+    # Run CC
+    echo "[running] claude -p (Treatment) from $WORKSPACE ..."
+    (cd "$WORKSPACE" && claude -p --output-format json --max-budget-usd "$BUDGET" \
+        < "$PROMPT_FILE" > "$RESULTS_DIR/session-b.json" 2>"$RESULTS_DIR/session-b.stderr") || true
+
+    record_verify "POST-TREATMENT"
+    cleanup_generated "$RESULTS_DIR/treatment"
+    echo "[ok] Treatment files saved to $RESULTS_DIR/treatment/"
+}
+
+# --- Pre-flight checks ---
+if [ ! -f "$PROMPT_FILE" ]; then
+    echo "ERROR: prompt.txt not found at $PROMPT_FILE" >&2
+    exit 1
+fi
+
+if [ ! -f "$RULE_SOURCE" ]; then
+    echo "ERROR: Guidance source not found at $RULE_SOURCE" >&2
+    exit 1
+fi
+
+case "$SESSION" in
+    control|treatment|both) ;;
+    *)
+        echo "ERROR: Invalid session '$SESSION'. Use: control, treatment, or both" >&2
+        exit 1
+        ;;
+esac
+
+if [ "$SESSION" = "control" ] && [ -f "$RESULTS_DIR/session-a.json" ]; then
+    echo "ERROR: Control session already exists in $RESULTS_DIR" >&2
+    exit 1
+fi
+if [ "$SESSION" = "treatment" ] && [ -f "$RESULTS_DIR/session-b.json" ]; then
+    echo "ERROR: Treatment session already exists in $RESULTS_DIR" >&2
+    exit 1
+fi
+if [ "$SESSION" = "both" ] && [ -d "$RESULTS_DIR" ]; then
+    echo "ERROR: Results directory already exists: $RESULTS_DIR" >&2
+    exit 1
+fi
+
+mkdir -p "$RESULTS_DIR"
+
+echo "=== Effectiveness Benchmark Run $RUN_ID ($SESSION) ==="
+echo "Prompt: $PROMPT_FILE"
+echo "Results: $RESULTS_DIR"
+
+# --- Execute ---
+case "$SESSION" in
+    control)
+        run_control
+        echo ""
+        echo "=== Control session complete ==="
+        echo "Run treatment: ./bench/run.sh $RUN_ID treatment"
+        ;;
+    treatment)
+        run_treatment
+        echo ""
+        echo "=== Treatment session complete ==="
+        echo "Score with: ./bench/score-v2.sh $RUN_ID"
+        ;;
+    both)
+        run_control
+        run_treatment
+        echo ""
+        echo "=== Run $RUN_ID Complete ==="
+        echo "Score with: ./bench/score-v2.sh $RUN_ID"
+        ;;
+esac