Google 数据 Python 库使用入门

Jeffrey Scudder，Google 数据 API 团队
2007 年 8 月

简介

因此，您决定使用 Google Data Python 客户端库通过众多 Google 数据服务之一编写应用。非常棒的选择！ 本简短教程的目标是帮助您快速开始使用客户端库来开发应用。

您可能希望立即开始构建应用。不过，您可能需要先配置开发环境并设置运行客户端库中包含的模块所需的工具。您只需按以下步骤操作，即可立即运行代码。

安装 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 下载页面下载源代码 tar 压缩文件。
  2. 下载软件包后，使用命令行将其解压缩。您可以使用以下 
    tar zxvf Python-2.<Your version>.tgz
  3. 接下来，您需要编译和安装 Python 解释器的源代码。在解压缩的目录中，运行 ./configure 以生成 makefile。
  4. 然后，运行 make。这将在本地目录中创建一个可正常运行的 Python 可执行文件。如果您没有根目录权限，或者只是想在主目录中使用 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 库。
  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 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 库之后，您就可以将该库用于试驾了。

运行测试和示例

Google 数据 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 Documents 帐号中的所有文档的列表：

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 数据 Python 客户端库，可以开始使用以下代码编写下一个出色的应用了：

随着您不断开发应用，您可能会遇到困难。如果是这样，请查看下面的资源列表：

如果您碰巧想到了该库的一项新功能（或者碰巧发现了一个错误），请在论坛中将其输入。我们一直关注您的反馈！

祝您编码顺利 :-)

附录：修改 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 变量并添加本地库副本的位置。