開始使用 Google Data Python 程式庫

Google Data APIs 團隊 Jeffrey Scudder
2007 年 8 月

簡介

您已決定使用 Google Data Python 用戶端程式庫，透過眾多 Google Data 服務之一編寫應用程式。選得好！本簡短教學課程的目標是協助您快速開始使用用戶端程式庫開發應用程式。

您可能想立即開始建立應用程式。 不過，您可能需要先設定開發環境，並設定執行用戶端程式庫所含模組所需的工具。按照下列步驟操作，即可立即執行程式碼。

安裝 Python

如果您要使用 Python 用戶端程式庫進行開發，則需要 Python 2.2 以上版本。許多作業系統都內建 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 檔案。如果您沒有根目錄權限，或只想從主目錄使用 Python，可以就此停止。您將可從這個目錄執行 Python，因此不妨將其新增至 PATH 環境變數。
  5. 我偏好在 /usr/bin/ 中安裝 Python，因為大多數 Python 指令碼都會在此尋找解譯器。 如果您有根存取權，請以根使用者身分執行 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 程式庫」。
  4. 下載適合您作業系統的版本。舉例來說，如果您使用 Windows，請下載 elementtree-1.2.6-20050316.win32.exe。 如果是其他作業系統，建議下載壓縮版本。
  5. 如果您使用的是 .tar.gz 或 .zip 版本的程式庫，請先解壓縮，然後執行 ./setup.py install 安裝。

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

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

安裝 Google 資料程式庫

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

下載程式庫後，請根據所選的下載類型，使用 unzip 或 tar zxvf 解壓縮。

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

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

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

  • 最後一個要介紹的選項，是將 src 目錄中的 gdata 和 atom 目錄，複製到執行 python 時所在的任何目錄中。 匯入時，Python 會在目前目錄中尋找，但除非您要建立簡單快速的項目，否則不建議使用這個方法。

安裝 Google Data 程式庫後，即可開始測試。

執行測試和範例

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 文件清單 API 範例會提示您輸入 Google 帳戶的電子郵件地址和密碼。如果您在 Google 文件中有任何文件或試算表，可以輸入 1 列出所選作業的檔案。(如果沒有任何文件或試算表，系統會顯示 404 錯誤。)

如果您對特定 Google Data 服務感興趣，請查看相關範例，瞭解如何使用程式庫。範例程式碼會展示大部分 (但不是全部) 的功能，因此建議您查看打算使用的服務說明文件，清楚瞭解 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 即可將所需模組放在任何位置。

我在 *nix 和 Mac OS X 系統上修改 PYTHONPATH，方法是在 .bashrc 殼層設定檔中設定。如果您使用 bash shell，可以在 ~/.bashrc 檔案中新增下列程式碼，設定變數。

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

然後執行 source ~/.bashrc，將這些變更套用至目前的 Shell 工作階段。

如果是 Windows XP，請找出您設定檔的環境變數：依序點選「控制台」 >「系統屬性」 >「進階」 >「環境變數」。然後建立或編輯 PYTHONPATH 變數，並加入本機程式庫副本的位置。