Como começar a usar a biblioteca Python de dados do Google

Jeffrey Scudder, equipe das APIs Google Data
agosto de 2007

Introdução

Você decidiu usar a biblioteca de cliente Python de dados do Google para gravar um aplicativo usando um dos vários serviços de dados do Google. Excelente escolha! O objetivo deste tutorial curto é ajudar você a começar a usar a biblioteca de cliente para desenvolver seu aplicativo.

Você provavelmente vai querer começar a criar seu aplicativo imediatamente. No entanto, talvez seja necessário configurar seu ambiente de desenvolvimento e as ferramentas necessárias para executar os módulos incluídos na biblioteca de cliente. Siga as etapas abaixo para começar a executar o código em pouco tempo.

Como instalar o Python

Se você for desenvolver com a biblioteca de cliente Python, vai precisar de uma versão funcional do Python 2.2 ou mais recente. Muitos sistemas operacionais vêm com uma versão do Python incluída, então talvez seja possível pular a etapa de instalação. Para saber qual versão do Python você tem, execute python -V em um terminal de linha de comando. Observação: o V está em maiúsculas. Isso vai resultar em algo como:

Python 2.4.3

Se você vir a versão 2.2 ou mais recente, poderá começar a instalar dependências. Caso contrário, confira abaixo as instruções de instalação/upgrade para seu sistema operacional.

Como instalar o Python no Windows

Há algumas implementações do Python para escolher no Windows, mas, para fins deste guia, vou usar o instalador .msi encontrado em python.org.

  1. Comece fazendo o download do instalador na página de download do Python.
  2. Execute o instalador e aceite todas as configurações padrão.
  3. Para verificar se a instalação está funcionando conforme esperado, abra um prompt de comando e execute python -V.

Como instalar o Python no Mac OS X

A lista de downloads em python.org tem instaladores .dmg para usuários de Mac. Estas são as etapas para instalar um deles:

  1. Acesse http://www.python.org/download/mac/.
  2. Nessa página, faça o download do instalador para a versão adequada do Mac OS X. Observação: a página de instalação do Python para Mac OS X 10.3.8 e versões anteriores é diferente das versões mais recentes do Mac OS X. Para encontrar sua versão do OS X, escolha Sobre este Mac no menu Apple, no canto superior esquerdo da tela.
  3. Depois que o download terminar, clique duas vezes no novo arquivo de imagem do disco (por exemplo, python-2.5-macosx.dmg) para montá-lo. Se você estiver usando o Safari, isso já foi feito.
  4. Abra a imagem ativada e clique duas vezes no pacote do instalador.
  5. Siga as instruções de instalação e leia as informações e os contratos de licença conforme forem apresentados. As configurações padrão vão funcionar bem aqui.
  6. Verifique a instalação abrindo o Terminal.app (em /Applications/Utilities) e executando python -V. A versão da instalação vai aparecer.

Como instalar o Python no Linux

Para instalar no Linux e em outros sistemas operacionais estilo *nix, prefiro baixar o código-fonte e compilá-lo. No entanto, talvez seja possível usar seu gerenciador de pacotes favorito para instalar o Python. Por exemplo, no Ubuntu, basta executar sudo apt-get install python na linha de comando. Para instalar da origem, siga estas etapas:

  1. Faça o download do tarball de origem na página de download do Python.
  2. Depois de baixar o pacote, descompacte-o usando a linha de comando. Você pode usar o seguinte 
    tar zxvf Python-2.<Your version>.tgz
  3. Em seguida, compile e instale o código-fonte do interpretador Python. No diretório descompactado, execute ./configure para gerar um makefile.
  4. Depois, execute make. Isso vai criar um arquivo executável do Python no diretório local. Se você não tiver permissão de root ou quiser usar o Python no diretório inicial, pare por aqui. Você poderá executar o Python nesse diretório. Por isso, talvez seja interessante adicioná-lo à variável de ambiente PATH.
  5. Prefiro ter o Python instalado em /usr/bin/, onde a maioria dos scripts Python procura o interpretador. Se você tiver acesso root, execute make install como root. Isso vai instalar o Python no local padrão e ele poderá ser usado por todos na sua máquina.
  6. Para verificar se a instalação está funcionando conforme esperado, abra um terminal e execute python -V.

Como instalar dependências

No momento, a única dependência externa é uma biblioteca XML chamada ElementTree. Se você estiver usando o Python 2.5 ou uma versão mais recente, não será necessário instalar o ElementTree, já que ele vem com o pacote do Python.

Para verificar se o ElementTree já está presente no seu sistema, faça o seguinte:

  1. Execute o interpretador Python. Normalmente, faço isso executando python na linha de comando.
  2. Tente importar o módulo ElementTree. Se você estiver usando o Python 2.5 ou uma versão mais recente, insira o seguinte no interpretador: 
    from xml.etree import ElementTree
     Para versões mais antigas, digite: 
    from elementtree import ElementTree
  3. Se a importação falhar, continue lendo esta seção. Se funcionar, pule para Instalar a biblioteca de dados do Google.
  4. Baixe uma versão adequada para seu sistema operacional. Por exemplo, se você estiver usando o Windows, faça o download de elementtree-1.2.6-20050316.win32.exe. Para outros sistemas operacionais, recomendo baixar uma versão compactada.
  5. Se você estiver usando uma versão .tar.gz ou .zip da biblioteca, primeiro descompacte e depois instale executando ./setup.py install.

A execução de ./setup.py install tenta compilar a biblioteca e colocá-la no diretório do sistema para seus módulos Python. Se você não tiver acesso root, instale os módulos no diretório principal ou em um local alternativo executando ./setup.py install --home=~. Isso vai colocar o código no seu diretório inicial.

Há outra opção que evita a instalação. Depois de descompactar o download, você vai encontrar um diretório chamado elementtree. Esse diretório contém os módulos que você precisa importar. Quando você chama a importação em Python, ela procura um módulo com o nome desejado em vários lugares. O primeiro lugar em que ele procura é o diretório atual. Portanto, se você sempre executar o código em um diretório, basta colocar o diretório elementtree lá. O Python também vai analisar os diretórios listados na variável de ambiente PYTHONPATH. Para instruções sobre como editar seu PYTHONPATH, consulte o Apêndice no final deste artigo. Recomendo usar ./setup.py install para elementtree.

Como instalar a biblioteca de dados do Google

Faça o download da biblioteca Python de dados do Google, se ainda não tiver feito isso. Procure a versão mais recente na página de downloads do projeto Python.

Depois de baixar a biblioteca, descompacte-a usando unzip ou tar zxvf, dependendo do tipo de download escolhido.

Agora você pode instalar os módulos da biblioteca para que eles possam ser importados para o Python. Há várias maneiras de fazer isso:

  • Se você puder instalar pacotes para todos os usuários, execute ./setup.py install no diretório principal do arquivo descompactado.
  • Se quiser instalar esses módulos para usar no diretório inicial, execute ./setup.py install --home=<seu diretório inicial>.

  • Em alguns casos, é melhor evitar a instalação dos módulos. Para isso, modifique a variável de ambiente PYTHONPATH para incluir um diretório que contenha os diretórios gdata e atom da biblioteca de cliente Python do Google Data. Para instruções sobre como modificar seu PYTHONPATH, consulte o Apêndice no fim deste artigo.

  • Uma última opção que vou mencionar é copiar os diretórios gdata e atom do diretório src para qualquer diretório em que você esteja ao executar python. O Python procura no diretório atual quando você faz uma importação, mas não recomendo esse método, a menos que você esteja criando algo rápido e simples.

Depois de instalar a biblioteca de dados do Google, você poderá testá-la.

Como executar testes e amostras

As distribuições da biblioteca de cliente Python do Google Data incluem alguns casos de teste usados no desenvolvimento da biblioteca. Elas também podem servir como uma verificação rápida para garantir que as dependências e a instalação da biblioteca estejam funcionando. No diretório de nível superior em que você descompactou sua cópia da biblioteca, tente executar:

./tests/run_data_tests.py

Se o script for executado corretamente, você verá uma saída na linha de comando como esta:

Running all tests in module gdata_test
.......
----------------------------------------------------------------------
Ran 7 tests in 0.025s

OK

Running all tests in module atom_test
..........................................
----------------------------------------------------------------------
Ran 42 tests in 0.016s

OK

...

Se você não viu nenhum erro durante a execução dos testes, provavelmente configurou o ambiente corretamente. Parabéns!

Agora você pode executar algo mais interessante. A distribuição contém um diretório samples com código que pode fornecer um ponto de partida para escrever seu aplicativo. Se quiser testar um exemplo interativo simples, execute ./samples/docs/docs_example.py. O exemplo da API Google Documents List vai pedir o endereço de e-mail e a senha da sua Conta do Google. Se você tiver documentos ou planilhas nos Documentos Google, liste-os inserindo 1 para a operação selecionada. Se você não tiver documentos ou planilhas, vai receber um erro 404.

Se houver um serviço específico do Google Data que lhe interesse, confira o exemplo para ter uma ideia básica de como usar a biblioteca. A maioria, mas não todos, dos recursos são demonstrados no código de amostra. Por isso, consulte a documentação do serviço com que você planeja trabalhar para ter uma ideia clara do que é possível fazer com a API.

Como escrever um exemplo de "Hello World"

Vamos começar com um exemplo simples. Confira um pequeno programa para imprimir uma lista de todos os documentos na sua conta do Google Documentos:

import gdata.docs.service

# Create a client class which will make HTTP requests with Google Docs server.
client = gdata.docs.service.DocsService()
# Authenticate using your Google Docs email address and password.
client.ClientLogin('jo@gmail.com', 'password')

# Query the server for an Atom feed containing a list of your documents.
documents_feed = client.GetDocumentListFeed()
# Loop through the feed and extract each document entry.
for document_entry in documents_feed.entry:
  # Display the title of the document on the command line.
  print document_entry.title.text

Salve o snippet de código acima como um arquivo e execute-o ou cole o código no interpretador Python para ver a biblioteca de cliente Python de dados do Google em ação.

Conclusão

Agora que você instalou e testou a biblioteca de cliente do Python do Google Data, já pode começar a escrever o próximo aplicativo incrível usando:

Ao continuar desenvolvendo seu aplicativo, você pode encontrar um problema. Se sim, confira a lista de recursos abaixo:

Se você tiver uma ótima ideia de recurso novo para a biblioteca ou encontrar um bug, informe no grupo de discussão. Queremos receber seu feedback!

Boa codificação :-)

Apêndice: como modificar o PYTHONPATH

Quando você importa um pacote ou módulo em Python, o interpretador procura o arquivo em uma série de locais, incluindo todos os diretórios listados na variável de ambiente PYTHONPATH. Muitas vezes, modifico meu PYTHONPATH para apontar para módulos em que copiei o código-fonte de uma biblioteca que estou usando. Isso evita a necessidade de instalar um módulo sempre que ele é modificado, porque o Python carrega o módulo diretamente do diretório que contém o código-fonte modificado.

Recomendo a abordagem PYTHONPATH se você estiver fazendo mudanças no código da biblioteca de cliente ou se não tiver direitos de administrador no seu sistema. Ao editar o PYTHONPATH, você pode colocar os módulos necessários em qualquer lugar.

Modifiquei meu PYTHONPATH em um sistema *nix e Mac OS X definindo-o no arquivo de configuração do shell .bashrc. Se você estiver usando o shell bash, adicione a seguinte linha ao arquivo ~/.bashrc para definir a variável.

export PYTHONPATH=$PYTHONPATH:/home/<my_username>/svn/gdata-python-client/src

Em seguida, aplique essas mudanças à sessão de shell atual executando source ~/.bashrc.

No Windows XP, abra as variáveis de ambiente do seu perfil: Painel de controle > Propriedades do sistema > Avançado > Variáveis de ambiente. Lá, você pode criar ou editar a variável PYTHONPATH e adicionar o local da cópia da biblioteca local.