Usando comando with para evitar acoplamento temporal

Hoje vamos falar sobre como melhorar um padrão que você provavelmente já viu em muito código:

    f = open(...)
    ....
    f.close()

 

    a = A(...)
    a.start(...)
    ...
    a.end()

 

    c = Coisa(...)
    c.cria(...)
    ....
    c.destroi()

 

    test = Test()
    test.setUp()
    test.run()
    test.tearDown()

Os trechos de código acima possuem em comum o que chamamos acoplamento temporal (do inglês, temporal coupling).

Acoplamento mede o quanto uma coisa depende de outra em software, e é comumente medida entre módulos ou componentes – tipo, o quanto certas classes ou funções dependem uma da outra. Em geral, é desejável que haja poucas interdependências, para evitar que a complexidade se espalhe em um projeto.

O acoplamento temporal acontece quando uma coisa precisa ser feita depois de outra, mesmo que seja dentro do mesmo módulo ou função. A relação de interdependência é com o tempo, isto é, o momento em que as coisas precisam acontecer. Alguns exemplos seriam: fechar um arquivo depois de terminar de carregar o conteúdo, liberar memória quando acabar de usar, etc.

Reduzindo o acoplamento temporal

Desde a versão 2.5, Python possui o comando with para lidar exatamente com este tipo de situação. Com ele, podemos fazer:

    with open(...) as f:
        dados = f.read()
    # processa dados aqui

Ao usar o bloco with para abrir um arquivo, o método close() é chamado por trás dos panos pelo gerenciador de contexto incondicionalmente (isto é, mesmo que ocorra alguma exceção no código de dentro do bloco).

O código equivalente seria:

    f = open(...)
    try:
        dados = f.read()
    finally;
        f.close()

Repare como o primeiro código é mais curto e mais simples que o segundo, pois há menos interdependências entre as coisas que estão acontecendo.

A ideia é não precisar lembrar de ter que escrever try/finally e chamar o close(), utilizando por trás dos panos um código que se certifique de que as coisas aconteçam na ordem esperada. A este código, chamamos de gerenciadores de contexto, ou context managers.

Implementando um gerenciador de contexto

A maneira mais simples de implementar um gerenciador de contexto Python é utilizar o decorator contextlib.contextmanager. Vejamos um exemplo:

import os
import contextlib

@contextlib.contextmanager
def roda_em_dir(dir):
    orig_dir = os.getcwd()
    os.chdir(dir)
    try:
        yield
    finally:
        os.chdir(orig_dir)

Esse gerenciador de contexto nos permite rodar um código em um diretório qualquer, e ao fim dele voltar para o diretório que estávamos antes.

A função os.getcwd() devolve o diretório atual e a função os.chdir() entra no diretório passado como argumento, e depois os.chdir() é usada novamente para voltar para o diretório original.

Veja como usá-lo:

print('Comecei no diretorio: %s' % os.getcwd())

with roda_em_dir('/etc'):
    print('Agora estou no diretorio: %s' % os.getcwd())

print('E agora, de volta no diretorio: %s' % os.getcwd())

Rodando esse código na minha máquina, a saída é:

Comecei no diretorio: /home/elias
Agora estou no diretorio: /etc
E agora, de volta no diretorio: /home/elias

A função roda_em_dir() é o que chamamos de uma corotina, pois utiliza o comando yield para “pausar” sua execução, entregando-a para o código que está dirigindo-a. Neste caso, isso é o trabalho do decorator contextlib.contextmanager, que entrega a execução para o código que está dentro do bloco with até que este termine, o que devolverá a execução para a corotina roda_em_dir(), que irá executar o código dentro do finally.

Não se preocupe se for um pouco difícil de entender como a coisa toda funciona, estamos passando por cima de alguns tópicos avançados aqui (decorators, corotinas, etc). O importante é que você se dê conta de que pode implementar um gerenciador de contexto rapidamente usando o contextlib.contextmanager com uma função que faça yield dentro de um bloco try/finally.

Vejamos um outro exemplo, desta vez vamos fazer um gerenciador de contexto que cria um arquivo temporário para utilizarmos em um código de teste, e deleta o arquivo automaticamente ao fim do bloco with:

import os
import contextlib
import tempfile

@contextlib.contextmanager
def arquivo_temp():
    _, arq = tempfile.mkstemp()
    try:
        yield arq
    finally:
        os.remove(arq)

Repare como desta vez, o comando yield não está mais sozinho, desta vez ele está enviando a variável arq que contém o nome do arquivo temporário para ser usado no with, como segue:

with arquivo_temp() as arq:
    print('Usando arquivo temporario %s' % arq)
    print('Arquivo existe? %s' % os.path.exists(arq))

print('E agora, arquivo existe? %s' % os.path.exists(arq))

Rodando na minha máquina, a saída ficou:

Usando arquivo temporario /tmp/tmp2IUF7H
Arquivo existe? True
E agora, arquivo existe? False

Note como a variável arq pode ser usada depois do with também: isto mostra que o contexto está sendo gerenciado de maneira especial, mas o espaço de nomes de variáveis ainda é o mesmo (ou seja, o comando with é mais parecido com if e for, do que com o comando def, por exemplo).

Para concluir

Bem, apesar do mecanismo por trás ser um pouquinho complicado de entender inicialmente, você pode perceber que implementar um gerenciador de contexto não é muito difícil. Você precisa usar o decorator contextlib.contextmanager em uma função geradora fazendo yield dentro de um bloco try/finally – moleza!

Você também pode implementar um gerenciador de contexto escrevendo uma classe que implemente o protocolo do comando with, que envolve basicamente implementar dois métodos especiais chamados __enter__ e __exit__ que sinalizam respectivamente entrar e sair do bloco with.

Em geral é mais conveniente utilizar o @contextlib.contextmanager, mas em alguns casos é melhor implementar os métodos. Por exemplo, caso queira compartilhar o próprio objeto gerenciador do contexto dentro do with, você pode usar return self no método __enter__.

Agora, vá refatorar aqueles códigos com acoplamento temporal e se divirta!

Tente outra vez

Imagine que você está escrevendo um código que dependa de recursos externos e que podem falhar caso um servidor não esteja disponível (tipo, baixar uma página ou acionar uma API) ou caso algum recurso (pendrive, drive de DVD, etc) ainda não esteja pronto para operar. Digamos que você queira fazer isso funcionar de maneira robusta, tentando de novo quando uma operação falhar.

Há um tempo atrás mostramos aqui no blog um pequeno exemplo disso, explicando como baixar uma URL com tolerância a falhas simples em Python só com a biblioteca padrão. Acontece que tem um jeito melhor de fazer esse tipo de coisa, que resulta em código limpo e fácil de mudar: usar a biblioteca retrying.

Para começar, instale o pacote retrying com:

pip install retrying

Agora, para usar no seu código, importe o decorator retry (aprenda aqui sobre decorators) e use-o para alguma função que você deseja tentar de novo quando falhar (isto é, quando levantar alguma exceção):

from retrying import retry

@retry
def faz_algo_nao_confiavel():
    print("Tentando...")
    import random
    if random.randint(0, 10) > 1:
        raise RuntimeError("Putz, deu zica!")
    else:
        return "Funcionou!"

A função acima só funciona sem levantar exceção 20% das vezes que é chamada. Colocando o decorator, ela fica envolta em uma lógica que tenta de novo até que funcione sem a exceção. Rodando algumas vezes no meu laptop, a saída fica:

>>> faz_algo_nao_confiavel()
Tentando...
'Funcionou!'
>>> faz_algo_nao_confiavel()
Tentando...
Tentando...
Tentando...
Tentando...
Tentando...
Tentando...
Tentando...
'Funcionou!'
>>> faz_algo_nao_confiavel()
Tentando...
Tentando...
'Funcionou!'

Esse é apenas o jeito mais simples de usar. Em problemas do mundo real, você provavelmente vai querer configurar um intervalo de espera entre cada tentativa e também um limite máximo:

@retry(stop_max_attempt_number=7, wait_fixed=2000)
def busca_algo_na_rede():
    ....

A função acima será tentada no máximo 7 vezes, esperando 2 segundos (2000 ms) entre cada tentativa.

Outra opção interessante é o backoff exponencial, útil quando você quer ajustar a taxa de tentativas para não exigir demais de um sistema remoto que pode estar tendo dificuldades de sobrecarga. Veja um exemplo:

@retry(wait_exponential_multiplier=500, wait_exponential_max=30000)
def aciona_outro_sistema():
    ...

Nesse exemplo, caso a função falhar, será tentada novamente com um intervalo de espera calculado usando uma fórmula exponencial, tentando a primeira vez após 1s, na segunda 2s, na próxima 4s, 8s, 16s até o limite de 30s e então seguirá tentando com esse limite.

Quando não é adequado usar @retry?

Essa ideia de tentar de novo só funciona bem para operações que sejam idempotentes, isto é, que você pode acionar várias vezes sem alterar o resultado.

Por isso, quando quiser adicionar @retry em uma função existente, tenha cuidado para que seja uma função segura de ser chamada mais de uma vez. Em alguns casos, você terá que criar uma nova função com a parte que pode falhar e que funcione dependendo apenas dos próprios parâmetros (tornando-a assim idempotente) e colocar o @retry nessa função.

Baixar página de servidor com tolerância a falhas simples

Um dia desses precisei fazer um script Python que baixava uma cacetada de páginas HTML de um servidor, que às vezes respondia com um erro para algumas das requisições. As requisições estavam corretas, as páginas existiam, mas por alguma falha no servidor elas não respondiam no momento exato da execução do script.

A solução foi fazer uma função que tenta carregar a URL, e caso não consiga, espera alguns segundos e tenta de novo:

import time
import urllib2

def get_url(url, retry=3, timeout=3):
    try:
        return urllib2.urlopen(url).read()
    except:
        if retry > 0:
            time.sleep(timeout)
            return get_url(url, retry - 1, timeout)
        else:
            raise

Python é lento? Que Python?

Já vi muita gente falando que Java é ruim porque é lento. Eu mesmo, há tempos atrás, falava isso. Esse é um dos muitos mitos que se propagam entre as pessoas, sem uma análise crítica mais aprofundada. Isso já foi verdade, láááá no começo. Hoje em dia, é possível conseguir melhor desempenho com programas escritos em Java do que programas escritos em C, que é o rei da performance, de acordo com o senso comum.

Hoje em dia, se fala muito que Python é uma ótima linguagem, com sintaxe e recursos excelentes, mas que possui desempenho ruim. Ou seja, dizem que é lento. Mas calma aí, vamos pensar um pouquinho e esclarecer algumas coisas.

Temos dois conceitos separados que muitas vezes são confundidos. Uma coisa é Python, a linguagem. Outra coisa é Python, o interpretador. A linguagem em si nada mais é do que a especificação, com as regras léxicas, sintáticas e semânticas. Já o interpretador Python é o programa que irá ler e executar os programas escritos usando a linguagem Python. Existem várias implementações, e não somente um único interpretador Python. Assim, não faz sentido afirmar que “Python é lento”. O que poderia ser dito é “todos os interpretadores Python existentes são lentos”, mas isso seria uma mentira.

Os interpretadores

O interpretador Python mais conhecido é o CPython, que é a implementação de referência da linguagem. É ele que vem instalado por padrão no Ubuntu, é ele que a grande maioria das pessoas instala quando vai aprender Python e é ele que é usado pelos desenvolvedores quando vão escrever programas em Python. É bem provável que você tenha o CPython instalado aí na sua máquina. Porém, apesar da popularidade, ele não é o único e também não é o mais performático.

Um interpretador que tem ganhado visibilidade é o PyPy. Diferentemente do CPython, que é escrito em linguagem C, o PyPy é escrito em um subconjunto de Python, o RPython. O que mais chama a atenção no PyPy é o desempenho. Ele consegue obter um desempenho bem melhor do que o CPython em muitos casos. Veja o gráfico abaixo, comparando a versão 2.2 do PyPy ao CPython em vários benchmarks (para a versão mais atual, acesse: speed.pypy.org).

Desempenho do PyPy vs CPython

Desempenho do PyPy vs CPython

Talvez você esteja pensando: como o PyPy, escrito em Python, pode ser mais rápido do que o CPython, que é escrito em C e compilado direto para código de máquina? O PyPy é escrito em Python, mas isso não quer dizer que ele é executado sobre um interpretador Python. O código do PyPy, escrito em RPython, é compilado para linguagem de máquina, podendo então ser executado diretamente sobre o hardware (sobre o SO, na verdade). Mas isso por si só não justifica o bom desempenho dele, afinal o CPython também é compilado para código de máquina.

O que diferencia o PyPy é o fato de ele utilizar um mecanismo chamado JIT (Just In Time compilation) durante a interpretação dos programas. O JIT fica analisando a execução do programa, pega as partes que são executadas com mais frequência e, dentre outras coisas, faz uma tradução em tempo de execução daquelas partes para código de máquina. Assim essas partes do programa não precisarão ser decodificadas e executadas pelo interpretador toda vez que tiverem que ser executadas. Além disso, o JIT pode fazer outros tipos de otimização no código, sempre em tempo de execução. Essa técnica é bem antiga, e é usada também em algumas implementações da JVM (Java Virtual Machine).

Mas o CPython e o PyPy não são as únicas implementações do interpretador Python. O Jython é um interpretador que roda sobre a JVM (que por sua vez roda sobre o SO, que roda sobre o hardware, o que acaba gerando problemas de desempenho). Outras implementações populares são: IronPython (implementação em C#), Stackless Python, Unladen Swallow (uma implementação da Google, que foi deixada meio de lado), dentre outros.

Enfim, o importante é perceber que não existe o tal interpretador Python. O que existe é uma variedade de implementações, cada uma com um objetivo. Enquanto para algumas o principal objetivo é oferecer integração com outras plataformas (Jython e IronPython), para outras o objetivo é levar o desempenho ao topo (PyPy, Stackless Python e Unladen Swallow).

O Django é um projeto de grande porte que é suportado pelos principais interpretadores existentes (CPython por padrão, PyPyJythonIronPython). A troca do interpretador que está por debaixo do Django irá impactar na performance dos aplicativos que estiverem rodando sobre o mesmo. Dá pra ter uma ideia mais prática do impacto que a troca do interpretador pode ter no desempenho de uma aplicação lendo esse post: http://tomvn.com/posts/load-testing-and-pypy-smoking-the-competition.html. No texto, o autor relata que implementou uma API e que obteve uma média de 600 requisições por segundo rodando a mesma sobre o CPython. Ao trocar para o PyPy, este número subiu para impressionantes 2k requisições por segundo.

Então Python não é lento?

Não necessariamente, embora em geral os interpretadores ainda não sejam tão bons de performance quanto código escrito em C/C++ ou Java (em 2013). Mas, para poder falar mais, seria necessário realizar experimentos comparando programas escritos em Python e interpretados pelo PyPy com programas escritos em C, por exemplo. Mas esse tipo de comparação é sempre muito subjetiva, pois depende dos recursos usados em cada implementação. De nada adianta comparar uma hashtable escrita em Java com uma hashtable escrita em Python, se uma delas for thread-safe e a outra não, por exemplo.

Acima de tudo, é importante perceber que a perda de performance é compensada pela agilidade possibilitada à equipe de desenvolvimento na hora de escrever uma aplicação e colocá-la em produção. Nem sempre o desempenho é o mais importante em um projeto, afinal, as horas de trabalho dos desenvolvedores também custam muito. Além disso, experimentos mostram que com PyPy é possível melhorar de forma significativa o desempenho de algumas aplicações que rodam no CPython.

Só não se esqueça do famoso mantra do Donald Knuth: “Premature optimization is the root of all evil“.

Comportamento inesperado na divisão inteira

Alerta de versão: esse post foi escrito com base na versão 2 da linguagem Python. Na versão 3, o operador de divisão inteira é o //.

Para quem já estudou um pouco de programação, o seguinte resultado não é surpresa alguma:

>>> 3 / 2
1

Por se tratar de uma divisão de números inteiros, o resultado é truncado em um número inteiro também. Até aí, está tudo dentro do esperado, não? Então, abra um shell Python e teste a seguinte operação:

>>> -3 / 2
-2

Quem imaginava que o resultado seria -1, levante a mão: \o_

Por que -2 ?!

Em Python, a divisão inteira arredonda o resultado para baixo, ou seja, sempre para o menor número inteiro mais próximo. Por exemplo: 3 / 2 seria 1.5, mas o resultado é arredondado para 1 (e não 2), pois 1 < 2. Já no caso de -3 / 2, o resultado seria -1.5, mas por se tratar de uma divisão inteira, ele é arredondado para -2 e não para -1, pois -2 < -1.

Isso não é muito comum nas linguagens de programação. Em C e Java, por exemplo, uma divisão inteira tem o seu resultado sempre arredondado em direção ao 0. Python, como já vimos, faz com que o resultado de uma divisão inteira seja arredondado para baixo. Veja a ilustração abaixo:

drawing

Mas por que Python faz dessa forma? Ninguém melhor para explicar isso do que o criador da linguagem, o Guido Van Rossum. Em um post no blog Python History, ele explica que resultados negativos de divisão inteira são arredondados em direção a -∞ para que a seguinte relação entre as operações de divisão (/) e de módulo (%) se mantenha também para as operações com resultados negativos:

quociente = numerador / denominador
resto = numerador % denominador
denominador * quociente + resto == numerador

Vamos testar?

>>> numerador = -3
>>> denominador = 2
>>> quociente = numerador / denominador
>>> resto = numerador % denominador
>>> print quociente, resto
-2 1
>>> print denominador * quociente + resto == numerador
True
# e agora, com numerador positivo
>>> numerador = 3
>>> quociente = numerador / denominador
>>> resto = numerador % denominador
>>> print quociente, resto
1 1
>>> print denominador * quociente + resto == numerador
True

Perceba que se o resultado fosse arredondado em direção ao zero, a propriedade não seria satisfeita.

Esse é um detalhe de implementação muito importante e que todo desenvolvedor Python deve conhecer para não introduzir bugs em seus códigos, para evitar de perder horas depurando algo que parecia fugir comportamento esperado e também para evitar sentimentos de “esse intepretador está errado!”.

Leia mais sobre o assunto no post do Guido Van Rossum no blog The History of PythonWhy Python’s Integer Division Floors.

Sugestão de livro: Two Scoops of Django

2scoops

O Django é uma baita ferramenta que auxilia muitos desenvolvedores a concretizar seus projetos web com agilidade e simplicidade impressionantes. A documentação do framework é bastante vasta. São blogs de desenvolvedores, listas de email, livros bem completos, a trilha no StackOverflow, além de muitos e muitos projetos abertos no GitHub e BitBucket, e é claro, a excelente e completíssima documentação oficial. Até aí, tudo perfeito. Material para iniciantes querendo aprender Django existe de monte, mas quando as dúvidas começam a ficar um pouco mais específicas, ou questões relacionadas à boas práticas em projetos Django, a coisa começa a ficar mais escassa. Felizmente para nós, Djangonautas, o Daniel Greenfeld e a Audrey Roy começaram a resolver um pouco desse problema escrevendo o excelente Two Scoops of Django: Best Practices for Django 1.5.

O livro não é um tutorial e tampouco uma documentação exaustiva do Django, mas sim uma valiosa coleção de dicas e conselhos sobre boas práticas em projetos Django, atualizada para a versão 1.5. Já nos primeiros capítulos, fiquei com aquela sensação de “putz, eu tô fazendo tudo do jeito mais difícil nos meus projetos!”. Os autores vão mostrando os problemas e apresentando as soluções de uma forma bem prática, passando dicas, alertas, e, o que achei mais legal de tudo, as Package Tips, que são dicas sobre pacotes de terceiros que os autores costumam usar em seus projetos e que são uma verdadeira mão-na-roda.

Talvez você esteja pensando consigo próprio: “ah, eu já vi várias coisas dessas espalhadas pela web…”. Aí é que está o ponto principal, pois os autores pegaram a vasta experiência que possuem e compilaram uma série de dicas em um só lugar. E quando falo de dicas, não pense que são trechinhos pequenos de texto com links para outros recursos. Pelo contrário, os autores se preocuparam em explicar bem o porquê das coisas, sem cansar o leitor.

Outra coisa que achei interessante é que, diferentemente de um monte de livros que a gente vê por aí, parece que os autores deixaram de lado a preocupação de que o livro deles possa ficar obsoleto por passar dicas pontuais de pacotes específicos para resolver determinados problemas. Me parece que muitos autores limitam a abrangência de seus livros por medo de abordar um assunto mais específico, que poderia sofrer mudanças em breve (talvez o sentimento de estar sendo eternizado pelo livro deixe alguns autores meio confusos). Os autores do Two Scoops of Django não se preocuparam muito com isso e até se comprometeram em publicar erratas caso alguns elementos sofram mudanças nos próximos tempos.

O livro em si é muito bem organizado, com um formato muito bom para a leitura. Os autores se preocuparam MUITO e conseguiram fazer um layout excelente para ser lido em e-readers. Eu comprei a versão para Kindle, e esse é o primeiro livro técnico que leio em que não é preciso ficar diminuindo o tamanho da fonte para conseguir ler decentemente os trechos de código. Parabéns aos autores pela preocupação com os leitores da versão digital do livro!

O conteúdo

Não vou fazer aqui uma análise completa do livro. Vou listar apenas algumas coisas importantes que aprendi com o livro:

  • Como estruturar meus projetos Django;
  • Que as class-based-views são muito fáceis de usar;
  • Que na versão 1.5 do Django ficou barbada estender o modelo User;
  • Que realizar processamento nos templates é roubada;
  • Que dá pra manter configurações (settings.py) específicas para diferentes ambientes;
  • Que import relativo existe; (isso mesmo, eu não conhecia esse recurso)
  • Que select_related() quebra um galhão pra consultas grandes;
  • E muitas outras coisas! (muitas mesmo!) 🙂

Enfim, o conteúdo do livro é fantástico! Recomendo a todo mundo que tem um pouquinho de experiência com o Django que compre e leia esse livro. Não é preciso ser especialista no framework para se aproveitar do conteúdo dele. Se você está na dúvida se o livro é adequado para você, dê uma conferida no conteúdo dele na página oficial.

Eu recomendo!

De 0 a 10, dou nota 10 para esse livro. Li ele apenas uma vez, mas já vou começar a reler para fixar bem as dicas, pois são muitas coisas novas.

Se quiser seguir minha dica, estão à venda as versões impressa e digital do livro. Comprando direto pela página do livro, é possível comprar o pacote digital (formatos PDF, mobi e ePub, tudo DRM-free) por 17 dólares (preço em 22/06/2013). Na Amazon americana, está à venda a versão impressa. E ainda, se quiser comprar pela Amazon Brasil, eles estão vendendo a versão para Kindle.

Se ainda estiver na dúvida se o livro vale mesmo a pena, leia os reviews dos leitores na Amazon.

Entendendo os decorators

Hoje me deparei com um excelente texto sobre decorators que me inspirou a escrever algo sobre o assunto que para muita gente ainda é um tanto quanto nebuloso. Vou tentar aqui explicar o funcionamento de um decorator e mostrar algumas possíveis aplicações.

Aviso aos iniciantes: esse assunto pode ser um pouco confuso para quem ainda está iniciando em programação. Caso sinta dificuldades, não desanime e pule antes para a seção que contém as referências para melhor entendimento do texto.

O que é um decorator?

Um decorator é uma forma prática e reusável de adicionarmos funcionalidades às nossas funções/métodos/classes, sem precisarmos alterar o código delas.

O framework para desenvolvimento web Django oferece diversos decorators prontos para os desenvolvedores. Por exemplo, para exigir que o acesso a determinada view seja feito somente por usuários autenticados, basta preceder o código da view (que em geral é uma funçãozinha ou classe) pelo decorator @login_required. Exemplo:

@login_required
def boas_vindas(request):
    return HttpResponse("Seja bem-vindo!")

É claro que isso não é mágica. Como a gente pode ver no código-fonte do decorator login_required, os detalhes estão apenas sendo ocultados do código-fonte do nosso projeto. Assim, ao invés de ter que, a cada view, escrever o código que verifica se determinado usuário está autenticado, basta usar o decorator. Isso faz com que adicionemos a funcionalidade de verificar se um usuário está ou não logado no site, com uma linha de código apenas. Que barbada, não?

O decorator é um açúcar sintático que Python oferece aos desenvolvedores desde a versão 2.4, facilitando o desenvolvimento de códigos reusáveis.

OK, mas como implementar um decorator?

Você já sabe como um decorator pode ser usado, então agora vamos entender as internas desse recurso do Python.

Um decorator é implementado como uma função que recebe uma função como parâmetro, faz algo, então executa a função-parâmetro e retorna o resultado desta. O algo é a funcionalidade que adicionamos a nossa função original através do decorator.

Vamos escrever um decorator que sirva para escrever na tela o nome da função a ser executada, antes da execução da mesma. Como descrito acima, precisamos definir uma função que receba outra função como parâmetro, imprima o nome dessa, execute a função e retorne o seu resultado. Veja o código:

def echo_funcname(func):

    def finterna(*args, **kwargs):
        print "Chamando funcao: %s()"  % (func.__name__)
        return func(*args, **kwargs)

    return finterna

@echo_funcname
def dobro(x):
    return x*2

dobro(10)

Antes de mais nada, observe atentamente a função echo_funcname, pois existem alguns conceitos importantes dentro dela.

def echo_funcname(func):

    def finterna(*args, **kwargs):
        print "Chamando funcao: %s()"  % (func.__name__)
        return func(*args, **kwargs)

    return finterna

Veja que ela receba um parâmetro func (que espera-se que seja uma função) e retorna outra função (finterna). A função retornada, finterna, é “configurada” para executar ao seu final a função recebida como argumento pela função externa (echo_funcname), bem como retornar o valor de retorno da função recebida. Em outras palavras, echo_funcname() cria dentro de si próprio uma função chamada finterna(), que no final (linha 5) chama a função recebida como parâmetro. Mas, é importante perceber que a palavra-chave def somente cria a função (isto é, instancia um objeto do tipo função), não executando ela. Ou seja, echo_funcname cria uma função, configura ela para executar func() ao seu final, não a executa, mas sim somente retorna o objeto função, que então poderá ser chamada por quem recebê-la. (um assunto muito importante para o entendimento desse conceito de função dentro de função é o conceito de closures).

Caso tenha ficado confuso, perceba que finterna é um objeto como qualquer outro que estamos acostumados a criar dentro de nossas funções, como uma lista, por exemplo. A diferença é que esse objeto é uma função, o que pode parecer um pouco estranho, em um primeiro momento. Sendo um objeto qualquer, a função é instanciada, recebe um nome (finterna), e pode ser retornada, assim como todo objeto (tudo isso sem ser executada, pois não chamamos finterna).

Veja um exemplo de visualização de uma função que define outra função internamente (visualização gerada pelo excepcional pythontutor.com):

func

Se quiser visualizar a versão interativa, clique aqui (powered by PythonTutor.com).

Tendo a função echo_funcname() definida, agora poderíamos fazer o seguinte:

def echo_funcname(func):

    def finterna(*args, **kwargs):
        print "Chamando funcao: %s()"  % (func.__name__)
        return func(*args, **kwargs)

    return finterna

def dobro(x):
    """ Uma funcao exemplo qualquer.
    """
    return 2*x

dobro_com_print = echo_funcname(dobro)
print dobro_com_print(10)

Ao executar o código acima, teremos como resposta na tela:

Chamando funcao: dobro()
20

Criamos uma função chamada dobro(), que recebe um número e retorna o dobro desse número. Depois, passamos esse objeto do tipo function para a função echo_funcname() e recebemos como retorno outro objeto do tipo function, ao qual referenciamos como dobro_com_print. Perceba que dobro_com_print nada mais é do que uma referência a uma função mais ou menos assim:

def finterna(*args, **kwargs):
    print "Chamando funcao: %s()"  % (dobro.__name__)
    return dobro(*args, **kwargs)

Essa função foi gerada dentro de echo_funcname() e retornada, já com dobro no lugar de func. Assim, quando chamamos a função como em print dobro_com_print(10), estamos chamando a função acima, e passando 10 como argumento.

Mas, esse negócio todo de passar uma função como parâmetro e receber uma função como retorno de uma chamada de função é um pouco confuso. Para abstrair um pouco esses detalhes, Python oferece a sintaxe do @nome_do_decorator que precede a definição de funções. Assim, ao invés de:

dobro_com_print = echo_funcname(dobro)
print dobro_com_print(10)

Poderíamos apenas preceder a definição da função dobro() com o decorator @echo_funcname:

@echo_funcname
def dobro(x):
    """ Uma funcao exemplo qualquer.
    """
    return 2*x

Agora, ao chamar a função dobro(), estaríamos chamando a função decorada (isto é, acrescida de funcionalidades). No nosso caso, o decorator apenas adiciona a impressão na tela de um aviso sobre a chamada da função.

Enfim, um decorator nada mais é do que uma função que recebe outra função como parâmetro, gera uma nova função que adiciona algumas funcionalidades à função original e a retorna essa nova função.

Concluindo …

Os decorators formam um recurso muito importante para diminuir a duplicação e aumentar o reuso de código em um projeto. O conceito pode ser um pouquinho complicado para entender de primeira, mas uma vez que você o domine, você começará a perceber diversas oportunidades para implementar e usar decorators em seus projetos.

Leia mais

Por se tratar de um assunto mais complicado para iniciantes, segue aqui uma lista de textos que poderiam ser lidos, possibilitando um melhor entendimento sobre o assunto.

Funções como objetos:

Closures: