Premiers pas avec la bibliothèque Python Google Data

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

Introduction

Vous avez décidé d'utiliser la bibliothèque cliente Python des données Google pour écrire une application à l'aide de l'un des nombreux services de données Google. Excellent choix ! L'objectif de ce court tutoriel est de vous aider à démarrer rapidement avec la bibliothèque cliente pour développer votre application.

Vous souhaitez probablement vous lancer et commencer à créer votre application tout de suite. Toutefois, vous devrez peut-être d'abord 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 du code en un rien de temps.

Installer Python

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

Python 2.4.3

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

Installer Python sur Windows

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

  1. Commencez par télécharger le programme d'installation sur 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 si 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 de Mac. Voici comment en installer un :

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

Installer Python sur Linux

Pour installer le SDK sur Linux et d'autres systèmes d'exploitation de type *nix, je préfère télécharger le code source et le compiler. Toutefois, vous pourrez peut-être utiliser votre gestionnaire de paquets favori pour installer Python. (Par exemple, sur Ubuntu, il suffit d'exécuter sudo apt-get install python sur la ligne de commande.) Pour installer à partir de la source, procédez comme suit :

  1. Téléchargez l'archive tar source depuis 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
  3. Vous devez ensuite compiler et installer le code source de l'interpréteur Python. Dans le répertoire décompressé, exécutez ./configure pour générer un fichier Makefile.
  4. Exécutez ensuite la commande make. Cela créera un fichier exécutable Python fonctionnel dans le répertoire local. Si vous ne disposez pas de l'autorisation root ou si vous souhaitez simplement utiliser Python depuis votre répertoire personnel, vous pouvez vous arrêter ici. Vous pourrez exécuter Python à partir de ce répertoire. Vous pouvez donc 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 que racine. Python sera installé à l'emplacement par défaut et sera utilisable par tous les utilisateurs de votre machine.
  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 ElementTree, car il est fourni avec le package Python.

Pour vérifier si ElementTree est déjà présent sur votre système :

  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 la commande suivante dans l'interpréteur : 
    from xml.etree import ElementTree
     Pour les versions antérieures, saisissez : 
    from elementtree import ElementTree
  3. Si l'importation échoue, vous devrez continuer à lire cette section. Si cela fonctionne, vous pouvez passer à la section Installer la bibliothèque Google Data.
  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, je vous recommande 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 d'abord, 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 placé dans votre répertoire personnel.

Il existe une autre option qui évite complètement l'installation. 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, il recherche un module portant le nom souhaité à plusieurs endroits. Le premier emplacement où il recherche le fichier se trouve dans le répertoire actuel. Par conséquent, 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

Si ce n'est pas déjà fait, téléchargez la bibliothèque Python Google Data. Recherchez la dernière version sur la page de téléchargement du projet Python.

Après avoir téléchargé la bibliothèque, décompressez-la à l'aide de unzip ou tar zxvf, selon le type de téléchargement que vous avez choisi.

Vous êtes maintenant prêt à installer les modules de bibliothèque afin qu'ils puissent être importés dans Python. Vous pouvez procéder de plusieurs manières :

  • Si vous avez la possibilité d'installer des packages pour que tous les utilisateurs y aient accès, 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, vous pouvez éviter d'installer les modules. Pour ce faire, modifiez votre variable d'environnement PYTHONPATH afin d'inclure un répertoire contenant les répertoires gdata et atom pour la bibliothèque cliente Python Google Data. Pour savoir comment modifier votre PYTHONPATH, consultez l'annexe à la fin de cet article.

  • Enfin, vous pouvez 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 recherchera le répertoire actuel lorsque vous effectuerez une importation, mais je ne recommande pas cette méthode, sauf si vous créez quelque chose de rapide et de simple.

Une fois la bibliothèque de données Google installée, vous pouvez la tester.

Exécuter des tests et des exemples

Les distributions de la bibliothèque cliente Python de Google Data incluent des cas de test utilisés pour développer la bibliothèque. Ils peuvent également servir de vérification rapide pour s'assurer que vos dépendances et l'installation de la bibliothèque fonctionnent. À partir du répertoire racine où vous avez décompressé votre copie de la bibliothèque, essayez d'exécuter la commande suivante :

./tests/run_data_tests.py

Si ce script s'exécute correctement, vous devriez obtenir un résultat semblable à celui-ci sur la ligne de commande :

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 affichée lors de l'exécution des tests, vous avez probablement configuré correctement votre environnement. Félicitations !

Vous pouvez maintenant exécuter quelque chose de plus intéressant. La distribution contient un répertoire samples qui contient du code pouvant servir de 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 de l'API Google Documents List vous demandera l'adresse e-mail et le mot de passe de votre compte Google. Si vous avez des documents ou des feuilles de calcul dans Google Documents, vous pouvez les lister en saisissant 1 pour l'opération sélectionnée. (Si vous n'avez aucun document ni feuille de calcul, une erreur 404 s'affichera.)

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

Écrire un exemple "Hello World"

Commençons par un exemple simple. Voici un petit programme pour imprimer la liste de tous les documents de votre compte Google Documents :

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 dans un fichier et exécutez-le, ou collez le code dans l'interpréteur Python pour voir la bibliothèque cliente Python Google Data en action.

Conclusion

Maintenant que vous avez installé et testé la bibliothèque cliente Python de Google Data, vous êtes prêt à écrire la prochaine grande application en utilisant :

Au fur et à mesure que vous développez votre application, vous pouvez rencontrer des problèmes. Si c'est le cas, veuillez consulter la liste des ressources ci-dessous :

Si vous avez une idée de nouvelle fonctionnalité pour la bibliothèque (ou si vous trouvez un bug), veuillez l'indiquer dans le groupe de discussion. Votre avis nous intéresse.

Bon codage :-)

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 mon PYTHONPATH pour qu'il pointe 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 chargera le module directement à partir du répertoire contenant le code source modifié.

Je vous recommande 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 PYTHONPATH, vous pouvez placer les modules requis où vous le souhaitez.

J'ai modifié mon fichier PYTHONPATH sur un système *nix et Mac OS X en le définissant dans mon fichier de configuration du shell .bashrc. Si vous utilisez le shell 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 de shell actuelle en exécutant source ~/.bashrc.

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