iMasters

A maioria dos programadores tem uma certa resistência em criar documentação

Na maioria das vezes, a documentação é parte essencial de projetos e o uso de uma linguagem de marcação pode tornar a escrita muito mais confortável, rápida e menos trabalhosa do que usar um editor WYSIWYG. Como a documentação é feita utilizando uma linguagem de marcação, facilita a utilização de controle de versão e dividir as seções entre diversos colaboradores, tornando a tarefa de criação de documentação ainda mais rápida, evitando problemas de acesso e gravação quando se trabalha em um único arquivo.

O Sphinx é muito prático e objetivo, faz com que os programadores tenham interesse e vontade em escrever documentações.

Muitas distribuições GNU/Linux já possuem o pacote do python-sphinx pronto, bastando um apt-get install python-sphinx (para Debian e Ubuntu) ou yum install python-sphinx (como Fedora/Red Hat/CentOS). Em outras distribuições e sistemas operacionais como Mac ou Windows, é necessário ter o Python instalado, pode-se utilizar o comando easy_install -U Sphinx para instalar o pacote e suas dependências (como Jinja) para ter o Sphinx e suas dependências instaladas.

Uma vez instalado, basta iniciar a criação de seu projeto de documentação com o utilitário sphinx-quickstart, a saída será como no exemplo abaixo:

anderson@yoda:~/tmp$ sphinx-quickstart 
Welcome to the Sphinx quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]: 

You have two options for placing the build directory for Sphinx output.

Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]: 

The project name will occur in several places in the built documentation.
> Project name: Teste Sphinx  
> Author name(s): Christiano Anderson

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]: 

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]: 

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: 

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: 
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: 
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: 
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: 
> coverage: checks for documentation coverage (y/N) [n]: 
> pngmath: include math, rendered as PNG images (y/N) [n]: 
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]: 
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: 

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]: 
> Create Windows command file? (Y/n) [y]: n

Finished: An initial directory structure has been created.

You should now populate your master file ./source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck

Depois de ter respondido as perguntas acima, um diretório com um Makefile e os subdiretórios build e source serão criados. No source, você vai trabalhar na criação do documento, enquanto que no build, ficará sua documentação depois de gerada.

Dentro do build, terá um arquivo conf.py, que agrega todos os parâmetros de configuração.  As opções estão comentadas, com um breve resumo de cada parâmetro, mas recomendo alterar a linha "language" para pt_BR se estiver criando sua documentação em português. Ficará desse jeito:

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = 'pt_BR'

Depois de configurado, basta criar seus documentos, são arquivos .rst com a formatação bem semelhante de wiki. Um exemplo de documento (arquivo intro.rst):

Título
======

A linguagem de marcação é semelhante a muitos wikis.

Subtítulo
---------

Você também pode usar **negrito**, *itálico*.

Uma lista enumerada ficaria assim:

   #. Primeira linha
   #. Segunda linha
   #. Terceira linha

.. hint::
   Aqui você pode colocar uma dica 

Depois basta referenciar seus arquivos dentro do index.rst, não sendo necessário colocar a extensão .rst. Exemplo:

.. Teste Sphinx documentation master file, created by
   sphinx-quickstart on Sun Oct 24 18:19:06 2010.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Teste Sphinx's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

   intro

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Para gerar a saída em PDF, basta digitar make latex no diretório principal da documentação. Depois basta entrar no diretório build/latex e digitar make all-pdf para que o PDF seja gerado, como no exemplo abaixo (a página do nosso exemplo de documento):

Dicas aos usuários de Debian/Ubuntu (e provavelmente outras distribuições): instale o pacote texlive-full para que o suporte a geração de PDF funcione.

Além da tela acima, o pacote gera automaticamente o índice, índice de imagens, índice de tabelas e demais facilidades utilizadas em documentação. A qualidade do documento fica realmente muito profissional, excelente para documentar projetos de software, criar material para treinamentos, apresentações e outras necessidades com toda a agilidade de trabalhar diretamente com linguagem de marcação. Para saber mais, visite os links abaixo: 

Veja todas as marcações disponíveis em reStructuredText quickstart.

Visite também o site do projeto: Python Sphinx

⁂

Quer escrever um código mais curto e limpo? Tem uma situação infeliz em que você precisa pôr o máximo que conseguir dentro de uma expressão? Prefere uma boa e rápida dose de hacks a passar o resto da sua vida lendo os documentos? Você veio ao lugar certo. Começaremos com uns truques rápidos que você já deve ter descoberto se já passou um tempo com o Phyton, mas prometo que há coisas mais aventureiras mais para o final.

Tentei fazer com que todos os trechos do código se executassem sozinhos. Se você quiser, cole-os na sua Python Shell e os teste. Você vai notar muitos exemplos contendo 'true example' e 'false example', com um comentário. Sinta se à vontade para trocar o comentário e ver o que acontece.

Você também verá alguns comentários em branco flutuando em volta do código. Seu objetivo é melhorar a legibilidade ao adicionar quebras de linhas ao mesmo tempo em que o intérprete do Phython analisa o código. Isso não seria necessário em um programa ‘real’ (‘não colados’).

Uma rápida distinção entre true vs True neste artigo: quando eu disser que um objeto é 'true', quero dizer que o objeto, se convertido a um boolean em uma instrução if ou em qualquer outro lugar, seria convertido a True, e não a False. Isso não significa que o objeto é necessariamente idêntico ou equivalente a True. Da mesma maneira, se eu disser que um objeto é 'false', quero dizer que o objeto seria convertido a False, não que ele seja necessariamente idêntico ou equivalente a False.

1 - Truques Rápidos

1.1 - Quatro tipos de Quotes

Vamos começar com algo rápido que você provavelmente já conhece. Se você está vindo de uma linguagem diferente, provavelmente está acostumado a usar quotes únicos para uma coisa, e quotes duplos para outra. O Phyton te permite usar os dois, apesar de eles não serem intercambiáveis (se você começar com um, você tem que terminar com o mesmo). O Phyton também tem mais dois tipos de quotes. Um quote triplo, ''', é criado ao digitar três quotes únicos. Um quote duplo-triplo, """, é criado ao digitar três quotes duplos. Portanto, você pode ter várias camadas de quoting antes de começar a se preocupar em deixar seus quotes escaparem. Por exemplo, isto é valido no Python:

print """I wish that I'd never heard him say, '''She said, "He said, 'Give me five dollars'"'''"""

1.2 - A verdade de Vários Objetos

Diferentemente de outras linguagens de programação (cof, cof, Javascript), os Phyton Types são false se estiverem vazios, e true se não estiverem vazios. Isso significa que você não tem que checar, por exemplo, se o comprimento de uma sequência (string), tupla, lista ou dicionário, é 0 ou equivalente a um vazio. É preciso checar apenas a verdade do objeto.

Como você já imaginava, o número zero também é false, enquanto todos os outros números são true.

Por exemplo, as expressões a seguir são equivalentes. Aqui, 'my_object' é um string, mas poderia facilmente ser outro Python type (com as devidas modificações para o teste de igualdade).

my_object = 'Test' # True example
# my_object = '' # False example

if len(my_object) > 0:
    print 'my_object is not empty'

if len(my_object):  # 0 will evaluate to False
    print 'my_object is not empty'

if my_object != '':
    print 'my_object is not empty'

if my_object: # an empty string will evaluate to False
    print 'my_object is not empty'

Em conclusão, não existe necessidade de checar comprimentos ou equivalências se você só está interessado em saber se o objeto é vazio ou não.

1.3 - Checando se um String contém um Substring

Aqui vai uma dica rápida que pode ser óbvia, mas precisei de um ano de programação em Phyton para descobri-la.

Você provavelmente sabe que pode testar se uma lista, tupla, ou dicionário contém um item ao testar a expressão 'item in list' ou 'item not in list'. Eu nunca imaginei que isso funcionaria para strings também. Eu sempre escrevia o código assim:

string = 'Hi there' # True example
# string = 'Good bye' # False example
if string.find('Hi') != -1:
    print 'Success!'

Esse é um código feio. É completamente equivalente a fazer 'if  substring in  string':

string = 'Hi there' # True example
# string = 'Good bye' # False example
if 'Hi' in string:
    print 'Success!'

Muito mais limpo e simples. Pode ser óbvio para 99% da população, mas eu gostaria de ter descoberto antes.

1.4 - Imprimindo uma lista de forma bonita

Listas não imprimem bem. É claro que fica óbvio o que é a lista, mas um usuário razoável não quer ver cochetes em volta de tudo. Existe uma solução trivial para isso, usando o método ‘join’ na sequência.

recent_presidents = ['George Bush', 'Bill Clinton', 'George W. Bush']
print 'The three most recent presidents were: %s.' % ', '.join(recent_presidents)
# prints 'The three most recent presidents were: George Bush, Bill Clinton, George W. Bush.

O método ‘join’ transforma a lista em string ao moldar cada item dentro do string, e então os conectando com o string em que o join foi chamado. Inclusive é inteligente não colocar um depois do último elemento.

Uma outra vantagem é que isso é muito rápido, executado em tempo linear. Nunca crie um string utilizando ‘+’ itens juntos para gerar um for loop: não é somente feio como também é bem mais demorado.

1.5 - Integer vs. Float Division

Por padrão, se você dividir um integer por outro, o resultado será truncado dentro de um integer. Por exemplo, executar 5/2 devolve 2.

Existem duas maneiras de consertar isso. A primeiro e mais simples delas é simplesmente transformar um dos integers em um float. Se os valores são estáticos, você pode apenas adicionar um .0 a ele para o transformar em float. 5.0/2 devolve 2.5. Alternativamente, você pode apenas moldar um dos valores: float(5) / 2 devolve 2.5.

A outra maneira vai resultar em um código mais limpo, mas você deve garantir que nenhum dos seus códigos está confiando nessa truncagem. Você pode fazer uma divisão from __future__ import para que o Phyton sempre retorne um float como resultado da divisão. Depois dessa importação, 5/2 vai retornar 2.5. Se você ainda precisar usar a divisão truncada de integer em outro lugar, você então pode usar o the // operator: 5//2  vai sempre devolver 2.

5/2        # Returns 2
5.0/2      # Returns 2.5
float(5)/2 # Returns 2.5
5//2       # Returns 2

from __future__ import division
5/2        # Returns 2.5
5.0/2      # Returns 2.5
float(5)/2 # Returns 2.5
5//2       # Returns 2

Nota

Em algum momento, a divisão de float será a default (padrão). Se você quiser que seu código garantidamente funcione em futuras versões do Python, use o // operator se você quer utilizar a divisão truncada, não importa se você está utilizando a divisão from __future__ import  ou não.

1.6 - Funções Lambda

Às vezes, você precisa passar uma função como um argumento, ou você quer fazer uma operação curta – mas complexa – múltiplas vezes. Você pode definir sua função da maneira normal, ou você pode fazer uma função lambda, uma mini-função que devolve o resultado de uma simples expressão. As duas definições são completamente idênticas.

def add(a,b): return a+b

add2 = lambda a,b: a+b

A vantagem da função lambda é que ela própria é uma expressão, e pode ser usada ao lado de outra declaração. Aqui temos um exemplo usando a map function, que chama uma função em cada elemento de uma lista, e devolve uma lista dos resultados. 

squares = map(lambda a: a*a, [1,2,3,4,5])
# squares is now [1,4,9,16,25]

Sem o lambda, você teria que definir a função separadamente. Voce apenas salvou uma linha de código e um nome variável (para a função).

Sintaxe: Funções Lambda

Uma função lambda tem a sintaxe: lambda variable(s) : expression

No próximo artigo, falaremos sobre o uso de listas inteligentes, como mapeá-las e filtrá-las e quando devemos usar o generator expressions.

Elcio resolveu a questão com apenas uma linha, o que considero muito elegante, mas a questão agora é a gama de funcionalidades que você pode ter com um objeto e uma string. Infelizmente, com string não dá para fazer muita coisa, como por exemplo converter em maiúsculas e minúsculas ou verificar se ela começa com uma vogal ou uma consoante.

Objetos em python são mais legais de trabalhar, pois com eles você tem uma gama de funcionalidades próprias que o elemento possui só pelo fato de ele existir. E o mais legal é que essas funcionalidades só vão existir nesse objeto. Isso quer dizer que você não corre o risco de errar, aplicando uma funcionalidade que não condiz com o que você deseja.

Vamos considerar o exemplo do outro artigo e reformatá-lo, só que desta vez usando o objeto time.

# Fonte:
# http://pleac.sourceforge.net/pleac_python/datesandtimes.html#AEN153
import datetime,time
data = "2008-08-12"
ndata = time.strptime(data, "%Y-%m-%d")
ndata = datetime.datetime(*ndata[0:5])

Pronto, agora você pode usar a variável ndata no formato que achar necessário. Como no nosso caso, podemos usar o formato ISO padrão:

print ndata.strftime('%d/%m/%Y')

O legal de usar objeto, neste caso, é que podemos fazer contas entre datas usando o timedelta do próprio objeto datetime. Assim podemos ver que dia será daqui a duas semanas com um código simples:

print "Daqui ha duas semanas sera " + ( ndata - datetime.timedelta(weeks=+2) ).strftime('%d/%m/%Y')

Note que na mesma linha coloquei o formatador de data para facilitar o resultado, mas você pode fazer o processo em duas linhas, se achar necessário.

Script final, completo

import datetime,time
data = "2008-08-12"
ndata = time.strptime(data, "%Y-%m-%d")
ndata = datetime.datetime(*ndata[0:5])
print ndata.strftime('%d/%m/%Y')
# "12/08/2008"
print "Daqui a duas semanas sera " + ( ndata - datetime.timedelta(weeks=+2)

artigo publicado originalmente no iMasters, por Michael Granados

Este artigo é uma anotação de uma palestra que fiz recentemente na Software Summit Passion em Gotemburgo, Suécia.

Escrever uma especificação em uma linguagem de programação completa como Python possui vantagens e desvantagens. Em relação às desvantagens, o Python não é uma linguagem declarativa, portanto, qualquer tentativa de torná-lo declarativo (além de apenas listar os tipos nativos de dados) exigirá algum tipo de personalização e/ou ferramentas para trabalhar. Como vantagem, tendo uma declaração na linguagem na qual você escreve seus servidores, você pode usar a própria especificação, em vez de um derivado gerado dela, e escrever geradores personalizados para outras linguagens é simples, desde que você possa fazer introspecção em Python atravessar a sua especificação, e a lógica templating de sua escolha para gerar o código-fonte - o que torna possível, por exemplo, atingir um terminal J2ME que só não vai aceitar as soluções existentes, e onde colocar um arquivo jar 150K para implementação do protocolo não é uma alternativa.

Para mim, essa jornada começou por volta de 2006, quando comecei a perder o controle sobre documentação de protocolo e versões de protocolo para o protocolo usado entre terminais e servidores no gerenciamento da solução Visual Units Logistics. Depois de procurar e descartar várias ferramentas existentes, e após ser inspirado pelo fato de que nós geralmente configuramos o JavaScript no JavaScript, comecei a esboçar (como tinta sobre papel) sobre como seria uma especificação de protocolo em Python. Esta é uma transcrição do que eu criei na época:

imei = long
log_message = string
timestamp = long
voltage = float
log = Message(imei, timestamp,
           log_message, voltage)
protocol = Protocol(log, ...)
protocol.parse(data)

Com isso como uma meta, eu criei a primeira versão de uma implementação de protocolo. Ela se parecia com a versão alvo, mas sofreu com uma abundância de repetição:

#protocol.py
LOG = 0x023
ALIVE = 0x021
message = Token('message', 'String', 'X')
timestamp = Token('timestamp', 'long', 'q')
signal = Token('signal', 'short', 'h')
voltage = Token('voltage', 'short', 'h')
msg_log = Message('LOG', LOG, timestamp, signal, voltage)
msg_alive = Message('ALIVE', ALIVE, timestamp)
protocol = Protocol(version=1.0, messages=[msg_log,msg_alive])
#usage
from protocol import protocol
parsed_data = protocol.parse(data)
open('Protocol.java’,'w').write(protocol.java_protocol())

A implementação em torno disso é simples, a classe Token sabe como analisar uma parte de uma mensagem, a classe Message sabe quais Tokens usar (e em que ordem), e a classe Protocol seleciona a instância de Mensagem correta utilizando um mapeamento de marcadores de bytes nas instâncias de Mensagens.

No entanto, nenhum apoio é dado para lidar com várias versões do protocolo e a quantidade de duplicação de nomes torna isso muito complexo - por isso me propus a criar uma versão melhor.

Algumas coisas complicaram a criação de uma versão melhor. O pior problema de todos provou ser somente eu. Nessa época, eu tinha usado Python por alguns anos, e comecei a me interessar pelas ferramentas mais sofisticadas disponíveis. Eu tinha acabado de aprender sozinho sobre metaclasses, e pensei que fossem um aplicativo engenhoso para orientação a objetos - e porque tinha encontrado um martelo novinho em folha, eu estava louco para encontrar um prego.

Infelizmente, eu não tinha uma necessidade urgente para a utilização de metaclasses, então eu inventei uma - eu queria evitar algumas tarefas na especificação de protocolo, então usei metaclasses para arrancar o método (constructor) init e substituí-lo por uma versão que registrou a instância em um mapa global e depois chamei o método init original. Isso foi errado em pelo menos três formas - uma vez que não era genérico, poderia ter sido feito diretamente no método init, se tivesse sido geral, teria sido um trabalho para um decorator, e é realmente uma ótima maneira de ofuscar o código:

__MSG_MAPPING__ = {}
def msg_initizer(cls, old_init):
    def new_init(self, name, marker, *args):
        __MSG_MAPPING__get(cls, {})[name] = self
        __MSG_MAPPING__[cls][struct.pack("!B", marker)] = self
        old_init(self, name, marker, *args)
    return new_init
class RegisterMeta(type):
    def __new__(cls, name, bases, attrs):
        attrs['__init__'] = msg_initizer(cls,
                                         attrs['__init__'])
        return super(RegisterMeta, cls).__new__(cls,
                                      name, bases, attrs)
class Message(object):
    __metaclass__ = RegisterMeta

A propósito, esse é o tipo de código do qual eu não tenho orgulho. A pior parte? Eu nem sequer removi a duplicação, embora a tenha diminuído um pouco - e o registro global de mensagens durante o carregamento de um protocolo realmente bagunçou qualquer tentativa de suporte para versão múltipla. Esse não foi o único problema; eu também extrapolei e queria suporte especificando a sintaxe do protocolo, usando uma classe Flow que definiu a ordenação coletiva das mensagens. Isso poderia ter sido uma boa ideia se tivéssemos realmente tido esses requisitos em nossos protocolos; já que eles são "autenticar, fazer qualquer coisa", adicionar suporte para isso apenas expandiu a base de código e fez a especificação de protocolo mais complexa para pouquíssimo ganho (especialmente pelo fato de que autenticamos de diferentes maneiras, dependendo do cliente). Adicionando insulto à injúria, isso é ainda mais detalhado do que a primeira tentativa.

#In protocol.py
imei = Token('imei', 'long')
message = Token('message', 'String')
timestamp = Token('timestamp', 'long')
signal = Token('signal', 'short')
voltage = Token('voltage', 'short')
auth = Token('auth', 'String')
Markers({'LOG': 0x023,
    'ALIVE': 0x021,
    'AUTH': 0x028})
Message('LOG', imei, timestamp, signal, voltage)
Message('ALIVE', imei, timestamp)
Message('AUTH', imei, timestamp, auth)
Flow([('AUTH'), ('LOG', 'ALIVE')])
#Usage
protocol = Protocol(version=2.0)
parsed_data = protocol.parse(data) #error if not auth parsed

Toda essa tentativa se tornou um exemplo de alerta - ela mostra o perigo de encontrar novas tecnologias interessantes e aplicá-las antes de compreendê-las totalmente, e mostra o perigo de engenharia e fluência de recurso. Felizmente, quando eu dei uma boa olhada no que havia criado, até mesmo no que eu fiz uns anos atrás, pude ver que isso era uma abominação, que depois foi retirada calmamente e deixada de lado, sem nem chegar aos testes de integração.

Finalmente, e progressivamente, decidi aplicar uma quantidade cuidadosa de magia de biblioteca padrão para fazer as especificações mais concisas e remover as coisas de que nós não precisávamos. Isso fez com que a especificação parecesse com algo assim:

#In protocol_4.2.py:
#Tokens
t('message', string)
t('timestamp',  i64)
t('signal', i16)
t('voltage', i16)
#Messages
LOG = ('A log message containing some debug info',
         0x023, timestamp, message, signal, voltage)
ALIVE = ('A message to signal that the terminal alive',
     0x021, timestamp)
#Usage
protocols = load_protocols('protocols')
parsed = protocols[4.2].parse(data)
protocols[4.2].write_java() #Writes to Protocol42.java

Ao mesmo tempo, era ainda resumida, mas essa versão realmente não teve sucesso, e a versão de produção é muito semelhante a esta. A duplicação de nomes é evitada usando duas técnicas diferentes - os tokens são definidos ao chamar um método t que cria a instância Token e a introduz de volta para a chamada namespace usando o nome fornecido:

#In types.py
from inspect import currentframe
def t(name, data_type):
    """Inserts name = (name, data_type) in locals()
    of calling scope"""
    currentframe().f_back.f_locals[name] = (name, data_type)

Para alguns, isso pode parecer uma blasfêmia, mas considere que a aplicação é extremamente simples no conceito, ela faz o trabalho ser feito e é fácil de explicar. Outra mudança é que as mensagens são criadas somente usando inspect para extrair membros do módulo que se parece com mensagens - todos os nomes em letras maiúsculas e uma tupla. Vale notar que pode ser que tenha havido inicialmente um erro de manipulação, mas eu o removi para fazer a análise de falha, em vez de aceitar uma especificação que poderia ou não ter contido erros.

Finalmente, a documentação java de origem e de html é criada percorrendo a instância de protocolo, e alimentando as informações em modelos simples - os experimentos foram feitos usando linguagem de programação literal usando REST para criar documentação, mas que no fim tendem a ofuscar, e não o contrário. Esse pode ser um efeito de implementação ingênua, ou esse problema não se presta bem à programação literal, mas, de qualquer forma, não valeu a pena nesse caso.

Há um trabalho e uma versão ligeiramente generalizada disponíveis no bitbucket, sobre os quais você poderia gostar de saber mais (e mais detalhes sobre a magia usada de Python).

⁂

Texto original disponível em http://blaag.haard.se/Protocol-specifications-written-in-Python/

Desde que, em retrospecto, fiz a escolha errada quando reduzi um curso de Python para quatro horas e baguncei com o exercício do decorator, prometi aos participantes do curso que escreveria um artigo sobre closures e decorators para explicá-los melhor - esta é a minha tentativa de o fazer.

Funções também são objetos. Na verdade, em Python são objetos de primeira classe - ou seja, eles podem ser tratados como qualquer outro objeto sem restrições especiais. Isso nos dá algumas opções interessantes, e eu vou tentar abordá-las sob todos os aspectos.

Um caso muito básico do fato de que funções são objetos é usá-las como se fosse um ponteiro de função em C; passá-la para outra função que irá utilizá-la. Para ilustrar isso, vamos dar uma olhada na implementação de uma função de repetição - ou seja, uma função que aceita outra como argumento em junto com um número, e depois chama a função passada um específico número de vezes:

>>> #A very simple function
>>> def greeter():
...   print("Hello")
...
>>> #An implementation of a repeat function
>>> def repeat(fn, times):
...   for i in range(times):
...     fn()
...
>>> repeat(greeter, 3)
Hello
Hello
Hello
>>>

Esse padrão é utilizado em um grande número de maneiras - passando uma função de comparação para um algoritmo de classificação, passando uma função de decodificação para um parser e, em geral, especializando o comportamento de uma função, ou passando partes específicas de um trabalho a ser feito para uma função que abstrai o fluxo de trabalho (por exemplo, sort () sabe como classificar listas, compare () sabe como comparar elementos).

As funções também podem ser declaradas no corpo de outra função, o que nos dá outra ferramenta importante. No caso mais básico, isso pode ser usado para "esconder" funções utilitárias no âmbito da função que as utiliza:

>>> def print_integers(values):
...   def is_integer(value):
...     try:
...       return value == int(value)
...     except:
...       return False
...   for v in values:
...     if is_integer(v):
...       print(v)
...
>>> print_integers([1,2,3,"4", "parrot", 3.14])
1
2
3

Isso pode ser útil, mas dificilmente é em si uma ferramenta muito poderosa. Comparado com o fato de que as funções podem ser passadas como argumentos, podemos adicionar comportamentos a funções depois que elas são construídas, ao empacotá-las em outra função. Um exemplo simples seria adicionar uma saída de rastreamento para uma função:

>>> def print_call(fn):
...   def fn_wrap(*args, **kwargs): #take any arguments
...     print("Calling %s" % (fn.func_name))
...     return fn(*args, **kwargs) #pass any arguments to fn()
...   return fn_wrap
...
>>> greeter = print_call(greeter) #wrap greeter
>>> repeat(greeter, 3)
Calling fn_wrap
Hello
Calling fn_wrap
Hello
Calling fn_wrap
Hello
>>>
>>> greeter.func_name
'fn_wrap'

Como você pode ver, podemos substituir a função greeter com uma nova função que usa print para registrar a chamada, e depois chama a função original. Como se vê nas duas últimas linhas do exemplo, o nome da função reflete que ela foi substituída, o que pode ou não ser o que nós quisemos. Se quisermos empacotar uma função, mantendo o nome original, podemos fazê-lo adicionando uma linha à nossa função print_call:

>>> def print_call(fn):
...   def fn_wrap(*args, **kwargs): #take any arguments
...     print("Calling %s" % (fn.func_name))
...     return fn(*args, **kwargs) #pass any arguments to fn()
...   fn_wrap.func_name = fn.func_name #Copy the original name
...   return fn_wrap

Uma vez que este está se transformando em um artigo muito longo, vou parar por aqui e voltar em breve com a parte dois, na qual veremos closures, partials, e (finalmente) decorators.

Até lá, se tudo isso for novo para você, use print_call como base para criar uma função que irá imprimir o nome da função e argumentos passados antes de chamar a função empacotada, e o nome da função e o valor de retorno antes de retornar.

⁂

Na Parte 01, nós vimos o envio de funções como argumentos para outras funções, em funções agrupadas e, finalmente, empacotar uma função em outra. Vamos começar esta parte, dando um exemplo de implementação para o exercício que eu dei na Parte 01:

System Message: ERROR/3 (<string>, line 11)

Unknown directive type "code".
.. code:: python
>>> def print_call(fn):
... def fn_wrap(*args, **kwargs):
... print("Calling %s with arguments: \n\targs: %s\n\tkwargs:%s" % (
... fn.__name__, args, kwargs))
... retval = fn(*args, **kwargs)
... print("%s returning '%s'" % (fn.func_name, retval))
... return retval
... fn_wrap.func_name = fn.func_name
... return fn_wrap
...
>>> def greeter(greeting, what='world'):
... return "%s %s!" % (greeting, what)
...
>>> greeter = print_call(greeter)
>>> greeter("Hi")
Calling greeter with arguments:
args: ('Hi',)
kwargs:{}
greeter returning 'Hi world!'
'Hi world!'
>>> greeter("Hi", what="Python")
Calling greeter with arguments:
args: ('Hi',)
kwargs:{'what': 'Python'}
greeter returning 'Hi Python!'
'Hi Python!'
>>>

Então, isso é no mínimo ligeiramente útil, mas vai ficar melhor! Você pode ou não ter ouvido falar de closures, e você pode ter ouvido de um grande número de definições do que uma closure é - eu não vou entrar em picuinhas, mas apenas dizer que uma closure é um bloco de código (por exemplo, uma função), que capta variáveis (ou faz um close over) não-locais (livre). Se tudo isso é meio sem lógica ou papo furado para você, provavelmente você está precisando de uma reciclagem, mas não tenha medo - eu vou mostrar, através de exemplo, e o conceito é bastante fácil de entender: uma função pode fazer referência a variáveis que são definidas no escopo de fechamento da função.

Por exemplo, dê uma olhada neste código:

    System Message: ERROR/3 (<string>, line 54)

    Unknown directive type "code".

    .. code:: python
     >>> a = 0
     >>> def get_a():
     ...   return a
     ...
     >>> get_a()
     0
     >>> a = 3
     >>> get_a()
     3

Como você pode ver, a função get_a pode obter o valor de a, e será capaz de ler o valor atualizado. No entanto, existe uma limitação - uma variável capturada não pode ser escrita para:

    System Message: ERROR/3 (<string>, line 70)

    Unknown directive type "code".

    .. code:: python
     >>> def set_a(val):
     ...   a = val
     ...
     >>> set_a(4)
     >>> a
     3

O que aconteceu aqui? Desde que uma closure não pode escrever todas as variáveis capturadas, a = val realmente escreve para uma variável local a que acompanha o nível de módulo a que queríamos escrever. Para contornar essa limitação (o que pode ou não ser uma boa ideia), podemos usar um tipo de recipiente:

    System Message: ERROR/3 (<string>, line 85)

    Unknown directive type "code".

    .. code:: python
     >>> class A(object): pass
     ...
     >>> a = A()
     >>> a.value = 1
     >>> def set_a(val):
     ...   a.value = val
     ...
     >>> a.value
     1
     >>> set_a(5)
     >>> a.value
     5

Assim, com o conhecimento de que uma função captura variáveis a partir de seu escopo de fechamento, finalmente estamos aproximando de algo interessante, e vamos começar pela implementação de um partial. Um partial é uma instância de uma função na qual você já preencheu alguns ou todos os argumentos; digamos, por exemplo, que você tem uma sessão com nome de usuário e senha armazenada, e uma função que consulta alguma camada de backend que leva argumentos diferentes, mas sempre requer credenciais. Em vez de passar as credenciais manualmente toda vez, podemos usar um partial para pré-preencher os valores:

    System Message: ERROR/3 (<string>, line 110)

    Unknown directive type "code".

    .. code:: python
     >>> #Our 'backend' function
     ... def get_stuff(user, pw, stuff_id):
     ...   """Here we would presumably fetch data using the supplied
     ...   credentials and id"""
     ...   print("get_stuff called with user: %s, pw: %s, stuff_id: %s" % (
     ...         user, pw, stuff_id))
     >>> def partial(fn, *args, **kwargs):
     ...   def fn_part(*fn_args, **fn_kwargs):
     ...     kwargs.update(fn_kwargs)
     ...     return fn(*args + fn_args, **kwargs)
     ...   return fn_part
     ...
     >>> my_stuff = partial(get_stuff, 'myuser', 'mypwd')
     >>> my_stuff(3)
     get_stuff called with user: myuser, pw: mypwd, stuff_id: 3
     >>> my_stuff(67)
     get_stuff called with user: myuser, pw: mypwd, stuff_id: 67

Partials podem ser utilizados em vários lugares para remover duplicação de código em que uma função é chamada em lugares diferentes com os mesmos, ou quase os mesmos, argumentos. Claro, você não precisa implementá-lo, basta fazer from functools import partial.

Finalmente, vamos dar uma olhada em função decorators. Uma função decorator é (pode ser implementada como) uma função que recebe uma função como parâmetro e retorna uma nova. Soa familiar? Deveria, porque já implementamos um working decorator: a nossa função print_call está pronta para ser usada como está:

    System Message: ERROR/3 (<string>, line 142)

    Unknown directive type "code".

    .. code:: python
     >>> @print_call
     ... def will_be_logged(arg):
     ...   return arg*5
     ...
     >>> will_be_logged("!")
     Calling will_be_logged with arguments:
          args: ('!',)
          kwargs:{}
     will_be_logged returning '!!!!!'
     '!!!!!'

Usar a notação @ é simplesmente uma abreviação conveniente para fazer:

    System Message: ERROR/3 (<string>, line 157)

    Unknown directive type "code".

    .. code:: python
     >>> def will_be_logged(arg):
     ...   return arg*5
     ...
     >>> will_be_logged = print_call(will_be_logged)

Mas e se quisermos ser capazes de parametrizar o decorator? Nesse caso, a função utilizada como um decorator receberá os argumentos, e deverá retornar uma função que envolve a função decorated:

    System Message: ERROR/3 (<string>, line 169)

    Unknown directive type "code".

    .. code:: python
     >>> def require(role):
     ...   def wrapper(fn):
     ...     def new_fn(*args, **kwargs):
     ...       if not role in kwargs.get('roles', []):
     ...         print("%s not in %s" % (role, kwargs.get('roles', [])))
     ...         raise Exception("Unauthorized")
     ...       return fn(*args, **kwargs)
     ...     return new_fn
     ...   return wrapper
     ...
     >>> @require('admin')
     ... def get_users(**kwargs):
     ...   return ('Alice', 'Bob')
     ...
     >>> get_users()
     admin not in []
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
       File "<stdin>", line 7, in new_fn
     Exception: Unauthorized
     >>> get_users(roles=['user', 'editor'])
     admin not in ['user', 'editor']
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
       File "<stdin>", line 7, in new_fn
     Exception: Unauthorized
     >>> get_users(roles=['user', 'admin'])
     ('Alice', 'Bob')

E aí está. Agora você está pronto para escrever decorators, e talvez usá-los para escrever aspectos orientados a Python; acrescentar @cache, @trace, @throtlle é bem trivial (e antes que você adicione @cache, faça a verificação functools mais uma vez se você estiver usando Python 3!).

⁂

Creio que Python é importante para o desenvolvimento de software. Embora existam linguagens mais poderosas (por exemplo, Lisp), mais rápidas (por exemplo C), mais usadas (como Java) e mais estranhas (por exemplo, Haskell), o Python obtém um monte de coisas diferentes de forma correta, e em uma combinação que nenhuma outra linguagem que eu conheço tem feito até agora.

Ele reconhece que você vai gastar muito mais tempo lendo código do que escrevendo-o e se concentra em orientar os desenvolvedores para escreverem um código legível. É possível escrever um código obfuscated em Python, mas a maneira mais fácil de escrever o código (assumindo que você conheça Python) é quase sempre uma forma que seja razoavelmente concisa, e mais importante: um código que sinaliza claramente a intenção. Se você souber Python, você pode trabalhar com quase qualquer Python sem muita dificuldade. Mesmo as bibliotecas que adicionam funcionalidades "mágicas" podem ser escritas em Python perfeitamente legível (compare isso com a compreensão da implementação de um framework, como o Spring em Java).

O Python também reconhece que a velocidade de desenvolvimento é importante. Um código legível e conciso é parte disso, e também é o acesso a construções poderosas que evitam a repetição tediosa de código. Manutenibilidade também está vinculado a isso - LoC pode ser tudo menos uma métrica inútil, mas diz algo sobre a quantidade de código que você tem que verificar, ler e/ou entender para solucionar problemas ou ajustar comportamentos.

Essa velocidade de desenvolvimento, a facilidade com que um programador de outras linguagens pode ter habilidades básicas em Python e a enorme biblioteca padrão são as chaves para outra área onde o Python se destaca - toolmaking. Qualquer grande projeto terá tarefas para automatizar, e automatizá-las em Python é, em minha experiência, mais rápido do que usar linguagens mais populares - na verdade, foi assim que comecei com Python, criando uma ferramenta para automatizar a configuração de Rational Purify para um projeto onde antes era uma tarefa que nunca havia sido executada (e vazamentos de memória não eram corrigidos). Eu já havia criado ferramentas para extrair informações de sistemas de registro e apresentá-las de uma forma útil para a equipe, ferramentas para verificar poms em um projeto Maven, integração Trac, ferramentas de monitoramento personalizadas... e muito mais. Todas essas ferramentas foram rápidas de implementar, economizaram muito tempo, e muitas deles mais tarde foram corrigidas e atualizadas por pessoas sem experiência em Python - sem quebrar.

Aquela construção de ferramentas personalizadas são dicas fáceis em outra força - a construção e a manutenção de software personalizado é fácil, ponto final. É por isso que, enquanto o enorme framework Django pode ser o mais famoso framework web Python, há também uma série de micro e pequenos frameworks de sucesso.

Ao trabalhar em uma poderosa linguagem de programação com uma grande variedade de bibliotecas padrão e de terceiros, muitas vezes você não precisa aceitar os trade-offs que são necessários ao usar qualquer estrutura framework off-the-shelf. Isso significa que você pode construir exatamente o software que seus clientes querem, em vez de dizer-lhes que "esta é a forma como é feito, desculpe". Para mim, essa é uma diferença enorme. Eu me sinto envergonhado quando tenho que dizer a um cliente que não, desculpe, isso parece uma simples exigência, mas o sistema que usamos torna isso impossível ou caro de implementar de forma proibitiva. Sempre que isso acontece, você falhou.

Escrever software que se encaixa ao modelo do cliente em vez de a um framework é importante, e eu sinto que muitos desenvolvedores hoje perderam de vista esse fato simples. Vários programadores agora passam mais tempo sendo configuradores de frameworks e inventores de desculpas para suas falhas, em vez de programarem de verdade.

Finalmente, se você for um(a) chefe ou gerente geral, usar o Python tem um benefício final - programadores de Python são menos frustrados*, o que os torna mais felizes, e ainda mais produtivos!

(* pode não ser verdade quando estiverem instalando extensões de código-fonte distribuídas C no Windows)

⁂

module = types.ModuleType(name)
inlined = transform(src)
code = compile(inlined, filename, 'exec')
sys.modules[name] = module
exec(code,  module.__dict__)

def transform(src):
    """Transforms the given source and return the AST"""
    tree = ast.parse(src)
    cm = ConstantMaker()
    newtree = cm.visit(tree)
    return newtree

def visit_Module(self, node):
    """Find eglible variables to be inlined and store
    the Name->value mapping in self._constants for later use"""
    assigns = [x for x in node.body if
               type(x) == _ast.Assign]
    for assign in assigns:
        if type(assign.value) in (_ast.Num, _ast.Str):
            for name in assign.targets:
                if RE_CONSTANT.match(name.id):
                    self._constants[name.id] = assign.value
    return self.generic_visit(node)

def visit_Name(self, node):
    """If node.id is in self._constants, replace the
    loading of the node with the actual value"""
    return self._constants.get(node.id, node)

ONE = 1
TWO = "two"
THREE = 3
FOUR = 4.0
def costly(iterations):
   tempstr = ""
   obj = MyClass()
   for i in range(iterations):
     tempstr += ONE * TWO * THREE + str(i)
     obj.change()
   tempstr += str(obj.value)
    eturn tempstr
class MyClass(object):
   def __init__(self):
     self.value = random.random()*THREE
   def change(self):
     self.value += random.random()*FOUR

Fredrik Håård