Cómo comenzar a usar la biblioteca de Python de datos de Google

Jeffrey Scudder, equipo de API de datos de Google
Agosto de 2007

Introducción

Por lo tanto, decidiste usar la biblioteca cliente de Python de datos de Google para escribir una aplicación mediante uno de los numerosos servicios de datos de Google. ¡Excelente elección! Con este instructivo breve, mi objetivo es que comiences a usar la biblioteca cliente con rapidez para desarrollar tu aplicación.

Es probable que quieras empezar a crear tu aplicación de inmediato. Sin embargo, primero debes configurar tu entorno de desarrollo y las herramientas que necesitarás para ejecutar los módulos incluidos en la biblioteca cliente. Siga los pasos que se indican a continuación para ejecutar el código de inmediato.

Instalar Python

Si vas a desarrollar con la biblioteca cliente de Python, necesitarás una versión de Python 2.2 o superior. 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: El elemento V está en mayúsculas). Esto debería mostrar algo como lo siguiente:

Python 2.4.3

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

Instala Python en Windows

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

  1. Primero, descarga el instalador desde la página de descargas de Python.
  2. Ejecuta el instalador. Puedes aceptar todas las configuraciones predeterminadas.
  3. Para ver si la instalación funciona como se esperaba, abre un símbolo del sistema y ejecuta python -V.

Instalación de Python en Mac OS X

La lista de descargas en python.org tiene instaladores .dmg para los usuarios de Mac. Estos son los pasos para instalar uno de ellos:

  1. Navega hasta http://www.python.org/download/mac/
  2. En esta página, descarga el instalador de 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 SO X, selecciona Acerca de esta Mac en el menú de Apple en la esquina superior izquierda de la pantalla.
  3. Una vez finalizada 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, esto ya se hizo por ti.
  4. Abre la imagen activada y haz doble clic en el paquete del instalador que está dentro.
  5. Sigue las instrucciones de instalación y lee la información y los acuerdos de licencia a medida que se presentan. 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.

Instala Python en Linux

Para instalar en Linux y en 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 fácil 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 comprimido de origen desde la página de descargas de Python.
  2. Una vez que hayas descargado el paquete, descomprímelo con la línea de comandos. Puedes usar los siguientes 
    tar zxvf Python-2.<Your version>.tgz
  3. A continuación, deberá compilar e instalar el código fuente para el intérprete de Python. En el directorio descomprimido, ejecuta ./configure para generar un archivo make.
  4. Luego, ejecuta make. Esto creará un archivo ejecutable de Python en el directorio local que funciona. Si no tienes permisos de administrador o si solo quieres usar Python desde tu directorio principal, puedes detenerte aquí. Podrás ejecutar Python desde este directorio, por lo que es posible que desees agregarlo a tu variable de entorno PATH.
  5. Prefiero tener instalado Python en /usr/bin/, donde la mayoría de las secuencias de comandos de Python buscan el intérprete. Si tienes acceso raíz, ejecuta make install como raíz. De esta forma, Python se instalará en la ubicación predeterminada, y todos los usuarios de tu máquina podrán usarlo.
  6. Abre una terminal y ejecuta python -V para verificar si la instalación funciona según lo esperado.

Instala dependencias

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

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

  1. Ejecuta el intérprete de Python. Normalmente, lo hago ejecutando python en la línea de comandos.
  2. Intenta importar el módulo ElementTree. Si usas Python 2.5 o versiones posteriores, ingresa lo siguiente en el intérprete: 
    from xml.etree import ElementTree
    . Para versiones anteriores, ingresa 
    from elementtree import ElementTree
    .
  3. Si la importación falla, deberá seguir leyendo esta sección. Si funciona, ve directamente a Instala la biblioteca de datos de Google.
  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, te recomendamos descargar una versión comprimida.
  5. Si usas una versión .tar.gz o .zip de la biblioteca, primero descomprime y, luego, instálala ejecutando ./setup.py install.

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

Hay 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 la importación desde Python, esta busca un módulo con el nombre deseado en varios lugares. El primer lugar en el que se ve está en el directorio actual, por lo que si siempre ejecutas tu código desde un directorio, puedes colocar el directorio elementtree allí. Python también analizará los directorios que se enumeran en tu variable de entorno PYTHONPATH. Para obtener instrucciones sobre cómo editar tu PYTHONPATH, consulta el Apéndice que se encuentra al final de este artículo. Recomendamos usar ./setup.py install para elementtree.

Cómo instalar la Biblioteca de datos de Google

Si aún no lo hiciste, descarga la biblioteca de Python de datos de Google. 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 elijas.

Ahora estás listo para instalar los módulos de biblioteca a fin de que se puedan importar a Python. Puedes hacerlo de cualquiera de las siguientes maneras:

  • Si tienes la capacidad de instalar paquetes para que todos los usuarios accedan, puedes ejecutar ./setup.py install desde el directorio principal del archivo sin empaquetar.
  • 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 recomendable que evites instalar los módulos por completo. Para ello, modifica la variable de entorno PYTHONPATH a fin de incluir un directorio que contenga los directorios gdata y atom para la biblioteca cliente de Python de datos de Google. Si deseas obtener instrucciones para modificar tu PYTHONPATH, consulta el Apéndice que se encuentra al final de este artículo.

  • Una última opción que mencionaré es copiar los directorios gdata y atom del directorio src a cualquier 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 un proceso rápido y simple.

Una vez que instales la biblioteca de datos de Google, estarás listo para probar la biblioteca.

Ejecutar pruebas y muestras

Las distribuciones de la biblioteca cliente de Python de datos de Google 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 garantizar que tus dependencias y la instalación de la biblioteca funcionen. Desde el directorio de nivel superior en el que descomprimiron tu copia de la biblioteca, intenta ejecutar lo siguiente:

./tests/run_data_tests.py

Si esta secuencia de comandos se ejecuta correctamente, debería ver un resultado en la línea de comandos de la siguiente manera:

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 vio ningún error mientras se ejecutaban las pruebas, es probable que haya configurado su entorno de forma correcta. ¡Felicitaciones!

Ahora puedes comenzar a ejecutar algo más interesante. La distribución contiene un directorio samples que contiene código que puede proporcionar un punto de partida para escribir tu aplicación. Si quieres probar una muestra interactiva sencilla, ejecuta ./samples/docs/docs_example.py. El ejemplo de la API de lista de documentos de Google te solicitará la dirección de correo electrónico y la contraseña de tu cuenta de Google. Si tienes documentos o hojas de cálculo en Documentos de Google, puedes enumerarlos si ingresas 1 para la operación seleccionada. (Si no tienes ningún documento o hoja de cálculo, recibirás un error 404).

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

Escribe un ejemplo de "Hello World"

Comencemos con un ejemplo simple. Aquí tienes un programa breve 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 pega el código en el intérprete de Python para ver la biblioteca cliente de Python de datos de Google en funcionamiento.

Conclusión

Ahora que ya instalaste y probaste la biblioteca cliente de Python de datos de Google, estás listo para comenzar a escribir la próxima gran aplicación con el siguiente comando:

A medida que desarrolles tu app, es posible que encuentres un inconveniente. Si es así, consulte la siguiente lista de recursos:

Si piensas en una gran función nueva para la biblioteca (o, por casualidad, encuentras un error), ingrésala en el grupo de discusión. Nos interesan tus comentarios.

Que disfrutes de la codificación :-)

Apéndice: Modificación de 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.

Recomendamos el enfoque PYTHONPATH si realizas cambios en el código de la biblioteca cliente o si no tienes derechos de administrador en tu sistema. Si editas PYTHONPATH, puedes colocar los módulos necesarios en cualquier lugar que desees.

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 Bash, puedes agregar la siguiente línea a tu archivo ~/.bashrc para establecer la variable.

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

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

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