Decorators and Generators

@deco written above def f() is shorthand for defining f and then rebinding that name: f = deco(f). A decorator is any callable that takes the function object and returns the object the name will point at.

maxsize caps how many results are stored - 128 by default, None for unbounded, 0 for none - and a full table drops the least recently used entry. typed=True adds argument types to the key, so 1 and 1.0 stop sharing.

A class decorator is called with the finished class object, after the class body has already executed, and whatever it returns is bound to the class name. Most decorators mutate the class and return the same object.

Calling an async def function runs none of its body; it returns a coroutine object. A plain def wrapper only holds that unstarted coroutine, so anything it does around the call observes nothing. The wrapper must be async def and await inside.

@retry(times=3) calls retry(times=3) first and decorates with whatever that call returns. So retry must be a factory that returns a decorator, which then takes the function and returns the wrapper - three nested levels instead of two.

Give the class an iter method. The simplest implementation is to write iter as a generator function that yields each element: Python then gets a fresh iterator on every loop, and you never write next or raise StopIteration yourself.

An iterable can hand out a fresh iterator via iter. An iterator is the cursor itself: it defines next to produce one item at a time, and its own iter returns self, so every iterator is also an iterable.

A for loop calls iter() on the object once to get an iterator, then calls next() on that iterator repeatedly, binding each result to the loop variable. When next() raises StopIteration, the loop catches it and ends normally.

Return self only when the object is itself a cursor over a source that cannot be replayed, such as a stream reader; it is then one-shot. A container that must survive repeated and nested loops builds a new iterator per call.

Each loop over a list calls iter() and gets a brand-new cursor starting at the first element. A generator object is already the cursor: its iter returns self, so a second loop resumes at the end and finishes without running the body.

A generator object is its own iterator and holds one position. Once it has raised StopIteration it is exhausted for good, so a second for loop starts at the end and finishes immediately, silently and without an error.

A list comprehension builds every element and holds them all at once. A generator expression builds an object that produces one element per next() call, so peak memory tracks a single item rather than the whole result.

yield from <iterable> yields every value that iterable produces, replacing an explicit for-loop that re-yields inside a generator function. Unlike that loop, it also forwards send, throw and close to a subgenerator and binds its return value.

Calling it runs none of the body. You get back a generator object, which is an iterator. The body starts only on the first next() call and runs up to the first yield, then pauses there.

In Python 3 these builtins return lazy iterator objects rather than lists. Each is its own iterator with a single forward cursor, so the first consumer drains it and every later consumer sees an empty sequence.

itertools.permutations treats order as significant, so ('a','b') and ('b','a') are both yielded. itertools.combinations yields each selection once, keeping the input's own order. For n items taken r at a time that is n!/(n-r)! tuples versus n!/(r!(n-r)!).

itertools.groupby groups only consecutive items whose computed key is equal, and it never sorts. On unsorted input the same key reappears later and starts a fresh group, so sort by the same key function first.

itertools.count, cycle and repeat never raise StopIteration, so draining one runs forever. The consumer has to stop them: wrap with itertools.islice or itertools.takewhile, zip against a finite iterable, or break out of the loop.

Both yield the items of the inner iterables one level flatter, lazily. itertools.chain(*rows) unpacks the outer sequence into arguments first, so it must be finite and in memory; chain.from_iterable(rows) takes the outer iterable itself and pulls it lazily.

The built-in zip stops at the shortest input and silently discards the rest. itertools.zip_longest runs until the longest input is exhausted and substitutes fillvalue, which defaults to None, for every missing element.

any() returns False and all() returns True on an empty iterable. all() is vacuously true because no element failed the test; any() found no truthy element, so there is nothing to report as True.

enumerate yields (index, item) pairs straight from any iterable, so the loop body never indexes back into the sequence and the object needs no len(). The start argument only shifts the counter; it never skips items.

It returns the second argument. With only one argument, next raises StopIteration on an exhausted iterator; supplying a fallback turns exhaustion into an ordinary return value. Any other exception the iterator raises still propagates.

Arguments are evaluated before the call. A list comprehension runs the predicate on every element and allocates the whole list first, so any() short-circuits over a result that has already cost full time and memory.

zip stops the moment its shortest input is exhausted, so trailing items of longer inputs are dropped with no warning. Since Python 3.10, passing strict=True makes zip raise ValueError when the inputs turn out to be unequal in length.