Pierwsze kroki z biblioteką Google Data Python

Jeffrey Scudder, zespół interfejsów API danych Google
Sierpień 2007

Wprowadzenie

Chcesz użyć biblioteki klienta Google Data w Pythonie, aby napisać aplikację korzystającą z jednej z wielu usług Google Data. Świetny wybór! Celem tego krótkiego samouczka jest szybkie wprowadzenie do korzystania z biblioteki klienta podczas tworzenia aplikacji.

Prawdopodobnie chcesz od razu zacząć tworzyć aplikację. Najpierw jednak może być konieczne skonfigurowanie środowiska programistycznego i narzędzi potrzebnych do uruchamiania modułów zawartych w bibliotece klienta. Wykonaj podane niżej czynności, aby szybko zacząć pisać kod.

Instalowanie Pythona

Jeśli zamierzasz tworzyć aplikacje za pomocą biblioteki klienta Python, musisz mieć działającą wersję Pythona 2.2 lub nowszą. Wiele systemów operacyjnych zawiera wersję Pythona, więc możesz pominąć krok instalacji. Aby sprawdzić, którą wersję Pythona masz, uruchom python -V w terminalu wiersza poleceń. (Uwaga: V jest pisane wielką literą). Powinno to dać wynik podobny do tego:

Python 2.4.3

Jeśli widzisz wersję 2.2 lub nowszą, możesz rozpocząć instalowanie zależności. W przeciwnym razie zapoznaj się z instrukcjami instalacji lub aktualizacji dla Twojego systemu operacyjnego.

Instalowanie Pythona w systemie Windows

W systemie Windows możesz wybrać jedną z wielu implementacji Pythona, ale na potrzeby tego przewodnika użyję instalatora MSI dostępnego na stronie python.org.

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

Instalowanie Pythona na komputerze Mac OS X

Na liście pobrań na stronie python.org znajdziesz instalatory .dmg dla użytkowników komputerów Mac. Aby zainstalować jeden z nich:

  1. Otwórz stronę http://www.python.org/download/mac/.
  2. Na tej stronie pobierz instalator odpowiedniej wersji systemu Mac OS X. Uwaga: strona instalacji Pythona w przypadku systemu Mac OS X 10.3.8 i starszych wersji różni się od strony w przypadku nowszych wersji systemu Mac OS X. Aby sprawdzić wersję systemu OS X, w menu Apple w lewym górnym rogu ekranu wybierz Ten Mac.
  3. Po zakończeniu pobierania kliknij dwukrotnie nowy plik obrazu dysku (np. python-2.5-macosx.dmg), aby go zamontować. Jeśli używasz Safari, ten krok został już wykonany.
  4. Otwórz zamontowany obraz i kliknij dwukrotnie pakiet instalacyjny.
  5. Postępuj zgodnie z instrukcjami instalacji i czytaj informacje oraz umowy licencyjne, które będą się pojawiać. W tym przypadku domyślne ustawienia będą działać prawidłowo.
  6. Zweryfikuj instalację, otwierając Terminal.app (w /Applications/Utilities) i uruchamiając python -V. Powinna się wyświetlić wersja instalacji.

Instalowanie Pythona w Linuksie

Aby zainstalować program w systemie Linux i innych systemach operacyjnych typu *nix, wolę pobrać kod źródłowy i go skompilować. Możesz jednak użyć ulubionego menedżera pakietów, aby zainstalować Pythona. (Na przykład w systemie Ubuntu wystarczy uruchomić polecenie sudo apt-get install python w wierszu poleceń). Aby zainstalować pakiet ze źródła, wykonaj te czynności:

  1. Pobierz spakowany plik źródłowy ze strony pobierania Pythona.
  2. Po pobraniu pakietu rozpakuj go za pomocą wiersza poleceń. Możesz użyć tych narzędzi: 
    tar zxvf Python-2.<Your version>.tgz
  3. Następnie musisz skompilować i zainstalować kod źródłowy interpretera Pythona. W rozpakowanym katalogu uruchom ./configure, aby wygenerować plik makefile.
  4. Następnie uruchom polecenie make. W katalogu lokalnym zostanie utworzony działający plik wykonywalny Pythona. Jeśli nie masz uprawnień roota lub po prostu chcesz używać Pythona z katalogu domowego, możesz zakończyć ten proces. Z tego katalogu będzie można uruchamiać Pythona, więc warto dodać go do zmiennej środowiskowej PATH.
  5. Wolę, aby Python był zainstalowany w /usr/bin/, gdzie większość skryptów Pythona szuka interpretera. Jeśli masz dostęp do roota, uruchom make install jako root. Spowoduje to zainstalowanie Pythona w domyślnej lokalizacji i będzie on dostępny dla wszystkich użytkowników komputera.
  6. Sprawdź, czy instalacja działa zgodnie z oczekiwaniami. W tym celu otwórz terminal i uruchom polecenie python -V.

Instalowanie zależności

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

Aby sprawdzić, czy biblioteka ElementTree jest już zainstalowana w systemie:

  1. Uruchom interpreter Pythona. Zwykle robię to, wykonując polecenie python w wierszu poleceń.
  2. Spróbuj zaimportować moduł ElementTree. Jeśli używasz Pythona w wersji 2.5 lub nowszej, wpisz w interpreterze: 
    from xml.etree import ElementTree
     W przypadku starszych wersji wpisz: 
    from elementtree import ElementTree
  3. Jeśli importowanie się nie powiedzie, czytaj dalej tę sekcję. Jeśli to zadziała, możesz przejść do sekcji Instalowanie biblioteki danych Google.
  4. Pobierz wersję odpowiednią dla Twojego systemu operacyjnego. Jeśli na przykład używasz systemu Windows, pobierz plik elementtree-1.2.6-20050316.win32.exe. W przypadku innych systemów operacyjnych zalecam pobranie wersji skompresowanej.
  5. Jeśli używasz wersji .tar.gz lub .zip biblioteki, najpierw ją rozpakuj, a potem zainstaluj, uruchamiając ./setup.py install.

Uruchomienie polecenia ./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 domowym lub w innym miejscu, uruchamiając polecenie ./setup.py install --home=~. Spowoduje to umieszczenie kodu w katalogu głównym.

Jest jeszcze jedna opcja, która pozwala uniknąć instalacji. Po rozpakowaniu pobranego pliku zobaczysz katalog o nazwie elementtree. Ten katalog zawiera moduły, które musisz zaimportować. Gdy wywołasz import z poziomu Pythona, będzie on szukać modułu o odpowiedniej nazwie w kilku miejscach. Najpierw szuka w bieżącym katalogu, więc jeśli zawsze uruchamiasz kod z jednego katalogu, możesz po prostu umieścić tam katalog elementtree. Python będzie też sprawdzać katalogi wymienione w zmiennej środowiskowej PYTHONPATH. Instrukcje edytowania znajdziesz w dodatku na końcu tego artykułu.PYTHONPATH Zalecam używanie ./setup.py install w przypadku elementtree.

Instalowanie biblioteki danych Google

Jeśli jeszcze tego nie zrobiono, pobierz bibliotekę Google Data Python. Najnowszą wersję znajdziesz na stronie pobierania projektu Python.

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

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

  • Jeśli masz możliwość instalowania pakietów, do których dostęp będą mieli wszyscy użytkownicy, możesz uruchomić ./setup.py install z głównego katalogu rozpakowanego archiwum.
  • Jeśli chcesz zainstalować te moduły do użytku w katalogu domowym, możesz uruchomić polecenie ./setup.py install --home=<twój katalog domowy>.

  • W niektórych przypadkach możesz woleć w ogóle nie instalować modułów. Aby to zrobić, zmodyfikuj zmienną środowiskową PYTHONPATH, tak aby zawierała katalog, w którym znajdują się katalogi gdata i atom biblioteki klienta Google Data Python. Instrukcje dotyczące modyfikowania PYTHONPATH znajdziesz w dodatku na końcu tego artykułu.

  • Ostatnią opcją, o której wspomnę, jest skopiowanie katalogów gdata i atom z katalogu src do katalogu, w którym się znajdujesz, gdy wykonujesz polecenie python. Podczas importowania Python będzie szukać w bieżącym katalogu, ale nie polecam tej metody, chyba że tworzysz coś prostego i szybkiego.

Po zainstalowaniu biblioteki danych Google możesz ją przetestować.

Przeprowadzanie testów i próbek

Dystrybucje biblioteki klienta Google Data w Pythonie zawierają niektóre przypadki testowe, które są używane podczas tworzenia biblioteki. Mogą też służyć jako szybkie sprawdzenie, czy zależności i instalacja biblioteki działają prawidłowo. W katalogu najwyższego poziomu, w którym rozpakowano kopię biblioteki, spróbuj uruchomić:

./tests/run_data_tests.py

Jeśli skrypt działa prawidłowo, w wierszu poleceń powinny pojawić się dane wyjściowe podobne do tych:

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 wykonywania testów nie pojawiły się żadne błędy, środowisko zostało prawdopodobnie skonfigurowane prawidłowo. Gratulacje!

Teraz możesz uruchomić coś ciekawszego. Dystrybucja zawiera katalog samples, który zawiera kod, który może stanowić punkt wyjścia do napisania aplikacji. Jeśli chcesz wypróbować prosty interaktywny przykład, uruchom ./samples/docs/docs_example.py. Przykładowy kod interfejsu Google Documents List API poprosi Cię o podanie adresu e-mail i hasła do Twojego konta Google. Jeśli masz dokumenty lub arkusze kalkulacyjne w Dokumentach Google, możesz je wyświetlić, wpisując 1 w wybranym działaniu. (Jeśli nie masz żadnych dokumentów ani arkuszy kalkulacyjnych, pojawi się błąd 404).

Jeśli interesuje Cię konkretna usługa Google Data, zapoznaj się z przykładowym kodem, aby uzyskać podstawowe informacje o tym, jak możesz korzystać z biblioteki. Większość funkcji jest przedstawiona w przykładowym kodzie, ale nie wszystkie. Aby uzyskać pełny obraz możliwości interfejsu API, zapoznaj się z dokumentacją usługi, z której zamierzasz korzystać.

Tworzenie przykładu „Hello World”

Zacznijmy od prostego przykładu. Oto krótki program, który wyświetla listę wszystkich dokumentów na Twoim 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 w pliku i uruchom go lub wklej kod do interpretera Pythona, aby zobaczyć, jak działa biblioteka klienta Google Data Python.

Podsumowanie

Po zainstalowaniu i przetestowaniu biblioteki klienta Google Data Python możesz zacząć pisać kolejną świetną aplikację, korzystając z:

Podczas dalszego rozwijania aplikacji możesz napotkać trudności. Jeśli tak, zapoznaj się z listą materiałów poniżej:

Jeśli przyjdzie Ci do głowy świetna nowa funkcja biblioteki (lub przypadkiem znajdziesz błąd), wpisz ją w grupie dyskusyjnej. Zawsze chętnie poznamy Twoją opinię.

Pozdrawiamy :-)

Dodatek: modyfikowanie zmiennej PYTHONPATH

Gdy importujesz pakiet lub moduł w Pythonie, interpreter szuka pliku w różnych lokalizacjach, w tym we wszystkich katalogach wymienionych w zmiennej środowiskowej PYTHONPATH. Często modyfikuję PYTHONPATH, aby wskazywał moduły, w których skopiowałem kod źródłowy używanej biblioteki. Dzięki temu nie musisz instalować modułu za każdym razem, gdy go zmodyfikujesz, ponieważ Python wczyta go 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, zalecam podejście PYTHONPATH. Edytując PYTHONPATH, możesz umieścić wymagane moduły w dowolnym miejscu.

Zmodyfikowałem(-am) zmienną PYTHONPATH w systemie *nix i Mac OS X, ustawiając ją 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 w bieżącej sesji powłoki, wykonując polecenie source ~/.bashrc.

W systemie Windows XP otwórz zmienne środowiskowe dla 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 w bibliotece lokalnej.