Wprowadzenie do biblioteki Google Data w Pythonie

Jeffrey Scudder, zespół Google Data API
sierpień 2007 r.

Wprowadzenie

Postanawiasz utworzyć aplikację za pomocą jednej z wielu usług danych Google, korzystając z biblioteki klienta Google Data w Pythonie. Świetny wybór! Ten krótki samouczek ma pomóc w szybkim rozpoczynaniu korzystania z biblioteki klienta podczas tworzenia aplikacji.

Warto od razu przystąpić do tworzenia aplikacji. Najpierw może być jednak konieczne skonfigurowanie środowiska programistycznego i narzędzi, których potrzebujesz do uruchomienia modułów zawartych w bibliotece klienta. Wykonaj poniższe czynności, aby kod został uruchomiony od razu.

Instalowanie Pythona

Jeśli zamierzasz programować przy użyciu biblioteki klienta w języku Python, potrzebujesz działającej wersji Pythona 2.2 lub nowszej. Wiele systemów operacyjnych ma dołączoną wersję Pythona, więc można pominąć etap instalacji. Aby sprawdzić, jaką masz wersję Pythona, uruchom python -V w terminalu wiersza poleceń. (Uwaga: V jest zapisany wielkimi literami). Powinno to wyglądać mniej więcej tak:

Python 2.4.3

Jeśli zobaczysz wersję 2.2 lub nowszą, możesz rozpocząć instalowanie zależności. W przeciwnym razie instrukcje instalacji/uaktualnienia systemu znajdziesz poniżej.

Instalowanie Pythona na komputerze z systemem Windows

Python można wybrać na kilka sposobów w systemie Windows, ale na potrzeby tego przewodnika użyję instalatora .msi dostępnego na stronie python.org.

  1. Zacznij od pobrania instalatora ze strony pobierania w języku Python.
  2. Uruchom instalator – możesz zaakceptować wszystkie ustawienia domyślne.
  3. Aby sprawdzić, czy instalacja działa zgodnie z oczekiwaniami, otwórz wiersz poleceń i uruchom python -V.

Instalowanie Pythona na Mac OS X

Lista plików do pobrania na python.org zawiera pliki .dmg dla użytkowników Maców. Aby go zainstalować:

  1. Wejdź na http://www.python.org/download/mac/.
  2. Pobierz z tej strony instalator dla odpowiedniej wersji systemu macOS X. Uwaga: strona instalacji Pythona dla systemu Mac OS X 10.3.8 i starszych jest inna niż nowsze wersje tego systemu. Aby sprawdzić wersję systemu operacyjnego X, wybierz O tym Macintoshu z menu Apple w lewym górnym rogu ekranu.
  3. Po zakończeniu pobierania kliknij dwukrotnie nowy plik obrazu dysku (np. python-2.5-macosx.dmg), aby go podłączyć. Jeśli używasz Safari, ta funkcja została już wykonana.
  4. Otwórz podłączony obraz i kliknij dwukrotnie pakiet instalatora.
  5. Postępuj zgodnie z instrukcjami instalacji i przeczytaj zawarte w nich informacje oraz umowy licencyjne. Tutaj również będą działać ustawienia domyślne.
  6. Zweryfikuj instalację, otwierając Terminal.app (w /Applications/Utilities) i uruchamiając python -V. Powinna wyświetlić się wersja instalacji.

Instalowanie Pythona na Linuksie

Aby instalować w systemie Linux i innych *systemach operacyjnych w stylu *nix, wolę pobrać kod źródłowy i go skompilować. Możesz jednak zainstalować Pythona za pomocą swojego ulubionego menedżera pakietów. (Na przykład w Ubuntu może to być równie proste jak uruchomienie sudo apt-get install python w wierszu poleceń). Aby zainstalować ze źródła, wykonaj te czynności:

  1. Pobierz tarball źródłowy ze strony pobierania Pythona.
  2. Po pobraniu pakietu rozpakuj go za pomocą wiersza poleceń. Możesz użyć tych 
    tar zxvf Python-2.<Your version>.tgz
  3. Następnie skompiluj i zainstaluj kod źródłowy interpretera Pythona. W katalogu zdekompresowanym uruchom polecenie ./configure, aby wygenerować plik Makefile.
  4. Następnie uruchom plik make. Spowoduje to utworzenie działającego pliku wykonywalnego Pythona w katalogu lokalnym. Jeśli nie masz uprawnień roota lub chcesz używać Pythona tylko w katalogu głównym, możesz to zrobić tutaj. Możesz uruchomić Pythona z tego katalogu, więc warto dodać go do zmiennej środowiskowej PATH.
  5. Wolę zainstalować kod w języku Python w tym języku (/usr/bin/), gdzie większość skryptów Pythona szuka tłumacza. Jeśli masz dostęp do roota, uruchom make install jako root. Python zostanie zainstalowany w domyślnej lokalizacji i będzie mógł być używany przez wszystkich użytkowników komputera.
  6. Sprawdź, czy instalacja działa zgodnie z oczekiwaniami, otwierając terminal i uruchamiając python -V.

Instalowanie zależności

Obecnie jedyną zależnością zewnętrzną jest biblioteka XML o nazwie ElementTree. Jeśli używasz Pythona w wersji 2.5 lub nowszej, nie musisz instalować elementu ElementTree, ponieważ jest on dołączony do pakietu Pythona.

Aby sprawdzić, czy ElementTTree jest już w Twoim systemie, wykonaj te czynności:

  1. uruchomić interpretera w Pythonie, Zwykle robię to w wierszu poleceń, uruchamiając polecenie python.
  2. Spróbuj zaimportować moduł ElementTree. Jeśli używasz Pythona w wersji 2.5 lub nowszej, wpisz w tłumaczeniu te informacje: 
    from xml.etree import ElementTree
    W przypadku starszych wersji wpisz: 
    from elementtree import ElementTree
  3. Jeśli import się nie uda, musisz dalej czytać tę sekcję. Jeśli tak, możesz przejść do artykułu Instalowanie biblioteki danych Google.
  4. Pobierz wersję odpowiednią dla Twojego systemu operacyjnego. Jeśli na przykład korzystasz z systemu Windows, pobierz elementtree-1.2.6-20050316.win32.exe. W przypadku innych systemów operacyjnych zalecamy pobranie wersji skompresowanej.
  5. Jeśli używasz wersji biblioteki .tar.gz lub .zip, najpierw rozpakuj ją, a potem zainstaluj, uruchamiając ./setup.py install.

Uruchomienie aplikacji ./setup.py install spowoduje skompilowanie biblioteki i umieszczenie jej w katalogu systemowym modułów Pythona. Jeśli nie masz dostępu do roota, możesz zainstalować moduły w katalogu głównym lub alternatywnym miejscu, uruchamiając ./setup.py install --home=~. Kod zostanie umieszczony w katalogu głównym.

Jest inna opcja, która całkowicie uniemożliwia instalację. Po dekompresowaniu pobranych plików znajdziesz katalog o nazwie elementtree. Ten katalog zawiera moduły, które musisz zaimportować. Gdy wywołujesz import z poziomu Pythona, szuka w kilku miejscach modułu o odpowiedniej nazwie. Wygląda na to, że znajduje się on w bieżącym katalogu, więc jeśli zawsze używasz kodu z jednego katalogu, możesz w nim umieścić katalog elementtree. Python przejrzy też katalogi w zmiennej środowiskowej PYTHONPATH. Instrukcje dotyczące edytowania PYTHONPATH znajdziesz w Dodatku na końcu tego artykułu. Zalecamy korzystanie z ./setup.py install w domenie elementtree.

Instalowanie Biblioteki danych Google

Pobierz bibliotekę danych Google w języku Python, jeśli jeszcze jej nie masz. Sprawdź najnowszą wersję na stronie pobierania projektu w tym języku.

Po pobraniu biblioteki rozpakuj ją za pomocą narzędzia unzip lub tar zxvf, w zależności od wybranego typu pobierania.

Teraz możesz zainstalować moduły biblioteki, aby można je było zaimportować do Pythona. Możesz to zrobić na kilka sposobów:

  • Jeśli masz możliwość instalowania pakietów dla wszystkich użytkowników, możesz uruchomić ./setup.py install z głównego katalogu rozpakowanego archiwum.
  • Jeśli chcesz zainstalować te moduły w swoim katalogu głównym, możesz uruchomić narzędzie ./setup.py install --home=<katalog domowy>.

  • W niektórych przypadkach należy unikać instalowania modułów. Aby to zrobić, zmodyfikuj zmienną środowiskową PYTHONPATH tak, aby zawierała katalog zawierający gdata i atom biblioteki klienta Google Python. Instrukcje dotyczące zmiany PYTHONPATH znajdziesz w Dodatku na końcu tego artykułu.

  • Ostatnią opcją, o której chcę wspomnieć, jest skopiowanie katalogów gdata i atom z katalogu src do dowolnego katalogu podczas wykonywania python. Python wyszuka go w bieżącym katalogu, ale nie zalecamy tej metody, chyba że tworzysz coś szybko i łatwo.

Po zainstalowaniu biblioteki danych Google możesz zabrać ją na jazdę próbną.

Wykonywanie testów i próbek

Rozkłady biblioteki klienta w języku Python Google obejmują przypadki użycia używane podczas jej tworzenia. Mogą również umożliwić szybkie sprawdzenie, czy zależności i instalacja biblioteki działają. W katalogu najwyższego poziomu, przy którym została wyodrębniona kopia biblioteki, uruchom polecenie:

./tests/run_data_tests.py

Jeśli ten skrypt działa prawidłowo, w wierszu poleceń powinny pojawić się takie dane:

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

...

Jeśli podczas testu nie wystąpiły żadne błędy, prawdopodobnie środowisko zostało skonfigurowane prawidłowo. Gratulacje!

Teraz możesz zacząć wyświetlać coś interesującego. Dystrybucja zawiera katalog samples zawierający kod, od którego możesz zacząć tworzyć aplikację. Jeśli chcesz wypróbować prostą, interaktywną próbkę, spróbuj użyć aplikacji ./samples/docs/docs_example.py. W przykładowym interfejsie API Dokumentów Google pojawi się prośba o podanie adresu e-mail i hasła do Twojego konta Google. Jeśli w Dokumentach Google są jakieś dokumenty lub arkusze kalkulacyjne, możesz je wyświetlić, wpisując 1 dla wybranej operacji. (Jeśli nie masz żadnych dokumentów ani arkuszy kalkulacyjnych, pojawi się błąd 404).

Jeśli interesuje Cię konkretna usługa danych Google, zapoznaj się z przykładem, aby dowiedzieć się, jak możesz korzystać z biblioteki. Większość (ale nie wszystkie) funkcji jest przedstawiona w przykładowym kodzie. Warto więc zapoznać się z dokumentacją usługi, z którą chcesz współpracować, aby dowiedzieć się, do czego możesz ją wykorzystać.

Przykład „Hello World”

Zacznijmy od prostego przykładu. Oto krótki program umożliwiający wydrukowanie listy wszystkich dokumentów na koncie Dokumentów 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

Zapisz powyższy fragment kodu jako plik i uruchom go lub wklej go do interpretera Pythona, aby wyświetlić bibliotekę klienta Google Data w języku Python.

Podsumowanie

Po zainstalowaniu i przetestowaniu biblioteki klienta Google Data w języku Python możesz zacząć tworzyć kolejną świetną aplikację, używając:

W miarę opracowywania aplikacji możesz natrafić na błędy. Jeśli tak, zapoznaj się z tą listą zasobów:

Jeśli natrafisz na jakąś świetną funkcję związaną z biblioteką (lub przez pomyłkę), możesz ją dodać do grupy dyskusyjnej. Chętnie poznamy Twoją opinię.

Miłego kodowania :-)

Dodatek: modyfikowanie ścieżki PYTHONPATH

Gdy importujesz pakiet lub moduł w Pythonie, interpreter szuka pliku w serii lokalizacji, w tym we wszystkich katalogach w zmiennej środowiskowej PYTHONPATH. Często modyfikuję PYTHONPATH, aby wskazywały moduły, z których skopiowałem kod źródłowy używanej przeze mnie biblioteki. Zapobiega to konieczności instalowania modułu przy każdej modyfikacji, ponieważ Python będzie wczytywać moduł bezpośrednio z katalogu zawierającego zmodyfikowany kod źródłowy.

Jeśli wprowadzasz zmiany w kodzie biblioteki klienta lub nie masz uprawnień administratora w systemie, zalecamy skorzystanie z metody PYTHONPATH. Edytując moduł PYTHONPATH, możesz umieścić wymagane moduły w dowolnym miejscu.

Zmieniłem PYTHONPATH w systemie *nix i Mac OS X, ustawiając go w pliku konfiguracji powłoki .bashrc. Jeśli używasz powłoki bash, możesz ustawić zmienną, dodając ten wiersz do pliku ~/.bashrc.

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

Następnie możesz zastosować te zmiany do bieżącej sesji powłoki, wykonując source ~/.bashrc.

W systemie Windows XP otwórz zmienne środowiskowe swojego profilu: Panel sterowania > Właściwości systemu > Zaawansowane > Zmienne środowiskowe. Następnie możesz utworzyć lub edytować zmienną PYTHONPATH i dodać lokalizację kopii biblioteki lokalnej.