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

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

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.1] — 2026-05-27
+
+### Changed
+
+- README rewrite: benefit-framed tagline, benchmark highlights, MCP-first quick start, persona-routed delivery methods
+- Moved project structure and guide authoring spec from README to CONTRIBUTING.md
+- Development section condensed to 5 lines + link
+
+### Added
+
+- CONTRIBUTING.md with project structure, guide authoring spec, and test instructions
+- Benchmark results (+21.9pp) featured in README highlights
+
 ## [0.2.0] — 2026-05-27
 
 ### Added

modern_python_guidance-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+## Project structure
+
+```
+src/modern_python_guidance/
+├── cli.py              # Entry point (search, retrieve, list, detect-version, mcp)
+├── mcp_server.py       # MCP server (JSON-RPC 2.0 over stdio)
+├── frontmatter.py      # YAML-subset parser (no PyYAML dependency)
+├── guide_index.py      # Guide discovery and indexing
+├── search.py           # Weighted keyword search + fuzzy fallback
+├── retrieve.py         # Guide retrieval and JSON rendering
+├── version_detect.py   # Python version auto-detection
+└── compat.py           # Shared helpers
+
+skills/modern-python-guidance/
+├── SKILL.md            # Agent Skills plugin entry point
+└── guides/             # 39 guide files by category
+```
+
+See [docs/design.md](docs/design.md) for the full design document.
+
+## Adding a new guide
+
+1. Create `skills/modern-python-guidance/guides/<category>/<id>.md`
+2. Include YAML frontmatter with these fields:
+
+| Field | Type | Values |
+|-------|------|--------|
+| `id` | string | Unique kebab-case identifier (must match filename) |
+| `title` | string | Short descriptive title |
+| `category` | string | Must match parent directory name |
+| `layer` | int | 1 (stdlib), 2 (frameworks), 3 (toolchain) |
+| `tags` | list | Search keywords |
+| `aliases` | list | Alternate names (old API names, etc.) |
+| `python` | string | Minimum version, e.g. `">=3.11"` |
+| `frequency` | string | `high` (LLMs do this often), `medium`, `low` |
+
+3. Write BAD/GOOD/Why/Version Notes sections
+4. Run `pytest` to verify the guide parses correctly
+
+## Running tests
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.2.0
+Version: 0.2.1
 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,29 +36,65 @@ 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 39 version-aware BAD/GOOD pattern guides that show the modern replacement, filtered by your project's Python version.
+Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
+
+## Highlights
+
+- **Measurable impact**: +14.7pp overall improvement in A/B benchmark with 38 scored items ([details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
+- **39 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
+- **Version-aware**: auto-detects your project's Python version and filters guides accordingly
+- **3 delivery methods**: MCP server, CLI, Agent Skills plugin
+- **Not Ruff**: Ruff auto-fixes syntax (`List` → `list`). mpg guides design decisions that Ruff can't touch — `TaskGroup` over `gather`, Pydantic V2 migration, SQLAlchemy 2.0 style
 
 > **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.
 
 ## Quick start
 
+### MCP (for AI coding agents)
+
+Install, then register the MCP server with your agent:
+
+```bash
+pip install modern-python-guidance
+```
+
+**Claude Code:**
+```bash
+claude mcp add mpg -- mpg mcp
+```
+
+**Other MCP-compatible agents** (Cursor, Windsurf, etc.) — add to your MCP config:
+```json
+{
+  "mcpServers": {
+    "mpg": {
+      "command": "mpg",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Your agent gets access to `search_guides`, `retrieve_guides`, `list_guides`, and `detect_python_version`.
+
+### CLI
+
 ```bash
-# Install
 pip install modern-python-guidance
 
 # Search for a pattern
 mpg search "pydantic validator"
-#   pydantic-v2-validators                   score=18.0  [pydantic]
 
 # Get the full guide
 mpg retrieve pydantic-v2-validators
-# --- pydantic-v2-validators (version match: YES) ---
-# ## BAD
-# @validator("name")
-# ...
-# ## GOOD
-# @field_validator("name")
-# ...
+```
+
+### Agent Skills (Claude Code plugin)
+
+```bash
+# Symlink into your project
+SKILL_DIR=$(python -c "from pathlib import Path; import modern_python_guidance; print(Path(modern_python_guidance.__file__).parent / 'skills' / 'modern-python-guidance')")
+ln -s "$SKILL_DIR" your-project/.claude/skills/modern-python-guidance
 ```
 
 `mpg` is the short alias for `modern-python-guidance`. Both work.
@@ -112,54 +148,6 @@ mpg list --python-version 3.9
 # Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
 ```
 
-## MCP server
-
-mpg includes a built-in [MCP](https://modelcontextprotocol.io) server that exposes all 4 commands as tools. AI agents (Claude Code, Cursor, Gemini CLI, etc.) can discover and call them directly.
-
-### Setup with Claude Code
-
-```bash
-claude mcp add mpg -- mpg mcp
-```
-
-Or add to `.mcp.json` manually:
-
-```json
-{
-  "mcpServers": {
-    "mpg": {
-      "command": "mpg",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-### Available tools
-
-| Tool | Description |
-|------|-------------|
-| `search_guides` | Search guides by keyword with fuzzy matching |
-| `retrieve_guides` | Get full BAD/GOOD content by guide ID |
-| `list_guides` | Browse all guides, filter by category/version |
-| `detect_python_version` | Auto-detect project Python version |
-
-The MCP server uses stdio transport (JSON-RPC 2.0) and adds zero additional dependencies.
-
-## Agent Skills integration
-
-This project doubles as a [Claude Code Agent Skills](https://docs.anthropic.com/en/docs/claude-code) plugin. Install it into your project's `.claude/skills/` to give Claude automatic access to modern Python patterns when writing or reviewing code.
-
-```bash
-# Find where the package is installed
-SKILL_DIR=$(python -c "from pathlib import Path; import modern_python_guidance; print(Path(modern_python_guidance.__file__).parent / 'skills' / 'modern-python-guidance')")
-
-# Symlink into your project
-ln -s "$SKILL_DIR" your-project/.claude/skills/modern-python-guidance
-```
-
-For other AI tools (Cursor, Copilot, etc.), use the CLI directly — pipe `mpg search` or `mpg retrieve` output into your workflow.
-
 ## Development
 
 ```bash
@@ -168,49 +156,9 @@ cd modern-python-guidance
 uv venv && source .venv/bin/activate
 uv pip install -e ".[dev]"
 pytest
-ruff check src/ tests/
 ```
 
-### Project structure
-
-```
-src/modern_python_guidance/
-├── cli.py              # Entry point (search, retrieve, list, detect-version, mcp)
-├── mcp_server.py       # MCP server (JSON-RPC 2.0 over stdio)
-├── frontmatter.py      # YAML-subset parser (no PyYAML dependency)
-├── guide_index.py      # Guide discovery and indexing
-├── search.py           # Weighted keyword search + fuzzy fallback
-├── retrieve.py         # Guide retrieval and JSON rendering
-├── version_detect.py   # Python version auto-detection
-└── compat.py           # Shared helpers
-
-skills/modern-python-guidance/
-├── SKILL.md            # Agent Skills plugin entry point
-└── guides/             # 39 guide files by category
-```
-
-See [docs/design.md](docs/design.md) for the full design document.
-
-## Contributing
-
-Contributions welcome! To add a new guide:
-
-1. Create `skills/modern-python-guidance/guides/<category>/<id>.md`
-2. Include YAML frontmatter with these fields:
-
-| Field | Type | Values |
-|-------|------|--------|
-| `id` | string | Unique kebab-case identifier (must match filename) |
-| `title` | string | Short descriptive title |
-| `category` | string | Must match parent directory name |
-| `layer` | int | 1 (stdlib), 2 (frameworks), 3 (toolchain) |
-| `tags` | list | Search keywords |
-| `aliases` | list | Alternate names (old API names, etc.) |
-| `python` | string | Minimum version, e.g. `">=3.11"` |
-| `frequency` | string | `high` (LLMs do this often), `medium`, `low` |
-
-3. Write BAD/GOOD/Why/Version Notes sections
-4. Run `pytest` to verify the guide parses correctly
+See [CONTRIBUTING.md](CONTRIBUTING.md) for project structure and guide authoring details.
 
 ## License
 

modern_python_guidance-0.2.1/README.md

@@ -0,0 +1,134 @@
+# modern-python-guidance
+
+[![CI](https://github.com/yottayoshida/modern-python-guidance/actions/workflows/ci.yml/badge.svg)](https://github.com/yottayoshida/modern-python-guidance/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
+[![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)
+
+Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
+
+## Highlights
+
+- **Measurable impact**: +14.7pp overall improvement in A/B benchmark with 38 scored items ([details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
+- **39 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
+- **Version-aware**: auto-detects your project's Python version and filters guides accordingly
+- **3 delivery methods**: MCP server, CLI, Agent Skills plugin
+- **Not Ruff**: Ruff auto-fixes syntax (`List` → `list`). mpg guides design decisions that Ruff can't touch — `TaskGroup` over `gather`, Pydantic V2 migration, SQLAlchemy 2.0 style
+
+> **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.
+
+## Quick start
+
+### MCP (for AI coding agents)
+
+Install, then register the MCP server with your agent:
+
+```bash
+pip install modern-python-guidance
+```
+
+**Claude Code:**
+```bash
+claude mcp add mpg -- mpg mcp
+```
+
+**Other MCP-compatible agents** (Cursor, Windsurf, etc.) — add to your MCP config:
+```json
+{
+  "mcpServers": {
+    "mpg": {
+      "command": "mpg",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Your agent gets access to `search_guides`, `retrieve_guides`, `list_guides`, and `detect_python_version`.
+
+### CLI
+
+```bash
+pip install modern-python-guidance
+
+# Search for a pattern
+mpg search "pydantic validator"
+
+# Get the full guide
+mpg retrieve pydantic-v2-validators
+```
+
+### Agent Skills (Claude Code plugin)
+
+```bash
+# Symlink into your project
+SKILL_DIR=$(python -c "from pathlib import Path; import modern_python_guidance; print(Path(modern_python_guidance.__file__).parent / 'skills' / 'modern-python-guidance')")
+ln -s "$SKILL_DIR" your-project/.claude/skills/modern-python-guidance
+```
+
+`mpg` is the short alias for `modern-python-guidance`. Both work.
+
+## CLI usage
+
+```bash
+# Search guides by keyword
+mpg search "pydantic validator"
+
+# Retrieve a specific guide (full BAD/GOOD content)
+mpg retrieve use-builtin-generics
+
+# List all guides compatible with your Python version
+mpg list --python-version 3.11
+
+# Auto-detect project Python version from pyproject.toml / .python-version
+mpg detect-version
+
+# Filter by category
+mpg search "timeout" --category async
+
+# JSON output (default when piped, explicit with --format)
+mpg search "typing" --format json | jq '.[0].id'
+```
+
+## Guide coverage
+
+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, 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 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+
+## Version-aware filtering
+
+Guides specify their minimum Python version. The CLI auto-detects your project's version from (in order):
+
+1. `--python-version` flag
+2. `pyproject.toml` `requires-python`
+3. `.python-version` file
+4. Default: 3.11
+
+```bash
+# Only shows guides compatible with Python 3.9
+mpg list --python-version 3.9
+# Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
+```
+
+## Development
+
+```bash
+git clone https://github.com/yottayoshida/modern-python-guidance.git
+cd modern-python-guidance
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for project structure and guide authoring details.
+
+## License
+
+Apache-2.0 OR MIT — see [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT).

modern_python_guidance-0.2.1/bench/fixtures/variant-a-modern/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "benchmark-app"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi",
+    "sqlalchemy[asyncio]",
+    "httpx",
+    "uvicorn",
+]
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

modern_python_guidance-0.2.1/bench/fixtures/variant-a-modern/src/app.py

@@ -0,0 +1,36 @@
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+
+engine = create_async_engine("sqlite+aiosqlite:///db.sqlite3")
+async_session = async_sessionmaker(engine, expire_on_commit=False)
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        yield session
+
+
+DbSession = Annotated[AsyncSession, Depends(get_db)]
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with engine.begin() as conn:
+        pass
+    yield {"db_pool": engine}
+    await engine.dispose()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/users")
+async def list_users(db: DbSession):
+    result = await db.execute(select(User))
+    return result.scalars().all()

modern_python_guidance-0.2.1/bench/fixtures/variant-a-modern/src/config.py

@@ -0,0 +1,20 @@
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from datetime import datetime, UTC
+
+
+@dataclass(slots=True)
+class AppConfig:
+    db_url: str
+    debug: bool = False
+    created_at: datetime = None
+
+    def __post_init__(self):
+        if self.created_at is None:
+            self.created_at = datetime.now(UTC)
+
+
+def load_config(path: Path) -> dict:
+    with open(path, "rb") as f:
+        return tomllib.load(f)

modern_python_guidance-0.2.1/bench/fixtures/variant-a-modern/src/crawler.py

@@ -0,0 +1,24 @@
+import asyncio
+
+import httpx
+
+
+async def crawl(urls: list[str]) -> list[str]:
+    results = []
+    async with httpx.AsyncClient() as client:
+        async with asyncio.TaskGroup() as tg:
+            for url in urls:
+                tg.create_task(_fetch(client, url, results))
+    return results
+
+
+async def _fetch(client: httpx.AsyncClient, url: str, results: list[str]) -> None:
+    async with asyncio.timeout(30):
+        response = await client.get(url)
+        results.append(response.text)
+
+
+async def download_large(client: httpx.AsyncClient, url: str, dest: str) -> None:
+    async with client.stream("GET", url) as resp:
+        async for chunk in resp.aiter_bytes():
+            pass

modern_python_guidance-0.2.1/bench/fixtures/variant-a-modern/src/models.py

@@ -0,0 +1,71 @@
+from datetime import datetime, UTC
+from typing import override
+
+from pydantic import BaseModel, ConfigDict, field_validator, field_serializer, model_validator
+from sqlalchemy import String, select
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+    email: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(default=datetime.now(UTC))
+
+
+class UserCreate(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    name: str
+    email: str | None = None
+
+    @field_validator("name")
+    @classmethod
+    def name_not_empty(cls, v: str) -> str:
+        if not v:
+            raise ValueError("Name cannot be empty")
+        return v
+
+    @field_serializer("email")
+    def mask_email(self, v: str | None) -> str | None:
+        if v is None:
+            return None
+        local, domain = v.split("@")
+        return f"{local[0]}***@{domain}"
+
+
+class UserResponse(BaseModel):
+    id: int
+    name: str
+    email: str | None = None
+
+    @model_validator(mode="after")
+    def check_consistency(self):
+        return self
+
+    def to_dict(self) -> dict:
+        return self.model_dump()
+
+    @classmethod
+    def from_orm(cls, obj):
+        return cls.model_validate(obj, from_attributes=True)
+
+
+class Registry[T]:
+    def __init__(self) -> None:
+        self._items: dict[str, T] = {}
+
+    @override
+    def __repr__(self) -> str:
+        return f"Registry({list(self._items.keys())})"
+
+    def add(self, key: str, value: T) -> None:
+        self._items[key] = value
+
+    def get(self, key: str) -> T | None:
+        return self._items.get(key)

modern_python_guidance-0.2.1/bench/fixtures/variant-a-modern/src/scanner.py

@@ -0,0 +1,42 @@
+import asyncio
+from enum import Enum
+from pathlib import Path
+
+
+class FileCategory(Enum):
+    IMAGE = "image"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    OTHER = "other"
+
+
+def categorize(ext: str) -> FileCategory:
+    match ext:
+        case ".jpg" | ".png" | ".gif":
+            return FileCategory.IMAGE
+        case ".mp4" | ".avi":
+            return FileCategory.VIDEO
+        case ".pdf" | ".docx":
+            return FileCategory.DOCUMENT
+        case _:
+            return FileCategory.OTHER
+
+
+def parse_log_line(line: str) -> str:
+    return line.removeprefix("[INFO] ").removesuffix("\n")
+
+
+async def safe_scan(paths: list[Path]) -> list[FileCategory]:
+    results = []
+    try:
+        async with asyncio.TaskGroup() as tg:
+            for p in paths:
+                tg.create_task(_scan_one(p, results))
+    except* OSError as eg:
+        for exc in eg.exceptions:
+            print(f"OS error: {exc}")
+    return results
+
+
+async def _scan_one(p: Path, results: list[FileCategory]) -> None:
+    results.append(categorize(p.suffix))

modern_python_guidance-0.2.1/bench/fixtures/variant-a-modern/src/utils.py

@@ -0,0 +1,17 @@
+import subprocess
+from typing import ParamSpec, TypeIs
+
+P = ParamSpec("P")
+
+
+def merge_defaults(user: dict, defaults: dict) -> dict:
+    return defaults | user
+
+
+def run_command(cmd: str, *extra: str) -> str:
+    result = subprocess.run([cmd, *extra], capture_output=True, text=True, check=True)
+    return result.stdout
+
+
+def is_positive_int(val: object) -> TypeIs[int]:
+    return isinstance(val, int) and val > 0

modern_python_guidance-0.2.1/bench/fixtures/variant-a-outdated/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "benchmark-app"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi",
+    "sqlalchemy",
+    "httpx",
+    "uvicorn",
+]
+
+[tool.black]
+line-length = 88
+
+[tool.isort]
+profile = "black"
+
+[tool.flake8]
+max-line-length = 88

modern_python_guidance-0.2.1/bench/fixtures/variant-a-outdated/setup.py

@@ -0,0 +1,7 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="benchmark-app",
+    version="0.1.0",
+    packages=find_packages(),
+)

modern_python_guidance-0.2.1/bench/fixtures/variant-a-outdated/src/app.py

@@ -0,0 +1,32 @@
+from fastapi import Depends, FastAPI
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+engine = create_engine("sqlite:///db.sqlite3")
+SessionLocal = sessionmaker(bind=engine)
+
+app = FastAPI()
+
+
+@app.on_event("startup")
+async def startup():
+    app.state.db_engine = engine
+
+
+@app.on_event("shutdown")
+async def shutdown():
+    engine.dispose()
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+@app.get("/users")
+def list_users(db: Session = Depends(get_db)):
+    users = db.query(User).all()
+    return users