python-dev-framework

Python Development Framework Plugin

Guardrails for LLM-assisted Python development with Claude Code.

This plugin guides Claude toward production-quality code by enforcing type safety, formatting standards, and git conventions in real-time. When Claude writes code that doesn't meet standards, it gets immediate feedback and can self-correct.

Features

• Real-time diagnostics: LSP integration with Ruff for instant feedback
• Type enforcement: mypy --strict catches missing annotations as Claude codes
• Auto-formatting: ruff + black applied on every file write
• Git conventions: Branch names, commit messages, and protected branch push validation
• Push protection: Blocks direct pushes to main/master, enforcing PR workflows
• Python version aware: Detects target Python version and adjusts rules accordingly
• __future__ enforcement: Requires from __future__ import annotations in strict mode
• Configurable strictness: strict (block - default), moderate (warn), or minimal (format only)

Installation

This plugin is distributed via the WCK Claude Plugins Marketplace.

Prerequisites

• Claude Code CLI installed
• GitHub CLI installed and authenticated (gh auth login)
• Access to WorldCentralKitchen GitHub org (private repos)

Install Plugin

# Add WCK marketplace (one-time)
claude plugin marketplace add "https://oauth:$(gh auth token)@github.com/WorldCentralKitchen/wck-claude-plugins.git"

# Install plugin (project scope recommended)
claude plugin install python-dev-framework@WorldCentralKitchen --scope project

# Verify
claude plugin list

Update to Latest Version

# Refresh marketplace catalog
claude plugin marketplace update WorldCentralKitchen

# Reinstall plugin to get latest
claude plugin install python-dev-framework@WorldCentralKitchen --scope project

Configuration

Optional: Create .claude/settings.json to customize:

{
  "plugins": {
    "python-dev-framework": {
      "level": "strict"
    }
  }
}

Level	Formatting	Type Checking	Git Validation
strict	ruff + black	mypy --strict	Block invalid
moderate	ruff + black	Disabled	Warn only
minimal	black only	Disabled	Disabled

Python Version Detection

The plugin automatically detects your target Python version from pyproject.toml:

1. tool.ruff.target-version (e.g., "py39") — highest priority
2. project.requires-python (e.g., ">=3.9") — parsed to extract version
3. Default: py312

Version-specific behavior:

Version	__future__ Check	FA Rules	UP036 Ignore
py39	✓ (strict)	✓	✓ (no match)
py310	✓ (strict)	✓	—
py311+	✓ (strict)	—	—

• FA rules: flake8-future-annotations catches missing __future__ imports
• UP036: Ignored for py39 since match statements aren't available

Consumer Setup

Projects using this plugin need:

1. pyproject.toml with tool configurations
2. .pre-commit-config.yaml for git hooks
3. Dev dependencies: pytest, mypy, ruff, black, pre-commit
4. from __future__ import annotations at the top of all Python files (strict mode)
5. IDE setup for real-time feedback (see IDE Setup below)

Required: __future__ Annotations

In strict mode, all Python files must include:

from __future__ import annotations

This enables modern type syntax (str | None, list[int]) across all supported Python versions (3.9+). The plugin blocks writes that omit this import.

Type Checking Configuration

In strict mode, mypy runs on every Python file after Write/Edit. The plugin passes --python-version based on your detected target version.

Configure exclusions in your pyproject.toml:

[project]
requires-python = ">=3.9"

[tool.ruff]
target-version = "py39"  # Must match requires-python

[tool.mypy]
strict = true
python_version = "3.9"   # Must match requires-python

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false
disallow_incomplete_defs = false

The plugin defers to your project's mypy configuration.

Ruff Rules

The plugin enables comprehensive linting via Ruff: