Layered tutor for any technical or coding topic

**LAYER 1 — Explain Like I'm 5** Imagine you have a favourite toy car. You love it exactly as it is, but you want it to sparkle. So you put it inside a clear box covered in glitter. The car hasn't changed at all — it's the same car — but now every time someone looks at it, they see glitter too. A decorator is that glitter box: it wraps something up without changing what's inside. --- **LAYER 2 — The Real Explanation** *What it is:* a decorator is a function that takes another function as input and returns a new function that usually calls the original one, with extra behaviour around it. *Why it exists:* you often want to add the same side concern — timing, logging, caching, access checks — to many functions. Without decorators you would paste that code into every one of them. *How it works:* in Python, functions are ordinary objects, so they can be passed around and returned like any other value. `@my_decorator` above a definition is just shorthand for `greet = my_decorator(greet)`. ```python import time def timed(func): # takes the original function def wrapper(*args, **kwargs): # accepts whatever the original accepts start = time.perf_counter() result = func(*args, **kwargs) # call the original, keep its result print(f"{func.__name__} took {time.perf_counter() - start:.4f}s") return result # hand the real result back to the caller return wrapper # this replaces the original name @timed def slow_add(a, b): time.sleep(0.1) return a + b ``` --- **LAYER 3 — Now I Get It** - `@decorator` is only syntax for reassigning the name to `decorator(original)`. - The wrapper must accept `*args, **kwargs` and return the original's result, or you have quietly broken the function. - Decorators run at definition time; the wrapper runs at call time. Confusing the two causes most surprises. --- **MISCONCEPTION ALERT** 1. Forgetting `functools.wraps`. Without it your decorated function reports the wrapper's `__name__` and loses its docstring, which breaks introspection, some frameworks, and `help()`. Put `@functools.wraps(func)` on the wrapper. 2. Assuming the decorator body runs on every call. It runs once, when the module is imported. Anything you want per call belongs inside the wrapper. --- **OPTIONAL — Further Exploration** - `functools.lru_cache` as a real-world decorator you already use - Decorators that take arguments (a third layer of nesting) - Class decorators and `contextlib.contextmanager`