<modernization_targets>$ARGUMENTS</modernization_targets>

Python Modernization Guide

The model applies modern Python 3.11+ patterns when writing or reviewing Python code.

Arguments

<modernization_targets/>

Instructions

If file paths provided:

Read each file
Identify legacy patterns
Apply modern transformations from the reference guide
Report changes made or recommended

If topic provided (e.g., "typing", "match-case"):

Provide guidance on that specific topic
Show before/after examples

If no arguments:

Ask what code to review or what topic to explain

Quick Reference: Modern Patterns

Type Hints (PEP 585, 604)

# Legacy (NEVER use)
from typing import List, Dict, Optional, Union

# Modern (ALWAYS use)
items: list[str]
config: dict[str, int] | None
value: int | str

Walrus Operator (PEP 572)

# Legacy
data = fetch_data()
if data:
    process(data)

# Modern
if data := fetch_data():
    process(data)

Match-Case (PEP 634)

Use match-case when using elif. Use if/elif only for inequalities or boolean operators.

# Modern (for any elif pattern)
match status_code:
    case 200:
        return "OK"
    case 404:
        return "Not Found"
    case _:
        return "Unknown"

Self Type (PEP 673)

from typing import Self


class Builder:
    def add(self, x: int) -> Self:
        self.value += x
        return self

Exception Notes (PEP 678)

except FileNotFoundError as e:
    e.add_note(f"Attempted path: {path}")
    raise

StrEnum (Python 3.11+)

from enum import StrEnum


class Status(StrEnum):
    PENDING = "pending"
    RUNNING = "running"

TOML Support (Python 3.11+)

import tomllib
from pathlib import Path

config = tomllib.load(Path("pyproject.toml").open("rb"))

Testing Patterns

ALWAYS use pytest-mock, NEVER unittest.mock:

# Legacy (NEVER use)
from unittest.mock import Mock, patch

# Modern (ALWAYS use)
from pytest_mock import MockerFixture


def test_feature(mocker: MockerFixture) -> None:
    mock_func = mocker.patch("module.function", return_value=42)

Framework Patterns

Typer CLI

ALWAYS use Annotated syntax:

from typing import Annotated
import typer


@app.command()
def process(
    input_file: Annotated[Path, typer.Argument(help="Input file")],
    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
) -> None:
    """Process input file."""
    pass

Rich Tables

Use explicit width control for production CLIs:

from rich.console import Console
from rich.table import Table
from rich.measure import Measurement


def _get_table_width(table: Table) -> int:
    temp_console = Console(width=9999)
    measurement = Measurement.get(temp_console, temp_console.options, table)
    return int(measurement.maximum)

Detailed Reference

For complete transformation rules, PEP references, and framework patterns, see:

references/modernization-guide.md

Core Principles

Use Python 3.11+ as minimum baseline
Leverage built-in generics (PEP 585) and pipe unions (PEP 604) exclusively
Apply walrus operator to reduce line count
Use match-case for elif patterns
Implement comprehensive type hints with Protocol, TypeVar, TypeGuard
Use Self type (PEP 673) for fluent APIs
Follow Typer patterns with Annotated syntax for CLIs
Use Rich for terminal output with proper width handling
Write pytest tests with pytest-mock and AAA pattern
Apply clean architecture with dependency injection

modernpython