Iniziare a utilizzare la libreria Google Data Python

Jeffrey Scudder, team delle API di dati di Google
agosto 2007

Introduzione

Hai quindi deciso di utilizzare la libreria client di Google Data Python per scrivere un'applicazione utilizzando uno dei numerosi servizi di dati di Google. Ottima scelta! L'obiettivo di questo breve tutorial è iniziare rapidamente a utilizzare la libreria client per sviluppare l'applicazione.

Probabilmente vorrai iniziare subito a creare la tua applicazione. Tuttavia, prima 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 per eseguire il codice in pochissimo tempo.

Installazione di Python

Se vuoi sviluppare con la libreria client Python, devi avere una versione di Python 2.2 o successiva funzionante. Molti sistemi operativi includono una versione di Python inclusa, per cui potresti saltare il passaggio di installazione. Per vedere quale versione di Python disponi, esegui python -V in un terminale a riga di comando. Tieni presente che V è in maiuscolo. Dovrebbe verificarsi un evento simile al seguente:

Python 2.4.3

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

Installare Python su Windows

Ci sono molte implementazioni tra cui scegliere in Windows, ma ai fini di questa guida userò il programma di installazione .msi disponibile su python.org.

  1. Per iniziare, scarica 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.

Installazione di Python su Mac OS X

L'elenco di download su python.org contiene programmi di installazione .dmg per gli utenti Mac. Per installare una di queste opzioni, procedi nel seguente modo:

  1. Visita il sito http://www.python.org/download/mac/.
  2. In 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 rispetto alle 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 disco (ad es. python-2.5-macosx.dmg) per montarlo. Se utilizzi Safari, questo è già stato fatto.
  4. Apri l'immagine montata e fai doppio clic sul pacchetto del programma di installazione all'interno.
  5. Segui le istruzioni di installazione e leggi le informazioni e i contratti di licenza che ti vengono mostrati. Le impostazioni predefinite andranno bene anche in questo caso.
  6. Verifica l'installazione aprendo Terminal.app (in /Applications/Utilities) ed eseguendo python -V. Dovrebbe essere visualizzata la versione dell'installazione.

Installare Python su Linux

Per installare su Linux e altri sistemi operativi in stile *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 facile come eseguire sudo apt-get install python sulla riga di comando. Per eseguire l'installazione dall'origine, procedi nel seguente modo:

  1. Scarica il tarball sorgente dalla pagina di download di Python.
  2. Dopo aver scaricato il pacchetto, aprilo utilizzando la riga di comando. Puoi utilizzare il seguente 
    tar zxvf Python-2.<Your version>.tgz
  3. Successivamente, dovrai compilare e installare il codice sorgente per l'interprete Python. Nella directory decompressa, esegui ./configure per generare un file di recupero.
  4. Quindi, esegui make. Verrà creato un file eseguibile Python funzionante nella directory locale. Se non hai l'autorizzazione root o vuoi utilizzare Python dalla home directory, puoi fermarti qui. Potrai eseguire Python da questa directory, quindi potresti aggiungerlo alla variabile di ambiente PATH.
  5. Preferisco avere Python 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 installerai Python nella posizione predefinita e sarà utilizzabile da tutti i computer.
  6. Verifica che la tua installazione funzioni come previsto aprendo un terminale ed eseguendo python -V.

Installazione delle dipendenze

Attualmente, l'unica dipendenza esterna è una libreria XML denominata ElementTree. Se utilizzi Python 2.5 o versioni successive, non è necessario installare ElementTree, che comprende il pacchetto Python.

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

  1. Esegui l'interprete Python. Di solito lo faccio eseguendo python dalla 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, dovrai continuare a leggere questa sezione. Se funziona, puoi passare direttamente all'installazione della libreria dei dati di Google.
  4. Scarica una versione appropriata per il tuo sistema operativo. Ad esempio, se utilizzi Windows, scarica elementtree-1.2.6-20050316.win32.exe. Per altri sistemi operativi, consiglio di scaricare una versione compressa.
  5. Se utilizzi una versione .tar.gz o .zip della libreria, prima disinstallala, poi installala eseguendo ./setup.py install.

L'esecuzione di ./setup.py install tenta di compilare la libreria e di inserirla nella directory di sistema per i tuoi moduli Python. Se non hai accesso root, puoi installare i moduli nella home directory o in una posizione alternativa eseguendo questo comando ./setup.py install --home=~. Il codice verrà inserito nella directory home.

Esiste un'altra opzione che non prevede 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 dall'interno di Python, cerca un modulo con il nome desiderato in diverse posizioni. Il primo posto sembra essere nella directory attuale, quindi se esegui sempre il codice da una directory, potresti semplicemente inserirla nella directory elementtree. Python esaminerà anche le directory elencate nella variabile di ambiente PYTHONPATH. Per istruzioni sulla modifica dell'PYTHONPATH, consulta l'Appendice alla fine di questo articolo. Consiglio di utilizzare ./setup.py install per elementtree.

Installare la libreria di dati di Google

Se non l'hai ancora fatto, scarica la libreria Python dei dati di Google. Cerca la versione più recente nella pagina dei download del progetto Python.

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

Ora puoi installare i moduli della libreria in modo da poterli importare in Python. Puoi farlo in diversi modi:

  • Se hai la possibilità di installare i pacchetti per tutti gli utenti, puoi eseguire ./setup.py install dalla directory principale dell'archivio non pacchettizzato.
  • Se vuoi installare questi moduli per l'utilizzo nella directory home, puoi eseguire ./setup.py install --home=<la tua directory home>.

  • In alcuni casi, si vuole evitare di installare del tutto i moduli. Per farlo, modifica la variabile di ambiente PYTHONPATH in modo da includere una directory contenente le directory gdata e atom per la libreria client Python di Google Data. Per istruzioni su come modificare PYTHONPATH, consulta l'Appendice alla fine di questo articolo.

  • Come ultima opzione posso menzionare, ad esempio copiare le directory gdata e atom dalla directory src a qualsiasi directory in cui ti trovi quando esegui python. Durante l'importazione, Python cercherà nella directory attuale, ma non consiglio questo metodo a meno che tu non stia creando qualcosa di semplice e veloce.

Dopo aver installato la libreria di dati di Google, puoi portarla per un test drive.

Esecuzione di test ed esempi

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

./tests/run_data_tests.py

Se questo script viene eseguito correttamente, dovresti vedere l'output nella riga di comando in questo modo:

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 vedi errori durante l'esecuzione dei test, probabilmente hai configurato correttamente il tuo ambiente. Complimenti.

Ora puoi iniziare a pubblicare qualcosa di più interessante. La distribuzione contiene una directory samples contenente il codice che può fornire un punto di partenza per la scrittura dell'applicazione. Se vuoi provare un semplice campione interattivo, prova a eseguire ./samples/docs/docs_example.py. Nell'esempio dell'API Documents List di Google ti verranno chiesti l'indirizzo email e la password per il 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, viene visualizzato un errore 404.

Se ti interessa un determinato servizio di dati di Google, osserva l'esempio per avere un'idea di base di come puoi utilizzare la libreria. Nel codice di esempio sono presenti molte delle funzionalità, ma non tutte. Per questo, ti consigliamo di consultare la documentazione del servizio con cui intendi lavorare per avere un quadro chiaro su cosa puoi fare con l'API.

Scrivere un esempio di "Hello World"

Iniziamo con un semplice esempio. 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 incolla il codice nell'interprete Python per visualizzare la libreria client di Google Data Python in azione.

Conclusione

Dopo aver installato e testato la libreria client Python di Google Data, puoi iniziare a scrivere la prossima fantastica applicazione utilizzando:

Mentre continui a sviluppare la tua applicazione, potresti trovare un problema. Consulta l'elenco delle risorse qui sotto:

Se pensi di una nuova fantastica funzionalità per la libreria (o per caso trovi un bug), inseriscila nel gruppo di discussione. Il tuo feedback è sempre utile per noi.

Buona programmazione :-)

Appendice: Modifica della funzione PYTHONPATH

Quando importi un pacchetto o un modulo in Python, l'interprete cerca il file in una serie di posizioni, incluse tutte le directory elencate nella variabile di ambiente PYTHONPATH. Spesso modifico PYTHONPATH in modo che punti ai moduli in cui ho copiato il codice sorgente della mia libreria. Questo evita la necessità di installare un modulo ogni volta che viene modificato perché Python caricherà il modulo 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 di amministratore sul sistema. Modificando il campo PYTHONPATH, puoi posizionare i moduli richiesti ovunque preferisci.

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

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

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

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