Comienza a usar la biblioteca de Python de Google Data

Jeffrey Scudder, equipo de las APIs de datos de Google
Agosto de 2007

Introducción

Decidiste usar la biblioteca cliente de Python de Google Data para escribir una aplicación con uno de los muchos servicios de Google Data. ¡Excelente elección! El objetivo de este breve instructivo es que comiences a usar rápidamente la biblioteca cliente para desarrollar tu aplicación.

Probablemente quieras comenzar a crear tu aplicación de inmediato. Sin embargo, primero deberás configurar tu entorno de desarrollo y preparar las herramientas que necesitarás para ejecutar los módulos incluidos en la biblioteca cliente. Sigue los pasos que se indican a continuación y ejecutarás código en muy poco tiempo.

Instalar Python

Si vas a desarrollar con la biblioteca cliente de Python, necesitarás una versión funcional de Python 2.2 o posterior. Muchos sistemas operativos incluyen una versión de Python, por lo que es posible que puedas omitir el paso de instalación. Para ver qué versión de Python tienes, ejecuta python -V en una terminal de línea de comandos. (Nota: La V está en mayúsculas). Esto debería generar un resultado similar al siguiente:

Python 2.4.3

Si ves la versión 2.2 o una posterior, puedes comenzar a instalar dependencias. De lo contrario, consulta a continuación las instrucciones de instalación o actualización para tu sistema operativo.

Cómo instalar Python en Windows

Hay varias implementaciones de Python para elegir en Windows, pero, para los fines de esta guía, usaré el instalador .msi que se encuentra en python.org.

  1. Para comenzar, descarga el instalador desde la página de descargas de Python.
  2. Ejecuta el instalador. Puedes aceptar todos los parámetros de configuración predeterminados.
  3. Para ver si la instalación funciona como se espera, abre un símbolo del sistema y ejecuta python -V.

Instala Python en Mac OS X

La lista de descargas en python.org incluye instaladores .dmg para los usuarios de Mac. Sigue estos pasos para instalar uno de ellos:

  1. Navega a http://www.python.org/download/mac/.
  2. En esta página, descarga el instalador para la versión adecuada de Mac OS X. Nota: La página de instalación de Python para Mac OS X 10.3.8 y versiones anteriores es diferente de las versiones más recientes de Mac OS X. Para encontrar tu versión de OS X, elige Acerca de esta Mac en el menú Apple que se encuentra en la esquina superior izquierda de la pantalla.
  3. Una vez que finalice la descarga, haz doble clic en el nuevo archivo de imagen de disco (p. ej., python-2.5-macosx.dmg) para activarlo. Si ejecutas Safari, este paso ya se completó por ti.
  4. Abre la imagen montada y haz doble clic en el paquete del instalador que se encuentra dentro.
  5. Sigue las instrucciones de instalación y lee la información y los acuerdos de licencia a medida que se te presenten. Nuevamente, la configuración predeterminada funcionará bien aquí.
  6. Para verificar la instalación, abre Terminal.app (en /Applications/Utilities) y ejecuta python -V. Debería aparecer la versión de la instalación.

Cómo instalar Python en Linux

Para instalar en Linux y otros sistemas operativos de estilo *nix, prefiero descargar el código fuente y compilarlo. Sin embargo, es posible que puedas usar tu administrador de paquetes favorito para instalar Python. (Por ejemplo, en Ubuntu, esto puede ser tan sencillo como ejecutar sudo apt-get install python en la línea de comandos). Para instalar desde la fuente, sigue estos pasos:

  1. Descarga el archivo tar.gz de la fuente desde la página de descargas de Python.
  2. Una vez que descargues el paquete, descomprímelo con la línea de comandos. Puedes usar lo siguiente 
    tar zxvf Python-2.<Your version>.tgz
  3. A continuación, deberás compilar e instalar el código fuente del intérprete de Python. En el directorio descomprimido, ejecuta ./configure para generar un archivo makefile.
  4. Luego, ejecuta make. Esto creará un archivo ejecutable de Python en funcionamiento en el directorio local. Si no tienes permiso de administrador o solo quieres usar Python desde tu directorio principal, puedes detenerte aquí. Podrás ejecutar Python desde este directorio, por lo que te recomendamos que lo agregues a tu variable de entorno PATH.
  5. Prefiero tener Python instalado en /usr/bin/, donde la mayoría de las secuencias de comandos de Python buscan el intérprete. Si tienes acceso de administrador, ejecuta make install como administrador. Esto instalará Python en la ubicación predeterminada y todos los usuarios de tu máquina podrán usarlo.
  6. Para verificar si la instalación funciona según lo esperado, abre una terminal y ejecuta python -V.

Instala dependencias

Actualmente, la única dependencia externa es una biblioteca XML llamada ElementTree. Si usas Python 2.5 o una versión posterior, no necesitarás instalar ElementTree, ya que se incluye en el paquete de Python.

Para ver si ElementTree ya está presente en tu sistema, haz lo siguiente:

  1. Ejecuta el intérprete de Python. Por lo general, ejecuto python en la línea de comandos.
  2. Intenta importar el módulo ElementTree. Si usas Python 2.5 o una versión posterior, ingresa lo siguiente en el intérprete: 
    from xml.etree import ElementTree
     Para versiones anteriores, ingresa lo siguiente: 
    from elementtree import ElementTree
  3. Si la importación falla, deberás seguir leyendo esta sección. Si funciona, puedes pasar a Cómo instalar la biblioteca de Google Data.
  4. Descarga una versión adecuada para tu sistema operativo. Por ejemplo, si usas Windows, descarga elementtree-1.2.6-20050316.win32.exe. Para otros sistemas operativos, recomiendo descargar una versión comprimida.
  5. Si usas una versión .tar.gz o .zip de la biblioteca, primero descomprímela y, luego, instálala ejecutando ./setup.py install.

Cuando ejecutas ./setup.py install, se intenta compilar la biblioteca y colocarla en el directorio del sistema para tus módulos de Python. Si no tienes acceso de administrador, puedes instalar los módulos en tu directorio principal o en una ubicación alternativa ejecutando ./setup.py install --home=~. Esto colocará el código en tu directorio principal.

Existe otra opción que evita la instalación por completo. Una vez que descomprimas la descarga, encontrarás un directorio llamado elementtree. Este directorio contiene los módulos que deberás importar. Cuando llamas a import desde Python, busca un módulo con el nombre deseado en varios lugares. El primer lugar en el que busca es el directorio actual, por lo que, si siempre ejecutas tu código desde un directorio, puedes colocar el directorio elementtree allí. Python también buscará en los directorios que se indican en la variable de entorno PYTHONPATH. Para obtener instrucciones sobre cómo editar tu archivo PYTHONPATH, consulta el Apéndice al final de este artículo. Te recomiendo que uses ./setup.py install para elementtree.

Cómo instalar la biblioteca de datos de Google

Descarga la biblioteca de Google Data para Python si aún no lo has hecho. Busca la versión más reciente en la página de descargas del proyecto de Python.

Después de descargar la biblioteca, descomprímela con unzip o tar zxvf, según el tipo de descarga que hayas elegido.

Ahora, puedes instalar los módulos de la biblioteca para que se puedan importar a Python. Puedes hacerlo de cualquiera de las siguientes maneras:

  • Si puedes instalar paquetes para que todos los usuarios accedan a ellos, puedes ejecutar ./setup.py install desde el directorio principal del archivo descomprimido.
  • Si quieres instalar estos módulos para usarlos en tu directorio principal, puedes ejecutar ./setup.py install --home=<tu directorio principal>.

  • En algunos casos, es posible que desees evitar la instalación de los módulos por completo. Para ello, modifica la variable de entorno PYTHONPATH para incluir un directorio que contenga los directorios gdata y atom para la biblioteca cliente de Python de Google Data. Si quieres obtener instrucciones para modificar tu PYTHONPATH, consulta el Apéndice al final de este artículo.

  • Una última opción que mencionaré es copiar los directorios gdata y atom del directorio src en el directorio en el que te encuentres cuando ejecutes python. Python buscará en el directorio actual cuando realices una importación, pero no recomiendo este método, a menos que estés creando algo rápido y simple.

Una vez que hayas instalado la biblioteca de Google Data, podrás probarla.

Ejecuta pruebas y muestras

Las distribuciones de la biblioteca cliente de Python de Google Data incluyen algunos casos de prueba que se usan en el desarrollo de la biblioteca. También pueden servir como una verificación rápida para asegurarse de que las dependencias y la instalación de la biblioteca funcionen. Desde el directorio de nivel superior en el que descomprimiste tu copia de la biblioteca, intenta ejecutar lo siguiente:

./tests/run_data_tests.py

Si este script se ejecuta correctamente, deberías ver un resultado en la línea de comandos como el siguiente:

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

...

Si no viste ningún error mientras se ejecutaban las pruebas, es probable que hayas configurado tu entorno correctamente. ¡Felicitaciones!

Ahora puedes comenzar a ejecutar algo más interesante. La distribución contiene un directorio samples que incluye código que puede proporcionar un punto de partida para escribir tu aplicación. Si quieres probar un ejemplo interactivo simple, ejecuta ./samples/docs/docs_example.py. La muestra de la API de Google Documents List te solicitará la dirección de correo electrónico y la contraseña de tu Cuenta de Google. Si tienes documentos u hojas de cálculo en Documentos de Google, puedes enumerarlos ingresando 1 para la operación seleccionada. (Si no tienes documentos ni hojas de cálculo, recibirás un error 404).

Si hay un servicio de datos de Google en particular que te interesa, consulta su muestra para tener una idea básica de cómo puedes usar la biblioteca. La mayoría de las funciones, pero no todas, se demuestran en el código de muestra, por lo que te recomendamos que consultes la documentación del servicio con el que planeas trabajar para tener una idea clara de lo que puedes hacer con la API.

Cómo escribir un ejemplo de "Hello World"

Comencemos con un ejemplo simple. Aquí tienes un programa corto para imprimir una lista de todos los documentos de tu cuenta de Documentos de 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

Guarda el fragmento de código anterior como un archivo y ejecútalo, o bien pégalo en el intérprete de Python para ver la biblioteca cliente de Python de Google Data en funcionamiento.

Conclusión

Ahora que instalaste y probaste la biblioteca cliente de Python de Google Data, puedes comenzar a escribir la próxima gran aplicación con los siguientes elementos:

A medida que sigas desarrollando tu aplicación, es posible que te encuentres con algún problema. Si es así, consulta la siguiente lista de recursos:

Si se te ocurre una nueva función excelente para la biblioteca (o si encuentras un error por casualidad), agrégala al grupo de debate. Siempre nos interesan tus comentarios.

¡Feliz programación! :-)

Apéndice: Cómo modificar PYTHONPATH

Cuando importas un paquete o módulo en Python, el intérprete busca el archivo en una serie de ubicaciones, incluidos todos los directorios que se enumeran en la variable de entorno PYTHONPATH. A menudo, modifico mi PYTHONPATH para que apunte a los módulos en los que copié el código fuente de una biblioteca que estoy usando. Esto evita la necesidad de instalar un módulo cada vez que se modifica, ya que Python cargará el módulo directamente desde el directorio que contiene el código fuente modificado.

Recomiendo el enfoque PYTHONPATH si vas a realizar cambios en el código de la biblioteca cliente o si no tienes derechos de administrador en tu sistema. Si editas el PYTHONPATH, puedes colocar los módulos requeridos donde quieras.

Modifiqué mi PYTHONPATH en un sistema *nix y Mac OS X configurándolo en mi archivo de configuración de shell .bashrc. Si usas el shell de bash, puedes configurar la variable agregando la siguiente línea a tu archivo ~/.bashrc.

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

Luego, puedes aplicar estos cambios a tu sesión actual de shell ejecutando source ~/.bashrc.

En Windows XP, abre las variables de entorno de tu perfil: Panel de control > Propiedades del sistema > Configuración avanzada > Variables de entorno. Desde allí, puedes crear o editar la variable PYTHONPATH y agregar la ubicación de la copia de tu biblioteca local.