Google Data Python 库使用入门

Jeffrey Scudder，Google Data API 团队
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 菜单中选择关于本机。
  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. 我希望将 Python 安装在 /usr/bin/ 中，因为大多数 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 库。
  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，请参阅本文末尾的附录。

  • 我要介绍的最后一个选项是将 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 Documents List 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 客户端库，接下来可以开始使用以下工具编写下一个出色的应用了：

在继续开发应用的过程中，您可能会遇到一些问题。如果是，请查看下方的资源列表：

如果您偶然想到一个很棒的新功能（或偶然发现一个 bug），请在讨论组中输入该功能（或 bug）。 我们一直期待您的反馈！

祝您编码愉快 :-)

附录：修改 PYTHONPATH

在 Python 中导入软件包或模块时，解释器会在一系列位置（包括 PYTHONPATH 环境变量中列出的所有目录）中查找相应文件。我经常修改 PYTHONPATH 以指向我已复制所用库的源代码的模块。这样一来，每次修改模块时都不需要重新安装，因为 Python 会直接从包含修改后的源代码的目录加载模块。

如果您要更改客户端库代码，或者您没有系统的管理员权限，建议您采用 PYTHONPATH 方法。通过修改 PYTHONPATH，您可以将必需的模块放置在任意位置。

我在 *nix 和 Mac OS X 系统上修改了 PYTHONPATH，方法是在 .bashrc shell 配置文件中设置它。如果您使用的是 bash shell，则可以通过在 ~/.bashrc 文件中添加以下行来设置变量。

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

然后，您可以通过执行 source ~/.bashrc 将这些更改应用于当前 shell 会话。

对于 Windows XP，请调出您个人资料的环境变量：控制面板 > 系统属性 > 高级 > 环境变量。然后，您可以创建或修改 PYTHONPATH 变量，并添加本地库副本的位置。