modern-python-guidance 0.5.1

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):

claude mcp add mpg -- mpg mcp

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

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

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

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. Non-Python files and clean files produce no output.

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

For manual CLI use, mpg check --quiet <file> provides the same check without the "no patterns found" message.

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.