prod-python

Production Python

Write Python like a senior developer — simple, readable, PEP-compliant. No AI slop. No over-engineering. No unnecessary abstractions.

Core principle: The best code is the simplest code that solves the problem correctly.

When to Use

• Writing any Python code (scripts, APIs, libraries, CLIs)
• Refactoring existing Python code
• Code reviews — flag AI patterns
• Code feels bloated, over-abstracted, or "AI-generated"

AI Slop — Eliminate on Sight

Module-Level Docstrings on Every File

# SLOP
"""User authentication module for handling login and registration."""

from flask import request

# CLEAN — filename says it all
from flask import request

Only add module docstrings for genuinely complex algorithms or non-obvious design decisions. Never add # src/path/file.py path comments.

Over-Documented Obvious Code

# SLOP — 20 lines to say "sum prices"
def calculate_total(items: List[Dict[str, Any]]) -> float:
    """
    Calculate the total price of items.

    Args:
        items: List of item dictionaries containing prices

    Returns:
        float: The total sum of all item prices

    Raises:
        ValueError: If items is empty
        KeyError: If price key missing
    """
    total = 0.0
    for item in items:
        total += item['price']
    return total

# CLEAN
def calculate_total(items: list[dict]) -> float:
    return sum(item['price'] for item in items)

Docstrings: one line max for obvious functions. Skip entirely if the signature tells the story.

Narrating Code with Comments

# SLOP
# Initialize the user list
users = []
# Loop through each record
for record in records:
    # Create user object
    user = User(record)
    # Append to list
    users.append(user)

# CLEAN
users = [User(r) for r in records]

Comments explain WHY, never WHAT. If you need to explain what code does, rewrite the code.

Legacy typing Imports

# SLOP — pre-3.9 style
from typing import List, Dict, Optional, Union, Tuple, Any

def process(data: List[Dict[str, Any]]) -> Optional[Dict[str, Union[str, int]]]:
    ...

# CLEAN — modern builtins + PEP 604
def process(data: list[dict]) -> dict | None:
    ...