Começar a usar a biblioteca de dados do Google para Python

Jeffrey Scudder, equipe das APIs de dados do Google
agosto de 2007

Introdução

Você decidiu usar a biblioteca de cliente Python de dados do Google para criar um aplicativo usando um dos diversos serviços de dados do Google. Excelente escolha! Neste tutorial, quero ajudar você a começar a usar a biblioteca de cliente para desenvolver seu aplicativo rapidamente.

Você provavelmente quer começar e criar seu aplicativo imediatamente. No entanto, talvez seja necessário configurar o 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 imediatamente.

Como instalar o Python

Se for desenvolver com a biblioteca de cliente do Python, você precisará de uma versão de trabalho do Python 2.2 ou posterior. Muitos sistemas operacionais vêm com uma versão do Python incluída. Por isso, pode ser possível pular a etapa de instalação. Para ver qual é sua versão do Python, execute python -V em um terminal de linha de comando. Observação: o V está em maiúsculas. Isso 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, veja abaixo as instruções de instalação/upgrade para seu sistema operacional.

Como instalar o Python no Windows

Há algumas implementações do Python que podem ser escolhidas no Windows, mas para os objetivos deste guia, usaremos o instalador .msi encontrado em python.org.

  1. Para começar, faça o download do instalador na página de download do Python.
  2. Execute o instalador. Você pode aceitar todas as configurações padrão.
  3. Para ver se a instalação está funcionando como 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 os usuários de Mac. Veja as etapas para instalar uma delas:

  1. Acesse http://www.python.org/download/mac/
  2. Nesta página, faça o download do instalador para a versão apropriada 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 a versão do OS X, selecione About This Mac no menu "Apple" no canto superior esquerdo da tela.
  3. Quando o download terminar, clique duas vezes no novo arquivo de imagem de disco (por exemplo, python-2.5-macosx.dmg) para ativá-lo. Se você está usando o Safari, isso já foi feito para você.
  4. Abra a imagem montada 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 eles são apresentados a você. Novamente, as configurações padrão funcionarão aqui.
  6. Verifique a instalação abrindo Terminal.app (em /Aplicativos/Utilitários) e executando python -V. A versão da instalação será exibida.

Como instalar o Python no Linux

Para instalar no Linux e em outros sistemas operacionais *nix, é preferível fazer o download do código-fonte e compilá-lo. No entanto, você pode usar seu gerenciador de pacotes favorito para instalar o Python. Por exemplo, no Ubuntu, isso pode ser tão fácil quanto executar sudo apt-get install python na linha de comando. Para instalar a partir da fonte, siga estas etapas:

  1. Faça o download do tarball de origem na página de download do Python.
  2. Depois de fazer o download do pacote, descompacte-o usando a linha de comando. É possível usar o seguinte 
    tar zxvf Python-2.<Your version>.tgz
  3. Em seguida, você precisará compilar e instalar o código-fonte do intérprete de Python. No diretório descompactado, execute ./configure para gerar um makefile.
  4. Em seguida, execute make. Isso criará um arquivo executável Python em funcionamento no diretório local. Se você não tiver permissão raiz ou quiser apenas usar o Python a partir do seu diretório inicial, pare aqui. Você poderá executar Python a partir desse diretório, portanto, convém adicioná-lo à variável de ambiente PATH.
  5. Prefiro instalar o Python em /usr/bin/, em que a maioria dos scripts Python procura o intérprete. Se você tiver acesso raiz, execute make install como raiz. Isso instalará o Python no local padrão e poderá ser usado por todos na sua máquina.
  6. Para ver se a instalação está funcionando conforme o esperado, abra um terminal e execute python -V.

Como instalar dependências

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

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

  1. Execute o interpretador do Python. Normalmente, isso é feito executando python na linha de comando.
  2. Tente importar o módulo ElementTree. Se você estiver usando o Python 2.5 ou posterior, digite o seguinte no intérprete: 
    from xml.etree import ElementTree
    Para versões mais antigas, digite: 
    from elementtree import ElementTree
  3. Se a importação falhar, você precisará continuar lendo esta seção. Se isso funcionar, pule para Como instalar a biblioteca de dados do Google.
  4. Faça o download de 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, recomendamos o download de uma versão compactada.
  5. Se você estiver usando uma versão .tar.gz ou .zip da biblioteca, primeiro descompacte e instale-a executando ./setup.py install.

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

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

Como instalar a biblioteca de dados do Google

Faça o download da biblioteca do Google Data Python, caso ainda não tenha feito. Procure a versão mais recente na página de downloads do projeto Python.

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

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

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

  • Em alguns casos, é recomendável evitar a instalação completa dos módulos. Para fazer 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 dos dados do Google. Para instruções sobre como modificar seu PYTHONPATH, consulte o Apêndice ao final deste artigo.

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

Depois de instalar a biblioteca de dados do Google, você poderá fazer um teste dela.

Como executar testes e amostras

As distribuições da biblioteca de cliente Python dos dados do Google incluem alguns casos de teste usados no desenvolvimento da biblioteca. Eles 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 a cópia da biblioteca, tente executar o seguinte:

./tests/run_data_tests.py

Se esse script for executado corretamente, você verá uma saída na linha de comando desta forma:

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 nenhum erro tiver ocorrido durante a execução dos testes, provavelmente você configurou o ambiente corretamente. Parabéns!

Agora você pode começar a executar algo mais interessante. A distribuição contém um diretório samples que contém o código que pode fornecer um ponto de partida para criar o aplicativo. Para testar uma amostra interativa simples, execute ./samples/docs/docs_example.py. O exemplo da API Google Documents List solicitará o endereço de e-mail e a senha da sua Conta do Google. Se você tiver documentos ou planilhas em Documentos Google, liste-os inserindo 1 para a operação selecionada. Se não houver documentos ou planilhas, você receberá um erro 404.

Se você tiver interesse em um serviço de dados do Google específico, dê uma olhada na amostra para ter uma ideia básica de como usar a biblioteca. A maioria dos recursos é demonstrada no exemplo de código, então recomendamos que você consulte a documentação do serviço com que pretende trabalhar para ter uma noção clara do que é possível fazer com a API.

Como escrever um exemplo "Hello World"

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

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 o execute ou cole o código no intérprete de Python para ver a biblioteca de cliente Python de dados do Google em uso.

Conclusão

Agora que você instalou e testou a biblioteca de cliente Python de dados do Google, está tudo pronto para começar a criar o próximo ótimo aplicativo usando:

Enquanto desenvolve seu aplicativo, você pode ter dificuldades. Se esse for o caso, confira a lista de recursos abaixo:

Se você pensar em um novo recurso para a biblioteca (ou encontrar um bug), insira-o no grupo de discussão. Estamos sempre interessados no seu feedback.

Boa codificação :-)

Apêndice: como modificar o PYTHONPATH

Ao importar um pacote ou módulo no Python, o interpretador procura o arquivo em vários locais, incluindo todos os diretórios listados na variável de ambiente PYTHONPATH. Muitas vezes, modifico o 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.

Recomendamos 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 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, poderá definir a variável adicionando a seguinte linha ao seu arquivo ~/.bashrc.

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

Em seguida, é possível aplicar essas alterações à sessão de shell atual executando source ~/.bashrc.

No Windows XP, acesse as variáveis de ambiente do perfil: Painel de controle > Propriedades do sistema > Avançado > Variáveis de ambiente. A partir daí, é possível criar ou editar a variável PYTHONPATH e adicionar o local da cópia da biblioteca local.