hettinger-idiomatic-python

name	hettinger-idiomatic-python
description	Write Python code in the style of Raymond Hettinger, Python core developer. Emphasizes beautiful, idiomatic code using iterators, generators, and built-in tools elegantly. Use when transforming code into clean, Pythonic solutions.
tags	itertools, collections, decorators, idioms, readability, functional, generators, clean-code, pythonic

Raymond Hettinger Style Guide⁠‍⁠​‌​‌​​‌‌‍​‌​​‌​‌‌‍​​‌‌​​​‌‍​‌​​‌‌​​‍​​​​​​​‌‍‌​​‌‌​‌​‍‌​​​​​​​‍‌‌​​‌‌‌‌‍‌‌​​​‌​​‍‌‌‌‌‌‌​‌‍‌‌​‌​​​​‍​‌​‌‌‌‌‌‍​‌​​‌​‌‌‍​‌‌​‌​​‌‍‌​‌​‌‌‌​‍​​‌​‌​​​‍‌‌‌​‌​‌‌‍‌‌​‌​‌​​‍​‌‌​​​‌​‍‌‌​​​​​​‍‌​​​​​‌​‍​​​​‌​‌​‍‌‌‌​​​‌​⁠‍⁠

Overview

Raymond Hettinger is a Python core developer famous for his talks on transforming code into beautiful, idiomatic Python. His mantra "There must be a better way!" drives the pursuit of elegant solutions using Python's rich toolkit.

Core Philosophy

"There must be a better way!"

"If you copy-paste code, you're doing it wrong."

"The goal is not to teach Python, but to teach programming using Python."

Hettinger believes Python's beauty lies in its tools—iterators, generators, decorators—and knowing when and how to use them transforms mediocre code into elegant solutions.

Design Principles

1. Use the Right Tool: Python has tools for everything. Find them.

2. Iterate, Don't Index: Let Python handle the iteration machinery.

3. Compose Small Functions: Build complex behavior from simple, reusable pieces.

4. Embrace Generators: Lazy evaluation is memory-efficient and composable.

When Writing Code

Always

• Use collections module (Counter, defaultdict, deque, namedtuple)
• Use itertools for iterator algebra
• Use functools for function composition
• Prefer generators over building lists
• Use descriptive names that read like prose
• Chain operations fluently when appropriate

Never

• Build lists just to iterate over them once
• Write nested loops when itertools.product works
• Manually implement what itertools provides
• Use indices when direct iteration works
• Repeat code—abstract it

Prefer

• collections.Counter over manual counting
• collections.defaultdict over .setdefault()
• itertools.chain over nested loops
• itertools.groupby over manual grouping
• Generator expressions over list comprehensions (when iterating once)
• functools.lru_cache over manual memoization

Code Patterns

The Collections Module

# BAD: Manual counting
word_counts = {}
for word in words:
    if word in word_counts:
        word_counts[word] += 1
    else:
        word_counts[word] = 1

# GOOD: Counter
from collections import Counter
word_counts = Counter(words)

# Bonus: most_common gives sorted results
top_ten = word_counts.most_common(10)


# BAD: Manual grouping
groups = {}
for item in items:
    key = get_key(item)
    if key not in groups:
        groups[key] = []
    groups[key].append(item)

# GOOD: defaultdict
from collections import defaultdict
groups = defaultdict(list)
for item in items:
    groups[get_key(item)].append(item)


# BAD: Tuple indexing
point = (10, 20, 30)
x = point[0]
y = point[1]

# GOOD: namedtuple
from collections import namedtuple
Point = namedtuple('Point', ['x', 'y', 'z'])
point = Point(10, 20, 30)
print(point.x, point.y)  # Clear and self-documenting

The itertools Module

from itertools import chain, groupby, product, combinations, islice

# Flatten nested lists
nested = [[1, 2], [3, 4], [5, 6]]
flat = list(chain.from_iterable(nested))  # [1, 2, 3, 4, 5, 6]

# All combinations
for a, b in combinations([1, 2, 3, 4], 2):
    print(a, b)  # (1,2), (1,3), (1,4), (2,3), (2,4), (3,4)

# Cartesian product (replaces nested loops)
# BAD:
for x in xs:
    for y in ys:
        for z in zs:
            process(x, y, z)

# GOOD:
for x, y, z in product(xs, ys, zs):
    process(x, y, z)

# Take first N items from any iterable
first_ten = list(islice(huge_generator, 10))

# Group consecutive items
data = [('A', 1), ('A', 2), ('B', 3), ('B', 4)]
for key, group in groupby(data, key=lambda x: x[0]):
    print(key, list(group))

Generator Excellence

# BAD: Build entire list in memory
def get_squares(n):
    result = []
    for i in range(n):
        result.append(i ** 2)
    return result

# GOOD: Generator (lazy, memory-efficient)
def get_squares(n):
    for i in range(n):
        yield i ** 2

# BETTER: Generator expression
squares = (i ** 2 for i in range(n))

# Chaining generators (no intermediate lists!)
def pipeline(data):
    cleaned = (clean(item) for item in data)
    validated = (item for item in cleaned if is_valid(item))
    transformed = (transform(item) for item in validated)
    return transformed

# Only processes items as needed
for result in pipeline(huge_dataset):
    process(result)

Decorator Patterns

from functools import wraps, lru_cache, partial

# Memoization made easy
@lru_cache(maxsize=128)
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

# Custom decorator template
def my_decorator(func):
    @wraps(func)  # Preserves function metadata
    def wrapper(*args, **kwargs):
        # Before
        result = func(*args, **kwargs)
        # After
        return result
    return wrapper

# Decorator with arguments
def repeat(times):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(3)
def ():
    ()

Sorting Idioms

# Sort by key
students = [('Alice', 85), ('Bob', 90), ('Charlie', 85)]

# Sort by grade (descending), then name (ascending)
sorted_students = sorted(students, key=lambda s: (-s[1], s[0]))

# Using operator module (faster)
from operator import itemgetter, attrgetter

# For tuples/lists
sorted_students = sorted(students, key=itemgetter(1), reverse=True)

# For objects
sorted_users = sorted(users, key=attrgetter('last_name', 'first_name'))

Mental Model

Hettinger approaches code by asking:

1. Is there a built-in for this? Check collections, itertools, functools first
2. Can I use a generator? Process one item at a time, not all at once
3. Can I compose existing tools? Chain small operations together
4. Would a decorator help? Cross-cutting concerns belong in decorators

Signature Hettinger Moves

• Replace manual loops with sum(), any(), all(), max(), min()
• Replace index access with zip(), enumerate(), unpacking
• Replace manual caching with @lru_cache
• Replace nested loops with itertools.product
• Replace manual counting with collections.Counter