Introduzione alla libreria Python di Google Data

Jeffrey Scudder, team delle API Google Data
Agosto 2007

Introduzione

Hai deciso di utilizzare la libreria client Python di Google Data per scrivere un'applicazione utilizzando uno dei numerosi servizi Google Data. Ottima scelta! Lo scopo di questo breve tutorial è quello di aiutarti a iniziare rapidamente a utilizzare la libreria client per sviluppare la tua applicazione.

Probabilmente vorrai iniziare subito a creare la tua applicazione. Prima di tutto, però, potresti dover configurare il tuo ambiente di sviluppo e impostare gli strumenti necessari per eseguire i moduli inclusi nella libreria client. Segui i passaggi riportati di seguito e potrai eseguire il codice in un attimo.

Installazione di Python

Se intendi sviluppare con la libreria client Python, ti servirà una versione funzionante di Python 2.2 o successive. Molti sistemi operativi includono una versione di Python, quindi potresti essere in grado di saltare il passaggio di installazione. Per vedere quale versione di Python hai, esegui python -V in un terminale della riga di comando. (Nota: la parola V è in maiuscolo.) Il risultato dovrebbe essere simile a questo:

Python 2.4.3

Se vedi la versione 2.2 o successive, puoi iniziare a installare le dipendenze. In caso contrario, consulta le istruzioni di installazione/upgrade per il tuo sistema operativo riportate di seguito.

Installare Python su Windows

In Windows sono disponibili diverse implementazioni di Python, ma ai fini di questa guida utilizzerò il programma di installazione .msi disponibile su python.org.

  1. Inizia scaricando il programma di installazione dalla pagina di download di Python.
  2. Esegui il programma di installazione. Puoi accettare tutte le impostazioni predefinite.
  3. Per verificare se l'installazione funziona come previsto, apri un prompt dei comandi ed esegui python -V.

Installare Python su Mac OS X

L'elenco dei download su python.org include programmi di installazione .dmg per gli utenti Mac. Ecco i passaggi per installarne uno:

  1. Vai all'indirizzo http://www.python.org/download/mac/.
  2. Da questa pagina, scarica il programma di installazione per la versione appropriata di Mac OS X. Nota: la pagina di installazione di Python per Mac OS X 10.3.8 e versioni precedenti è diversa da quella delle versioni più recenti di Mac OS X. Per trovare la versione di OS X, scegli Informazioni su questo Mac dal menu Apple nell'angolo in alto a sinistra dello schermo.
  3. Al termine del download, fai doppio clic sul nuovo file immagine del disco (ad es. python-2.5-macosx.dmg) per montarlo. Se utilizzi Safari, questo passaggio è già stato eseguito.
  4. Apri l'immagine montata e fai doppio clic sul pacchetto del programma di installazione al suo interno.
  5. Segui le istruzioni di installazione e leggi le informazioni e i contratti di licenza man mano che ti vengono presentati. Anche in questo caso, le impostazioni predefinite vanno bene.
  6. Verifica l'installazione aprendo Terminal.app (in /Applicazioni/Utility) ed eseguendo python -V. Dovrebbe essere visualizzata la versione dell'installazione.

Installare Python su Linux

Per l'installazione su Linux e altri sistemi operativi di tipo *nix, preferisco scaricare il codice sorgente e compilarlo. Tuttavia, potresti riuscire a utilizzare il tuo gestore di pacchetti preferito per installare Python. Ad esempio, su Ubuntu può essere semplice come eseguire sudo apt-get install python dalla riga di comando. Per installare da origine:

  1. Scarica il tarball di origine dalla pagina di download di Python.
  2. Una volta scaricato il pacchetto, decomprimilo utilizzando la riga di comando. Puoi utilizzare i seguenti 
    tar zxvf Python-2.<Your version>.tgz
  3. Successivamente, devi compilare e installare il codice sorgente per l'interprete Python. Nella directory decompressa, esegui ./configure per generare un makefile.
  4. Poi esegui make. Verrà creato un file eseguibile Python funzionante nella directory locale. Se non disponi dell'autorizzazione di root o vuoi semplicemente utilizzare Python dalla tua home directory, puoi interrompere la procedura qui. Potrai eseguire Python da questa directory, quindi ti consigliamo di aggiungerla alla variabile di ambiente PATH.
  5. Preferisco che Python sia installato in /usr/bin/, dove la maggior parte degli script Python cerca l'interprete. Se hai accesso root, esegui make install come root. In questo modo Python verrà installato nella posizione predefinita e potrà essere utilizzato da tutti gli utenti della macchina.
  6. Verifica che l'installazione funzioni come previsto aprendo un terminale ed eseguendo python -V.

Installazione delle dipendenze

Al momento, l'unica dipendenza esterna è una libreria XML denominata ElementTree. Se utilizzi Python versione 2.5 o successive, non dovrai installare ElementTree perché è incluso nel pacchetto Python.

Per verificare se ElementTree è già presente sul tuo sistema:

  1. Esegui l'interprete Python. Di solito, eseguo questa operazione eseguendo python nella riga di comando.
  2. Prova a importare il modulo ElementTree. Se utilizzi Python 2.5 o versioni successive, inserisci quanto segue nell'interprete: 
    from xml.etree import ElementTree
     Per le versioni precedenti, inserisci: 
    from elementtree import ElementTree
  3. Se l'importazione non va a buon fine, devi continuare a leggere questa sezione. Se funziona, puoi passare a Installazione della libreria Google Data.
  4. Scarica una versione adatta al tuo sistema operativo. Ad esempio, se utilizzi Windows, scarica elementtree-1.2.6-20050316.win32.exe. Per gli altri sistemi operativi, ti consiglio di scaricare una versione compressa.
  5. Se utilizzi una versione .tar.gz o .zip della libreria, decomprimila e installala eseguendo ./setup.py install.

L'esecuzione di ./setup.py install tenta di compilare la libreria e inserirla nella directory di sistema per i moduli Python. Se non hai l'accesso root, puoi installare i moduli nella tua home directory o in un'altra posizione eseguendo ./setup.py install --home=~. In questo modo, il codice verrà inserito nella tua home directory.

Esiste un'altra opzione che evita del tutto l'installazione. Una volta decompresso il download, troverai una directory denominata elementtree. Questa directory contiene i moduli che dovrai importare. Quando chiami l'importazione da Python, cerca un modulo con il nome desiderato in diverse posizioni. Il primo posto in cui cerca è la directory corrente, quindi se esegui sempre il codice da una directory, puoi semplicemente inserire lì la directory elementtree. Python esaminerà anche le directory elencate nella variabile di ambiente PYTHONPATH. Per istruzioni sulla modifica del tuo PYTHONPATH, consulta l'appendice alla fine di questo articolo. Ti consiglio di utilizzare ./setup.py install per elementtree.

Installazione della libreria Google Data

Se non l'hai ancora fatto, scarica la libreria Python di Google Data. Cerca l'ultima versione nella pagina dei download del progetto Python.

Dopo aver scaricato la libreria, decomprimila utilizzando unzip o tar zxvf a seconda del tipo di download scelto.

Ora puoi installare i moduli della libreria in modo che possano essere importati in Python. Puoi farlo in diversi modi:

  • Se hai la possibilità di installare pacchetti a cui tutti gli utenti possono accedere, puoi eseguire ./setup.py install dalla directory principale dell'archivio decompresso.
  • Se vuoi installare questi moduli per utilizzarli nella tua home directory, puoi eseguire ./setup.py install --home=<your home directory>.

  • In alcuni casi, è consigliabile evitare del tutto l'installazione dei moduli. Per farlo, modifica la variabile di ambiente PYTHONPATH in modo che includa una directory che contenga le directory gdata e atom per la libreria client Python di Google Data. Per istruzioni sulla modifica del tuo PYTHONPATH, consulta l'appendice alla fine di questo articolo.

  • Un'ultima opzione che menzionerò è la copia delle directory gdata e atom dalla directory src in qualsiasi directory in cui ti trovi quando esegui python. Python cercherà nella directory corrente quando esegui un'importazione, ma non consiglio questo metodo a meno che tu non stia creando qualcosa di rapido e semplice.

Una volta installata la libreria Google Data, puoi provarla.

Esecuzione di test e campioni

Le distribuzioni della libreria client Python di Google Data includono alcuni casi di test utilizzati nello sviluppo della libreria. Possono anche fungere da controllo rapido per assicurarsi che le dipendenze e l'installazione della libreria funzionino. Dalla directory di primo livello in cui hai decompresso la tua copia della libreria, prova a eseguire:

./tests/run_data_tests.py

Se questo script viene eseguito correttamente, dovresti vedere un output nella riga di comando simile a questo:

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 non hai riscontrato errori durante l'esecuzione dei test, probabilmente hai configurato correttamente l'ambiente. Complimenti!

Ora puoi iniziare a eseguire qualcosa di più interessante. La distribuzione contiene una directory samples che include codice che può fornire un punto di partenza per scrivere l'applicazione. Se vuoi provare un semplice esempio interattivo, esegui ./samples/docs/docs_example.py. L'esempio dell'API Google Documents List ti chiederà l'indirizzo email e la password del tuo Account Google. Se hai documenti o fogli di lavoro in Documenti Google, puoi elencarli inserendo 1 per l'operazione selezionata. (Se non hai documenti o fogli di lavoro, riceverai un errore 404.)

Se ti interessa un particolare servizio Google Data, dai un'occhiata all'esempio per farti un'idea di base di come puoi utilizzare la libreria. La maggior parte delle funzionalità, ma non tutte, sono illustrate nel codice di esempio, quindi ti consigliamo di consultare la documentazione del servizio che intendi utilizzare per avere un'idea chiara di cosa puoi fare con l'API.

Scrivere un esempio di "Hello World"

Iniziamo con un esempio semplice. Ecco un breve programma per stampare un elenco di tutti i documenti nel tuo account Documenti 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

Salva lo snippet di codice riportato sopra come file ed eseguilo oppure incollalo nell'interprete Python per vedere la libreria client Python di Google Data in azione.

Conclusione

Ora che hai installato e testato la libreria client Python di Google Data, puoi iniziare a scrivere la prossima grande applicazione utilizzando:

Man mano che continui a sviluppare la tua applicazione, potresti incontrare un problema. In caso affermativo, consulta l'elenco di risorse riportato di seguito:

Se ti viene in mente una nuova funzionalità per la libreria (o se trovi un bug), inseriscila nel gruppo di discussione. Siamo sempre interessati al tuo feedback.

Buona programmazione :-)

Appendice: Modifica di PYTHONPATH

Quando importi un pacchetto o un modulo in Python, l'interprete cerca il file in una serie di posizioni, inclusi tutti i directory elencati nella variabile di ambiente PYTHONPATH. Modifico spesso il mio PYTHONPATH per indirizzare i moduli in cui ho copiato il codice sorgente di una libreria che sto utilizzando. In questo modo, non è necessario installare un modulo ogni volta che viene modificato, perché Python lo caricherà direttamente dalla directory che contiene il codice sorgente modificato.

Consiglio l'approccio PYTHONPATH se apporti modifiche al codice della libreria client o se non disponi dei diritti amministrativi sul tuo sistema. Modificando PYTHONPATH, puoi posizionare i moduli richiesti dove preferisci.

Ho modificato il mio PYTHONPATH su un sistema *nix e Mac OS X impostandolo nel file di configurazione della shell .bashrc. Se utilizzi la shell bash, puoi impostare la variabile aggiungendo la seguente riga al file ~/.bashrc.

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

Puoi quindi applicare queste modifiche alla sessione shell corrente eseguendo source ~/.bashrc.

Per Windows XP, visualizza le variabili di ambiente per il tuo profilo: Pannello di controllo > Proprietà del sistema > Avanzate > Variabili di ambiente. Da qui, puoi creare o modificare la variabile PYTHONPATH e aggiungere la posizione della copia della libreria locale.