Premiers pas avec la bibliothèque Python Google Data

Jeffrey Scudder, équipe Google Data APIs
Août 2007

Introduction

Vous avez donc décidé d'utiliser la bibliothèque cliente Python Google Data pour créer une application à l'aide de l'un des nombreux services de données Google. Excellent choix ! Avec ce court tutoriel, je vais vous apprendre à utiliser rapidement la bibliothèque cliente pour développer votre application.

Vous souhaitez probablement commencer à créer votre application immédiatement. Toutefois, vous devrez peut-être commencer par configurer votre environnement de développement et les outils dont vous aurez besoin pour exécuter les modules inclus dans la bibliothèque cliente. Suivez les étapes ci-dessous pour exécuter le code en un rien de temps.

Installer Python

Si vous souhaitez développer avec la bibliothèque cliente Python, vous aurez besoin d'une version fonctionnelle de Python 2.2 ou version ultérieure. De nombreux systèmes d'exploitation sont fournis avec une version de Python. Vous pouvez donc ignorer l'étape d'installation. Pour connaître votre version de Python, exécutez python -V dans un terminal de ligne de commande. (Remarque: V est en majuscules.) Vous devriez obtenir le résultat suivant:

Python 2.4.3

Si vous voyez la version 2.2 ou une version ultérieure, vous pouvez commencer à installer des dépendances. Sinon, consultez les instructions d'installation/de mise à niveau ci-dessous pour votre système d'exploitation.

Installer Python sur Windows

Il existe de nombreuses implémentations Python sous Windows, mais pour les besoins de ce guide, j'utilise le programme d'installation .msi disponible sur python.org.

  1. Commencez par télécharger le programme d'installation à partir de la page de téléchargement de Python.
  2. Exécutez le programme d'installation. Vous pouvez accepter tous les paramètres par défaut.
  3. Pour vérifier que votre installation fonctionne comme prévu, ouvrez une invite de commande et exécutez python -V.

Installer Python sur Mac OS X

La liste des téléchargements sur python.org contient des programmes d'installation .dmg pour les utilisateurs Mac. Pour installer l'un d'entre eux, procédez comme suit:

  1. Accédez à http://www.python.org/download/mac/.
  2. Sur cette page, téléchargez le programme d'installation pour la version appropriée de Mac OS X. Remarque: La page d'installation de Python pour Mac OS X 10.3.8 et versions antérieures est différente des versions plus récentes de Mac OS X. Pour connaître votre version du système d'exploitation, sélectionnez À propos de ce Mac dans le menu Apple situé dans l'angle supérieur gauche de l'écran.
  3. Une fois le téléchargement terminé, double-cliquez sur le nouveau fichier image du disque (par exemple, python-2.5-macosx.dmg) pour l'installer. Si vous utilisez Safari, cette opération a déjà été effectuée pour vous.
  4. Ouvrez l'image installée et double-cliquez sur le package du programme d'installation.
  5. Suivez les instructions d'installation et lisez les informations et les contrats de licence tels qu'ils vous sont présentés. Ici aussi, les paramètres par défaut fonctionneront correctement.
  6. Vérifiez l'installation en ouvrant le Terminal.app (dans /Applications/Utilities) et en exécutant python -V. La version de l'installation devrait s'afficher.

Installer Python sous Linux

Pour une installation sous Linux et sur d'autres systèmes d'exploitation de type *nix, je préfère télécharger le code source et le compiler. Vous pouvez toutefois utiliser Python pour installer Python. (Par exemple, sur Ubuntu, cela peut être aussi simple que d'exécuter sudo apt-get install python sur la ligne de commande.) Pour effectuer l'installation à partir de la source, procédez comme suit:

  1. Téléchargez le package tarball source sur la page de téléchargement de Python.
  2. Une fois le package téléchargé, décompressez-le à l'aide de la ligne de commande. Vous pouvez utiliser les 
    tar zxvf Python-2.<Your version>.tgz
    suivantes :
  3. Vous devez ensuite compiler et installer le code source pour l'interpréteur Python. Dans le répertoire décompressé, exécutez ./configure pour générer un fichier makefile.
  4. Exécutez ensuite make. Un fichier exécutable Python fonctionnel est alors créé dans le répertoire local. Si vous ne disposez pas d'une autorisation racine ou si vous souhaitez simplement utiliser Python à partir de votre répertoire d'accueil, vous pouvez vous arrêter ici. Vous pourrez exécuter Python à partir de ce répertoire. Vous voudrez donc peut-être l'ajouter à votre variable d'environnement PATH.
  5. Je préfère que Python soit installé dans /usr/bin/, où la plupart des scripts Python recherchent l'interpréteur. Si vous disposez d'un accès racine, exécutez make install en tant qu'utilisateur racine. Cela installera Python à l'emplacement par défaut, et tous les utilisateurs de votre machine pourront l'utiliser.
  6. Vérifiez que votre installation fonctionne comme prévu en ouvrant un terminal et en exécutant python -V.

Installer les dépendances

Actuellement, la seule dépendance externe est une bibliothèque XML nommée ElementTree. Si vous utilisez Python 2.5 ou une version ultérieure, vous n'aurez pas besoin d'installer ÉlémentTree, car il est fourni avec le package Python.

Pour voir si ElementTree est déjà présent sur votre système, procédez comme suit:

  1. Exécutez l'interpréteur Python. Pour ce faire, j'exécute généralement python sur la ligne de commande.
  2. Essayez d'importer le module ElementTree. Si vous utilisez Python 2.5 ou une version ultérieure, saisissez ce qui suit dans l'interpréteur : 
    from xml.etree import ElementTree
    Pour les versions plus anciennes, saisissez : 
    from elementtree import ElementTree
  3. Si l'importation échoue, vous devez lire cette section. Si cela fonctionne, passez à la section Installer la bibliothèque de données Google.
  4. Téléchargez une version adaptée à votre système d'exploitation. Par exemple, si vous utilisez Windows, téléchargez elementtree-1.2.6-20050316.win32.exe. Pour les autres systèmes d'exploitation, nous vous recommandons de télécharger une version compressée.
  5. Si vous utilisez une version .tar.gz ou .zip de la bibliothèque, décompressez-la, puis installez-la en exécutant ./setup.py install.

L'exécution de ./setup.py install tente de compiler la bibliothèque et de la placer dans le répertoire système de vos modules Python. Si vous n'avez pas accès à la racine, vous pouvez installer les modules dans votre répertoire d'accueil ou dans un autre emplacement en exécutant ./setup.py install --home=~. Le code sera alors placé dans votre répertoire d'accueil.

Il existe une autre option qui évite l'installation complète. Une fois le téléchargement décompressé, vous trouverez un répertoire nommé elementtree. Ce répertoire contient les modules que vous devrez importer. Lorsque vous appelez l'importation depuis Python, elle recherche un module portant le nom souhaité à plusieurs endroits. Elle se trouve d'abord dans le répertoire actuel. Si vous exécutez toujours votre code à partir d'un répertoire, vous pouvez simplement y placer le répertoire elementtree. Python examinera également les répertoires listés dans votre variable d'environnement PYTHONPATH. Pour savoir comment modifier votre PYTHONPATH, consultez l'Annexe à la fin de cet article. Je vous recommande d'utiliser ./setup.py install pour elementtree.

Installer la bibliothèque de données Google

Téléchargez la bibliothèque Python Google Data si vous ne l'avez pas encore fait. Recherchez la dernière version sur la page des téléchargements du projet Python.

Une fois la bibliothèque téléchargée, décompressez-la en utilisant unzip ou tar zxvf, selon le type de téléchargement choisi.

Vous êtes maintenant prêt à installer les modules de la bibliothèque afin de pouvoir les importer dans Python. Il y a plusieurs manières de procéder :

  • Si vous avez la possibilité d'installer des packages auxquels tous les utilisateurs peuvent accéder, vous pouvez exécuter ./setup.py install à partir du répertoire principal de l'archive décompressée.
  • Si vous souhaitez installer ces modules pour les utiliser dans votre répertoire d'accueil, vous pouvez exécuter ./setup.py install --home=<votre répertoire d'accueil>.

  • Dans certains cas, il est préférable d'éviter l'installation des modules. Pour ce faire, modifiez votre variable d'environnement PYTHONPATH pour inclure un répertoire contenant les répertoires gdata et atom de la bibliothèque cliente Python Google Data. Pour savoir comment modifier votre fichier PYTHONPATH, consultez l'Annexe à la fin de cet article.

  • Une dernière option que je vais mentionner consiste à copier les répertoires gdata et atom du répertoire src dans le répertoire dans lequel vous vous trouvez lorsque vous exécutez python. Python consultera le répertoire actuel lorsque vous effectuerez une importation, mais je ne recommande pas cette méthode, sauf si vous créez une solution simple et rapide.

Une fois que vous avez installé la bibliothèque de données Google, vous pouvez l'essayer.

Exécuter des tests et des exemples

Les distributions de la bibliothèque cliente Python Google Data incluent des scénarios de test qui sont utilisés pour le développement de la bibliothèque. Elles peuvent également servir à vérifier rapidement le bon fonctionnement de vos dépendances et de l'installation de votre bibliothèque. À partir du répertoire de premier niveau dans lequel vous avez décompressé la copie de la bibliothèque, exécutez la commande suivante:

./tests/run_data_tests.py

Si ce script s'exécute correctement, le résultat devrait ressembler à ceci:

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 aucune erreur ne s'est produite pendant l'exécution des tests, cela signifie que vous avez probablement correctement configuré votre environnement. Félicitations !

Maintenant, vous pouvez commencer quelque chose de plus intéressant. La distribution contient un répertoire samples qui contient du code pouvant fournir un point de départ pour écrire votre application. Si vous souhaitez essayer un exemple interactif simple, exécutez ./samples/docs/docs_example.py. L'exemple d'API Google Documents List vous invite à saisir l'adresse e-mail et le mot de passe de votre compte Google. Si vous disposez de documents ou de feuilles de calcul dans Google Docs, vous pouvez les répertorier en saisissant 1 pour l'opération sélectionnée. Si vous ne disposez d'aucun document ni feuille de calcul, une erreur 404 s'affiche.

Si un service de données Google particulier vous intéresse, consultez son exemple pour avoir une idée de la façon dont vous pouvez utiliser la bibliothèque. La plupart des fonctionnalités, mais pas toutes, sont illustrées dans l'exemple de code. Vous pouvez donc consulter la documentation du service avec lequel vous prévoyez de travailler pour avoir une idée claire de ce que vous pouvez faire avec l'API.

Écrire un exemple "Hello World"

Commençons par un exemple simple. Voici un court programme permettant d'imprimer la liste de tous les documents de votre compte Google Docs:

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

Enregistrez l'extrait de code ci-dessus sous forme de fichier et exécutez-le, ou collez le code dans l'interpréteur Python pour afficher la bibliothèque cliente Python Google Data en action.

Conclusion

Maintenant que vous avez installé et testé la bibliothèque cliente Python Google Data, vous pouvez commencer à écrire la prochaine application de qualité en utilisant:

À mesure que vous développez votre application, vous risquez de rencontrer un problème. Si c'est le cas, veuillez consulter la liste des ressources ci-dessous:

Si vous pensez à une nouvelle fonctionnalité intéressante de la bibliothèque (ou si vous en avez trouvé un, par exemple), veuillez la saisir dans le groupe de discussion. Votre avis nous intéresse.

Bonne continuation :-)

Annexe: Modifier le PYTHONPATH

Lorsque vous importez un package ou un module en Python, l'interpréteur recherche le fichier dans une série d'emplacements, y compris tous les répertoires listés dans la variable d'environnement PYTHONPATH. Je modifie souvent PYTHONPATH pour pointer vers les modules dans lesquels j'ai copié le code source d'une bibliothèque que j'utilise. Cela évite d'avoir à installer un module chaque fois qu'il est modifié, car Python le charge directement à partir du répertoire qui contient le code source modifié.

Nous vous recommandons d'utiliser l'approche PYTHONPATH si vous modifiez le code de la bibliothèque cliente ou si vous ne disposez pas des droits d'administrateur sur votre système. En modifiant le fichier PYTHONPATH, vous pouvez placer les modules requis où vous le souhaitez.

J'ai modifié mon PYTHONPATH sur un système *nix et Mac OS X en le définissant dans mon fichier de configuration shell .bashrc. Si vous utilisez l'interface système bash, vous pouvez définir la variable en ajoutant la ligne suivante à votre fichier ~/.bashrc.

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

Vous pouvez ensuite appliquer ces modifications à votre session d'interface système actuelle en exécutant source ~/.bashrc.

Sous Windows XP, affichez les variables d'environnement associées à votre profil : Panneau de configuration > Propriétés système > Avancé > Variables d'environnement. Vous pouvez alors créer ou modifier la variable PYTHONPATH, puis ajouter l'emplacement de la copie locale de votre bibliothèque.