terça-feira, 5 de fevereiro de 2013

Mega-Tutorial Flask | The Flask Mega-Tutorial (pt-BR)


Olá pessoal!

Outro dia encontrei esse tutorial. Achei super legal e por isso resolvi reproduzi-lo aqui.

Esta postagem é uma tradução livre para o português do Brasil, feita por mim, a partir do texto original, publicado por Miguel Grinberg em 07/05/2012.

Mega-Tutorial Flask - Parte I: Olá, Mundo!

Este é o primeiro artigo em uma série onde eu estarei documentando minha experiência criando aplicações web em Python usando o microframework Flask.

Aqui está um índice de todos os artigos da série que foram publicados até agora:

  • Parte I: Olá, Mundo!
  • Parte II: Templates
  • Parte III: Formulários Web (Web Forms)
  • Parte IV: Banco de Dados
  • Parte V: Contas de Usuário
  • Parte VI: Páginas de Perfil e Avatares
  • Parte VII: Testes Unitários
  • Parte VIII: Seguidores, Contatos e Amigos
  • Parte IX: Paginação
  • Parte X: Busca em Todo o Texto
  • Parte XI: Suporte a E-mail
  • Parte XII: Lift facial
  • Parte XIII: Datas e Horas
  • Parte XIV: Internacionalização e Localização

Minha Formação

Eu sou um engenheiro de software com mais de dez anos de experiência no desenvolvimento de aplicações complexas em várias linguagens. Aprendi Python para criar bindings para uma biblioteca C++ no trabalho.

Além de Python, tenho criado aplicações web com PHP, Ruby, Smalltalk, e acredite ou não, até em C++. De todos esses, a combinação Python/Flask é a que eu tenho achado ser a mais flexível.

A aplicação

O aplicativo que vou desenvolver como parte deste tutorial é um serviço de microblog decentemente caracterizado que eu decidi batizar de microblog. Muito criativo, eu sei.

Estes são alguns dos conteúdos que serão abordados ao longo da criação do aplicativo:

  • Gerenciamento de usuários, incluindo controle de acessos, sessões, papeis de usuários e avatares;
  • Gestão de bancos de dados, inclusive manipulação de migração;
  • Suporte a formulários web (Web Forms), incluindo validação de campos;
  • Paginação de listas longas de itens;
  • Pesquisa full text (em todo o conteúdo);
  • Notificação de usuários por e-mail;
  • Templates HTML e RSS;
  • Suporte a múltiplas línguas (idiomas);
  • Cacherização e outras otimizações de desempenho;
  • Técnicas de debug para servidores de desenvolvimento e de produção; e
  • Instalação em um servidor de produção.

Então, como você pode perceber, com este projeto exemplo estarei discorrendo sobre os principais elementos de uma aplicação web. Espero que esta aplicação, quando finalizada, possa servir de modelo para a criação de outros projetos web.

Requisitos

Se você dispõe de um computador que rode Python 2.6 ou 2.7 provavelmente não terá problemas. A aplicação tutorial deverá executar de forma similar tanto no Windows quanto no OS X quanto no Linux.

O tutorial assume que você está familiarizado com o terminal (prompt de comando para usuários do Windows) e conhece as funções básicas de linha de comando para gerenciamento de arquivos do seu sistema operacional. Caso contrário, eu recomendo que você aprenda a criar diretórios de arquivos, cópias, etc, utilizando a linha de comando antes de continuar.

Finalmente, você deve se sentir confortável codificando em Python. Também é recomendável ter familiaridade com módulos e pacotes do Python.

Instalando o Flask

Ok, vamos começar!

Se você ainda não o fez, instale o Python 2.7.

Agora temos que instalar Flask e várias extensões que iremos utilizar. Minha forma de fazer isso é criar um ambiente virtual onde tudo é instalado de modo que a instalação do Python principal não é afetada. Como um benefício adicional, você não precisa de acesso root para fazer a instalação desta maneira.

Então, abra uma sessão do terminal, escolha um local e crie uma nova pasta para sua aplicação. Vamos chamar a pasta do aplicativo de microblog.

Em seguida, baixe o virtualenv.py e salve-o na nova pasta.

Para criar o ambiente virtual execute o seguinte comando:

$ python virtualenv.py flask

O comando acima cria um ambiente Python completo dentro da pasta flask.

Ambientes virtuais podem ser ativados e desativados quando desejado. Um ambiente ativado acrescenta sua pasta bin ao PATH do sistema de modo que, por exemplo, quando você digita python você obtém a versão do ambiente virtual e não a do sistema. Eu, pessoalmente, não gosto deste recurso. Para usar os ambientes virtuais sem ter que ativá-los basta simplesmente invocar o interpretador digitando seu caminho completo.

Se você estiver no Linux, OS X ou Cygwin instale o Flask e as extensões inserindo os seguintes comandos, um após o outro:

$ flask/bin/pip install flask
$ flask/bin/pip install flask-login
$ flask/bin/pip install flask-openid
$ flask/bin/pip install flask-mail
$ flask/bin/pip install flask-sqlalchemy
$ flask/bin/pip install sqlalchemy-migrate
$ flask/bin/pip install flask-whooshalchemy
$ flask/bin/pip install flask-wtf
$ flask/bin/pip install flask-babel
$ flask/bin/pip install flup

Se você estiver usando o Windows os comandos são um pouco diferentes:

$ flask\Scripts\pip install flask
$ flask\Scripts\pip install flask-login
$ flask\Scripts\pip install flask-openid
$ flask\Scripts\pip install flask-sqlalchemy
$ flask\Scripts\pip install sqlalchemy-migrate
$ flask\Scripts\pip install flask-whooshalchemy
$ flask\Scripts\pip install flask-wtf
$ flask\Scripts\pip install flask-babel
$ flask\Scripts\pip install flup

Estes comandos irão baixar e instalar todos os pacotes que nós usaremos em nossa aplicação.

Nota sobre o SQLAlchemy: A versão 0.8 do SQLAlchemy não é retro-compatível com versões anteriores. Particularmente, o módulo sqlalchemy-migrate não funciona com ela. Por esta razão nós precisaremos forçar a instalação da versão 0.7.9 com o seguinte comando:

$ flask/bin/pip uninstall sqlalchemy
$ flask/bin/pip install sqlalchemy==0.7.9

Uma vez que o sqlalchemy-migrate está atualizado para suportar a versão 0.8, devemos ser capazes de trabalhar com a versão mais recente.

Os usuários do Windows tem mais um passo. Se você tiver boas habilidades de observação você pode ter notado que flask-mail não foi incluído na lista de comando de instalação do Windows. Esta extensão não instala corretamente no Windows, por isso temos que executar uma solução alternativa:

$ flask\Scripts\pip install --no-deps lamson chardet flask-mail

Eu não vou entrar em detalhes sobre isso. Se você quiser mais informações consulte a documentação do flask-mail.

Se a instalação de todos os pacotes foi bem sucedida você pode excluir o arquivo virtualenv.py uma vez que não é mais necessário.

"Olá, mundo!" em Flask

Você agora tem um sub-diretório flask dentro da pasta do seu microblog que está populada com um interpretador Python, um framework Flask e as extensões que usaremos em nosso projeto. Agora é tempo de escrevermos nossa primeira aplicação web!

Navegue para o diretório microblog para criarmos a estrutura básica de nosso aplicativo:

mkdir app
mkdir app/static
mkdir app/templates
mkdir tmp

A pasta app será onde colocaremos todos os pacotes de nossa aplicação. O sub-diretório static será onde guardaremos todos os conteúdos estáticos como imagens, arquivos .js e folhas de estilo. O sub-diretório templates obviamente será onde ficarão os templates da aplicação.

Vamos agora criar um simples script de inicialização para nosso pacote app (arquivo app/__init__.py);

from flask import Flask

app = Flask(__name__)
from app import views

O script acima simplesmente instancia o objeto app (da classe Flask) e importa o módulo views que nós não criamos ainda.

As views são os controladores que respondem as requisições dos navegadores web. Em Flask views são codificadas como funções Python. Cada view é mapeada para uma ou mais URLs.

Vamos escrever nossa primeira view (aquivo app/views.py):

from app import app

@app.route('/')
@app.route('/index')
def index():
    return "Hello, World!"

Esta view é realmente muito simples. Apenas retorna uma string para ser exibida no navegador web. Os dois decorators route acima da função mapeia as URLs '/' e '/index' para esta função.

O passo final para se ter uma aplicação web totalmente funcional é criar um script que inicia o servidor web de desenvolvimento com nossa aplicativo. Vamos chamar esse script de run.py e colocá-lo na pasta raiz:

#!flask/bin/python
from app import app
app.run(debug = True)

O script simplesmente importa a variável app de nosso pacote app e invoca seu método run para startar o serviço. Lembre-se que a variável app é uma instância da classe Flask criada anteriormente.

Para iniciar o aplicativo basta executar este script. No OS X, Linux e Cygwin você tem que indicar que este é um arquivo executável antes de executá-lo:

$ chmod a+x run.py

Então o script pode ser simplesmente executado conforme a seguir:

$ ./run.py

No Windows o processo é um pouco diferente. Não é necessário indicar que este arquivo é executável. Ao invés, você tem que rodar o script como um argumento do interpretador Python:

$ flask\Scripts\python run.py

Depois que o servidor inicializa ele irá escutar a porta 5000. Agora abra seu navegador web e acesse a URL abaixo:

http://localhost:5000

Alternativamente você poderá acessar a URL:

http://localhost:5000/index

Vê o mapeamento de rotas em ação? A primeira rota mapeia para a URL '/' enquanto a segunda mapeia para '/index'. Ambas as rotas estão associadas a nossa view que produzem o mesmo resultado. Se você entrar com qualquer outra URL você verá uma mensagem de erro pois apenas essas duas estão mapeadas para uma view.

Quando você quiser parar o servidor de desenvolvimento basta teclar Ctrl-C.

E assim eu concluo a primeira parte deste tutorial.

Para aqueles que não gostam de digitar, é possível baixar o código deste tutorial no link abaixo:

Download microblog-0.1.zip.

Note que você ainda precisará instalar o Flask conforme indicado acima antes de poder executar a aplicação.

O que vem a seguir

Na próxima parte desta série nós modificaremos nossa pequena aplicação para usar templates HTML.

Espero ver vocês no próximo capítulo.

Miguel.

Referências


  1. http://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-i-hello-world
  2. http://blog.miguelgrinberg.com/author/Miguel%20Grinberg
  3. http://python.org/
  4. http://flask.pocoo.org/
  5. http://docs.python.org/tutorial/modules.html
  6. http://python.org/download/
  7. http://pypi.python.org/pypi/virtualenv
  8. https://raw.github.com/pypa/virtualenv/master/virtualenv.py
  9. https://github.com/miguelgrinberg/microblog/archive/v0.1.zip