modern-python-guidance 0.5.8

Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python

modern-python-guidance

Stop your AI from writing typing.List, @validator, and setup.py. 41 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: AI writes modern Python 98% of the time with mpg, vs 79% without — even with vague prompts (Opus 4.8, V5 benchmark details)
• 41 guides across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
• Version-aware: auto-detects your project's Python version and filters guides accordingly
• 4 delivery methods: MCP server, CLI, Agent Skills, and Rules (auto-injects on .py file touch)
• 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

Claude Code (recommended)

pip install modern-python-guidance
mpg setup

This registers the MCP server, links Agent Skills, and creates a Rules file (.claude/rules/modern-python.md) in one command. The Rules file auto-injects modern Python guidance whenever you touch Python-related files. Start a new Claude Code session afterwards — newly registered MCP servers, skills, and rules take effect on the next launch.

CLI

pip install modern-python-guidance
mpg search "pydantic validator"
mpg retrieve pydantic-v2-validators

mpg is the short alias for modern-python-guidance. Both work.

Manual setup / other agents

MCP registration (Claude Code):

# uv tool / pipx installs (mpg is on PATH):
claude mcp add mpg -- mpg mcp

# venv installs — Claude Code spawns MCP servers outside your venv, so register
# the interpreter's absolute path (`mpg setup` does this automatically):
claude mcp add mpg -- "$(python -c 'import sys; print(sys.executable)')" -m modern_python_guidance mcp

Other MCP-compatible agents (Cursor, Windsurf, etc.) — add to your MCP config:

{
  "mcpServers": {
    "mpg": {
      "command": "mpg",
      "args": ["mcp"]
    }
  }
}

For venv installs, set "command" to your interpreter's absolute path and "args" to ["-m", "modern_python_guidance", "mcp"] for the same reason as above.

Agent Skills + Rules only (Claude Code):

mpg setup --skills-only

mpg setup flags:

Flag	Purpose
--mcp-only	MCP registration only
--skills-only	Project-local artifacts only (Skills + Rules)
--scope {user,local}	MCP scope (default: user)
--project-dir PATH	Target project for Skills/Rules symlinks
--dry-run	Show what would be done

After registering, mpg setup checks whether a same-name registration in a higher-precedence scope (local > project > user) would shadow the one it just wrote, and prints a warning with the exact claude mcp remove command if so.

Uninstall — reverse mpg setup (deregister the MCP server and unlink Agent Skills + Rules):

mpg uninstall            # remove all
mpg uninstall --dry-run  # preview what would be removed

Flag	Purpose
--mcp-only	MCP deregistration only
--skills-only	Project-local artifacts only (Skills + Rules)
--project-dir PATH	Target project for Skills/Rules symlinks
--dry-run	Show what would be done

mpg uninstall clears the MCP registration from every scope setup can write to (user and local), removes only the symlinks mpg created (never their targets or other files), and is idempotent — running it on an already-clean state is a harmless no-op.

CLI usage

# 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

# Scan a file for outdated patterns
mpg check app.py
mpg check app.py --format json | jq '.summary.guide_ids'
mpg check app.py --exit-zero  # always exit 0

# JSON output (default when piped, explicit with --format)
mpg search "typing" --format json | jq '.[0].id'

Guide coverage

41 guides across 3 layers:

Layer	Categories	Count	Examples
1 — stdlib	typing, async, stdlib, data-structures	18	list over List, match/case, TaskGroup, deferred annotations, t-strings
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 41 guides, or browse them on GitHub.

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. pyproject.toml Poetry python constraint (^3.10, ~3.11, >=3.10,<3.14)
4. .python-version file
5. Default: 3.11

# Only shows guides compatible with Python 3.9
mpg list --python-version 3.9
# Excludes: TaskGroup (3.11+), match/case (3.10+), etc.

Recommended hooks

Add a PostToolUse hook to auto-check Python files whenever Claude edits them. Create or update .claude/settings.json in your project:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"MultiEdit\"",
        "hooks": [
          {
            "type": "command",
            "command": "mpg hook claude-post-tool-use"
          }
        ]
      }
    ]
  }
}

The hook reads stdin from Claude Code, checks any .py file for outdated patterns, and surfaces findings as inline feedback. The project's target Python version is auto-detected from the nearest pyproject.toml (requires-python or Poetry's python constraint) or .python-version, walking up from the edited file — the same sources as mpg detect-version — so patterns that require a newer Python than your project targets are not flagged. The resolved target is shown in the summary line ([target: py3.X]). Non-Python files and clean files produce no output.

If mpg is installed in a venv (not uv tool/pipx), use the interpreter's absolute path in command: /path/to/venv/bin/python -m modern_python_guidance hook claude-post-tool-use.

Verify with /hooks in Claude Code to confirm the hook is active.

For manual CLI use, mpg check --quiet <file> --python-version X.Y runs the same check — pass your project's floor explicitly, since unlike the hook, mpg check does not auto-detect it.

Development

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 for project structure and guide authoring details.

License

Apache-2.0 OR MIT — see LICENSE and LICENSE-MIT.