{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"decorators","title":"Decorators: wrapping a function with retry, timing or a cache","url":"https://addaly.com/learn/python-for-ai/decorators","position":66,"of":89,"minutes":9,"answer":"A decorator is a function that takes a function and returns a replacement; @wraps keeps the original's name, and lru_cache on a model call returns the same answer forever for the same arguments.","keyIdea":"A decorator is a function that takes a function and returns a replacement; @wraps keeps the original's name, and lru_cache on a model call returns the same answer forever for the same arguments, which is a saving or a bug depending on whether you wanted fresh output."},"body":{"format":"markdown","text":"## Functions are values\n\nYou met this in module 3 when you passed a function to `sorted` as `key=`. A function can be stored in a variable, put in a list, passed as an argument, and returned from another function. A decorator uses all of that at once.\n\n```python\ndef shout(func):\n    def wrapper(*args, **kwargs):\n        result = func(*args, **kwargs)\n        return result.upper()\n    return wrapper\n\ndef greet(name):\n    return f\"hello {name}\"\n\ngreet = shout(greet)\nprint(greet(\"asha\"))          # HELLO ASHA\n```\n\n`shout` receives `greet`, builds a new function `wrapper` that calls `greet` and changes the result, and returns `wrapper`. The last line replaces the name `greet` with the wrapper. The `@` syntax is that last line moved to the top:\n\n```python\n@shout\ndef greet(name):\n    return f\"hello {name}\"\n```\n\nIdentical meaning. `@shout` above a `def` means \"after defining this, pass it through `shout` and bind the result to the same name\". That is all the syntax does.\n\n`*args, **kwargs` in the wrapper means it accepts whatever the original accepted and passes it straight through. `wrapper` closes over `func` (it remembers which function it wraps), which is the closure idea from the scope lesson doing real work.\n\n## `@wraps`\n\n```python\nprint(greet.__name__)     # wrapper\n```\n\nThe replacement has its own name and docstring, so tracebacks, logs and `help()` now say `wrapper` for every decorated function in the program. Fix it with `functools.wraps`, which copies the original's metadata onto the wrapper:\n\n```python\nfrom functools import wraps\n\ndef shout(func):\n    @wraps(func)\n    def wrapper(*args, **kwargs):\n        return func(*args, **kwargs).upper()\n    return wrapper\n```\n\nAlways. A decorator without `@wraps` is a small lie in every traceback.\n\n## A retry decorator\n\nModule 6 wrote a retry loop inline. As a decorator, it applies to any function by adding one line:\n\n```python\nimport random, time\nfrom functools import wraps\n\ndef retry(attempts=3, base=1.0, on=(ConnectionError,)):\n    def decorator(func):\n        @wraps(func)\n        def wrapper(*args, **kwargs):\n            for i in range(attempts):\n                try:\n                    return func(*args, **kwargs)\n                except on as e:\n                    if i == attempts - 1:\n                        raise\n                    delay = base * 2 ** i + random.uniform(0, 1)\n                    log.warning(\"%s failed (%s); retry in %.1fs\", func.__name__, e, delay)\n                    time.sleep(delay)\n        return wrapper\n    return decorator\n\n@retry(attempts=4, on=(requests.ConnectionError, requests.ConnectTimeout))\ndef fetch(url):\n    return session.get(url, timeout=(5, 30))\n```\n\nThree layers, because the decorator takes arguments: `retry(...)` returns `decorator`, which receives the function and returns `wrapper`. Read it from the inside out once and it stops being confusing.\n\nNote `on=`. The lesson on retries still applies: only retry exceptions that mean nothing happened. A decorator that retries on `Exception` will retry a read timeout on a paid `POST`.\n\n## Timing\n\n```python\ndef timed(func):\n    @wraps(func)\n    def wrapper(*args, **kwargs):\n        start = time.perf_counter()\n        try:\n            return func(*args, **kwargs)\n        finally:\n            log.info(\"%s took %.2fs\", func.__name__, time.perf_counter() - start)\n    return wrapper\n```\n\nThe `finally` makes the timing log appear even when the function raises, so a slow failure is visible as slow.\n\n## Caching, and the model-call question\n\n```python\nfrom functools import lru_cache\n\n@lru_cache(maxsize=1000)\ndef embed(text: str) -> tuple[float, ...]:\n    return tuple(client.embeddings.create(input=text, model=m).data[0].embedding)\n```\n\n`lru_cache` keeps a dict from arguments to result. The second call with the same `text` returns instantly and costs nothing. For embeddings (deterministic, expensive, often repeated) this is exactly right.\n\nTwo constraints follow from \"a dict keyed on the arguments\". The arguments must be **hashable**: strings, numbers, tuples yes; lists and dicts no, with a `TypeError` that names the type. Convert a list of messages to a tuple of tuples, or key on a string. And the cache lives in **memory** for the life of the process, so `maxsize=None` on a function called with a million distinct inputs is a slow memory leak. Set a size, or use a disk cache: module 9 builds one on `sqlite3`.\n\nNow the question. Should a chat completion be cached? At temperature 0 the same prompt gives nearly the same answer, so caching saves money during development when you re-run the same script twenty times. But a cached call is a call that will **never** return a different answer, and \"the model keeps saying the same thing\" is a confusing bug to chase when the cause is a decorator on a function three files away. Cache embeddings freely. Cache completions deliberately, with a way to turn it off, and never in a path where fresh output is the point.\n\n`cache_info()` on a cached function reports hits and misses; `cache_clear()` empties it. Both are useful in tests.\n\n## Decorators you already use\n\n`@dataclass`, `@property`, `@classmethod`, `@contextmanager`, `@pytest.fixture`, and the route decorators in web frameworks are all the same mechanism: a function that receives your function or class and returns something in its place. Knowing that, you can read what each one does by reading its source.\n\n## Order matters\n\n```python\n@timed\n@retry(attempts=3)\ndef fetch(url): ...\n```\n\nDecorators apply bottom-up: `retry` wraps `fetch`, then `timed` wraps the result. So the timing covers all attempts. Swap them and each attempt is timed separately. Neither is wrong; know which you asked for.\n\n## Try this now\n\nWrite `retry` and `timed`, stack them on a function that calls Ollama, and read the log with both orders. Then put `lru_cache` on an embedding function, call it twice with the same text, and check `cache_info()`."},"check":{"question":"A developer puts `@functools.lru_cache(maxsize=None)` on `ask(prompt: str)` to avoid paying twice for identical prompts. Later they change it to accept `ask(messages: list)` and every call raises `TypeError: unhashable type: 'list'`. What is the cache doing that a list breaks?","options":[{"text":"The cache keys a dict on the arguments, so each must be hashable; a list is not, while a string or a tuple is.","correct":true},{"text":"`lru_cache` serialises arguments to JSON to compare them, and lists cannot be serialised without a custom encoder.","correct":false,"tempting":"There is no JSON involved; the cache uses ordinary hashing, and lists are perfectly serialisable to JSON."},{"text":"`maxsize=None` disables the cache, so the decorator falls back to a strict mode that rejects mutable arguments.","correct":false,"tempting":"`maxsize=None` means unbounded, not disabled; the hashing requirement applies at every size."},{"text":"Lists are passed by reference and the cache refuses them to avoid returning a stale result when the list is later modified by the caller, which is a protection that strings do not need.","correct":false,"tempting":"That is a good reason to avoid caching on mutable arguments, but it is not what the error says; the mechanism is the hash requirement."}]},"prev":{"slug":"context-managers","title":"Context managers: the cleanup that runs even when the block raises","url":"https://addaly.com/learn/python-for-ai/context-managers"},"next":{"slug":"running-a-type-checker","title":"Running a type checker: the bugs it finds that tests do not","url":"https://addaly.com/learn/python-for-ai/running-a-type-checker"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Decorators: wrapping a function with retry, timing or a cache', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/decorators (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Decorators: wrapping a function with retry, timing or a cache","courseTitle":"Python, from Zero, for AI","module":{"index":7,"slug":"objects-and-the-shape-of-programs","title":"Objects, generators and the shape a larger program takes"},"answer":null,"keyIdea":"A decorator is a function that takes a function and returns a replacement; @wraps keeps the original’s name, and lru_cache on a model call returns the same answer forever for the same arguments, which is a saving or a bug depending on whether you wanted fresh output.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"functions-are-values","runs":[{"text":"Functions are values"}]},{"t":"p","runs":[{"text":"You met this in module 3 when you passed a function to "},{"text":"sorted","code":true},{"text":" as "},{"text":"key=","code":true},{"text":". A function can be stored in a variable, put in a list, passed as an argument, and returned from another function. A decorator uses all of that at once."}]},{"t":"code","lang":"python","label":"Python","text":"def shout(func):\n    def wrapper(*args, **kwargs):\n        result = func(*args, **kwargs)\n        return result.upper()\n    return wrapper\n\ndef greet(name):\n    return f\"hello {name}\"\n\ngreet = shout(greet)\nprint(greet(\"asha\"))          # HELLO ASHA"},{"t":"p","runs":[{"text":"shout","code":true},{"text":" receives "},{"text":"greet","code":true},{"text":", builds a new function "},{"text":"wrapper","code":true},{"text":" that calls "},{"text":"greet","code":true},{"text":" and changes the result, and returns "},{"text":"wrapper","code":true},{"text":". The last line replaces the name "},{"text":"greet","code":true},{"text":" with the wrapper. The "},{"text":"@","code":true},{"text":" syntax is that last line moved to the top:"}]},{"t":"code","lang":"python","label":"Python","text":"@shout\ndef greet(name):\n    return f\"hello {name}\""},{"t":"p","runs":[{"text":"Identical meaning. "},{"text":"@shout","code":true},{"text":" above a "},{"text":"def","code":true},{"text":" means “after defining this, pass it through "},{"text":"shout","code":true},{"text":" and bind the result to the same name”. That is all the syntax does."}]},{"t":"p","runs":[{"text":"*args, **kwargs","code":true},{"text":" in the wrapper means it accepts whatever the original accepted and passes it straight through. "},{"text":"wrapper","code":true},{"text":" closes over "},{"text":"func","code":true},{"text":" (it remembers which function it wraps), which is the closure idea from the scope lesson doing real work."}]},{"t":"h2","id":"wraps","runs":[{"text":"@wraps","code":true}]},{"t":"code","lang":"python","label":"Python","text":"print(greet.__name__)     # wrapper"},{"t":"p","runs":[{"text":"The replacement has its own name and docstring, so tracebacks, logs and "},{"text":"help()","code":true},{"text":" now say "},{"text":"wrapper","code":true},{"text":" for every decorated function in the program. Fix it with "},{"text":"functools.wraps","code":true},{"text":", which copies the original’s metadata onto the wrapper:"}]},{"t":"code","lang":"python","label":"Python","text":"from functools import wraps\n\ndef shout(func):\n    @wraps(func)\n    def wrapper(*args, **kwargs):\n        return func(*args, **kwargs).upper()\n    return wrapper"},{"t":"p","runs":[{"text":"Always. A decorator without "},{"text":"@wraps","code":true},{"text":" is a small lie in every traceback."}]},{"t":"h2","id":"a-retry-decorator","runs":[{"text":"A retry decorator"}]},{"t":"p","runs":[{"text":"Module 6 wrote a retry loop inline. As a decorator, it applies to any function by adding one line:"}]},{"t":"code","lang":"python","label":"Python","text":"import random, time\nfrom functools import wraps\n\ndef retry(attempts=3, base=1.0, on=(ConnectionError,)):\n    def decorator(func):\n        @wraps(func)\n        def wrapper(*args, **kwargs):\n            for i in range(attempts):\n                try:\n                    return func(*args, **kwargs)\n                except on as e:\n                    if i == attempts - 1:\n                        raise\n                    delay = base * 2 ** i + random.uniform(0, 1)\n                    log.warning(\"%s failed (%s); retry in %.1fs\", func.__name__, e, delay)\n                    time.sleep(delay)\n        return wrapper\n    return decorator\n\n@retry(attempts=4, on=(requests.ConnectionError, requests.ConnectTimeout))\ndef fetch(url):\n    return session.get(url, timeout=(5, 30))"},{"t":"p","runs":[{"text":"Three layers, because the decorator takes arguments: "},{"text":"retry(...)","code":true},{"text":" returns "},{"text":"decorator","code":true},{"text":", which receives the function and returns "},{"text":"wrapper","code":true},{"text":". Read it from the inside out once and it stops being confusing."}]},{"t":"p","runs":[{"text":"Note "},{"text":"on=","code":true},{"text":". The lesson on retries still applies: only retry exceptions that mean nothing happened. A decorator that retries on "},{"text":"Exception","code":true},{"text":" will retry a read timeout on a paid "},{"text":"POST","code":true},{"text":"."}]},{"t":"h2","id":"timing","runs":[{"text":"Timing"}]},{"t":"code","lang":"python","label":"Python","text":"def timed(func):\n    @wraps(func)\n    def wrapper(*args, **kwargs):\n        start = time.perf_counter()\n        try:\n            return func(*args, **kwargs)\n        finally:\n            log.info(\"%s took %.2fs\", func.__name__, time.perf_counter() - start)\n    return wrapper"},{"t":"p","runs":[{"text":"The "},{"text":"finally","code":true},{"text":" makes the timing log appear even when the function raises, so a slow failure is visible as slow."}]},{"t":"h2","id":"caching-and-the-model-call-question","runs":[{"text":"Caching, and the model-call question"}]},{"t":"code","lang":"python","label":"Python","text":"from functools import lru_cache\n\n@lru_cache(maxsize=1000)\ndef embed(text: str) -> tuple[float, ...]:\n    return tuple(client.embeddings.create(input=text, model=m).data[0].embedding)"},{"t":"p","runs":[{"text":"lru_cache","code":true},{"text":" keeps a dict from arguments to result. The second call with the same "},{"text":"text","code":true},{"text":" returns instantly and costs nothing. For embeddings (deterministic, expensive, often repeated) this is exactly right."}]},{"t":"p","runs":[{"text":"Two constraints follow from “a dict keyed on the arguments”. The arguments must be "},{"text":"hashable","b":true},{"text":": strings, numbers, tuples yes; lists and dicts no, with a "},{"text":"TypeError","code":true},{"text":" that names the type. Convert a list of messages to a tuple of tuples, or key on a string. And the cache lives in "},{"text":"memory","b":true},{"text":" for the life of the process, so "},{"text":"maxsize=None","code":true},{"text":" on a function called with a million distinct inputs is a slow memory leak. Set a size, or use a disk cache: module 9 builds one on "},{"text":"sqlite3","code":true},{"text":"."}]},{"t":"p","runs":[{"text":"Now the question. Should a chat completion be cached? At temperature 0 the same prompt gives nearly the same answer, so caching saves money during development when you re-run the same script twenty times. But a cached call is a call that will "},{"text":"never","b":true},{"text":" return a different answer, and “the model keeps saying the same thing” is a confusing bug to chase when the cause is a decorator on a function three files away. Cache embeddings freely. Cache completions deliberately, with a way to turn it off, and never in a path where fresh output is the point."}]},{"t":"p","runs":[{"text":"cache_info()","code":true},{"text":" on a cached function reports hits and misses; "},{"text":"cache_clear()","code":true},{"text":" empties it. Both are useful in tests."}]},{"t":"h2","id":"decorators-you-already-use","runs":[{"text":"Decorators you already use"}]},{"t":"p","runs":[{"text":"@dataclass","code":true},{"text":", "},{"text":"@property","code":true},{"text":", "},{"text":"@classmethod","code":true},{"text":", "},{"text":"@contextmanager","code":true},{"text":", "},{"text":"@pytest.fixture","code":true},{"text":", and the route decorators in web frameworks are all the same mechanism: a function that receives your function or class and returns something in its place. Knowing that, you can read what each one does by reading its source."}]},{"t":"h2","id":"order-matters","runs":[{"text":"Order matters"}]},{"t":"code","lang":"python","label":"Python","text":"@timed\n@retry(attempts=3)\ndef fetch(url): ..."},{"t":"p","runs":[{"text":"Decorators apply bottom-up: "},{"text":"retry","code":true},{"text":" wraps "},{"text":"fetch","code":true},{"text":", then "},{"text":"timed","code":true},{"text":" wraps the result. So the timing covers all attempts. Swap them and each attempt is timed separately. Neither is wrong; know which you asked for."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Write "},{"text":"retry","code":true},{"text":" and "},{"text":"timed","code":true},{"text":", stack them on a function that calls Ollama, and read the log with both orders. Then put "},{"text":"lru_cache","code":true},{"text":" on an embedding function, call it twice with the same text, and check "},{"text":"cache_info()","code":true},{"text":"."}]}],"check":{"question":[{"text":"A developer puts "},{"text":"@functools.lru_cache(maxsize=None)","code":true},{"text":" on "},{"text":"ask(prompt: str)","code":true},{"text":" to avoid paying twice for identical prompts. Later they change it to accept "},{"text":"ask(messages: list)","code":true},{"text":" and every call raises "},{"text":"TypeError: unhashable type: 'list'","code":true},{"text":". What is the cache doing that a list breaks?"}],"options":[{"text":[{"text":"The cache keys a dict on the arguments, so each must be hashable; a list is not, while a string or a tuple is."}],"correct":true,"tempting":null},{"text":[{"text":"lru_cache","code":true},{"text":" serialises arguments to JSON to compare them, and lists cannot be serialised without a custom encoder."}],"correct":false,"tempting":[{"text":"There is no JSON involved; the cache uses ordinary hashing, and lists are perfectly serialisable to JSON."}]},{"text":[{"text":"maxsize=None","code":true},{"text":" disables the cache, so the decorator falls back to a strict mode that rejects mutable arguments."}],"correct":false,"tempting":[{"text":"maxsize=None","code":true},{"text":" means unbounded, not disabled; the hashing requirement applies at every size."}]},{"text":[{"text":"Lists are passed by reference and the cache refuses them to avoid returning a stale result when the list is later modified by the caller, which is a protection that strings do not need."}],"correct":false,"tempting":[{"text":"That is a good reason to avoid caching on mutable arguments, but it is not what the error says; the mechanism is the hash requirement."}]}],"order":[2,1,3,0],"why":null},"prev":{"slug":"context-managers","title":"Context managers: the cleanup that runs even when the block raises","minutes":8},"next":{"slug":"running-a-type-checker","title":"Running a type checker: the bugs it finds that tests do not","minutes":9}}}