Clean Python Modules

Modules should read as small, cohesive units. Keep related code close, expose one clear concept, and avoid abstractions that do not carry real responsibility.

M1: Keep Declarations Close To Use

Declare variables near the code that needs them. A value defined at the top of a function but used much later forces the reader to remember stale context.

# Bad - formatter is irrelevant until much later
def send_digest(users: list[User], now: datetime) -> Digest:
    formatter = DateFormatter("en_US")
    active_users = [user for user in users if user.active]
    recipients = [user.email for user in active_users]
    subject = f"Digest for {len(recipients)} users"
    return Digest(recipients=recipients, subject=subject, generated_at=formatter.format(now))