O caminho até o decorador

O que é um decorador, em uma ideia

Decorador tem fama de assunto difícil, e quase sempre isso vem de começar pelo símbolo @ antes de entender a ideia por baixo. Vamos pelo caminho contrário. Um decorador não é um recurso mágico da linguagem; é um jeito de usar duas coisas que você já conhece. A primeira é que, em Python, uma função é um objeto como outro qualquer: você pode guardá-la numa variável, colocá-la numa lista, passá-la para outra função e devolvê-la de dentro de uma função. A segunda é a closure, uma função escrita dentro de outra que lembra das variáveis de fora. Junte as duas e o decorador aparece sozinho.

def saudacao():
    return "Olá!"

# Uma função pode ir para uma variável, sem parênteses.
apontador = saudacao
print(apontador())     # Olá!

# E pode ser passada como argumento para outra função.
def executar_duas_vezes(func):
    return func() + " " + func()

print(executar_duas_vezes(saudacao))   # Olá! Olá!

Sem parênteses, saudacao é o objeto função; com parênteses, você a executa.

Closure, a peça que faltava

A parte que falta é conseguir devolver uma função nova. Para isso, escrevemos uma função dentro de outra. A função interna usa a variável da externa (a função recebida) e é devolvida para ser chamada depois. Como ela lembra dessa variável mesmo depois que a externa terminou, temos uma closure. Repare que devolvemos o objeto função, sem parênteses; quem recebeu decide quando chamar. Esse é o esqueleto exato de todo decorador que você vai escrever pelo resto do curso.

def com_moldura(func):
    def wrapper():
        print("=== inicio ===")
        func()
        print("=== fim ===")
    return wrapper           # devolve a função interna, sem chamar

def dizer_ola():
    print("Olá, mundo")

# Envolvemos dizer_ola na moldura e guardamos o resultado.
decorada = com_moldura(dizer_ola)
decorada()
# === inicio ===
# Olá, mundo
# === fim ===

com_moldura recebe uma função e devolve wrapper, que a chama entre duas linhas.

Leia esse exemplo com calma, porque ele é o coração do módulo. A função com_moldura é o decorador. Ela não faz nada sozinha: recebe uma função qualquer no parâmetro func, define uma função interna wrapper que chama func no meio de duas mensagens, e devolve wrapper. Quando escrevemos decorada = com_moldura(dizer_ola), a variável decorada passa a apontar para o wrapper, que por dentro lembra qual era a func original. Chamar decorada() executa a versão envolvida. Note que dizer_ola em nada foi alterada; ela continua intacta. O que ganhamos foi uma nova função com comportamento a mais ao redor dela.

Fixando a ideia central

Antes de conhecer o atalho do símbolo @ na próxima aula, garanta que a ideia base está firme. Um decorador é, em uma frase, uma função que recebe uma função e devolve uma função. A função devolvida (o wrapper) chama a original e acrescenta comportamento antes, depois, ou nos dois momentos. Nada nisso exige sintaxe nova; é tudo função de primeira classe mais closure, dois assuntos que você já viu. Se esse esqueleto ficou claro, o resto do módulo é aprender formas mais elegantes e completas de escrever a mesma coisa.