Python 2.4 trouxe uma novidade interessante: os decorators. Vamos dar uma olhada no documento que traz as novidades do python 2.4 para entender isso melhor:

Python 2.2 estendeu o modelo de objetos do Python adicionando métodos estáticos e métodos de classe, mas não estendeu a sintaxe do Python com uma nova forma de definir métodos estáticos ou de classe. Ao invés disso, você usa a declaração def da forma normal, e passa o método resultante para a função staticmethod() ou classmethod() function que encapsula a função como um método do tipo correspondente. Seu código ficaria semelhante a isso:

class C:
   def meth (cls):
       ...
   
   meth = classmethod(meth)   # Reassocia o nome ao método de classe

Se o método fosse muito longo, seria fácil de esquecer a invocação de classmethod() depois do corpo da função.

(...)

A notação é copiada de Java e usa o caracter "@" como um indicador. Usando a nova sintaxe, o exemplo acima poderia ser escrito como:

class C:

   @classmethod
   def meth (cls):
       ...

Ou seja: o decorator é usado para encapsular uma função em outra função. Poderíamos dizer que esse é um Design Pattern do Python.É parecido com o decorator descrito no livro da Gangue dos Quatro, mas não exatamente igual: lá, se fala de uma classe que decora outra classe. Aqui, estamos falando de uma função que decora outra função. Decoradores de classe foram propostos para o python 3000, mas a discussão não parece ter andado muito pra frente.

O que python 2.4 fez foi pegar uma forma comum de desenvolvimento no python (encapsular uma função em outra função) e adicionar um açucar sintático. Um exemplo:

Podemos usar o módulo atexit para registrar uma função quando o interpretador python for encerrado corretamente.

>>> import atexit
>>> @atexit.register
... def sai():
...     print('Adeus')
...
>>>
Adeus

Sem o decorator, o código teria de ser digitado da seguinte forma:

>>> import atexit
>>> def sai():
...     print('Adeus')
...
>>> atexit.register(sai)
>>>
Adeus

Veja que sem o decorator, o registro da função para o atexit ocorreu depois da declaração da função. Com o decorator, ela é registrada logo no início da declaração da função, tornando muito mais claro ao programador o registro da função no atexit.

Decorador para garantir os tipos dos parâmetros passados

Digamos que uma função recebe o primeiro argumento inteiro e o segundo string:

@param(IntType, StringType)
def funcao(x, s):
....

Precisamos de decorators?

Avaliando mais profundamente, os @decorators são uma pequena modificação que não adicionam nada novo à linguagem. Qual a vantagem disso?

Segundo Michele Simionato, "a introdução dos decorators mudou significativamente a forma que estruturamos nossos programas em Python. Creio que essas mudanças são para melhor, e que decorators são uma grande idéia já que::

• decorators ajudam a reduzir boilerplate code
• decorators ajudam na separação de responsabilidades
• decorators melhoram a legibilidade e a manutebilidade
• decorators são muito explícitos.

Uma coisa a ser notada: um decorador muda a assinatura da função que ele decora. Um exemplo prático:

Resultado:

calling funcao with args ('a',), {}
newf
documentacao de decorator

Observe que a função funcao teve seu nome e documentação trocadas pelas do decorator. Para que isso não ocorra, seria necessário que decorator_trace fosse declarada da seguinte forma:

Python 2.5 provê uma forma mais simples de decorar a função sem mudar sua assinatura: usando o update_wrapper do módulo functools.

Um exemplo de decorator que não muda a assinatura da função decorada:

Exemplos de uso

• Jeremy Jones publicou no site da O'Reilly um tutorial de como usar decorators para gerenciar threads no pyGTK
• O Turbo Gears usa decorators para decidir quais métodos devem ser expostos na web

Nota

Na verdade, o texto contém uma pequena inverdade, que você já deve ter percebido à essa altura: qualquer objeto callable em python pode ser usado como decorator(no decorator pra verificação de tipos, ele é uma classe e não uma função).

Em python existem 4 objetos callable (funções, métodos, classes e algumas instâncias de classes cuja classe tenha o método __call__ (http://www.python.org/doc/1.4/tut/node92.html)). Por exemplo, no artigo em http://www.ddj.com/184406073#l10 na listagem 5, Phillip Eby usa uma classe como decorator. Nesse caso, hello passa a ser uma instância da classe traced.

Referências

• http://safari.oreilly.com/0132269937/ch14lev1sec1
• http://www.ddj.com/184406073
• Rodrigo Cacilhas, que me passou o código do decorator param