The Decorator pattern — wrapping behavior at runtime

Python's @decorator syntax and the OOP Decorator pattern are related in spirit — both "wrap something to add behavior without changing its source" — but they're not the same mechanism. A Python decorator wraps a function, applied at definition time, affecting every call to that function. The Decorator pattern wraps an object instance, applied at runtime, affecting only that specific instance — two other instances of the same class, undecorated, behave completely normally.

Every combination of optional add-ons needs its own subclass — this explodes combinatorially, and it can't handle a customer choosing extras at runtime (a subclass hierarchy is fixed at compile time; you can't dynamically compose CoffeeWithMilk and CoffeeWithCaramel into a new class while the program is running).

Each decorator implements the same interface (Beverage) as the thing it wraps, holds a reference to the wrapped object, and calls through to it — adding its own contribution before or after. Because every decorator satisfies the same interface as a plain Coffee, decorators can be stacked in any combination, chosen entirely at runtime, without a single new subclass — SugarDecorator(MilkDecorator(Coffee())) and MilkDecorator(SugarDecorator(Coffee())) are both valid, and both are just Coffee instances as far as any code calling .cost() is concerned.

A subclass changes behavior for every instance of that subclass, decided at class-definition time. A decorator changes behavior for one specific wrapped instance, decided at the moment it's constructed — two Coffee objects can be wrapped completely differently, side by side, in the same running program. This is the concrete version of "favor composition over inheritance": instead of a rigid hierarchy baked in ahead of time, behavior is assembled out of independently swappable pieces at runtime, the same underlying idea the composition-over-inheritance lesson covers more generally.

Python's own built-in I/O stack is a real-world Decorator chain: wrapping a raw byte stream with a buffering layer, then a text-encoding layer, is exactly this pattern — each layer implements a compatible read/write interface, wraps the layer beneath it, and adds one specific capability. Django middleware (covered in its own lesson) is architecturally similar in spirit too: each middleware wraps "the rest of the chain," adding behavior before and after calling through to what it wraps — the same "wrap and delegate, adding your own contribution" shape, applied to request handling instead of objects.

An exploding number of subclasses covering every combination of optional features (WithMilk, WithSugar, WithMilkAndSugar, ...) is the tell — especially when which combination applies isn't known until runtime. If the combinations are fixed and small, plain subclassing is often simpler and doesn't need the extra indirection; Decorator earns its keep once the combinations are numerous, dynamic, or chosen by the end user.