terça-feira, 3 de agosto de 2010

Sprint de Tradução do Python 3000 pra pt-BR

Vendo alguns tweets acabei me deparando com o projeto do Robert Lehmann, que está desenvolvendo um mecanismo de i18n pra ser usado no Sphinx. A idéia é tornar possível sites como o http://docs.python.org usarem os mesmos .rst, porém, com apoio de arquivos .po, pra gerar sites traduzidos.

Achei a idéia muito boa, afinal, muita gente tem necessidade de traduzir documentação gerada com o Sphinx pra diversas línguas. A idéia é que as traduções sejam simples de serem executadas. Assim, ele está usando um software de tradução colaborativa web, o Pootle.

Alguns dias depois de ver a notícia me veio a cabeça: Por que não tentar um sprint pra traduzir o máximo que nós pudermos pra pt-BR? Afinal, a comunidade de pythonistas brasileiras é muito grande!
Foi assim que eu envei uma chamada pra lista da PythonBrasil, convidando todos a participarem de um sprint numa quarta-feira (14/07/2010), às 19h no canal #python-docs-br na Freenode.

Alguns amigos e ex-amigos de trabalho já estavam traduzindo algumas strings la na instância do Pootle que o Robert criou e foi fácil achar gente pra ajudar :-)


Como foi o Sprint

Eu não tinha muita idéia de como seria o sprint, mas eu tinha o que eu precisava: gente disposta a ajudar e que sabia inglês. O sprint foi totalmente colaborativo, e todo mundo se ajudou. O Robert ficou presente no canal do início ao fim - ele gostou muito da idéia do sprint.

Nós fomos os primeiros a usar massivamente o sistema, e vimos algumas coisas que dificultaram as traduções e que esperamos que nos próximos encontros não tenhamos os mesmos problemas.

Infelizmente, muita gente apareceu bem depois que nós já havíamos iniciado e algumas pessoas não puderam ficar no momento da tradução. Outro problema foi que acabou não dando tempo de revisar muita coisa, pois o Pootle dificultou um pouco achar os tópicos dentro do .po.


Os documentos

Nós acabamos por usar uns sites que disponibilizavam documentos colaborativos. Tentamos o Typewith.me primeiro, mas ele não estava aguentando muita gente no mesmo documento. Optamos por usar o Collabedit.com.

Para evitar que o documento seja alterado, disponibilizei-o aqui: http://gist.github.com/506293


Participantes

Algumas pessoas estavam presentes mas acabaram não traduzindo nada no sprint, porém, muita gente tem traduzido esporadicamente um pouco lá no site.

Estavam no canal na hora do sprint e adicionaram seu nomes:


  • Hugo Lopes Tavares (hugo_br)
  • Renato de Pontes Pereira (renatopp)
  • Diógenes Augusto Fernandes Hermínio (diofeher)
  • Hugo Henriques Maia Vieira (hugomaiavieira)
  • Gabriel Manhães Monnerat (gmonnerat)
  • Gabriel Lima de Oliveira (gabrieloliveira)
  • Herman da Rosa Caldara (herman)
  • André Ericson (ShexNivis)
  • Jonh Edson Ribeiro de Carvalho (jonhedson)
  • Daniel Gonçalves (spanazzi)
  • Osvaldo M Yasuda (omyasuda)
  • Robert Lehmann (stargaming)

O Pŕoximo

Ainda não marcamos, mas acabei de olhar meus e-mails e vi que a galera já está querendo outro!

E aí, vamos aproveitar e contribuir com nossa comunidade? :)



domingo, 11 de julho de 2010

Mini-sprint pra tradução da documentação do Python

Depois de ver os esforços de Robert Lehmann para criar um mecanismo de i18n pro Sphinx, de forma a tornar possível manter múltiplas traduções da documentação oficial do Python eu decidi dar uma olhada no site e acabei traduzindo algumas strings.

Bem, a primeira coisa que eu notei foi que o meu amigo Hugo Maia Vieira já havia traduzido alguns arquivos e pareceu ter grandes interesses em traduzir a documentação.

Entrei em contato com o Robert hoje, perguntando sobre o sitema que ele está criando e sobre quão estável está o sistema de traduções. Ele deixou bem claro que está totalmente em beta, mas que haveria possibilidades de criar traduções, e que era pra eu avisá-lo quando eu fosse alterar uma quantidade grande de arquivos, que ele iria tentar não fazer bagunça no sistema :)


A Idéia de um Mini-Sprint
Há pouco tempo o pessoal da Python Software Foundation começou a patrocinar sprints, começando com o Packaging Sprint, em Montréal. Dois caras do projeto distutils, também participantes do Google Summer of Code 2010, fizeram um mini-sprint há poucos dias, e parece que foi bem interessante.

Pois bem, eu tive a idéia de fazer um mini-sprint pra traduzir um pouco da documentação do Python 3, e ver que bicho dá.

A comunidade brasileira de Python é imensa, e eu creio que essas traduções serão úteis a todos. Além disso, se conseguirmos realizar com sucesso o sprint, seremos pioneiros!

Além do mais, é uma forma de ajudar o Robert com idéias de como facilitar a forma que as traduções são feitas.


Onde e Quando
Estou pensando em organizar o mini-sprint na quarta-feira (14/07/2010), começando às 19:00 e terminando no máximo 23:00, chat através do canal #python-docs-br, na rede Freenode.

Os documentos que eu vejo como mais importantes são (não nessa ordem):
  • tutorial
  • faq
  • library
  • howto
  • whatsnew
  • install
  • using
  • glossary
  • reference

Como Participar
Basta aparecer no canal #python-docs-br na Freenode antes das 19:00, no dia 14/07/2010 e dizer que quer participar!

Crie uma conta no http://pootle.python.org/ e comece a brincar um pouco pra ver como é o sistema, assim no Sprint teremos menos problemas.

domingo, 13 de junho de 2010

My first 2 weeks in Google Summer of Code (May 24 - June 4)


My Acceptance in Google Summer of Code

My proposal has been sent to Python Software Foundation, to work on Pip, and my abstract was:
"The goal is to make pip less error-prone, work well in python2.x and
python3.x, make the tests more internet-independent, run platform
independently, add needed features by developers, write more
documentation and make people love it and see that easy_install's age
has gone."


I was very happy because my proposal was accepted and now I can work in a well known opensource project, with different people around the world working with me - this is a great oportunity Google, PSF and Pip guys are giving me and I will enjoy the most!

So, I got my job started in May 24 and this post is about my first two weeks.


First Two Weeks: Cotinuous Integration Server

My first two weeks were about setting up a continuous integration server with builds for python2.4, python2.5 and python2.6, both in Ubuntu Server 9.10 and Windows 2008 Server. Ian Bicking gave me access to a server (in cloud) and I used Hudson CI Server to create the buids. Access it here: http://ci.cloudsilverlining.org/view/pip

I added some documentation while getting this work done and some other work, related to continuous integration, like some features requests in the Issue Tracker have been done too.


The Meetings

My mentors Carl Meyer, Ian Bicking and Jannis Leidel, decided with me, to have weekly meetings in IRC, on Thursday, 10:00 PM (UTC), in #pip channel at Freenode. I am very lucky, because my mentors are really cool guys, are always helping me and the meetings are informal and I feel free to speak.
We had a meeting through Skype (me, Carl and Ian) and I started it a bit nervous, because it had too long I do not talk only in english to people, but they understood my intentions and the meeting was quick and focused.

The second meeting was with all of them, but just through IRC and it took a bit longer, but we discussed more stuff and for what I realized, I was doing a good job.


The Lesson

I got a lesson from this all: learn by yourself, don't depend on your college/school, learn english as soon as possible and help the community.

I started programming when I was 14. It had a good time learning C and algorithms and getting help through IRC. When I was 16 I started working in a research group, in my school, and I was the youngest guy and I have learned too much there and I knew great people. I learned Python, Agile methods, top technologies and other things with them, and I was still in high school. Now I am in my first college year, 18 years old and I realize that I am lucky, because I thoroughly enjoyed the opportunities I had. And if I've not took english classes when I was younger, I could not have learned what I learnt about computing, software and all around these.


In PyConBrasil 2008 I asked an advice to Bruce Eckel, and his advice was basically: "Do something for the community". And I am doing it since that!

So, my advice to people are starting now: learn english, study by yourself and meet great people!

Thank you all guys, for helping me along my journey!

quarta-feira, 26 de maio de 2010

Prompt colorido e com git branch

Meu terminal (gnome-terminal + bash) está assim no meu Ubuntu 9.10:






Eu alterei a fonte para Monaco 12px, troquei as cores e adicionei ao prompt o branch do repositório que eu estou (caso a pasta seja um repositório git).

E como isso foi feito?




Instalando a Fonte Monaco no Ubuntu



A instalação da fonte Monaco no Ubuntu pode ser feita da seguinte maneira:



sudo mkdir /usr/share/fonts/macfonts
sudo wget http://jorrel.googlepages.com/Monaco_Linux.ttf -O /usr/share/fonts/macfonts/Monaco_Linux.ttf
sudo fc-cache -f -v


O diretório /usr/share/fonts/macfonts será criado, a fonte Monaco_Linux.ttf será colocada em tal diretório e as configurações de fontes do sistema serão atualizadas. Muito simples!


(Créditos do post http://jorrel.blogspot.com/2007/11/monaco-on-ubuntu.html)



Como Adicionar o git branch ao Prompt


No terminal há uma variável de ambiente chamada PS1, ela guarda a mensagem que será apresentada ao usuário do terminal. Imagine a seguinte situação:


hugo@hugo-laptop:~$ echo $PS1
\u@\h:\w$

Isso significa que será mostrado na mensagem o usuário do sistema, um arroba, o hostname, dois pontos, o diretório atual e um cifrão. Em outras palavras, significa dizer que o usuário é identificado por \u, enquanto o hostname é \h e o diretório é \w.


Para personalizar as mensagens é simples, basta alterar o valor da variável PS1! Por exemplo:


hugo@hugo-laptop:~$ pwd
/home/hugo
hugo@hugo-laptop:~$ export PS1="prompt do \u:\w$ "
prompt do hugo:~$ pwd
/home/hugo
prompt do hugo:~$


A idéia é adicionar à mensagem o nome do branch do repositório git. Para saber o nome do branch no git basta um `git branch` e olhar a linha que começa com asterisco. Por exemplo:



hugo@hugo-laptop:~/should-dsl$ git branch
master
* matchers-as-functions
new_matchers_based_on_hamcrest
nsigustavo_master
rodrigomanhes
separate-matchers
hugo@hugo-laptop:~/should-dsl$


Se for desejado saber apenas o branch atual, podemos usar o grep pra fazer isso:


hugo@hugo-laptop:~/should-dsl$ git branch | grep ^\*
* matchers-as-functions
hugo@hugo-laptop:~/should-dsl$


E se quisermos apenas o nome do branch, sem o asterisco, podemos usar o sed pra remove-lo:


hugo@hugo-laptop:~/should-dsl$ git branch | grep ^\* | sed 's/\* //'
matchers-as-functions
hugo@hugo-laptop:~/should-dsl$

Agora já podemos adicionar o nosso branch à mensagem do terminal:


hugo@hugo-laptop:~/should-dsl$ branch=`git branch 2>/dev/null| grep ^\* | sed 's/\* //'`
hugo@hugo-laptop:~/should-dsl$ export PS1="\u@\h:\w($branch)$ "
hugo@hugo-laptop:~/should-dsl(matchers-as-functions)$

O redirecionamento de erros é pra tratar o caso do comando `git branch` dar um erro, ou seja, a pasta atual não ser um repositório git.



Mas o interessante é ter cores, não!?



Cores no Terminal


É possível usar cores nos terminais unix através de algumas sequências ASCII de cores. Há uma biblioteca, termcolor, que traz esse recurso pro python. Assim, é possível usá-la pra colorir o terminal. Mas no nosso caso vamos ser mais hardcores e lidarmos com as nossas sequências manualmente (porque queremos ser independentes!).



O padrão das sequências de cores é basicamente o seguinte: uma sequência dizendo que se inicia a sequencia, um modificador opcional, a cor, o texto e o finalizador de cor. O que eu quero dizer por modificador é um negrito, por exemplo.



A cor verde, por exemplo, é identificada pelo número 32. A sequência de cores se inicia sempre com um \033[ e sempre termina com um \033[m. Um texto colorido de verde no terminal pode ser feito assim:







Para quem não conseguir visualizar a imagem, o texto no terminal é:


hugo@hugo-laptop:~$ echo -e "\033[32mHello World (verde)\033[m"
Hello World (verde)
hugo@hugo-laptop:~$

Agora chegou a hora de juntar tudo num lugar só!



Mostrando o git branch colorido no prompt


Os comandos aqui usados já foram explicados, então o código segue:


function git_branch_name() {
git branch 2>/dev/null | grep -e '^*' | sed -E 's/^\* (.+)$/(\1) /'
}

function show_colored_git_branch_in_prompt() {
PS1="\[\033[01;32m\]\u@\h:\[\033[01;34m\]\w\[\033[31m\]\$(git_branch_name)\[\033[m\]$ "
}

show_colored_git_branch_in_prompt

Adicione este trecho ao ~/.bashrc e seja feliz!



Caso você queira ver as modificações sem ter que abrir outro terminal, use o comando source:


$ source ~/.bashrc



Peguei a dica nesse post: http://asemanfar.com/Current-Git-Branch-in-Bash-Prompt e alterei algumas coias. Os comentários são excelentes!



Espero que tenham gostado da dica ;-)




Updates:



  • Corrigido PS1 pra ser dinâmico, e não estático
  • Corrigida duplicação de `function`. Valeu Siminino!


quinta-feira, 20 de maio de 2010

Apresentando Retrospectivas

O que será abordado aqui


Eu participava de retrospectivas e até liderava algumas sem conhecer direito, no final acabava sendo algo que não gerava tanto valor e ficavam palavras ao vento. O que eu apresentar aqui no texto é baseado no capítulo 13 do livro Agile Coaching, "Driving Change with Retrospectives" e nos conhecimentos adquirido blogs e livros a fora.


Introdução



Retrospectivas são usadas desde a era industrial pra analisar o que aconteceu com as equipes e estudar possíveis melhorias. Muitas vezes é criada uma linha do tempo (timeline) pra registrar a evolução da equipe. Em Lean Manufecturing essa prática é conhecida como Kaizen, que significa melhora contínua.




Retrospectiva, segundo o Aurélio é:

s.f. O mesmo que retrospecto


Enquanto retrospecto é definido da seguinte forma:

s.m. Vista ou análise de fato passado.


Segundo a Wikipedia, a palavra retrospectiva vem do latim retrospectare, que significa "olhar pra trás". Ou seja, retrospectivas são nada mais, nada menos, que encontros nos quais o objetivo é olhar os fatos decorridos e tentar encontrar pontos que podem ser melhorados e estudar como aplicar tais melhorias, visando aumentar os ganhos e diminuir os desperdícios.

Henrik Kniberg diz em seu famoso livro Scrum and XP from the Trenches: "Sem retrospectivas você percebe que a equipe continua cometendo os mesmos erros de sempre". Retrospectivas tratam do processo que a equipe utiliza, são uma maneira de identificar onde as coisas não estão saindo como o esperado e estudar como reduzir os problemas.

Muitas equipes que tentam fazer retrospectivas acabam desistindo de fazê-las, pois dizem que não sentiram resultados. O problema é que na verdade quem fez não sabia como fazer uma retrospectiva. Pode parecer estranho, mas justificar pra equipe que restrospectivas são fundamentais não é tão simples. Muita gente entorta o nariz da primeira vez, até ver que funciona.

Segundo Rachel Davies e Liz Sedley, autoras do livro Agile Coaching, as retrospectivas devem ser a primeira prática ágil a ser usada pelas equipes que estão começando a usar métodos ágeis. O motivo é que nas retrospectivas são discutidos vários problemas e durante a próxima iteração a equipe já pode introduzir as mudanças e ver melhorias!

O Papel do Facilitador



Toda retrospectiva precisa de alguém pra facilitar o encontro. Alguém que guie a retrospectiva, que consiga extrair os problemas, idéias e soluções da equipe. Tal pessoa é o facilitador da retrospectiva.

Facilitando uma Retrospectiva



Cada vez que uma iteração termina deve ser feita uma retrospectiva pra abordar os seguintes tópicos:

  • Quais idéias a equipe teve desde a última iteração?
  • Quais áreas a equipe quer focar em melhorar?
  • Em quais idéias eles podem trabalhar na próxima iteração?

Metade do tempo da retrospectiva deve ser gasto olhando pra iteração passada pra ver o que aconteceu e os porquês. Em seguida idéias são levantadas para que possam ser criados planos de ação (action plans), que dizem o que deve ser feito pra implantar melhorias.

Basicamente facilitar uma retrospectiva é isso, e os próximos passos são integrar à próxima iteração as ações mais prioritárias.

Para que uma retrospectiva seja proveitosa, leva tempo e prática. Não adianta tentar consertar muitos problemas numa única iteração - não vai dar certo!

A Retrospectiva Feita nos Dojos



É um costume em coding dojos fazer uma retrospectiva no fim. Sempre que chega no tempo combinado da duração do dojo, é feito uma retrospectiva. A maneira mais básica de fazer a retrospectiva é dividir o quadro (ou flip chart) em duas colunas: O Que Foi Bom, O Que Foi Ruim. Algumas pessoas gostam de colocar uma divisão entre as duas colunas pra pegar informações sobre o que pode ser melhorado.

Um exemplo de uma imagem de retrospectiva de um dojo com duas colunas pode ser visto na seguinte imagem:

Imagem de uma retrospectiva


O problema é que na retrospectiva que acontece nos dojos ficam muitas palavras ao vento. Na maioria das vezes não dá pra criar um plano de ações para melhorar o processo. A retrospectiva acaba ficando mais como lição e compartilhamento de visões, sem ter, de fato, ações de melhorias. O ponto é que a maioria das retrospectivas feitas nos dojos são, a meu ver, mal aproveitadas.



Como Olhar Para O Passado



Há algumas maneiras de recolher informações do passado. O objetivo nesse momento da retrospectiva é entender o que aconteceu, e os membros da equipe precisam compartilhar suas histórias individuais e integrá-las com as dos outros membros. Algumas maneiras de alcançar tal objetivo são:

Linha de tempo colorida: É criada uma linha de tempo no quadro ou em algum lugar onde possa ser colado post-its e escrever os acontecimentos na linha de tempo. Post-its coloridos com frases descritivas são usados para indicar os sentimentos da equipe em determinado lugar na linha de tempo. Normalmente é usada a cor verde para o que foi proveitoso, rosa ou vermelho para o que foi estressante e amarelo para o que for neutro. Talvez seja necessário colocar uma legenda para as cores ao lado da linha de tempo pra que ninguém se perca.

Galeria de arte (art gallery): O facilitador pede a equipe que cada um desenhe uma imagem do que o projeto se parece pra eles, depois cola as imagens em algum lugar visível a todos. Assim que todos terminarem o facilitador pede que cada explique o seu desenho. Pode parecer estranho, mas as pessoas são muito boas em encontrar metáforas pro que é difícil de ser explicado com palavras. Um relato interessante citado no livro Agile Coaching foi de uma retrospectiva em que um membro desenhou um boneco de palitinhos dentro de uma caixa, e quando foi explicar pra equipe o desenho ele disse que era assim que ele se sentia no projeto - ele trabalhou muito isolado dos outros, e era como se ele não fizesse mais parte do projeto.

Há uma variação de art gallery que o Patrick Kua desenvolveu que é muito interessante, o nome é Mr. Squiggle.

Funciona da seguinte maneira: o facilitador desenha alguns traços em papéis (podem ser usados post-its) e entrega um papel pra cada membro da equipe, contendo os mesmos traços criados pelo facilitador. Dê a equipe 5 minutos pra desenharem nos papéis o que o projeto representa pra eles, usando os rabiscos que o facilitador colocou no papel. Depois peça que cada um explique seu desenho para a equipe.

O interessante do Mr. Squiggle é que cada um faz um desenho totalmente diferente, mesmo iniciando com os mesmos traços.

Bad Smells



"If it stinks, change it"
Avó do Kent Beck, discutindo sobre como criar os filhos


Assim como com código, é possível ver Bad Smells em retrospectivas - aqueles indícios de que há algo errado.

Idéias da última iteração são ignoradas É pedido a equipe novas idéias sem discutir o que aconteceu na última iteração. Isso não funciona, pois os problemas são evitados.

Palavras ao vento Vários itens estão nas colunas "O que foi bom" e "O que não foi bom", mas nenhuma ação é tomada em relação aos dados recolhidos. No fim das contas a retrospectiva serviu apenas como uma conversa e lição de vida.

Mudar o mundo Algumas equipes criam listas com coisas a serem melhoradas sem considerar a viabilidade de fazer aquelas ações na próxima iteração. Isso traz desapontamento à equipe, porque não conseguiram fazer o que planejaram, e a cada retrospectiva são adicionadas mais ações.

Ações sem "Donos" Ações que foram criadas e não possuem donos, algo como "Melhorar a comunicação" e "Fazer mais refactoring", não deveriam ser ações, pois são problemas que devem ser trabalhados. Se não houver discussão, a equipe não vai saber como implementar tais "pseudoações".

Falta de tempo para melhorar A equipe leva cinco minutos depois de uma apresentação de uma release ou demo pra conversar brevemente sobre os acontecimentos e chama isso de retrospectiva. Esse é um sinal de que a equipe não vê benefícios em retrospectivas.

Peneirando Informações



Depois que foram recolhidas informações suficientes da equipe é necessário gerar insights. Caso haja alguma informação que ainda não foi compreendida, a equipe deve esclarecê-la - não deve ser pedido diretamente para a pessoa que escreveu a nota explicar, deve ser pedido à equipe. Caso haja frases genéricas como "Ambiente de testes quebrado" ou "Cliente muito ocupado", deve ser pedido exemplos pra tornar mais fácil de ilustrar o problema pra todos.

Depois de andar sobre a timeline procurando por insights é a hora de escolher os tópicos mais importantes pra focar. Uma das técnicas é votação por pontos (dot voting). Cada membro da equipe tem três pontos que pode colocar em qualquer tópico que ache que é mais prioritário - inclusive pode usar os três pontos em um tópico só. Os tópicos com maior pontuação farão parte do planejamento de ações (action planning).

Após extrair os tópicos que a equipe quer focar, procura-se por melhorias no processo que a equipe possa fazer na próxima iteração.

Olhando pro Futuro



A segunda metade da retrospectiva deve olhar pra próxima iteração, que é quando a equipe vai trabalhar o gostaria de mudar no processo. Será necessário mais que concordar que mudanças são necessárias, a equipe deve trabalhar nas ações levantadas pra implantar as mudanças.

Antes de começar a criar ações novas, um tempo deve ser dedicado para revisar o que aconteceu com as ações da última retrospectiva. Se não foram terminadas a equipe precisa entender o motivo antes de adicionar criar mais ações. Na maioria dos casos é porque as ações não tinham dono ou porque a equipe "não teve tempo".

Um tempo deve ser investido na retrospectiva pra trabalhar num plano de ações realista, que seja claro pra todos da equipe. Para que as ações fiquem prontas a equipe precisa terminá-las. O facilitador combina com a equipe quanto tempo será gasto com as melhorias no processo na próxima interação, lembrando que as ações serão feitas enquanto a equipe continua trabalhando no plano do release, ou seja, enquanto continuam a desenvolver software.

Como Criar O Plano de Ações



Assim como no desenvolvimento de software, a equipe deve dar passos de bebê (baby steps) na hora de criar as ações pra serem implementadas na próxima iteração. Nem sempre as ações são problemas que podem ser corrigidos - às vezes são estudos sobre algum problema, estabilizar um estilo de código, etc.

Bas Vodde tem um texto excelente de como criar planos de ação, que as autoras do livro Agile Coaching resumiram no livro.

Para ter ações que funcionam, a equipe precisa, além de identificar o que precisa ser alterado, dizer como serão implementadas as mudanças. O processo de recolher as ações que Bas Vodde usa é o seguinte: cada ação tem um objetivo a longo prazo e uma ação para ser feita agora. Por exemplo:

Objetivo a longo prazo: Ter testes de aceitação automatizados
Ação para agora: Fulano vai automatizar o teste ABC usando XYZ.


No exemplo citado por Bas Vodde a equipe consiste de oito membros. Inicialmente cada membro gera um conjunto de ações - separadamente - cada uma com um objetivo a longo prazo e uma ação para ser feita; a equipe tem 10 minutos pra gerar as ações.

Após geradas as ações, a equipe se divide em duplas. Durante 10 minutos cada dupla agrupa suas ações e seleciona as 5 mais prioritárias.

Depois que as duplas selecionarem 5 ações, são gerados grupos de 4 pessoas. Cada grupo agrupa suas ações e seleciona apenas 4 de todas as 10 ações selecionadas (2 duplas selecionaram 5 ações cada) - durante o limite de 10 minutos.

Para finalizar, a equipe inteira reúne-se e de todas as 8 ações selecionadas (2 grupos de 4 pessoas e cada grupo selecionou 4 ações), seleciona as 3 mais importantes pra serem implementadas na próxima iteração.

A vantagem dessa técnica é que ela reúne tanto esforço individual quanto em grupo, além de ter que haver um consenso entre todos os membros da equipe sobre quais são as prioridades. Devagar e com passos de bebê. Independente do número de ações geradas inicialmente, no fim, apenas três ações são selecionadas. Selecionar ações demais é um erro, que já foi descrito anteriormente como bad smell (Mudar o Mundo).

Depois da retrospectiva as ações precisam ser planejadas na próxima iteração. A equipe combina como serão priorizadas as ações e post-its com as ações podem ser grudados no quadro, para que não sejam esquecidos durante a próxima iteração.

Um Formato Pra Começar



Há vários formatos de retrospectivas, alguns mais complicados que outros. Acima foi descrito um formato, mas não é recomendável que seja usado da primeira vez. Antes da retrospectiva começar é necessário arrumar uma sala pra fazer a retrospectiva e material como canetas, papel e post-its - um quadro seria muito bom.

Um exemplo de como dividir a retrospectiva, citado no livro Agile Coaching segue:
  • Revise o objetivo do encontro, e relembre a equipe das regras básicas (5 minutos)
  • Crie uma linha de tempo (15 minutos)
  • Pegue insights baseado na linha de tempo (15 minutos)
  • Selecione tópicos para focar (10 minutos)
  • Revise o progresso de ações prévias (5 minutos)
  • Gere idéias para melhorias (15 minutos)
  • Faça um planejamento de ações (15 minutos)

Esse formato é recomendável pra quem quer iniciar retrospectivas, mas usar o mesmo formato sempre não é interessante, pois se torna chato, tanto pra equipe quanto pro facilitador. Então, varie os formatos. Há vários formatos listados na wiki Agile Retrospective e podem ser encontrados em http://agileretrospectivewiki.org/index.php?title=Retrospective_Plans.

Diretriz Primária (Prime Directive)



Tratando-se de retrospectivas há algumas regras básicas, como em qualquer outra reunião, como: não usar computadores, colocar os telefones no silencioso, esperar a vez pra falar. Além das regras básicas há uma diretriz que é chamada de prime directive, que diz: "Independente do que nós descobrirmos, entendemos e acreditamos que todos fizeram o melhor que podiam, dado o que sabiam na época, seus conhecimentos e habilidades, os recursos disponíveis, e a situação em questão".

É claro que o mundo não é perfeito e as pessoas cometem erros. Apesar da diretriz primária parecer dizer que problemas não serão causados por indivídios, é bom deixar claro que as retrospectivas não são o melhor lugar para discutir problemas de perfomance dos membros. Retrospectivas devem focar em como melhorar o processo; caso a performance de algum indíviduo venha à tona, mude o foco de volta para as ações da equipe.

Rachel Davies e Liz Sedley recomendam que na primeira vez que for feita uma retrospectiva, seja colado na parede a prime directive e que você explique para a equipe o que ela significa.

Minha Tentativa Com O Mr. Squiggle



Ontem (20/05/2010) eu não esperava, mas o Gustavo Rezende me pediu pra fazer uma retrospectiva com os aspiras lá no NSI, sem preparar nada. Eu havia comentado com ele sobre essa técnica de desenhos e ele achou interessante e falou pra eu fazer. Bem, eu não havia preparado nada e era o fim de uma release de um projeto que os nossos aspiras estavam fazendo. Eles fizeram uma demonstração para o suposto cliente, que era o Ronaldo Amaral. Eles pecaram em várias coisas, mas era a primeira vez que eles trabalhavam em equipes e não conheciam as tecnologias e métodos ágeis 3 semanas atrás.

O interessante é que foi uma retrospectiva de fechamento, e no fim, eu usei os mesmos rabiscos que o Patrick Kua (porém numa disposição diferente): uma bolinha, uma reta na horizontal e outra na vertical.


Mr. Squiggle com Aspiras do NSI


Foi muito interessante ver que todos fizeram desenhos totalmente diferentes, mas que acabaram refletindo uma coisa só: o quanto eles tinha aprendido enquanto trabalhavam no projeto. Todos relataram sobre o quanto aprenderam, como foi o trabalho em equipe, como estudaram as tecnologias e etc. Como a idéia não era ter próxima iteração, pra mim não havia sentido fazer um planejamento de ações, porque o projeto que eles iniciaram iria parar ali. Mas Ronaldo achou melhor dar continuidade até na sexta-feira (mais 2 dias).

Pode parecer muito estranho de primeira, mas esse formato com desenhos funciona.

Checklist



No livro Agile Coaching há no fim de cada capítulo uma checklist que mostra os pontos principais pra executar com sucesso o que foi descrito no capítulo. No capítulo sobre retrospectivas a checklist se resume a:
  • Comece a retrospectiva olhando pro passado para entender o que aconteceu o o porquê. Dê tempo suficiente à equipe para contar a história inteira

  • Gaste a segunda metade da retrospectiva olhando pro futuro e decidindo o que irá no plano de ações

  • Procure por bad smells que estão atrapalhando a equipe a ser mais efetiva. Se as retrospectivas não estão melhorando o processo, pense em como você poderia melhorá-las

  • Ache os problemas que a equipe mais quer consertar. Use a votação por pontos para focar no que a equipe gastará suas energias

  • Não adicione mais ações durante a iteração antes da próxima retrospectiva. Até mesmo duas ou três ações terminadas a cada iteração podem causar um impacto significante por vários meses

  • Se as ações da última retrospectiva não foram finalizadas, procure saber os motivos antes de adicionar mais




Referências



O livro Agile Coaching é excelente, a maior parte do conteúdo do post é baseado no capítulo 13 dele. Há um livro só sobre retrospectivas, Agile Retrospectives. Tem um livro que eu nunca li, o Project Retrospectives, mas já fiz umas pesquisas no site deles, que por sinal tem um material muito bom.


Updates:

Adicionada foto dos desenhos feitos pelos aspiras na retrospeciva (Mr. Squiggle)



quinta-feira, 13 de maio de 2010

Gerenciando ambientes virtuais e pacotes python de forma fácil

Bem, eu estou devendo há um tempo um post sobre integração entre a Python C/API e a Ruby C/API, mas esse post vai ficar no forno mais um tempinho, porque eu tive um insight maneiro e quero compartilhar.

Ontem eu estava dando uma olhada no virtualenvwrapper, por recomendação do Hugo Maia Vieira e aproveitei pra fazer umas brincadeirinhas com ele junto ao pip.
Vou explicar a idéia de cada projeto envolvido nessa brincadeira e mostrar como criar uma maneira simples de usar ambientes virtuais personalizados e gerenciar pacotes Python (python packages).



pip


pip significa "pip install [Python] packages", ou seja, é um instalador de pacotes Python. O instalador de pacotes que já está padronizado entre os pythonistas é o easy_install, eu sei. Porém, quem nunca teve problemas com o easy_install? Quem nunca teve problemas pra desinstalar um pacote? Oh shit! Como assim o easy_install não desinstala? A maneira de "desinstalar" pacotes no easy_install é dizer que o pacote é multiversionado, e ele ainda reside no sistema mesmo assim. O que eu costumava fazer era ir lá na pasta onde ficavam meus pacotes python e remover os arquivos e remover a entrada do easy-install.pth (que guarda as referências do caminhos dos pacotes). Eu até criei um easy_uninstall pra remover meus pacotes :-).

Esse ano eu estou participando do Google Summer of Code e vou trabalhar no pip! Muito provavelmente vou blogar (num futuro próximo) sobre o pip e o que eu ando fazendo nele e o que eu tenho aprendido com o pessoal do projeto. Vai ser uma grande oportunidade pra mim e vou tentar aproveitar o máximo.

O objetivo do pip é ser um substituto do easy_install, mas com muito mais funcionalidades. Vou citar algumas coisas que o pip faz, pondo o nome do comando no cabeçalho.



pip install


O nome já diz tudo: instala algum pacote (ou alguns).

$ pip install PACOTE_DESEJADO

pip uninstall


Uma coisa básica é que o pip desinstala pacotes! Que maravilha, não? O easy_install não faz nem isso!


$ pip uninstall PACOTE_DESEJADO

pip freeze



A idéia é que você às vezes precisa saber quais pacotes você tem instalado no sistema, e o comando freeze lista todos os pacotes instalados no python em que o pip foi rodado.
$ pip freeze


pip bundle



O pip consegue criar bundles. Bundles são pacotes que contém vários pacotes. A idéia é criar um pacotão com tudo necessário pra instalar um software - dependências e etc. Ano passado eu trabalhei em um sistema que ia ser implantado em Angola e no local que ia ser instalado o sistema não havia conexão de internet boa (era 56k) e não era garantido de chegar lá em Angola e conseguir usar a internet. O que a minha equipe fez foi criar um pacotão com todas dependências de sistema e outro pacotão com todas as dependências dos pacotes python. Os meus amigos Diego Manhães e Vanderson Mota ficaram responsáveis por isso, e eu garanto que não foi trivial.

Usando o pip essa tarefa se torna fácil, porque é possível criar um pybundle com os pacotes (e suas respectivas dependências). Por exemplo:

$ pip bundle pycukes.pybundle pycukes


E para instalar no sistema (sem a necessidade de uma conexão de internet), basta levar o arquivo pycukes.pybundle num pendrive ou dvd e fazer:

$ pip install pycukes.pybundle


E nesse caso todas as dependências serão instaladas junto ao pycukes.

pip search



Sabe aquele dia que um apt-cache search salva a sua vida? Então, o pip também tem um comando search que pode salvar você! É como se você tivesse ido ao PyPI e digitado alguma coisa no campo de busca e clicado no botão Search. Você pode ver os nomes dos pacotes e as descrições dos mesmos.

$ pip search TERMO_DA_BUSCA



virtualenv


O virtualenv cria ambientes virtuais pra você usar um interpretador Python sem ser o do sistema. Quem nunca bagunçou o Python do sistema quando quis fazer alguma brincadeira? Então, o virtualenv veio pra solucionar esse e outros problemas. Você não precisa mais de ser superusuário pra instalar pacotes. Você pode ter quantos interpretadores python você quiser, e cada um deles pode ter pacotes diferentes. Ou seja, você consegue isolar um ambiente pra instalar e usar pacotes python.


Criar um ambiente virtual é muito simples:

$ virtualenv meu_ambiente


Porém, pra usar algum ambiente virtual é necessário ativar esse ambiente. Você pode fazer da seguinte forma:

$ source CAMINHO/PARA/meu_ambiente/bin/activate

ou

$ . CAMINHO/PARA/meu_ambiente/bin/activate


Após isso você verá que que o texto do seu terminal foi modificado (variável de ambiente $PS1), e lá tem o nome do seu ambiente entre parênteses. Agora você pode instalar o que quiser ali e apagar o que quiser! Fazer qualquer tipo de experimento.

O único problema nessa abordagem é que você ainda aproveita os pacotes instalados no python do sistema. A maneira de solucionar isso é dizendo que você quer criar um ambiente virtual que não tem nenhum pacote aproveitado do sistema:

$ virtualenv --no-site-packages meu_ambiente


Imagina que você criou um ambiente virtual e quer usar o pip nele, você só precisa USAR! O virtualenv já vem com o pip instalado. Mas caso você queira atualizar o pip, faça um:

$ pip install -U pip


Sempre que você quiser sair do ambiente virtual, chame o deactivate:

$ deactivate


E voltará ao ambiente normal.

Agora você já pode ser feliz com seus pacotes python e fazer o experimento que quiser, e ter quantos ambientes virtuais (isolados) você quiser. Bom, não?!



virtualenvwrapper



Quem já está acostumado a usar o virtualenv sabe que é um saco ter que lembrar os caminhos dos ambientes e ficar dando source no caminho do activate. Outra coisa chata é quando você precisa ir pra pasta de site-packages do ambiente virtual. Pensando nessas coisinhas enjoadas um cara pegou e criou um script que adiciona várias funcionalidades ao virtualenv, o virtualenvwrapper. A instalação do virtualenvwrapper é simples:

$ pip install virtualenvwrapper


Porém, ainda não dá pra sair usando. Você precisa carregar o script (virtualenvwrapper.sh) sempre que quiser usar os recursos do virtualenvwrapper. No fim das contas é melhor adicionar ao seu ~/.bashrc. Depois de instalar o virtualenvwrapper com o pip ou easy_install (eu usei o python do sistema), faça:

$ echo "source `which virtualenvwrapper.sh`" >> ~/.bashrc
$ mkdir ~/.virtualenvs

E você criará uma pasta (a padrão) pra armazenar os ambientes virtuais e sempre terá os comandos do virtualenvwrapper disponíveis.

Depois de reiniciar o terminal, você já pode usar o virtualenvwrapper! Digite:

$ workon


E você provavelmente vai ver uma linha em branco, porque você ainda não tem nenhum ambiente virtual criado com o virtualenvwrapper.


mkvirtualenv


O comando mkvirtualenv cria um ambiente virtual baseado no nome que você passar, e você pode passar os mesmos parâmetros que são passados ao virtualenv.

$ mkvirtualenv --no-site-packages meu_ambiente


Quando você digitar o comando acima criará um ambiente virtual com nome de meu_ambiente, que não compartilha pacotes com o python do sistema e irá automaticamente ativar o ambiente.


rmvirtualenv

Quando não houver mais interesse em usar um ambiente virtual, ele pode ser apagado com o comando rmvirtualenv. É necessário estar com o ambiente em questão desativado - caso esteja ativado use o deactivate.

$ rmvirtualenv meu_ambiente


workon



O comando workon quando chamado sem parâmetros mostra todos os ambientes virtuais existentes. Mas quando chamado com o nome do ambiente virtual, ativa o ambiente e executa os hooks (caso existam).

$ workon # lista os ambientes virtuais
$ workon meu_ambiente # ativa o ambiente virtual meu_ambiente


cdvirtualenv


Muda o diretório atual para o diretório do ambiente virtual. Por exemplo, você está na pasta /tmp e quer ir pra pasta do ambiente meu_ambiente:

(meu_ambiente)hugo@hugo-laptop:/tmp$ pwd
/tmp
(meu_ambiente)hugo@hugo-laptop:/tmp$ cdvirtualenv
(meu_ambiente)hugo@hugo-laptop:~/.virtualenvs/meu_ambiente $ pwd
/home/hugo/.virtualenvs/meu_ambiente


cdsitepackages

O comando cdsitepackages muda do diretório atual para o diretório de site-packages do ambiente virtual.

$ cdsitepackages



lssitepackages

O comando lssitepackages faz um ls na pasta site-packages.

$ lssitepackages



cpvirtualenv

Quando houver necessidade de clonar um ambiente virtual, seja porque você precisa basear-se nos pacotes já instalados ou por qualquer outro motivo, use o cpvirtualenv.

$ cpvirtualenv meu_ambiente meu_ambiente_clonado




Hooks



Hooks são scripts que são ativados antes, depois ou durante o acontecimento de um evento. Por exemplo, no Git você pode criar um script pra que após cada push executado no repositório diga ao servidor de integração contínua pra rodar o build.

No virtualenvwrapper existem hooks também, com a mesma idéia. A documentação do virtualenvwrapper documenta os hooks na área de Per-User Customization. Vou explicar apenas dois deles, o postactivate e o mpostmkvirtualenv.

postactivate



É um shell script que você deve colocar na sua $WORKON_HOME/postactivate - no nosso caso $WORKON_HOME será ~/.virtualenvs. O caso abaixo muda o diretório corrente para o diretório PASTA sempre que algum ambiente virtual for ativado:

$ echo 'cd PASTA_QUALQUER' >> $WORKON_HOME/postactivate


postmkvirtualenv



Uma das dicas que o Doug Hellmann, o autor do virtualenvwrapper, dá na documentação é que às vezes você precisa instalar alguns pacotes pra ter seu ambiente virtual pronto pra usar. Eu fiz isso. Sempre que eu crio um ambiente virtual alguns pacotes são instalados. No meu caso eu ainda fiz mais, eu adicionei um link pra um pacote python que é instalado junto ao Ubuntu (no caso o GTK e o Cairo, pra eu usar o pynotify no ambiente virtual).

Vamos fazer um caso simples: atualizar o pip, instalar o ipython e o nosetests.

$ echo 'pip install -U pip' >> $WORKON_HOME/postmkvirtualenv
$ echo 'pip install ipython nose' >> $WORKON_HOME/postmkvirtualenv


Agora sempre que um ambiente virtual for criado ele atualizará o pip do ambiente virtual e instalará no mesmo ambiente o pacote ipython e nose.


Peon



Imagine que você quer executar algum comando sempre que algum arquivo for modificado num determinado diretório. Como faz? Bem, você pode criar um script que cria um checksum baseado no somatório do tamanho de cada arquivo e na data de modificação. Bem, é assim que todo mundo faz. O Jeff Winkler teve a idéia de fazer um script que ficava procurando por mudanças em arquivos terminados em .py e quando havia modificação, rodava o nosetests. Ele chamou o script de nosy.



O Bernardo Heynemann acabou pegando a idéia do Jeff e criando o peon, que busca recursivamente por modificações em arquivos terminados em .py e usa o pynotify pra mostrar um alerta, caso o comando passado retorne algum status code diferente de zero.

Pra instalar o peon você pode baixar o projeto no github, cloná-lo ou instalá-lo através do arquivo compactado gerado pelo github:

$ git clone http://github.com/heynemann/peon.git
$ cd peon
$ pip install .

ou

$ pip install http://github.com/heynemann/peon/zipball/master


Para usar o peon é super simples, basta chamá-lo passando o comando que você quer que seja executado quando alguma modificação for feita. No meu caso, eu queria que o peon rodasse um script que fazia build e rodava os testes de um projeto, e caso houvesse alguma falha ou erro no script de build, mostrasse a notificação com o pynotify. No meu caso era um Makefile que o peon rodava. Era basicamente:

$ peon make


O meu problema



O pynotify é um pacote instalado pelo Ubuntu, sob o pacote do GTK e quando eu criava um ambiente virtual totalmente isolado (--no-site-packages) eu não tinha acesso ao GTK e nem ao Cairo (dependência) e assim, não tinha como usar o pynotify pra exibir os alertas.

A minha solução



A primeira coisa é que eu precisava instalar o peon sempre que eu criasse um ambiente virtual. Fiz isso usando o postmkvirtualenv. Outra coisa que eu acabei fazendo foi criar um link simbólico dentro dos meus site-packages apontando pro GTK e pro Cairo. A solução que eu cheguei foi usar o postmkvirtualenv pra criar os links simbólicos e adicionar às entradas devidas no easy-install.pth.

Ok, falei um monte de coisas. Mas... e aí, como eu faço isso? A primeira coisa é instalar o peon. Uma das features do github é que ele oferece download dos repositórios de forma compactada. Assim, pra instalar o peon basta um:

$ echo 'pip install http://github.com/heynemann/peon/zipball/master' >>\
> $WORKON_HOME/postmkvirtualenv


Agora a parte complicada é fazer os links simbólicos e adicionar as entradas no easy-install.pth.

$ echo "
> cwd=`pwd`
> cdsitepackages
> ln -s /usr/lib/pymodules/python2.6/gtk-2.0 .
> ln -s /usr/lib/pymodules/python2.6/cairo .
> sed -i '1a ./gtk-2.0' easy-install.pth
> sed -i '1a ./cairo' easy-install.pth
> cd $cwd
> " >> $WORKON_HOME/postmkvirtualenv


A primeira linha, cwd=`pwd`, e a última, cd $cwd foram adicionadas pra ser possível voltar pro diretório atual depois de executar o hook.

Agora já é possível usar o peon com ambientes virtuais sem problemas!

Faça o teste ;-)



O meu objetivo com isso



No fim das contas eu acabei criando um postmkvirtualenv que instala alguns pacotes, inclusive o peon, e cria os links simbólicos. Eu sempre crio os links e instalo o peon porque o meu objetivo com os ambientes virtuais é ter um ambiente virtual pra cada projeto que eu contribuo, assim, cada projeto é totalmente isolado do outro e eu tenho um alerta caso os testes não sejam executados com sucesso em algum momento.


Observações



Tudo que eu falei aqui está relacionado a Python 2.x. Todos os lugares onde o pip foi usado apenas pra fazer instalação de pacotes do PyPI, o easy_install poderia ter sido usado (apesar de desencorajado!).


Referências



A documentação do pip tem bastante informação e o pessoal (inclusive eu) está sempre online no #pip na freenode.


Há um post excelente pra quem quer ver o virtualenvwrapper na prática: http://mathematism.com/2009/jul/30/presentation-pip-and-virtualenv/

Nesse mesmo post há um screencast muito interessante também!


Até o próximo post ;-)





Updates:

  • corrigido erro relacionado a aspas no echo. Valeu Hugo Maia e Álvaro!

  • corrigido erro de portugues: s/enjuado/enjoado/g Valeu Hugo Maia!





segunda-feira, 1 de março de 2010

Introdução à Ruby/C API

Em Ruby há também formas de estender e embarcar o interpretador. Porém, diferentemente das documentações do Python, a documentação disponível em Ruby sempre se refere aos fatos como "estender o interpretador ruby", ou "ruby c extension", raramente falam exatamente sobre embarcar (embed). Os motivos para usar a Ruby API são os mesmos motivos que os para usar a Python/C API.

O texto abordará os mesmos tópicos do post anterior sobre a Python/C API e referenciará por vezes o post anterior. A versão do interpretador coberta pelo texto é a 1.8.

O básico da Ruby API

Ruby é uma linguagem dinâmica, assim como Python, e não precisa de especificações de tipo. Sendo assim, existe um tipo genérico quando trabalha-se com a a API: VALUE. Diferentemente da Python/C API não é usado um ponteiros pro tipo genérico, é simplesmente VALUE.

Na API não há uma exclusividade de convenção de nomes - nem tudo inicia-se com rb_. Há macros definidas como RSTRING, StringValue e chamadas como rb_define_module. Mas pode-se identificar que todas as chamadas a funções da API começam com rb_ ou ruby_.

Quando a intenção é embarcar o interpretador temos que iniciá-lo e finalizá-lo. Podemos fazer isso através das funções ruby_init e ruby_finalize, que iniciam e finalizam o interpretador ruby, respectivamente.

A Ruby API pode ser acessada através do cabeçalho ruby.h, que varia a localização em diferentes sistemas e eu conheço apenas uma maneira longa de achar o diretório, que é através do módulo rbconfig, que o mkmf usa pra achar os arquivos. O comando poderia ser feito em uma chamada longa ao interpretador diretamente na linha de comando como segue:

hugo@hugo-laptop:~$ ruby -r rbconfig \
> -e "puts Config::MAKEFILE_CONFIG['topdir']"
/usr/lib/ruby/1.8/i486-linux
hugo@hugo-laptop:~$

Isso significa que na minha máquina o arquivo ruby.h está na pasta /usr/lib/ruby/1.8/i486-linux.

Incluir o cabeçalho ruby.h cabeçalho implica em incluir diversos outros, como <stdio.h>, <stdlib.h>, <string.h>, <limits.h> (se disponíveis).

DICA: Inclua sempre o cabeçalho ruby.h antes de qualquer cabeçalho, pois o Ruby define algumas pre-processor definitions nos cabeçalhos padrões (pelo menos no GNU/Linux!).

Exemplo #1 - embarcando o interpretador: usando o método upcase

O exemplo tem a finalidade de transformar uma string minúscula em uma maiúscula, usando o interpretador Ruby pra isso. Em Ruby o método upcase está definido na classe String. Faremos então uma conversão do tipo C pra uma string em Ruby e chamaremos em seguida o método upcase:

#include "ruby.h"

int main() {
VALUE string_convertida,
resultado;
ID upcase_id;
char *string_minuscula = "hugo";
ruby_init();
upcase_id = rb_intern("upcase");

string_convertida = rb_str_new2(string_minuscula);
resultado = rb_funcall(string_convertida, upcase_id, 0);
printf("antes: %s, depois: %s\n", string_minuscula, \
StringValuePtr(resultado));

ruby_finalize();
return 0;

}

O primeiro passo foi incluir o cabeçalho ruby.h pra ter acesso à API. Depois foram definidas duas variáveis do tipo VALUE, onde string_convertida guardará a string convertida de C pra Ruby e resultado guardará o retorno do método upcase.
A variável upcase_id merece uma atenção especial. Na Ruby API pra passar nomes, em muitos dos casos, não pode ser através de uma string, mas através de um ID. Nesse caso, essa variável guardará o ID do nome upcase.
A variável string_minuscula guarda o valor "hugo", em minúsculo, pra ser convertido pra maiúsculo.

A chamada a função ruby_init é pra iniciar o interpretador Ruby pra termos acesso as facilidades do mesmo. A chamada a rb_intern retorna o ID do nome "upcase" caso exista, caso contrário ele criará na tabela de símbolos o id referente ao nome - por isso tem que ser chamado após a inicialização do interpretador.

A função rb_str_new2 cria uma string em ruby, passando como argumento o valor em C.

rb_funcall chama uma função em um determinado objeto. O primeiro parâmetro é o objeto em que reside a função, o segundo é o ID do nome da função, o terceiro o número de parâmetros e daí em diante os parâmetros. No caso acima não era necessário passar parâmetros, assim, o terceiro argumento foi 0 e não houve mais nenhum argumento após este.

A macro StringValuePtr retorna uma string (char *) com o valor da string em ruby. Após tudo isto o interpretador é finalizado, chamando ruby_finalize.

Os protótipos podem ser entendidos como:

ID rb_intern(char *nome);
VALUE rb_str_new2(char *string);
VALUE rb_funcall(VALUE obj, ID nome_id, int argc, ...);
char* StringValuePtr(VALUE string);

O executável pode ser gerado usando o GCC da seguinte maneira:

hugo@hugo-laptop:~/Desktop/posts/rb$ gcc -o upcase upcase.c \
> -I/usr/lib/ruby/1.8/i486-linux -lruby1.8
hugo@hugo-laptop:~/Desktop/posts/rb$ ./upcase
antes: hugo, depois: HUGO
hugo@hugo-laptop:~/Desktop/posts/rb$

A opção -lruby1.8 varia de sistema pra sistema, mas normalmente a opção pra linkar a biblioteca do interpretador é -lruby ou -lrubyVERSAO.

Algo correspondente em Ruby seria:

hugo@hugo-laptop:~/Desktop/posts/rb$ irb
irb(main):001:0> string_minuscula = "hugo"
=> "hugo"
irb(main):002:0> resultado = string_minuscula.upcase
=> "HUGO"
irb(main):003:0> puts "antes: #{string_minuscula}, " \
irb(main):004:0* "depois: #{resultado}"
antes: hugo, depois: HUGO
=> nil
irb(main):005:0>


Exemplo #2 - estendendo o interpretador: Criando um módulo com funções matemáticas

Nesse exemplo criaremos um módulo Matematica que conterá duas funções: fatorial e raiz_quadrada.

Em Ruby todo módulo de extensão precisa de apenas uma coisa: uma função Init_NOMEDOMODULO. O código segue:

#include "ruby.h"
#include <math.h>

int fatorial_c_puro(int n)
{
if (n <= 1)
return 1;
return n * fatorial_c_puro(n-1);
}

VALUE raiz_quadrada(VALUE self, VALUE x)
{
double raiz = sqrt(NUM2DBL(x));
return rb_float_new(raiz);
}

VALUE fatorial(VALUE self, VALUE x)
{
int x_int = NUM2INT(x);
return INT2NUM(fatorial_c_puro(x_int));
}

void Init_matematica()
{
VALUE modulo_matematica;
modulo_matematica = rb_define_module("Matematica");
rb_define_module_function(modulo_matematica, \
"fatorial", \
fatorial, \
1);
rb_define_module_function(modulo_matematica, \
"raiz_quadrada", \
raiz_quadrada, \
1);
}

A abordagem foi idêntica a usada no post sobre a Python/C API, que consiste em ter 1 função em C puro pra calcular fatorial e duas que usam a API.

A macro NUM2DBL converte um objeto numérico de ruby pro tipo double em C. A NUM2INT converte um objeto numérico pra um int e INT2NUM converte um int pra Fixnum ou Bignum.

A função responsável por iniciar o módulo sempre que é feito um require é Init_matematica. Reparem que em Python seria initmatematica, mas em Ruby o prefixo é Init_ ao invés de init.

Dentro da função que inicializa o módulo temos uma variável modulo_matematica que guarda o módulo em si. rb_define_module define um módulo com o valor de Matematica e duas funções fatorial e raiz_quadrada, ambas têm 1 parâmetro. Assim, a função fatorial será acessível da seguinte forma Matematica::fatorial.

Os protótipos podem ser entendidos como:

double NUM2DBL(VALUE n);
int NUM2INT(VALUE n);
VALUE INT2NUM(int n);
VALUE rb_define_module(char *nome);
void rb_define_module_function(VALUE modulo, \
char *nome, \
VALUE(*funcao)(), \
int argc);

Agora precisamos gerar o modulo pra ser usado pelo interpretador Ruby. A maneira mais elegante de se fazer isso é usar o módulo padrão mkmf. Porém, as duas maneiras serão mostradas.

A primeira maneira é através de uma chamada direta ao gcc, que é simples:

hugo@hugo-laptop:~/Desktop/posts/rb$ gcc -shared matematica.c \
> -I/usr/lib/ruby/1.8/i486-linux -o matematica.so -lm
hugo@hugo-laptop:~/Desktop/posts/rb$

A outra maneira é através do mkmf. Essa maneira consiste em criar um script em ruby que é responsável por criar um Makefile que gera o módulo. O arquivo se chamará extconf.rb e o conteúdo será o seguinte:

require 'mkmf'

create_makefile('matematica')

Isso significa que nós criaremos um Makefile que usará o compilador padrão, criando o arquivo matematica.so, matematica.dll ou matematica.bundle - dependo do sistema. No meu caso é um .so. Após criado o arquivo, basta rodá-lo pra criar o Makefile e depois uma simples chamada ao make cria os arquivos.

PS.: O arquivo extconf.rb deve estar no mesmo diretório em que os arquivos escritos em C.

DICA: Veja a documentação da função dir_config do módulo mkmf aqui: http://ruby-doc.org/stdlib/libdoc/mkmf/rdoc/files/mkmf_rb.html#M000549

hugo@hugo-laptop:~/Desktop/posts/rb$ ruby extconf.rb
creating Makefile
hugo@hugo-laptop:~/Desktop/posts/rb$ make
cc -I. -I/usr/lib/ruby/1.8/i486-linux \
-I/usr/lib/ruby/1.8/i486-linux \
-I. -D_FILE_OFFSET_BITS=64 \
-fPIC -fno-strict-aliasing \
-g -g -O2 -fPIC -c matematica.c
cc -shared -o matematica.so upcase.o matematica.o \
-L. -L/usr/lib -L. -Wl,-Bsymbolic-functions \
-rdynamic -Wl,-export-dynamic \
-lruby1.8 -lpthread -ldl -lcrypt -lm -lc
hugo@hugo-laptop:~/Desktop/posts/rb$

É possível testar facilmente se o módulo Matematica está acessível através de um require 'matematica'.

hugo@hugo-laptop:~/Desktop/posts/rb$ irb
irb(main):001:0> require 'matematica'
=> true
irb(main):002:0> Matematica::fatorial 5
=> 120
irb(main):003:0> Matematica::raiz_quadrada 2
=> 1.4142135623731
irb(main):004:0>


Referências

Eu comecei a estudar a Ruby C API através do projeto RubyPython, mas pra entender muita coisa eu usei como referência o livro Programming Ruby, 2nd edition, que tem o capítulo 21 dedicado a API. Também usei uma apresentação de slides com o título de Ruby C Extensions, que tem como autor Mark Volkmann. Eu tentei olhar a documentação no site oficial da linguagem, mas foi difícil de ter acesso e eu recomendo fortemente o livro, tanto pro uso da API quanto pra aprender Ruby e a apresentação mostra muitos pontos rápidamente e com exemplos.

Num futuro próximo escreverei um post sobre como fazer Ruby se comunicar com Python e vice-versa, com interface em ambos lados. Tentarei mostrar um pequeno exemplo, mas talvez nesse meio tempo eu escreva sobre algo diferente ou até mesmo detalhar mais um pouco uma das duas APIs ou aproveitar o feedback recebido e mostrar algo em que os autores dos comentários que chegaram a mim queiram ver ou aprender.

Até o próximo post ;-)

terça-feira, 23 de fevereiro de 2010

Introdução à Python/C API

Nas últimas semanas antes do carnaval eu estava estudando um projeto - RubyPython - o qual tenho grandes intenções em contribuir, pois visa integrar python e ruby com uma interface em Ruby, algo que eu, pessoalmente, acho interessante.
O projeto usa a Python/C API e a Ruby API (ambas em C), assim, eu tive que dar uma olhada nas duas APIs pra poder entender o código.

Já que eu tenho estudado um pouco das duas APIs vou começar escrevendo sobre a API do Python, porque há tempos estou pra aprende-la e até antes do rubypython não tinha tido coragem pra aprender.

Este texto tem como público alvo quem já conhece Python e tem uma base na linguagem C. Será abordado a API da linguagem Python 2.5, que é compatível com as versões 2.4 e 2.6. A API da versão 3 é diferente e não será abordada em nenhum lugar no texto.


Mas afinal, por que fazer em C?

Há duas razões pra usar a Python/C API: escrever módulos de extensão (extension modules) para estender o interpretador Python e embarcar (embed) o interpretador Python (usá-lo como um componente em uma aplicação).

Pode-se entender módulos de extensão como bibliotecas escritas em C/C++ usadas dentro do interpretador Python; e embarcar o interpretador significa usar as facilidades do interpretador a partir da API para escrever código em C ou C++.

Uma das maiores vantagens de usar a Python/C API é sem dúvidas performance. Outra vantagem é poder usar bibliotecas já prontas e adaptá-las pra serem usadas com Python.
Um exemplo de módulo de extensão é a biblioteca PIL.


O básico da Python/C API

Python é uma linguagem dinâmica e nós não temos que nos preocupamos com tipagem estática quando escrevemos código Python. Assim sendo, a API trata todos objetos Python como sendo de um tipo só: um ponteiro para PyObject: PyObject *.

Toda a API está disponível através do cabeçalho Python.h, que normalmente fica em /usr/include/pythonVERSAO, mas você pode descobrir facilmente usando o seguinte comando:

$ python-config --include

No meu caso eu obtive:

hugo@hugo-laptop:~$ python-config --include
-I/usr/include/python2.5 -I/usr/include/python2.5

O -I é a opção que deve ser passada ao GCC para incluir esse diretório nas buscas por cabeçalhos.
Então, antes de tudo nos nossos módulos de extensão ou antes de embarcar o python, devemos escrever o seguinte:

#include "Python.h"

DICA: Evite usar <Python.h> (com <> ao invés de "") pra evitar problemas de multi-plataformas.

Incluir o cabeçalho Python.h implica em incluir também alguns cabeçalhos padrões como: <stdio>, <string.h>, <errno.h>, <limits.h> e <stdlib.h> (se disponíveis).

DICA: Inclua sempre o cabeçalho Python.h antes de qualquer cabeçalho, pois o Python define algumas pre-processor definitions nos cabeçalhos padrões em algumas plataformas.

Todos os "nomes" visíveis através do cabeçalho Python.h começam com Py ou _Py, sendo os que começam com underline usados pra uso interno e devem ser evitados em código de produção.

Sempre que for necessário usar algum recurso como bibliotecas/módulos padrões do interpretador Python é necessário inicializá-lo e após todo o uso finalizá-lo. As funções Py_Initialize e Py_Finalize são respectivamente responsáveis por iniciar e finalizar o interpretador.


Exemplo #1 - embarcando o interpretador: Usando a biblioteca string

Para mostrar um caso do uso de Python embarcado vamos usar a biblioteca padrão string para tornar a string "hugo" em "HUGO" usando o método upper:

#include "Python.h"

int main()
{
PyObject *modulo_string,
*string_maiuscula;
char *string_minuscula = "hugo",
*resultado;
Py_Initialize();

modulo_string = PyImport_ImportModule("string");
string_maiuscula = PyObject_CallMethod(modulo_string, "upper", "s", string_minuscula);
resultado = PyString_AsString(string_maiuscula);
printf("antes: %s, depois: %s\n", string_minuscula, resultado);

Py_Finalize();
return 0;
}

Primeiro nós incluímos o nosso cabeçalho padrão Python.h, depois definimos duas variáveis do tipo PyObject * que serão usadas posteriormente para armazenar o módulo string e o resultado do método upper; em seguida definimos duas variáveis do tipo char * que armazenarão a nossa string "hugo" e o resultado da chamada ao método upper convertido pra C, para que usássemos com a função printf (perceba que não inclui-se <stdio.h> pois está implícito).

Após nossas declarações iniciamos o interpretador Python para que possamos usar uma de suas bibliotecas padrões.

O módulo string é obtivo através da chamada à função PyImport_ImportModule, que importa um módulo (dos módulos definidos em sys.modules).

Depois que já temos o módulo string precisamos chamar o método upper, passando como argumento uma única string (indicada por "s").
Quem nos auxilia nesse caso é a função PyObject_CallMethod, que espera como primeiro parâmetro um objeto python, como segundo o nome do método (tipo char *) e em seguida um formato dos parâmetros (que no nosso caso o "s" significa que haverá em seguida apenas UM parâmetro e que será uma string) e por último passamos o nosso tão aguardado parâmetro pro método upper.

Talvez observando os protótipos destas duas funções os parâmetros fiquem mais claros:

PyObject* PyImport_ImportModule(const char *name)
PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)

O retorno da chamada a PyObject_CallMethod no código acima é um objeto python que guardará a nossa string em upper case. Porém, a função printf definida em <stdio.h> não conhece os PyObject * da vida. Assim é necessário converter o valor de PyObject * pra char *, usando a função PyString_AsString.
Por fim encerramos o interpretador Python através da função Py_Finalize.

Nós temos o código, mas não temos o executável ainda. Usarei o GCC pra compilar esse código (meu fonte é up.c):

hugo@hugo-laptop:~/pythoncapi$ gcc -o up up.c -I/usr/include/python2.5 -lpython2.5
hugo@hugo-laptop:~/pythoncapi$ ./up
antes: hugo, depois: HUGO

A opção -lpython2.5 foi usada pra linkar a biblioteca do python2.5.

Um pouco trabalhoso, não? Se fosse em Python puro (usando a mesma abordagem) seria apenas:

>>> import string
>>> string_minuscula = "hugo"
>>> resultado = string.upper(string_minuscula)
>>> print resultado
HUGO

Exemplo #2 - estendendo o interpretador: Criando um módulo com funções matemáticas

Módulos de extensão não necessariamente usam as facilidades do interpretador Python, podendo somente criar extensões pro intepretador. Assim, no nosso caso vamos criar apenas duas funções: fatorial e raiz_quadrada e as mesmas serão acessíveis através do módulo matematica.

Para todo módulo de extensão é necessário uma função initNOMEDOMODULO e uma definição de métodos que o módulo conterá. Vamos ao código:

#include "Python.h"
#include <math.h>

int fatorial_c_puro(int n)
{
if (n <= 1)
return 1;
return n * fatorial_c_puro(n - 1);
}

PyObject *raiz_quadrada(PyObject *self, PyObject *n)
{
double raiz = sqrt(PyFloat_AsDouble(n));
return PyFloat_FromDouble(raiz);
}


PyObject *fatorial(PyObject *self, PyObject *n)
{
int n_int = PyInt_AsLong(n);
return PyInt_FromLong(fatorial_c_puro(n_int));
}

PyMethodDef funcoes_matematicas[] = {
{"raiz_quadrada", (PyCFunction)raiz_quadrada, METH_O},
{"fatorial", (PyCFunction)fatorial, METH_O},
{NULL, NULL},
};

void initmatematica()
{
Py_InitModule("matematica", funcoes_matematicas);
}

A primeira função - fatorial_c_puro - foi criada somente pra "limpar" o nosso código e deixar mais simples de entender as chamadas da API e simplesmente retorna o fatorial de um determinado número.

Toda função do tipo: Py_As, como em PyFloat_AsDouble converte do tipo em python pro tipo em C (no caso desta última converte um float em Python pra um double em C). E as funções que ao invés do As possuem o From, como em PyFloat_FromDouble convertem do tipo em C pro tipo em Python.

Toda função que será usada pelo Python tem como primeiro parâmetro um self, que é o contexto/namespace da função. As funções raiz_quadrada e fatorial recebem apenas um parâmetro, porém o self é obrigatório e não conta no número de parâmetros, é como se não existisse na definição da função.

Todo módulo tem uma definição de métodos, que são declarados em um array do tipo PyMethodDef que deve ter como último elemento uma struct com pelo menos NULL e NULL pra indicar o fim do array com as definições. No caso da variável funcoes_matematicas as duas primeiras structs tem como primeiro elemento o nome do método, como segundo a função em C (que usa a Python/C API) que é responsável pelo método, o terceiro é uma macro indicando o número de parâmetros e o quarto e último é a docstring, que nós não colocamos e que por padrão é vazia. No caso onde há apenas um parâmetro usa-se METH_O para evitar parsing manual de parâmetros.

Para facilitar, entenda PyMethodDef como definido da seguinte maneira:

typedef struct {
char *nome;
PyCFunction funcao;
int flags;
char *docstring;
} PyMethodDef;

Vale falar um pouco sobre essa indicação dos parâmetros através de flags. Na API você pode usar algumas indicações de número de parâmetros através de flags, dentre as mais usadas: METH_VARARGS, METH_KEYWORDS, METH_O e METH_NOARGS. Os dois primeiros são bem autoexplicáveis. Neles é necessário fazer o parsing manual dos parâmetros, mesmo que só tenha sido passado um. Pra facilitar nossa vida foi usado METH_O que significa que será recebido apenas um parâmetro.

Outro ponto é o casting pra PyCFunction. O casting foi usado pra evitar warnings do compilador e nada mais.

Como todo módulo precisa de uma função de inicialização do módulo, foi criada a função initmatematica, que dentro dela é inicializado o módulo matematica que contém funcoes_matematicas como os métodos do módulo.

Eu usei o gcc pra gerar o módulo e o python interativo pra mostrar o uso:

hugo@hugo-laptop:~/pythoncapi$ gcc -shared -o matematica.so\
> matematica.c -I/usr/include/python2.5 -lm
hugo@hugo-laptop:~/pythoncapi$ python
Python 2.5.2 (r252:60911, Jan 20 2010, 23:16:55)
[GCC 4.3.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import matematica
>>> matematica.fatorial(5)
120
>>> matematica.raiz_quadrada(2)
1.4142135623730951
>>>

A opção -shared do gcc gera um objeto sem linkage e a -lm é pra linkar a biblioteca matemática.


Referências

Quando eu comecei a estudar a Python/C API foi pela documentação oficial do Python 2.5, o qual eu tinha baixado o fonte. Porém, pelo site docs.python.org é possível acessar a documentação oficial da API da última versão do Python (atualmente 2.6): http://docs.python.org/c-api. Atualmente eu tenho usado o pdf Python/C API Reference Manual pra fazer consultas e o mesmo está acessível também pela página da API da versão 2.5 da linguagem: http://www.python.org/doc/2.5.2/api/api.html.


Esse texto termina aqui, porém tentarei em breve escrever mais sobre a Python/C API e sobre a Ruby API e depois sobre a integração das duas, pra tentar chegar em como o RubyPython funciona.


Até o próximo post ;-)



Updates:
24/02/2010 - O Magno Lima me alertou que eu tinha escrito fibonnaci mas tinha implementado um fatorial. Corrigido!

terça-feira, 2 de fevereiro de 2010

Migrando de Serviço de Blog

Estou largando nesse momento o meu blog na Wordpress: http://hugolt.wordpress.com para usar esse aqui no Blogger.

Motivo da mudança
Eu me cansei de brigar com os htmls no Wordpress, eu gostaria de usar o meu próprio CSS customizado, sem ter que pagar anuidade alguma por isso.
Eu começei a escrever meus posts usando reStructuredText e talvez até use Markdown em algumas situações, pois é mais cômodo que escrever HTML na mão (e a interface do Wordpress pra escrever posts é meio tosca). Eu até criei um CSS parecidíssimo com o que o GitHub usa pra usar nos arquivos markdowns que eu estava escrevendo e o Wordpress não me deixava personalizar o meu blog!
Além disso tudo a interface do Wordpress pra escrever os posts não é lá grandes coisas, é (atualmente) bem lenta comparada a essa do Blogger.

Migração dos Posts
O Blogger não permite importar blogs de outros serviços diferentes do próprio Blogger -diferente do Wordpress - e isso significa que eu não vou migrar todos os posts antigos pra cá.

Futuro do Blog
Espero que com esse novo blog eu blogue mais, pois não tenho mais motivos pra evitar escrever os posts (fora o motivo que sempre tinha: falta de tempo!).

Até o próximo post :-)