CS Fundamentals Trainer · Guias

Decoradores, geradores e async em Python

Decoradores construídos com closures, functools.wraps e lru_cache (e a armadilha dos métodos), pipelines preguiçosos de geradores, corrotinas e o laço de eventos, gather contra await sequencial, cancelamento, TaskGroup e nunca bloquear o laço.

18 min de leitura

Decoradores, geradores e async/await parecem três recursos sem relação, e compartilham uma ideia: uma função é um valor, e uma função pode ser suspensa. Um decorador recebe uma função e devolve outra. Um gerador é uma função que pausa em yield e mantém suas variáveis locais até ser pedido que continue. Uma corrotina é a mesma maquinaria apontada para a espera por E/S. Se você entende os dois primeiros, o asyncio deixa de ser mágica. Este guia constrói cada um do zero e mede as partes que importam (o custo de um wrapper, o que o lru_cache traz e o que mantém vivo, como se comportam pipelines preguiçosos, o que a concorrência no asyncio realmente entrega). Ele pressupõe como o Python funciona; os scripts, rodados no CPython 3.13, estão no apêndice. Para as escolhas de desempenho entre threads, processos e asyncio, veja desempenho e concorrência em Python.

1. Decoradores

Um decorador é uma função que recebe uma função

def shout(fn):
    def wrapper(*args, **kwargs):
        return fn(*args, **kwargs).upper()
    return wrapper

@shout
def greet(name):
    return f"hello {name}"

A linha @shout é exatamente greet = shout(greet). O nome greet agora se refere a wrapper, que fecha sobre a função original (veja closures em como o Python funciona). greet("ana") retornou HELLO ANA.

Três fatos explicam quase todo bug de decorador:

Sempre use functools.wraps

Sem ele, greet.__name__ era 'wrapper' e greet.__doc__ era None, o que quebra tracebacks, ferramentas de documentação e tudo que inspeciona a função. Decorar o wrapper com @functools.wraps(fn) copia os metadados e também define __wrapped__, que aponta de volta para o original (greet2.__wrapped__("x") retornou hello x, sem o wrapper).

Decoradores com argumentos

@retry(3) é uma chamada que precisa retornar um decorador, então há três níveis aninhados: a fábrica recebe o argumento, o decorador recebe a função, o wrapper recebe a chamada:

def retry(times):
    def deco(fn):
        @functools.wraps(fn)
        def wrapper(*a, **k):
            for attempt in range(1, times + 1):
                try:
                    return fn(*a, **k)
                except ValueError:
                    if attempt == times:
                        raise
        return wrapper
    return deco

Uma função que falhou duas vezes e teve sucesso na terceira chamada retornou ok, com as duas falhas registradas. (Tentar de novo deve vir junto com um atraso, um limite do que se repete e operações idempotentes: veja padrões de resiliência.)

Uma classe também pode ser um decorador, implementando __call__; isso é conveniente quando o wrapper precisa de estado. Uma classe Count que guardava um contador de chamadas informou 2 depois de duas chamadas. Use functools.update_wrapper ali para a mesma cópia de metadados. functools.partial é parecido mas diferente: ele preenche argumentos de antemão (partial(int, base=2)("101") deu 5).

O que um wrapper custa

Um wrapper é uma chamada Python extra a cada invocação. Um milhão de chamadas levou 73 ms para uma função simples e 177 ms quando ela foi envolvida por um decorador de passagem direta: cerca de 100 ns a mais por chamada. Isso não é nada perto de uma consulta ao banco de dados e é perceptível em uma função chamada dezenas de milhões de vezes em um laço apertado, que é quando você faria o profile primeiro.

functools.lru_cache

Um decorador de cache guarda resultados por argumentos. fib(27) calculada recursivamente levou 40 ms sem cache e 0,05 ms com @functools.lru_cache(maxsize=None); seu cache_info() informou hits=25, misses=28, porque cada valor foi calculado uma vez. Quatro regras impedem que ele se volte contra você:

Para resultados que precisam expirar (uma chamada remota, um valor de banco de dados), use um cache com limite de tempo; veja estratégias de cache.

Usos comuns de decoradores além desses: medição de tempo e logging, verificações de autorização, registro de rotas ou handlers (@app.route), e @staticmethod, @classmethod, @property e @dataclass, que são todos decoradores. Para mais de dois ou três níveis de aninhamento, uma classe ou um gerenciador de contexto costuma ser mais claro.

2. Geradores

Uma função que pausa

Uma função que contém yield é uma função geradora: chamá-la não executa o corpo; retorna um objeto gerador. Cada next() roda até o próximo yield, devolve o valor e congela as variáveis locais e a posição até o próximo next(). Quando o corpo termina, StopIteration é levantada.

Geradores também podem receber valores. Neste acumulador, send(x) retoma o yield pausado com x como seu valor:

def accumulator():
    total = 0
    while True:
        x = yield total
        if x is None: break
        total += x

Depois de preparado com next(g), g.send(10), g.send(5) e g.send(1) retornaram 10, 15 e 16. Esse canal de mão dupla é a ideia sobre a qual as corrotinas são construídas (seção 3).

Pipelines são preguiçosos

Encadear geradores monta um pipeline em que cada valor passa por todas as etapas, um de cada vez, e nada é calculado até alguém pedir. Montei read_lines() (que imprime cada linha que produz), depois as etapas nonempty() e lengths(). Pedir o primeiro resultado imprimiu apenas produced 'a' e retornou 1: a fonte tinha lido uma linha, não cinco. É assim que se processa um arquivo maior que a memória, ou se para cedo sem pagar pelo resto. Medido em como o Python funciona: somar 10 milhões de quadrados precisou de cerca de 409 MB com uma lista e 1,4 KB com um gerador.

Delegação e limpeza

Lembre do guia anterior que um gerador é de uso único: iterá-lo uma segunda vez não produz nada. Se você precisa percorrer duas vezes, guarde uma lista ou chame a função geradora de novo.

3. async e await

Corrotinas

Uma função definida com async def é uma função corrotina: chamá-la retorna um objeto corrotina e não executa nada. Chamei work("a", 0.1) e obtive um objeto do tipo coroutine. Uma corrotina é um objeto parecido com um gerador cujas pausas acontecem em await. Algo precisa conduzi-la: o laço de eventos, que roda corrotinas em uma thread e, sempre que uma espera algo que não está pronto (um temporizador, um socket), passa para outra.

asyncio.run(main()) inicia um laço e roda uma corrotina de nível superior até ela terminar.

Await em sequência não é concorrente

O erro mais comum é escrever await um depois do outro e esperar sobreposição. Três esperas de 0,2 s:

Como foram executadasTempo total
await a(); await b(); await c()0,60 s
await asyncio.gather(a(), b(), c())0,20 s

await significa "espere aqui até isto terminar". Para sobrepor, inicie o trabalho primeiro (gather, create_task ou um TaskGroup) e dê await no grupo.

Esquecer o await

Se você chama uma função corrotina e nunca dá await no resultado, nada acontece, exceto que o Python avisa quando o objeto é destruído: coroutine 'work' was never awaited. Trate esse aviso como um bug.

Timeouts, cancelamento e grupos

A regra que mantém o asyncio rápido

O laço roda em uma thread, então uma corrotina nunca deve bloquear. Um time.sleep(0.2), uma chamada HTTP síncrona, um driver de banco de dados que não é assíncrono ou um cálculo grande dentro de uma corrotina congela todas as outras tarefas durante todo o tempo. No guia anterior, cinco tarefas chamando time.sleep(0.2) levaram 1,00 s em vez de 0,2 s. Para chamadas bloqueantes use await asyncio.to_thread(fn, ...) (uma thread), ou um pool de processos para trabalho de CPU, ou uma biblioteca assíncrona.

E o asyncio não deixa o cálculo mais rápido: ele torna a espera concorrente. Ele brilha com muitas conexões que passam a maior parte do tempo ociosas, como servidores, crawlers e clientes de API (compare com o projeto do web crawler).

Threads ou async?

Threadsasyncio
Trocao SO interrompe a qualquer momentosó em await
Condições de corridapossíveis em qualquer lugar (use locks)só entre pontos de await, portanto bem menos
Bibliotecasqualquer biblioteca bloqueante funcionaexige bibliotecas assíncronas
Escalamilhares de threads é pesadodezenas de milhares de tarefas é rotina
Depuraçãomais difícil de raciocinaruma thread, mais fácil de raciocinar, mas a "coloração" se espalha: quem chama funções assíncronas também precisa ser assíncrono

4. Erros comuns

5. Perguntas que os entrevistadores gostam de fazer

"O que faz o @decorator?"

É a forma abreviada de f = decorator(f) na hora da definição. O decorador devolve um substituto, normalmente um wrapper que fecha sobre o original.

"Por que usar functools.wraps?"

Para copiar o nome, a docstring e outros metadados da função envolvida para o wrapper, e para expor o original como __wrapped__.

"Como você escreveria um decorador que recebe argumentos?"

Uma função que recebe os argumentos e devolve o decorador de verdade, que devolve o wrapper: três funções aninhadas (ou uma classe com __init__ e __call__).

"Qual é a diferença entre um gerador e uma lista?"

Um gerador produz valores de forma preguiçosa, um de cada vez, em memória constante, e pode ser consumido uma vez. Uma lista guarda todos os valores e permite indexação e reutilização.

"Como o yield se relaciona com async/await?"

Os dois suspendem uma função e a retomam depois com o estado local intacto. As corrotinas são conduzidas por um laço de eventos que as retoma quando aquilo que elas esperavam fica pronto. No Python antigo, as corrotinas eram literalmente geradores com yield from.

"Como você executa coisas de forma concorrente no asyncio?"

Inicie-as juntas com asyncio.gather, create_task ou um TaskGroup, e depois dê await no grupo. Dar await em uma depois da outra é sequencial.

"O que acontece se você chama uma função bloqueante dentro de uma corrotina?"

O laço de eventos inteiro para até ela retornar, então todas as outras tarefas travam. Use uma biblioteca assíncrona, asyncio.to_thread ou um pool de processos.

"Por que o lru_cache pode causar um vazamento de memória?"

Em um método, o self entra na chave, então o cache mantém todas as instâncias vivas; com maxsize=None ele também cresce sem limite.

6. Coisas a mencionar em uma entrevista

Resumo rápido

Apêndice: o código dos experimentos

Python 3.13 (CPython), apenas biblioteca padrão (TaskGroup e except* exigem 3.11 ou posterior). Rode cada arquivo com python3 file.py. Os tempos variam conforme a máquina; os comportamentos e a ordem dos eventos devem ser os mesmos.

decorators.py: decoradores, wraps, argumentos, empilhamento, lru_cache, decoradores de classe e o custo do wrapper:

import functools, time, timeit

# 1. a decorator is just f = deco(f)
def shout(fn):
    def wrapper(*a, **k):
        return fn(*a, **k).upper()
    return wrapper
@shout
def greet(name):
    """Say hello."""
    return f"hello {name}"
print(greet("ana"), "| name:", greet.__name__, "| doc:", greet.__doc__)

def shout2(fn):
    @functools.wraps(fn)
    def wrapper(*a, **k): return fn(*a, **k).upper()
    return wrapper
@shout2
def greet2(name):
    """Say hello."""
    return f"hello {name}"
print("with wraps:", greet2.__name__, "|", greet2.__doc__, "| original:", greet2.__wrapped__("x"))

# 2. decorator with arguments = a function that returns a decorator
def retry(times):
    def deco(fn):
        @functools.wraps(fn)
        def wrapper(*a, **k):
            for attempt in range(1, times + 1):
                try: return fn(*a, **k)
                except ValueError as e:
                    print(f"  attempt {attempt} failed: {e}")
                    if attempt == times: raise
        return wrapper
    return deco
calls = {"n": 0}
@retry(3)
def flaky():
    calls["n"] += 1
    if calls["n"] < 3: raise ValueError("boom")
    return "ok"
print("retry result:", flaky())

# 3. decorators run at definition time, wrappers at call time
order = []
def trace(fn):
    order.append(f"decorated {fn.__name__}")
    def w(*a, **k): order.append(f"called {fn.__name__}"); return fn(*a, **k)
    return w
@trace
def a(): pass
order.append("after def"); a()
print(order)

# 4. stacking: bottom decorator applies first
def tag(name):
    def d(fn):
        def w(): return f"<{name}>{fn()}</{name}>"
        return w
    return d
@tag("b")
@tag("i")
def text(): return "x"
print(text())

# 5. lru_cache
@functools.lru_cache(maxsize=None)
def fib(n): return n if n < 2 else fib(n - 1) + fib(n - 2)
def fib_plain(n): return n if n < 2 else fib_plain(n - 1) + fib_plain(n - 2)
t = time.perf_counter(); fib_plain(27); plain = time.perf_counter() - t
t = time.perf_counter(); fib(27); cached = time.perf_counter() - t
print(f"fib(27) plain {plain*1e3:.0f} ms | lru_cache {cached*1e3:.2f} ms | {fib.cache_info()}")
@functools.lru_cache(maxsize=None)
def f(x): return x
try: f([1])
except TypeError as e: print("unhashable arg:", e)
# cache on a method keeps instances alive
import gc, weakref
class S:
    @functools.lru_cache(maxsize=None)
    def m(self): return 1
s = S(); s.m(); r = weakref.ref(s); del s; gc.collect()
print("instance still alive after del (lru_cache on method):", r() is not None)

# 6. partial, class-based decorator
from functools import partial
p2 = partial(int, base=2); print("partial:", p2("101"))
class Count:
    def __init__(self, fn): self.fn = fn; self.n = 0; functools.update_wrapper(self, fn)
    def __call__(self, *a, **k): self.n += 1; return self.fn(*a, **k)
@Count
def hi(): return "hi"
hi(); hi(); print("class decorator calls:", hi.n)

# 7. cost of a wrapper
def plain_fn(x): return x
@shout2
def w_fn(x): return str(x)
def deco_id(fn):
    @functools.wraps(fn)
    def w(*a, **k): return fn(*a, **k)
    return w
wrapped = deco_id(plain_fn)
n = 1_000_000
print(f"1M calls: plain {timeit.timeit(lambda: plain_fn(1), number=n)*1e3:.0f} ms, wrapped {timeit.timeit(lambda: wrapped(1), number=n)*1e3:.0f} ms")

gen_async.py: geradores, pipelines, send, yield from, contextmanager, corrotinas, gather, cancelamento, TaskGroup e um semáforo:

import asyncio, time, inspect
from contextlib import contextmanager

# generators: send, close, yield from, pipeline
def accumulator():
    total = 0
    while True:
        x = yield total
        if x is None: break
        total += x
g = accumulator(); next(g)
print("send:", g.send(10), g.send(5), g.send(1))
def read_lines():
    for line in ["a", "bb", "", "ccc", "dd"]:
        print("  produced", repr(line)); yield line
def nonempty(src):
    for x in src:
        if x: yield x
def lengths(src):
    for x in src: yield len(x)
it = lengths(nonempty(read_lines()))
print("first result:", next(it))                       # only reads what it needs
def inner(): yield 1; yield 2; return "done"
def outer():
    r = yield from inner(); yield r
print("yield from:", list(outer()))
def cleanup():
    try: yield 1; yield 2
    finally: print("  cleanup ran")
c = cleanup(); next(c); c.close()

@contextmanager
def timer(label):
    t = time.perf_counter()
    try: yield
    finally: print(f"{label}: {1e3*(time.perf_counter()-t):.0f} ms")
with timer("contextmanager"): time.sleep(0.05)

# coroutines
async def work(name, delay):
    await asyncio.sleep(delay); return name
co = work("a", 0.1)
print("calling an async def gives:", type(co).__name__, "| nothing ran yet")
co.close()
async def seq():
    t = time.perf_counter()
    await work("a", .2); await work("b", .2); await work("c", .2)
    return time.perf_counter() - t
async def conc():
    t = time.perf_counter()
    await asyncio.gather(work("a", .2), work("b", .2), work("c", .2))
    return time.perf_counter() - t
print(f"awaited one after another: {asyncio.run(seq()):.2f} s | gather: {asyncio.run(conc()):.2f} s")

# forgotten await
async def forgot():
    work("x", 0.01)          # coroutine created, never awaited
import warnings
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always"); asyncio.run(forgot()); import gc; gc.collect()
print("forgotten await warns:", [str(x.message) for x in w][:1])

# timeouts and cancellation
async def slow(): await asyncio.sleep(5)
async def with_timeout():
    try: await asyncio.wait_for(slow(), 0.1)
    except asyncio.TimeoutError: return "timed out after 0.1 s"
print(asyncio.run(with_timeout()))
async def cancel_demo():
    async def task():
        try: await asyncio.sleep(5)
        except asyncio.CancelledError: print("  task saw CancelledError"); raise
    t = asyncio.create_task(task()); await asyncio.sleep(0.05); t.cancel()
    try: await t
    except asyncio.CancelledError: return f"cancelled={t.cancelled()}"
print(asyncio.run(cancel_demo()))

# TaskGroup (3.11+): one failure cancels the siblings
async def tg():
    done = []
    async def ok(): await asyncio.sleep(0.5); done.append("ok")
    async def bad(): await asyncio.sleep(0.05); raise RuntimeError("bad")
    msg = None
    try:
        async with asyncio.TaskGroup() as g:
            g.create_task(ok()); g.create_task(bad())
    except* RuntimeError as eg:
        msg = [str(e) for e in eg.exceptions]
    return f"group raised {msg}, sibling finished: {bool(done)}"
print(asyncio.run(tg()))

# async generator and semaphore
async def ticker(n):
    for i in range(n): await asyncio.sleep(0.01); yield i
async def consume():
    return [x async for x in ticker(3)]
print("async for:", asyncio.run(consume()))
async def limited():
    active = peak = 0
    sem = asyncio.Semaphore(3)
    async def job():
        nonlocal active, peak
        async with sem:
            active += 1; peak = max(peak, active); await asyncio.sleep(0.05); active -= 1
    t = time.perf_counter(); await asyncio.gather(*(job() for _ in range(12)))
    return peak, time.perf_counter() - t
peak, el = asyncio.run(limited()); print(f"12 jobs, semaphore(3): peak concurrency {peak}, {el:.2f} s")

Fontes

  1. Documentação do Python, functools (wraps, lru_cache, partial, cached_property) e Function definitions (decorators).
  2. Documentação do Python, Generator expressions and yield expressions, e contextlib.
  3. Documentação do Python, asyncio: Coroutines and Tasks (gather, TaskGroup, wait_for, cancelamento, to_thread) e Developing with asyncio (chamadas bloqueantes, corrotinas nunca aguardadas).
  4. Python Enhancement Proposals, PEP 318: Decorators for Functions and Methods, PEP 342: Coroutines via Enhanced Generators, PEP 380: Syntax for Delegating to a Subgenerator, PEP 492: Coroutines with async and await syntax, e PEP 654: Exception Groups and except*.
  5. David Beazley, A Curious Course on Coroutines and Concurrency (PyCon 2009), para construir corrotinas a partir de geradores.

Pratique este tema: Python

Mais guias