開始使用 Google Data Python 程式庫

Jeffrey Scudder，Google Data API 團隊
2007 年 8 月

簡介

因此，您決定使用 Google Data Python 用戶端程式庫，使用眾多的 Google Data 服務來編寫應用程式。選得好！ 我想藉由這個簡短的教學課程，快速開始使用用戶端程式庫來開發應用程式。

建議您馬上加入，然後立即開始建立應用程式。 首先，您可能需要設定開發環境，並設定執行用戶端程式庫中所需模組所需的工具。請按照下列步驟進行，您將立即執行程式碼。

安裝 Python

如要使用 Python 用戶端程式庫進行開發作業，您必須具備 2.2 以上版本的 Python 有效版本。許多作業系統隨附 Python 版本，因此您可以略過安裝步驟。如要查看您的 Python 版本，請在指令列終端機中執行 python -V。(注意：V 是大寫)。 這應該會產生類似下方的結果：

Python 2.4.3

如果您看到 2.2 版或更高版本，就可以開始安裝依附元件。否則，請參閱下方說明，瞭解您作業系統適用的安裝/升級操作說明。

在 Windows 上安裝 Python

在 Windows 中，有好幾種 Python 需要實作，但本指南而言，我將使用 python.org 上的 .msi 安裝程式。

  1. 首先，請前往 Python 下載頁面下載安裝程式。
  2. 執行安裝程式 - 可接受所有預設設定
  3. 如要查看安裝項目是否正常運作，請開啟命令提示字元並執行 python -V。

在 Mac OS X 上安裝 Python

python.org 的下載內容清單提供 Mac 使用者專用的 .dmg 安裝程式。請按照下列步驟安裝其中一種版本：

  1. 前往 http://www.python.org/download/mac/。
  2. 請從這個頁面下載適當版本的 Mac OS X 安裝程式。注意：Mac OS X 10.3.8 及以下版本的 Python 安裝頁面與較新版本的 Mac OS X 不同。如要查看 OS X 版本，請在畫面左上角的 Apple 選單中選擇 [關於這台 Mac]。
  3. 下載完成後，按兩下新的磁碟映像檔 (例如 python-2.5-macosx.dmg) 即可掛接。如果您使用的是 Safari，則已經完成這個步驟。
  4. 開啟掛接映像檔，並按兩下當中的安裝程式套件。
  5. 按照安裝指示操作，並詳閱系統顯示的資訊和授權協議。同樣地，這裡可以套用預設設定。
  6. 開啟 Terminal.app (位於 /Applications/Utilities) 並執行 python -V，藉此驗證安裝程序。系統隨即顯示安裝的版本。

在 Linux 上安裝 Python

若要在 Linux 和其他 *nix 樣式的作業系統上安裝，我希望能下載並編譯原始碼。 不過，您可以使用自己偏好的套件管理員來安裝 Python。 (例如，在 Ubuntu 上，輕鬆地在指令列中執行 sudo apt-get install python)。如要從來源安裝，請依照下列步驟操作：

  1. 從 Python 下載頁面下載來源 tarball。
  2. 下載套件之後，請使用指令列解除封裝。您可以使用下列 
    tar zxvf Python-2.<Your version>.tgz
  3. 接下來，您必須編譯並安裝 Python 解譯器的原始碼。在解壓縮目錄中執行 ./configure 以產生 makefile。
  4. 然後執行 make。這項操作會在本機目錄中建立可正常運作的 Python 執行檔。如果您沒有 Root 權限，或是只是想從主目錄使用 Python，可以在這裡停止使用。您將可從這個目錄執行 Python，因此建議您將其新增至 PATH 環境變數。
  5. 我希望在 /usr/bin/ 中安裝 Python，其中大部分 Python 指令碼會尋找解譯器。 如果您擁有 Root 權限，請以 Root 權限執行 make install。這麼做會在預設位置安裝 Python，且所有機器使用者都能使用。
  6. 開啟終端機並執行 python -V，檢查安裝作業是否正常運作。

安裝依附元件

目前唯一的外部依附元件是名為 ElementTree 的 XML 程式庫。如果您使用的是 Python 2.5 以上版本，則無須安裝 ElementTree，因為這是 Python 套件。

如要查看系統是否已有 ElementTree，請執行下列步驟：

  1. 執行 Python 解譯器。我通常是在指令列上執行 python 來完成這項作業。
  2. 請嘗試匯入 ElementTree 模組。如果您使用的是 Python 2.5 以上版本，請在解譯器中輸入以下內容： 
    from xml.etree import ElementTree
    如果您使用的是舊版，請輸入： 
    from elementtree import ElementTree
  3. 如果匯入失敗，您就必須繼續閱讀本節的內容。如果可以，您可以跳至安裝 Google Data Library。
  4. 下載適用於您作業系統的版本。舉例來說，如果您使用的是 Windows，請下載 elementtree-1.2.6-20050316.win32.exe。如果是其他作業系統，建議你下載壓縮版本。
  5. 如果您使用的是 .tar.gz 或 .zip 版本的程式庫，請先取消封裝，再執行 ./setup.py install 進行安裝。

執行 ./setup.py install 時，會嘗試編譯程式庫，並將其放入 Python 模組的系統目錄中。如果您沒有 Root 存取權，則可在 ./setup.py install --home=~ 中安裝模組，或是在其他位置安裝模組。這麼做會將程式碼放入主目錄中。

另一種可避免完全安裝。解壓縮下載作業後，您會看到名為 elementtree 的目錄。這個目錄包含您要匯入的模組。當您在 Python 中呼叫 Import 時，會在多個位置尋找具有所需名稱的模組。其首先出現的位置是目前的目錄，因此，如果您一律會從一個目錄執行程式碼，只要將 elementtree 目錄放入該目錄即可。Python 也會查看 PYTHONPATH 環境變數中列出的目錄。如需編輯 PYTHONPATH 的操作說明，請參閱本文結尾處的附錄。建議您將 ./setup.py install 用於 elementtree。

安裝 Google Data Library

如果尚未下載 Google Data Python 程式庫，請先下載。如要尋找最新版本，請前往 Python 專案的下載頁面。

下載程式庫後，請根據您選擇的下載類型，使用 unzip 或 tar zxvf 解除封裝。

現在您已準備好安裝程式庫模組，可以將其匯入 Python。您可以透過下列方式證明自己的身分：

  • 如果您能夠為所有使用者安裝套件，可以從已解壓縮的封存檔案主要目錄中執行 ./setup.py install。
  • 如果您要將這些模組安裝到主目錄中，請執行 ./setup.py install --home=<您的主目錄>。

  • 在某些情況下，建議您完全避免安裝模組。如要這麼做，請修改 PYTHONPATH 環境變數，加入包含 Google Data Python 用戶端程式庫的 gdata 和 atom 目錄的目錄。如需修改 PYTHONPATH 的操作說明，請參閱本文結尾處的附錄。

  • 我最後要提的是，執行 python 時，請將 gdata 和 atom 目錄從 src 目錄複製到您目前所在的目錄。Python 會在您匯入檔案時在目前的目錄中尋找，但我不建議使用這個方法，除非您要建立簡單快速的方法。

安裝 Google Data Library 後，即可為程式庫進行測試。

執行測試與範例

Google Data Python 用戶端程式庫的發行版包含一些在測試開發時使用的測試案例。也能做為快速檢查，確保依附元件和程式庫安裝項目運作正常。在從已解壓縮程式庫的頂層目錄中，嘗試執行下列動作：

./tests/run_data_tests.py

如果這個指令碼正確執行，您在指令列中看到的內容應該如下：

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

...

如果您在執行測試時沒有看到任何錯誤，表示可能是您的環境設定正確無誤。恭喜！

您現在可以開始執行更有趣的事情了。發布版本內含 samples 目錄，其中包含了撰寫應用程式起點的程式碼。如要嘗試簡單的互動式範例，請嘗試執行 ./samples/docs/docs_example.py。 Google Documents List API 範例將提示您輸入「Google 帳戶」的電子郵件地址和密碼。如果 Google 文件中有文件或試算表，您可以對所選作業輸入 1 來列出這些文件或試算表。(如果您沒有任何文件或試算表，系統會顯示 404 錯誤)。

如果您有興趣使用特定 Google 資料服務，請觀看該服務的範例，以便瞭解如何使用程式庫。程式碼範例中示範了大多數 (但並非全部) 功能，因此建議您針對打算合作的服務查看說明文件，瞭解該 API 的用途。

撰寫「Hello World」範例

讓我們先從一個簡單的範例開始。以下流程是列印 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

您可以將上方程式碼片段儲存為檔案並加以執行，或將程式碼貼到 Python 解譯器，以便查看 Google Data Python 用戶端程式庫。

結語

您已經安裝並測試了 Google Data Python 用戶端程式庫，現在可以開始使用以下項目撰寫下一個很棒的應用程式：

開發應用程式時，您可能會碰到困境。如果是的話，請參閱下列資源：

如果您覺得程式庫有很棒的新功能 (或偶爾會發現錯誤)，請在討論群組中輸入相關資訊。我們非常重視您的意見回饋！

祝您一切順利 :-)

附錄：修改 PYTHONPATH

當您在 Python 中匯入套件或模組時，解譯器會在一系列位置尋找檔案，包括 PYTHONPATH 環境變數中列出的所有目錄。我通常會修改 PYTHONPATH，以指向已複製所用程式庫原始碼的模組。這可防止每次修改模組時都不需要安裝模組，因為 Python 會從包含修改原始碼的目錄直接載入模組。

如果您要變更用戶端程式庫程式碼，或您沒有系統的管理員權限，建議您使用 PYTHONPATH 方法。編輯 PYTHONPATH 後，您可以將所需的模組放入任意位置。

我在 .bashrcnix 和 Mac OS X 系統上設定我的 PYTHONPATH，藉此在 .bashrc 殼層設定檔中修改了我的 PYTHONPATH。如果您使用的是 bash 殼層，可以在 ~/.bashrc 檔案中加入以下這一行，以設定變數。

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

接著，您可以執行 source ~/.bashrc 來將這些變更套用至目前的殼層工作階段。

對於 Windows XP，請為您的設定檔開啟環境變數：控制台 > 系統屬性 > 進階 > 環境變數。接著，您可以建立或編輯 PYTHONPATH 變數，並新增本機資料庫副本的位置。